1=pod 2 3=head1 NAME 4 5BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, 6BIO_gets, BIO_get_line, BIO_puts 7- BIO I/O functions 8 9=head1 SYNOPSIS 10 11 #include <openssl/bio.h> 12 13 int BIO_read_ex(BIO *b, void *data, size_t dlen, size_t *readbytes); 14 int BIO_write_ex(BIO *b, const void *data, size_t dlen, size_t *written); 15 16 int BIO_read(BIO *b, void *data, int dlen); 17 int BIO_gets(BIO *b, char *buf, int size); 18 int BIO_get_line(BIO *b, char *buf, int size); 19 int BIO_write(BIO *b, const void *data, int dlen); 20 int BIO_puts(BIO *b, const char *buf); 21 22=head1 DESCRIPTION 23 24BIO_read_ex() attempts to read I<dlen> bytes from BIO I<b> and places the data 25in I<data>. If any bytes were successfully read then the number of bytes read is 26stored in I<*readbytes>. 27 28BIO_write_ex() attempts to write I<dlen> bytes from I<data> to BIO I<b>. 29If successful then the number of bytes written is stored in I<*written> 30unless I<written> is NULL. 31 32BIO_read() attempts to read I<len> bytes from BIO I<b> and places 33the data in I<buf>. 34 35BIO_gets() performs the BIOs "gets" operation and places the data 36in I<buf>. Usually this operation will attempt to read a line of data 37from the BIO of maximum length I<size-1>. There are exceptions to this, 38however; for example, BIO_gets() on a digest BIO will calculate and 39return the digest and other BIOs may not support BIO_gets() at all. 40The returned string is always NUL-terminated and the '\n' is preserved 41if present in the input data. 42On binary input there may be NUL characters within the string; 43in this case the return value (if nonnegative) may give an incorrect length. 44 45BIO_get_line() attempts to read from BIO I<b> a line of data up to the next '\n' 46or the maximum length I<size-1> is reached and places the data in I<buf>. 47The returned string is always NUL-terminated and the '\n' is preserved 48if present in the input data. 49On binary input there may be NUL characters within the string; 50in this case the return value (if nonnegative) gives the actual length read. 51For implementing this, unfortunately the data needs to be read byte-by-byte. 52 53BIO_write() attempts to write I<len> bytes from I<buf> to BIO I<b>. 54 55BIO_puts() attempts to write a NUL-terminated string I<buf> to BIO I<b>. 56 57=head1 RETURN VALUES 58 59BIO_read_ex() returns 1 if data was successfully read, and 0 otherwise. 60 61BIO_write_ex() returns 1 if no error was encountered writing data, 0 otherwise. 62Requesting to write 0 bytes is not considered an error. 63 64BIO_write() returns -2 if the "write" operation is not implemented by the BIO 65or -1 on other errors. 66Otherwise it returns the number of bytes written. 67This may be 0 if the BIO I<b> is NULL or I<dlen <= 0>. 68 69BIO_gets() returns -2 if the "gets" operation is not implemented by the BIO 70or -1 on other errors. 71Otherwise it typically returns the amount of data read, 72but depending on the implementation it may return only the length up to 73the first NUL character contained in the data read. 74In any case the trailing NUL that is added after the data read 75is not included in the length returned. 76 77All other functions return either the amount of data successfully read or 78written (if the return value is positive) or that no data was successfully 79read or written if the result is 0 or -1. If the return value is -2 then 80the operation is not implemented in the specific BIO type. 81 82=head1 NOTES 83 84A 0 or -1 return is not necessarily an indication of an error. In 85particular when the source/sink is nonblocking or of a certain type 86it may merely be an indication that no data is currently available and that 87the application should retry the operation later. 88 89One technique sometimes used with blocking sockets is to use a system call 90(such as select(), poll() or equivalent) to determine when data is available 91and then call read() to read the data. The equivalent with BIOs (that is call 92select() on the underlying I/O structure and then call BIO_read() to 93read the data) should B<not> be used because a single call to BIO_read() 94can cause several reads (and writes in the case of SSL BIOs) on the underlying 95I/O structure and may block as a result. Instead select() (or equivalent) 96should be combined with non blocking I/O so successive reads will request 97a retry instead of blocking. 98 99See L<BIO_should_retry(3)> for details of how to 100determine the cause of a retry and other I/O issues. 101 102If the "gets" method is not supported by a BIO then BIO_get_line() can be used. 103It is also possible to make BIO_gets() usable even if the "gets" method is not 104supported by adding a buffering BIO L<BIO_f_buffer(3)> to the chain. 105 106=head1 SEE ALSO 107 108L<BIO_should_retry(3)> 109 110=head1 HISTORY 111 112BIO_gets() on 1.1.0 and older when called on BIO_fd() based BIO did not 113keep the '\n' at the end of the line in the buffer. 114 115BIO_get_line() was added in OpenSSL 3.0. 116 117BIO_write_ex() returns 1 if the size of the data to write is 0 and the 118I<written> parameter of the function can be NULL since OpenSSL 3.0. 119 120=head1 COPYRIGHT 121 122Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved. 123 124Licensed under the Apache License 2.0 (the "License"). You may not use 125this file except in compliance with the License. You can obtain a copy 126in the file LICENSE in the source distribution or at 127L<https://www.openssl.org/source/license.html>. 128 129=cut 130
