BIO_new creates a new BIO with the given method and a reference count of one. It returns the fresh BIO, or NULL on error.

BIO_free decrements the reference count of bio. If the reference count drops to zero, it (optionally) calls the BIO's callback with BIO_CB_FREE, calls the destroy callback, if present, on the method and frees bio itself. It then repeats that for the next BIO in the chain, if any.

It returns one on success or zero otherwise.

BIO_vfree performs the same actions as BIO_free, but has a void return value. This is provided for API-compat.

TODO(fork): remove.

BIO_up_ref increments the reference count of bio and returns one.

BIO_read calls the bio callback_ex if set with BIO_CB_READ, attempts to read len bytes into data, then calls callback_ex with BIO_CB_READ+BIO_CB_RETURN. If len is less than or equal to zero, the function does nothing and return zero. If callback_ex is set BIO_read returns the value from calling the callback_ex, otherwise BIO_read returns the number of bytes read, zero on EOF, or a negative number on error.

BIO_read_ex calls BIO_read and stores the number of bytes read in read_bytes. It returns one on success and zero otherwise.

WARNING: Don't use this, use BIO_read instead. BIO_read_ex returns zero on EOF, which disallows any mechanism to notify the user that an EOF has occurred and renders this API unusable. See openssl/openssl#8208.

BIO_gets calls callback_ex from bio if set with BIO_CB_GETS, attempts to read a line from bio and writes at most size bytes into buf. Then it calls callback_ex with BIO_CB_GETS+BIO_CB_RETURN. If size is less than or equal to zero, the function does nothing and returns zero. If callback_ex is set, BIO_gets returns the value from calling callback_ex, otherwise BIO_gets returns the number of bytes read, or a negative number on error.

This function's output always includes a trailing NUL byte, so it will read at most |size - 1| bytes. If the function read a complete line, the output will include the newline character, '\n'. If no newline was found before |size - 1| bytes or EOF, it outputs the bytes which were available.

BIO_write call the bio callback_ex if set with BIO_CB_WRITE, writes len bytes from data to bio, then calls callback_ex with BIO_CB_WRITE+BIO_CB_RETURN. If len is less than or equal to zero, the function does nothing and return zero. If callback_ex is set BIO_write returns the value from calling the callback_ex, otherwise BIO_write returns the number of bytes written, or a negative number on error.

BIO_write_ex calls BIO_write and stores the number of bytes written in written_bytes, unless written_bytes is NULL. It returns one on success and zero otherwise.

BIO_write_all writes len bytes from data to bio, looping as necessary. It returns one if all bytes were successfully written and zero on error.

BIO_puts calls the bio callback_ex if set with BIO_CB_PUTS, attempts to write a NUL terminated string from buf to bio, then calls callback_ex with BIO_CB_PUTS+BIO_CB_RETURN. If callback_ex is set BIO_puts returns the value from calling the callback_ex, otherwise BIO_puts returns the number of bytes written, or a negative number on error. Unless the application defines a custom bputs method, this will delegate to using bwrite.

BIO_flush flushes any buffered output. It returns one on success and zero otherwise.

BIO_ctrl call the bio callback_ex if set with BIO_CB_CTRL, sends the control request cmd to bio, then calls callback_ex with BIO_CB_CTRL

• BIO_CB_RETURN. The cmd argument should be one of the BIO_C_* values.

BIO_ptr_ctrl acts like BIO_ctrl but passes the address of a void* pointer as parg and returns the value that is written to it, or NULL if the control request returns <= 0.

BIO_int_ctrl acts like BIO_ctrl but passes the address of a copy of iarg as parg.

BIO_reset resets bio to its initial state, the precise meaning of which depends on the concrete type of bio. It returns one on success and zero otherwise.

BIO_eof returns non-zero when bio has reached end-of-file. The precise meaning of which depends on the concrete type of bio. Note that in the case of BIO_pair this always returns non-zero.

BIO_set_flags ORs flags with bio->flags.

BIO_test_flags returns bio->flags AND flags.

BIO_should_read returns non-zero if bio encountered a temporary error while reading (i.e. EAGAIN), indicating that the caller should retry the read.

