1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions 6*2175Sjp161948 7*2175Sjp161948=head1 SYNOPSIS 8*2175Sjp161948 9*2175Sjp161948 #include <openssl/bio.h> 10*2175Sjp161948 11*2175Sjp161948 int BIO_read(BIO *b, void *buf, int len); 12*2175Sjp161948 int BIO_gets(BIO *b,char *buf, int size); 13*2175Sjp161948 int BIO_write(BIO *b, const void *buf, int len); 14*2175Sjp161948 int BIO_puts(BIO *b,const char *buf); 15*2175Sjp161948 16*2175Sjp161948=head1 DESCRIPTION 17*2175Sjp161948 18*2175Sjp161948BIO_read() attempts to read B<len> bytes from BIO B<b> and places 19*2175Sjp161948the data in B<buf>. 20*2175Sjp161948 21*2175Sjp161948BIO_gets() performs the BIOs "gets" operation and places the data 22*2175Sjp161948in B<buf>. Usually this operation will attempt to read a line of data 23*2175Sjp161948from the BIO of maximum length B<len>. There are exceptions to this 24*2175Sjp161948however, for example BIO_gets() on a digest BIO will calculate and 25*2175Sjp161948return the digest and other BIOs may not support BIO_gets() at all. 26*2175Sjp161948 27*2175Sjp161948BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>. 28*2175Sjp161948 29*2175Sjp161948BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b> 30*2175Sjp161948 31*2175Sjp161948=head1 RETURN VALUES 32*2175Sjp161948 33*2175Sjp161948All these functions return either the amount of data successfully read or 34*2175Sjp161948written (if the return value is positive) or that no data was successfully 35*2175Sjp161948read or written if the result is 0 or -1. If the return value is -2 then 36*2175Sjp161948the operation is not implemented in the specific BIO type. 37*2175Sjp161948 38*2175Sjp161948=head1 NOTES 39*2175Sjp161948 40*2175Sjp161948A 0 or -1 return is not necessarily an indication of an error. In 41*2175Sjp161948particular when the source/sink is non-blocking or of a certain type 42*2175Sjp161948it may merely be an indication that no data is currently available and that 43*2175Sjp161948the application should retry the operation later. 44*2175Sjp161948 45*2175Sjp161948One technique sometimes used with blocking sockets is to use a system call 46*2175Sjp161948(such as select(), poll() or equivalent) to determine when data is available 47*2175Sjp161948and then call read() to read the data. The equivalent with BIOs (that is call 48*2175Sjp161948select() on the underlying I/O structure and then call BIO_read() to 49*2175Sjp161948read the data) should B<not> be used because a single call to BIO_read() 50*2175Sjp161948can cause several reads (and writes in the case of SSL BIOs) on the underlying 51*2175Sjp161948I/O structure and may block as a result. Instead select() (or equivalent) 52*2175Sjp161948should be combined with non blocking I/O so successive reads will request 53*2175Sjp161948a retry instead of blocking. 54*2175Sjp161948 55*2175Sjp161948See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to 56*2175Sjp161948determine the cause of a retry and other I/O issues. 57*2175Sjp161948 58*2175Sjp161948If the BIO_gets() function is not supported by a BIO then it possible to 59*2175Sjp161948work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)> 60*2175Sjp161948to the chain. 61*2175Sjp161948 62*2175Sjp161948=head1 SEE ALSO 63*2175Sjp161948 64*2175Sjp161948L<BIO_should_retry(3)|BIO_should_retry(3)> 65*2175Sjp161948 66*2175Sjp161948TBA 67