1.Dd $Mdocdate: September 9 2015 $ 2.Dt BIO_CTRL 3 3.Os 4.Sh NAME 5.Nm BIO_ctrl , 6.Nm BIO_callback_ctrl , 7.Nm BIO_ptr_ctrl , 8.Nm BIO_int_ctrl , 9.Nm BIO_reset , 10.Nm BIO_seek , 11.Nm BIO_tell , 12.Nm BIO_flush , 13.Nm BIO_eof , 14.Nm BIO_set_close , 15.Nm BIO_get_close , 16.Nm BIO_pending , 17.Nm BIO_wpending , 18.Nm BIO_ctrl_pending , 19.Nm BIO_ctrl_wpending , 20.Nm BIO_get_info_callback , 21.Nm BIO_set_info_callback 22.Nd BIO control operations 23.Sh SYNOPSIS 24.In openssl/bio.h 25.Ft long 26.Fo BIO_ctrl 27.Fa "BIO *bp" 28.Fa "int cmd" 29.Fa "long larg" 30.Fa "void *parg" 31.Fc 32.Ft long 33.Fo BIO_callback_ctrl 34.Fa "BIO *b" 35.Fa "int cmd" 36.Fa "void (*fp)(struct bio_st *, int, const char *, int, long, long)" 37.Fc 38.Ft char * 39.Fo BIO_ptr_ctrl 40.Fa "BIO *bp" 41.Fa "int cmd" 42.Fa "long larg" 43.Fc 44.Ft long 45.Fo BIO_int_ctrl 46.Fa "BIO *bp" 47.Fa "int cmd" 48.Fa "long larg" 49.Fa "int iarg" 50.Fc 51.Ft int 52.Fo BIO_reset 53.Fa "BIO *b" 54.Fc 55.Ft int 56.Fo BIO_seek 57.Fa "BIO *b" 58.Fa "int ofs" 59.Fc 60.Ft int 61.Fo BIO_tell 62.Fa "BIO *b" 63.Fc 64.Ft int 65.Fo BIO_flush 66.Fa "BIO *b" 67.Fc 68.Ft int 69.Fo BIO_eof 70.Fa "BIO *b" 71.Fc 72.Ft int 73.Fo BIO_set_close 74.Fa "BIO *b" 75.Fa "long flag" 76.Fc 77.Ft int 78.Fo BIO_get_close 79.Fa "BIO *b" 80.Fc 81.Ft int 82.Fo BIO_pending 83.Fa "BIO *b" 84.Fc 85.Ft int 86.Fo BIO_wpending 87.Fa "BIO *b" 88.Fc 89.Ft size_t 90.Fo BIO_ctrl_pending 91.Fa "BIO *b" 92.Fc 93.Ft size_t 94.Fo BIO_ctrl_wpending 95.Fa "BIO *b" 96.Fc 97.Ft int 98.Fo BIO_get_info_callback 99.Fa "BIO *b" 100.Fa "bio_info_cb **cbp" 101.Fc 102.Ft int 103.Fo BIO_set_info_callback 104.Fa "BIO *b" 105.Fa "bio_info_cb *cb" 106.Fc 107.Ft typedef void 108.Fo bio_info_cb 109.Fa "BIO *b" 110.Fa "int oper" 111.Fa "const char *ptr" 112.Fa "int arg1" 113.Fa "long arg2" 114.Fa "long arg3" 115.Fc 116.Sh DESCRIPTION 117.Fn BIO_ctrl , 118.Fn BIO_callback_ctrl , 119.Fn BIO_ptr_ctrl , 120and 121.Fn BIO_int_ctrl 122are BIO "control" operations taking arguments of various types. 123These functions are not normally called directly, 124various macros are used instead. 125The standard macros are described below, macros specific to a 126particular type of BIO are described in the specific BIO's manual 127page as well as any special features of the standard calls. 128.Pp 129.Fn BIO_reset 130typically resets a BIO to some initial state, in the case 131of file related BIOs for example it rewinds the file pointer 132to the start of the file. 133.Pp 134.Fn BIO_seek 135resets a file related BIO's (that is file descriptor and 136FILE BIOs) file position pointer to 137.Fa ofs 138bytes from start of file. 139.Pp 140.Fn BIO_tell 141returns the current file position of a file related BIO. 142.Pp 143.Fn BIO_flush 144normally writes out any internally buffered data, in some cases 145it is used to signal EOF and that no more data will be written. 146.Pp 147.Fn BIO_eof 148returns 1 if the BIO has read EOF, the precise meaning of 149"EOF" varies according to the BIO type. 150.Pp 151.Fn BIO_set_close 152sets the BIO 153.Fa b 154close flag to 155.Fa flag . 156.Fa flag 157can take the value 158.Dv BIO_CLOSE 159or 160.Dv BIO_NOCLOSE . 161Typically 162.Dv BIO_CLOSE 163is used in a source/sink BIO to indicate that the underlying I/O stream 164should be closed when the BIO is freed. 165.Pp 166.Fn BIO_get_close 167returns the BIO's close flag. 168.Pp 169.Fn BIO_pending , 170.Fn BIO_ctrl_pending , 171.Fn BIO_wpending , 172and 173.Fn BIO_ctrl_wpending 174return the number of pending characters in the BIO's read and write buffers. 175Not all BIOs support these calls. 176.Fn BIO_ctrl_pending 177and 178.Fn BIO_ctrl_wpending 179return a 180.Vt size_t 181type and are functions, 182.Fn BIO_pending 183and 184.Fn BIO_wpending 185are macros which call 186.Fn BIO_ctrl . 187.Sh RETURN VALUES 188.Fn BIO_reset 189normally returns 1 for success and 0 or -1 for failure. 190File BIOs are an exception, they return 0 for success and -1 for failure. 191.Pp 192.Fn BIO_seek 193and 194.Fn BIO_tell 195both return the current file position on success 196and -1 for failure, except file BIOs which for 197.Fn BIO_seek 198always return 0 for success and -1 for failure. 199.Pp 200.Fn BIO_flush 201returns 1 for success and 0 or -1 for failure. 202.Pp 203.Fn BIO_eof 204returns 1 if EOF has been reached 0 otherwise. 205.Pp 206.Fn BIO_set_close 207always returns 1. 208.Pp 209.Fn BIO_get_close 210returns the close flag value 211.Dv BIO_CLOSE 212or 213.Dv BIO_NOCLOSE . 214.Pp 215.Fn BIO_pending , 216.Fn BIO_ctrl_pending , 217.Fn BIO_wpending , 218and 219.Fn BIO_ctrl_wpending 220return the amount of pending data. 221.Sh NOTES 222Because it can write data, 223.Fn BIO_flush 224may return 0 or -1 indicating that the call should be retried later 225in a similar manner to 226.Fn BIO_write . 227The 228.Fn BIO_should_retry 229call should be used and appropriate action taken is the call fails. 230.Pp 231The return values of 232.Fn BIO_pending 233and 234.Fn BIO_wpending 235may not reliably determine the amount of pending data in all cases. 236For example in the case of a file BIO some data may be available in the 237.Vt FILE 238structure's internal buffers but it is not possible 239to determine this in a portably way. 240For other types of BIO they may not be supported. 241.Pp 242If they do not internally handle a particular 243.Fn BIO_ctrl 244operation, filter BIOs usually pass the operation 245to the next BIO in the chain. 246This often means there is no need to locate the required BIO for 247a particular operation, it can be called on a chain and it will 248be automatically passed to the relevant BIO. 249However this can cause unexpected results: 250for example no current filter BIOs implement 251.Fn BIO_seek , 252but this may still succeed if the chain ends 253in a FILE or file descriptor BIO. 254.Pp 255Source/sink BIOs return an 0 if they do not recognize the 256.Fn BIO_ctrl 257operation. 258.Sh BUGS 259Some of the return values are ambiguous and care should be taken. 260In particular a return value of 0 can be returned if an operation 261is not supported, if an error occurred, if EOF has not been reached 262and in the case of 263.Fn BIO_seek 264on a file BIO for a successful operation. 265