BIO_should_write returns non-zero if bio encountered a temporary error while writing (i.e. EAGAIN), indicating that the caller should retry the write.

BIO_should_retry returns non-zero if the reason that caused a failed I/O operation is temporary and thus the operation should be retried. Otherwise, it was a permanent error and it returns zero.

BIO_should_io_special returns non-zero if bio encountered a temporary error while performing a special I/O operation, indicating that the caller should retry. The operation that caused the error is returned by BIO_get_retry_reason.

BIO_RR_CONNECT indicates that a connect would have blocked

BIO_RR_ACCEPT indicates that an accept would have blocked

BIO_get_retry_reason returns the special I/O operation that needs to be retried. The return value is one of the BIO_RR_* values.

BIO_set_retry_reason sets the special I/O operation that needs to be retried to reason, which should be one of the BIO_RR_* values.

BIO_clear_flags ANDs bio->flags with the bitwise-complement of flags.

BIO_set_retry_read sets the BIO_FLAGS_READ and BIO_FLAGS_SHOULD_RETRY flags on bio.

BIO_set_retry_write sets the BIO_FLAGS_WRITE and BIO_FLAGS_SHOULD_RETRY flags on bio.

BIO_get_retry_flags gets the BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL and BIO_FLAGS_SHOULD_RETRY flags from bio.

BIO_clear_retry_flags clears the BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL and BIO_FLAGS_SHOULD_RETRY flags from bio.

BIO_method_type returns the type of bio, which is one of the BIO_TYPE_* values.

BIO_method_name returns the name of bio.

These are passed to the BIO callback

The callback is called before and after the underling operation, The BIO_CB_RETURN flag indicates if it is after the call

bio_info_cb is a type of callback function providing information about a BIO operation. state identifies the current state of the BIO object, such as BIO_CONN_S_BEFORE. res represent the result of the operation that triggered the callback. This can be a positive value, zero, or a negative value depending on the operation and its outcome.

BIO_callback_fn_ex parameters have the following meaning: bio the bio that made the call oper the operation being performed, may be or'd with BIO_CB_RETURN argp, argi, and argl depends on the value of oper bio_ret is the return value from the BIO method itself, if the callback is called before the operation the value 1 is used len the length of data requested to be read or written processed points to the location which will be updated with the amount of data actually read or written

BIO_callback_ctrl allows the callback function to be manipulated. The cmd arg will generally be BIO_CTRL_SET_CALLBACK but arbitrary command values can be interpreted by the BIO.

BIO_pending returns the number of bytes pending to be read.

BIO_ctrl_pending calls BIO_pending and exists only for compatibility with OpenSSL.

BIO_wpending returns the number of bytes pending to be written.

BIO_set_close sets the close flag for bio. The meaning of which depends on the type of bio but, for example, a memory BIO interprets the close flag as meaning that it owns its buffer. It returns one on success and zero otherwise.

BIO_get_close returns the close flag for bio.

BIO_number_read returns the number of bytes that have been read from bio.

BIO_number_written returns the number of bytes that have been written to bio.

BIO_set_callback_ex sets the callback_ex for bio. The callback is invoked without incrementing the BIO's reference count, so a callback must not call BIO_free on the BIO it is invoked on.

BIO_set_callback sets the legacy callback for bio. The same reference count note as BIO_set_callback_ex applies. When both callback and callback_ex are set, callback_ex will be used. Added for compatibility with existing applications.

BIO_set_callback_arg sets the callback arg for bio.

BIO_get_callback_arg returns the callback argument for BIO bio.

Managing chains of BIOs.

BIOs can be put into chains where the output of one is used as the input of the next etc. The most common case is a buffering BIO, which accepts and buffers writes until flushed into the next BIO in the chain.

BIO_push adds appended_bio to the end of the chain with bio at the head. It returns bio. Note that appended_bio may be the head of a chain itself and thus this function can be used to join two chains.

BIO_push takes ownership of the caller's reference to appended_bio.

BIO_pop removes bio from the head of a chain and returns the next BIO in the chain, or NULL if there is no next BIO.

