xref: /openssl/doc/man3/BIO_read.pod (revision da1c088f)
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