168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisBIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions 668651Skris 768651Skris=head1 SYNOPSIS 868651Skris 968651Skris #include <openssl/bio.h> 1068651Skris 1168651Skris int BIO_read(BIO *b, void *buf, int len); 1268651Skris int BIO_gets(BIO *b,char *buf, int size); 1368651Skris int BIO_write(BIO *b, const void *buf, int len); 1468651Skris int BIO_puts(BIO *b,const char *buf); 1568651Skris 1668651Skris=head1 DESCRIPTION 1768651Skris 1868651SkrisBIO_read() attempts to read B<len> bytes from BIO B<b> and places 1968651Skristhe data in B<buf>. 2068651Skris 2168651SkrisBIO_gets() performs the BIOs "gets" operation and places the data 2268651Skrisin B<buf>. Usually this operation will attempt to read a line of data 2368651Skrisfrom the BIO of maximum length B<len>. There are exceptions to this 2468651Skrishowever, for example BIO_gets() on a digest BIO will calculate and 2568651Skrisreturn the digest and other BIOs may not support BIO_gets() at all. 2668651Skris 2768651SkrisBIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>. 2868651Skris 2968651SkrisBIO_puts() attempts to write a null terminated string B<buf> to BIO B<b> 3068651Skris 3168651Skris=head1 RETURN VALUES 3268651Skris 3368651SkrisAll these functions return either the amount of data successfully read or 3468651Skriswritten (if the return value is positive) or that no data was successfully 3568651Skrisread or written if the result is 0 or -1. If the return value is -2 then 3668651Skristhe operation is not implemented in the specific BIO type. 3768651Skris 3868651Skris=head1 NOTES 3968651Skris 4068651SkrisA 0 or -1 return is not necessarily an indication of an error. In 4168651Skrisparticular when the source/sink is non-blocking or of a certain type 4268651Skrisit may merely be an indication that no data is currently available and that 4368651Skristhe application should retry the operation later. 4468651Skris 4568651SkrisOne technique sometimes used with blocking sockets is to use a system call 4668651Skris(such as select(), poll() or equivalent) to determine when data is available 4768651Skrisand then call read() to read the data. The equivalent with BIOs (that is call 4868651Skrisselect() on the underlying I/O structure and then call BIO_read() to 4968651Skrisread the data) should B<not> be used because a single call to BIO_read() 5068651Skriscan cause several reads (and writes in the case of SSL BIOs) on the underlying 5168651SkrisI/O structure and may block as a result. Instead select() (or equivalent) 5268651Skrisshould be combined with non blocking I/O so successive reads will request 5368651Skrisa retry instead of blocking. 5468651Skris 5568651SkrisSee L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to 5668651Skrisdetermine the cause of a retry and other I/O issues. 5768651Skris 5868651SkrisIf the BIO_gets() function is not supported by a BIO then it possible to 5968651Skriswork around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)> 6068651Skristo the chain. 6168651Skris 6268651Skris=head1 SEE ALSO 6368651Skris 6468651SkrisL<BIO_should_retry(3)|BIO_should_retry(3)> 6568651Skris 6668651SkrisTBA 67