The caller takes ownership of the chain's reference to bio.

BIO_next returns the next BIO in the chain after bio, or NULL if there is no such BIO.

BIO_free_all calls BIO_free.

TODO(fork): update callers and remove.

BIO_find_type walks a chain of BIOs and returns the first that matches type, which is one of the BIO_TYPE_* values.

BIO_copy_next_retry sets the retry flags and retry_reason of bio from the next BIO in the chain.

BIO_printf behaves like printf but outputs to bio rather than a FILE. It returns the number of bytes written or a negative number on error.

BIO_indent prints min(indent, max_indent) spaces. It returns one on success and zero otherwise.

BIO_hexdump writes a hex dump of data to bio. Each line will be indented by indent spaces. It returns one on success and zero otherwise.

BIO_dump writes a hex dump of data for len bytes to bio. It returns the exact number of bytes written to bio on success, or a negative value on error. If len is zero or data is NULL with len being zero, it returns 0.

ERR_print_errors prints the current contents of the error stack to bio using human readable strings where possible.

BIO_read_asn1 reads a single ASN.1 object from bio. If successful it sets *out to be an allocated buffer (that should be freed with OPENSSL_free), *out_size to the length, in bytes, of that buffer and returns one. Otherwise it returns zero.

If the length of the object is greater than max_len or 2^32 then the function will fail. Long-form tags are not supported. If the length of the object is indefinite the full contents of bio are read, unless it would be greater than max_len, in which case the function fails.

If the function fails then some unknown amount of data may have been read from bio.

BIO_s_mem returns a BIO_METHOD that uses a in-memory buffer.

BIO_new_mem_buf creates read-only BIO that reads from len bytes at buf. It returns the BIO or NULL on error. This function does not copy or take ownership of buf. The caller must ensure the memory pointed to by buf outlives the BIO.

If len is negative, then buf is treated as a NUL-terminated string, but don't depend on this in new code.

BIO_mem_contents sets *out_contents, if not null, to point to the current contents ofbio and *out_len, if not null, to contain the length of that data.

It returns one on success and zero otherwise.

BIO_get_mem_data sets *contents to point to the current contents of bio and returns the length of the data. Despite being a macro, this function should always take |char *| as a value and nothing else.

WARNING: don't use this, use BIO_mem_contents. A negative return value or zero from this function can mean either that it failed or that the memory buffer is empty.

BIO_get_mem_ptr sets *out to a BUF_MEM containing the current contents of bio. It returns one on success or zero on error.

BIO_set_mem_buf sets b as the contents of bio. If take_ownership is non-zero, then b will be freed when bio is closed. Returns one on success or zero otherwise.

BIO_set_mem_eof_return sets the value that will be returned from reading bio when empty. If eof_value is zero then an empty memory BIO will return EOF (that is it will return zero and BIO_should_retry will be false). If eof_value is non zero then it will return eof_value when it is empty and it will set the read retry flag (that is BIO_read_retry is true). To avoid ambiguity with a normal positive return value, eof_value should be set to a negative value, typically -1.

For a read-only BIO, the default is zero (EOF). For a writable BIO, the default is -1 so that additional data can be written once exhausted.

BIO_NOCLOSE will not close the underlying file on BIO free

BIO_CLOSE will close the underlying file on BIO free

BIO_FP_TEXT will cause the file to be treated as a text file instead of the default behavior of treating it as a raw binary file. This is only relevant on Windows due to CRLF endings.

BIO_s_fd returns a BIO_METHOD for file descriptor fds.

BIO_new_fd creates a new file descriptor BIO wrapping fd. If close_flag is non-zero, then fd will be closed when the BIO is.

BIO_set_fd sets the file descriptor of bio to fd. If close_flag is non-zero then fd will be closed when bio is. It returns one on success or zero on error.

This function may also be used with socket BIOs (see BIO_s_socket and BIO_new_socket).

BIO_get_fd returns the file descriptor currently in use by bio or -1 if bio does not wrap a file descriptor. If there is a file descriptor and out_fd is not NULL, it also sets *out_fd to the file descriptor.

This function may also be used with socket BIOs (see BIO_s_socket and BIO_new_socket).

