1.Dd $Mdocdate: February 16 2015 $ 2.Dt BIO_READ 3 3.Os 4.Sh NAME 5.Nm BIO_read , 6.Nm BIO_write , 7.Nm BIO_gets , 8.Nm BIO_puts 9.Nd BIO I/O functions 10.Sh SYNOPSIS 11.In openssl/bio.h 12.Ft int 13.Fo BIO_read 14.Fa "BIO *b" 15.Fa "void *buf" 16.Fa "int len" 17.Fc 18.Ft int 19.Fo BIO_gets 20.Fa "BIO *b" 21.Fa "char *buf" 22.Fa "int size" 23.Fc 24.Ft int 25.Fo BIO_write 26.Fa "BIO *b" 27.Fa "const void *buf" 28.Fa "int len" 29.Fc 30.Ft int 31.Fo BIO_puts 32.Fa "BIO *b" 33.Fa "const char *buf" 34.Fc 35.Sh DESCRIPTION 36.Fn BIO_read 37attempts to read 38.Fa len 39bytes from BIO 40.Fa b 41and places the data in 42.Fa buf . 43.Pp 44.Fn BIO_gets 45performs the BIOs "gets" operation and places the data in 46.Fa buf . 47Usually this operation will attempt to read a line of data 48from the BIO of maximum length 49.Fa len . 50There are exceptions to this however, for example 51.Fn BIO_gets 52on a digest BIO will calculate and return the digest 53and other BIOs may not support 54.Fn BIO_gets 55at all. 56.Pp 57.Fn BIO_write 58attempts to write 59.Fa len 60bytes from 61.Fa buf 62to BIO 63.Fa b . 64.Pp 65.Fn BIO_puts 66attempts to write a null terminated string 67.Fa buf 68to BIO 69.Fa b . 70.Sh RETURN VALUES 71All these functions return either the amount of data successfully 72read or written (if the return value is positive) or that no data 73was successfully read or written if the result is 0 or -1. 74If the return value is -2, then the operation is not implemented 75in the specific BIO type. 76.Sh NOTES 77A 0 or -1 return is not necessarily an indication of an error. 78In particular when the source/sink is non-blocking or of a certain type 79it may merely be an indication that no data is currently available and that 80the application should retry the operation later. 81.Pp 82One technique sometimes used with blocking sockets 83is to use a system call (such as 84.Xr select 2 , 85.Xr poll 2 86or equivalent) to determine when data is available and then call 87.Xr read 3 88to read the data. 89The equivalent with BIOs (that is call 90.Xr select 2 91on the underlying I/O structure and then call 92.Fn BIO_read 93to read the data) should 94.Em not 95be used because a single call to 96.Fn BIO_read 97can cause several reads (and writes in the case of SSL BIOs) 98on the underlying I/O structure and may block as a result. 99Instead 100.Xr select 2 101(or equivalent) should be combined with non blocking I/O 102so successive reads will request a retry instead of blocking. 103.Pp 104See 105.Xr BIO_should_retry 3 106for details of how to determine the cause of a retry and other I/O issues. 107.Pp 108If the 109.Fn BIO_gets 110function is not supported by a BIO then it is possible to 111work around this by adding a buffering BIO 112.Xr BIO_f_buffer 3 113to the chain. 114.Sh SEE ALSO 115.Xr BIO_should_retry 3 116