BIO_s_file returns a BIO_METHOD that wraps a FILE.

BIO_new_file creates a file BIO by opening filename with the given mode. See the fopen manual page for details of the mode argument.

BIO_new_fp creates a new file BIO that wraps the given FILE. If close_flag is BIO_CLOSE, then fclose will be called on stream when the BIO is closed. If close_flag is BIO_FP_TEXT, the file will be set as a text file after opening (only on Windows).

BIO_get_fp sets *out_file to the current FILE for bio. It returns one on success and zero otherwise.

BIO_set_fp sets the FILE for bio. If close_flag is BIO_CLOSE then fclose will be called on file when bio is closed. If close_flag is BIO_FP_TEXT, the file will be set as a text file (only on Windows). It returns one on success and zero otherwise.

BIO_read_filename opens filename for reading and sets the result as the FILE for bio. It returns one on success and zero otherwise. The FILE will be closed when bio is freed. On Windows, the file is opened in binary mode.

BIO_write_filename opens filename for writing and sets the result as the FILE for bio. It returns one on success and zero otherwise. The FILE will be closed when bio is freed. On Windows, the file is opened in binary mode.

BIO_append_filename opens filename for appending and sets the result as the FILE for bio. It returns one on success and zero otherwise. The FILE will be closed when bio is freed. On Windows, the file is opened in binary mode.

BIO_rw_filename opens filename for reading and writing and sets the result as the FILE for bio. It returns one on success and zero otherwise. The FILE will be closed when bio is freed. On Windows, the file is opened in binary mode.

BIO_tell returns the file offset of bio, or a negative number on error or if bio does not support the operation.

TODO(https://crbug.com/boringssl/465): On platforms where long is 32-bit, this function cannot report 64-bit offsets.

BIO_seek sets the file offset of bio to offset. It returns a non-negative number on success and a negative number on error. If bio is a file descriptor BIO, it returns the resulting file offset on success. If bio is a file BIO, it returns zero on success.

WARNING: This function's return value conventions differs from most functions in this library.

TODO(https://crbug.com/boringssl/465): On platforms where long is 32-bit, this function cannot handle 64-bit offsets.

BIO_new_socket allocates and initialises a fresh BIO which will read and write to the socket fd. If close_flag is BIO_CLOSE then closing the BIO will close fd. It returns the fresh BIO or NULL on error.

BIO_new_connect returns a BIO that connects to the given hostname and port. The host_and_optional_port argument should be of the form "www.example.com" or "www.example.com:443". If the port is omitted, it must be provided with BIO_set_conn_port.

It returns the new BIO on success, or NULL on error.

BIO_set_conn_hostname sets host_and_optional_port as the hostname and optional port that bio will connect to. If the port is omitted, it must be provided with BIO_set_conn_port.

It returns one on success and zero otherwise.

BIO_set_conn_port sets port_str as the port or service name that bio will connect to. It returns one on success and zero otherwise.

BIO_set_conn_int_port sets *port as the port that bio will connect to. It returns one on success and zero otherwise.

BIO_set_nbio sets whether bio will use non-blocking I/O operations. It returns one on success and zero otherwise. This only works for connect BIOs and must be called before bio is connected to take effect.

For socket and fd BIOs, callers must configure blocking vs. non-blocking I/O using the underlying platform APIs.

BIO_do_connect connects bio if it has not been connected yet. It returns one on success and <= 0 otherwise.

BIO_f_md provides a filter BIO that digests any data passed through it. The BIO must be initialized with BIO_set_md or BIO_get_md_ctx before it can be used.

BIO_get_md_ctx writes a reference of b's EVP_MD_CTX* to *ctx. It returns one on success and zero on error.

BIO_set_md set's b's EVP_MD* to md. It returns one on success and zero on error.

BIO_get_md set's *md to b's EVP_MD*. It returns one on success and zero on error.

BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT is unsupported as it is unused by consumers and depends on timeval, which is not 2038-clean on all platforms.

BIO_s_datagram returns the datagram BIO_METHOD. A datagram BIO provides a wrapper around datagram sockets.

BIO_new_dgram creates a new datagram BIO wrapping fd. If close_flag is non-zero, then fd will be closed when the BIO is freed.

BIO_ctrl_dgram_connect attempts to connect the datagram BIO to the specified peer address. It returns 1 on success and a non-positive value on error.

BIO_ctrl_set_connected marks the datagram BIO as connected to the specified peer address. This is used for handling DTLS connection-oriented BIOs. It returns 1 on success and a non-positive value on error.

BIO_dgram_recv_timedout returns 1 if the most recent datagram receive operation on bp timed out, and a non-positive value otherwise. Any error for this socket gets reset by this call.

BIO_dgram_send_timedout returns 1 if the most recent datagram send operation on bp timed out, and a non-positive value otherwise. Any error for this socket gets reset by this call.

BIO_dgram_get_peer stores the address of the peer the datagram BIO is connected to in peer. It returns 1 on success and a non-positive value on error.

BIO_dgram_set_peer sets the peer address for the datagram BIO to peer. It returns 1 on success and a non-positive value on error.

BIO_ADDR_new allocates and initializes a new BIO_ADDR structure. Returns the new BIO_ADDR structure on success, NULL on error.

BIO_ADDR_copy copies the contents of the BIO_ADDR structure from src to dst. Returns 1 on success, 0 on error.

BIO_ADDR_dup creates a copy of the BIO_ADDR. Returns the new BIO_ADDR structure on success, NULL on error.

BIO_ADDR_free releases all resources associated with the BIO_ADDR structure. If 'ap' is NULL, no action occurs.

BIO_ADDR_clear zeros the contents of the BIO_ADDR structure but does not free it. If 'ap' is NULL, no action occurs.

BIO_ADDR_rawmake sets up a BIO_ADDR with the provided values. family is the Address family (e.g., AF_INET, AF_INET6). where is a pointer to the address data. wherelen is the length of the address data. For AF_UNIX, wherelen is expected to be the length of the path string not including the terminating NUL. port is the port number in host byte order. Returns 1 on success, 0 on error.

BIO_ADDR_family returns the address family of the BIO_ADDR. Returns the address family (e.g., AF_INET, AF_INET6) on success, -1 on error.

BIO_ADDR_rawaddress retrieves the raw address data from a BIO_ADDR structure. The address data from ap is copied into the buffer p if p is not NULL. If l is not NULL, *l will be updated with the size of the address data. For AF_INET, this is the 4-byte IPv4 address; for AF_INET6, the 16-byte IPv6 address; for AF_UNIX, the socket path followed by a NUL terminator. The length stored in *l includes the NUL for AF_UNIX so that it matches the number of bytes written to p. Returns 1 on success, 0 if the address family is unsupported or ap is NULL.

BIO_ADDR_rawport returns the port number stored in the BIO_ADDR. Returns the port number in host byte order.

BIO Pairs.

BIO pairs provide a "loopback" like system: a pair of BIOs where data written to one can be read from the other and vice versa.

BIO_new_bio_pair sets *out1 and *out2 to two freshly created BIOs where data written to one can be read from the other and vice versa. The writebuf1 argument gives the size of the buffer used in *out1 and writebuf2 for *out2. It returns one on success and zero on error.

BIO_destroy_bio_pair destroys the connection between b and b->ptr->peer. It disconnects both BIOs, resets their state, but does not free their memory. It always returns one to indicate success.

BIO_ctrl_get_read_request returns the number of bytes that the other side of bio tried (unsuccessfully) to read.

BIO_ctrl_get_write_guarantee returns the number of bytes that bio (which must have been returned by BIO_new_bio_pair) will accept on the next BIO_write call.

BIO_shutdown_wr marks bio as closed, from the point of view of the other side of the pair. Future BIO_write calls on bio will fail. It returns one on success and zero otherwise.

BIO_get_new_index returns a new "type" value for a custom BIO.

BIO_meth_new returns a newly-allocated BIO_METHOD or NULL on allocation error. The type specifies the type that will be returned by BIO_method_type. If this is unnecessary, this value may be zero. The name parameter is vestigial and may be NULL.

Use the BIO_meth_set_* functions below to initialize the BIO_METHOD. The function implementations may use BIO_set_data and BIO_get_data to add method-specific state to associated BIOs. Additionally, BIO_set_init must be called after an associated BIO is fully initialized. State set via BIO_set_data may be released by configuring a destructor with BIO_meth_set_destroy.

BIO_meth_free releases memory associated with method.

BIO_meth_set_create sets a function to be called on BIO_new for method and returns one. The function should return one on success and zero on error.

BIO_meth_get_create returns create function of method.

BIO_meth_set_destroy sets a function to release data associated with a BIO and returns one. The function's return value is ignored.

BIO_meth_get_destroy returns destroy function of method.

BIO_meth_set_write sets the implementation of BIO_write for method and returns one. BIO_METHODs which implement BIO_write should also implement BIO_CTRL_FLUSH. (See BIO_meth_set_ctrl.)

BIO_meth_set_read sets the implementation of BIO_read for method and returns one.

BIO_meth_set_gets sets the implementation of BIO_gets for method and returns one.

BIO_meth_get_gets returns gets function of method.

BIO_meth_set_ctrl sets the implementation of BIO_ctrl for method and returns one.

BIO_meth_get_ctrl returns ctrl function of method.

BIO_meth_set_callback_ctrl sets the implementation of callback_ctrl for method and returns one.

BIO_meth_get_callback_ctrl returns callback_ctrl function of method.

BIO_set_data sets custom data on bio. It may be retried with BIO_get_data.

This function should only be called by the implementation of a custom BIO. In particular, the data pointer of a built-in BIO is private to the library. For other uses, see BIO_set_ex_data and BIO_set_app_data.

BIO_get_data returns custom data on bio set by BIO_get_data.

This function should only be called by the implementation of a custom BIO. In particular, the data pointer of a built-in BIO is private to the library. For other uses, see BIO_get_ex_data and BIO_get_app_data.

BIO_set_init sets whether bio has been fully initialized. Until fully initialized, BIO_read and BIO_write will fail.

BIO_get_init returns whether bio has been fully initialized.

These are values of the cmd argument to BIO_ctrl.

BIO_CTRL_RESET implements BIO_reset. The arguments are unused.

BIO_CTRL_EOF implements BIO_eof. The arguments are unused.

BIO_CTRL_INFO is a legacy command that returns information specific to the type of BIO. It is not safe to call generically and should not be implemented in new BIO types.

BIO_CTRL_GET_CLOSE returns the close flag set by BIO_CTRL_SET_CLOSE. The arguments are unused.

BIO_CTRL_SET_CLOSE implements BIO_set_close. The larg argument is the close flag.

BIO_CTRL_PENDING implements BIO_pending. The arguments are unused.

BIO_CTRL_FLUSH implements BIO_flush. The arguments are unused.

BIO_CTRL_WPENDING implements BIO_wpending. The arguments are unused.

BIO_CTRL_SET_CALLBACK sets an informational callback of type int cb(BIO *bio, int state, int ret)

BIO_CTRL_GET_CALLBACK returns the callback set by BIO_CTRL_SET_CALLBACK.

The following are never used, but are defined to aid porting existing code.

BIO_f_base64 returns a filter BIO that base64-encodes data written into it, and decodes data read from it. BIO_gets is not supported. Call BIO_flush when done writing, to signal that no more data are to be encoded. The flag BIO_FLAGS_BASE64_NO_NL may be set to encode all the data on one line.

Use EVP_EncodeBlock and EVP_DecodeBase64 instead.

BIO_set_shutdown sets a method-specific "shutdown" bit on bio.

BIO_get_shutdown returns the method-specific "shutdown" bit.

BIO_meth_set_puts sets the implementation of BIO_puts for method and returns 1.

BIO_meth_get_puts returns puts function of method.

BIO_s_secmem returns the normal BIO_METHOD BIO_s_mem. Deprecated since AWS-LC does not support secure heaps.

BIO_set_write_buffer_size returns zero.

TODO (CryptoAlg-2398): Add OPENSSL_DEPRECATED. nginx defines -Werror and depends on this.