BIO abstracts over a file-descriptor like interface.
- Allocation and freeing
- Basic I/O
- Low-level control functions
- Managing chains of BIOs
- Printf functions
- Utility functions
- Memory BIOs
- File descriptor BIOs
- File BIOs
- Socket BIOs
- Connect BIOs
- Datagram BIOs
- BIO Pairs
- BIO_CTRL_RESET 1
- BIO_CTRL_EOF 2
- BIO_CTRL_INFO 3
- BIO_CTRL_SET 4
- BIO_CTRL_GET 5
- BIO_CTRL_GET_CLOSE 8
- BIO_CTRL_SET_CLOSE 9
- BIO_CTRL_PENDING 10
- BIO_CTRL_FLUSH 11
- BIO_CTRL_WPENDING 13
- BIO_CTRL_SET_CALLBACK 14
- BIO_CTRL_GET_CALLBACK 15
- BIO_CTRL_SET_FILENAME 30
- Deprecated functions
Allocation and freeing.
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.
OPENSSL_EXPORT BIO *BIO_new(const BIO_METHOD *method);
BIO_free decrements the reference count of bio. If the reference count drops to zero, it 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.
OPENSSL_EXPORT int BIO_free(BIO *bio);
BIO_vfree performs the same actions as BIO_free, but has a void return value. This is provided for API-compat.
OPENSSL_EXPORT void BIO_vfree(BIO *bio);
BIO_up_ref increments the reference count of bio and returns one.
OPENSSL_EXPORT int BIO_up_ref(BIO *bio);
BIO_read attempts to read len bytes into data. It returns the number of bytes read, zero on EOF, or a negative number on error.
OPENSSL_EXPORT int BIO_read(BIO *bio, void *data, int len);
BIO_gets "reads a line" from bio and puts at most size bytes into buf. It returns the number of bytes read or a negative number on error. The phrase "reads a line" is in quotes in the previous sentence because the exact operation depends on the BIO's method. For example, a digest BIO will return the digest in response to a BIO_gets call.
TODO(fork): audit the set of BIOs that we end up needing. If all actually return a line for this call, remove the warning above.
OPENSSL_EXPORT int BIO_gets(BIO *bio, char *buf, int size);
BIO_write writes len bytes from data to BIO. It returns the number of bytes written or a negative number on error.
OPENSSL_EXPORT int BIO_write(BIO *bio, const void *data, int len);
BIO_puts writes a NUL terminated string from buf to bio. It returns the number of bytes written or a negative number on error.
OPENSSL_EXPORT int BIO_puts(BIO *bio, const char *buf);
BIO_flush flushes any buffered output. It returns one on success and zero otherwise.
OPENSSL_EXPORT int BIO_flush(BIO *bio);
Low-level control functions.
These are generic functions for sending control requests to a BIO. In general one should use the wrapper functions like BIO_get_close.
BIO_ctrl sends the control request cmd to bio. The cmd argument should be one of the BIO_C_* values.
OPENSSL_EXPORT long BIO_ctrl(BIO *bio, int cmd, long larg, void *parg);
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.
OPENSSL_EXPORT char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
BIO_int_ctrl acts like BIO_ctrl but passes the address of a copy of iarg as parg.
OPENSSL_EXPORT long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
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.
OPENSSL_EXPORT int BIO_reset(BIO *bio);
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.
OPENSSL_EXPORT int BIO_eof(BIO *bio);
BIO_set_flags ORs flags with bio->flags.
OPENSSL_EXPORT void BIO_set_flags(BIO *bio, int flags);
BIO_test_flags returns bio->flags AND flags.
OPENSSL_EXPORT int BIO_test_flags(const BIO *bio, int 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.
OPENSSL_EXPORT int BIO_should_read(const BIO *bio);
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.
OPENSSL_EXPORT int BIO_should_write(const BIO *bio);
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.
OPENSSL_EXPORT int BIO_should_retry(const BIO *bio);
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.
OPENSSL_EXPORT int BIO_should_io_special(const BIO *bio);
BIO_RR_CONNECT indicates that a connect would have blocked
#define BIO_RR_CONNECT 0x02
BIO_RR_ACCEPT indicates that an accept would have blocked
#define BIO_RR_ACCEPT 0x03
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.
OPENSSL_EXPORT int BIO_get_retry_reason(const BIO *bio);
BIO_clear_flags ANDs bio->flags with the bitwise-complement of flags.
OPENSSL_EXPORT void BIO_clear_flags(BIO *bio, int flags);
OPENSSL_EXPORT void BIO_set_retry_read(BIO *bio);
OPENSSL_EXPORT void BIO_set_retry_write(BIO *bio);
OPENSSL_EXPORT int BIO_get_retry_flags(BIO *bio);
OPENSSL_EXPORT void BIO_clear_retry_flags(BIO *bio);
BIO_method_type returns the type of bio, which is one of the BIO_TYPE_* values.
OPENSSL_EXPORT int BIO_method_type(const BIO *bio);
bio_info_cb is the type of a callback function that can be called for most BIO operations. The event argument is one of BIO_CB_* and can be ORed with BIO_CB_RETURN if the callback is being made after the operation in question. In that case, return_value will contain the return value from the operation.
typedef long (*bio_info_cb)(BIO *bio, int event, const char *parg, int cmd, long larg, long return_value);
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.
OPENSSL_EXPORT long BIO_callback_ctrl(BIO *bio, int cmd, bio_info_cb fp);
BIO_pending returns the number of bytes pending to be read.
OPENSSL_EXPORT size_t BIO_pending(const BIO *bio);
BIO_ctrl_pending calls BIO_pending and exists only for compatibility with OpenSSL.
OPENSSL_EXPORT size_t BIO_ctrl_pending(const BIO *bio);
BIO_wpending returns the number of bytes pending to be written.
OPENSSL_EXPORT size_t BIO_wpending(const BIO *bio);
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.
OPENSSL_EXPORT int BIO_set_close(BIO *bio, int close_flag);
BIO_number_read returns the number of bytes that have been read from bio.
OPENSSL_EXPORT size_t BIO_number_read(const BIO *bio);
BIO_number_written returns the number of bytes that have been written to bio.
OPENSSL_EXPORT size_t BIO_number_written(const 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.
OPENSSL_EXPORT BIO *BIO_push(BIO *bio, BIO *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.
OPENSSL_EXPORT BIO *BIO_pop(BIO *bio);
BIO_next returns the next BIO in the chain after bio, or NULL if there is no such BIO.
OPENSSL_EXPORT BIO *BIO_next(BIO *bio);
BIO_free_all calls BIO_free.
TODO(fork): update callers and remove.
OPENSSL_EXPORT void BIO_free_all(BIO *bio);
BIO_find_type walks a chain of BIOs and returns the first that matches type, which is one of the BIO_TYPE_* values.
OPENSSL_EXPORT BIO *BIO_find_type(BIO *bio, int type);
BIO_copy_next_retry sets the retry flags and retry_reason of bio from the next BIO in the chain.
OPENSSL_EXPORT void BIO_copy_next_retry(BIO *bio);
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.
OPENSSL_EXPORT int BIO_printf(BIO *bio, const char *format, ...)
BIO_indent prints min(indent, max_indent) spaces. It returns one on success and zero otherwise.
OPENSSL_EXPORT int BIO_indent(BIO *bio, unsigned indent, unsigned max_indent);
BIO_hexdump writes a hex dump of data to bio. Each line will be indented by indent spaces.
OPENSSL_EXPORT int BIO_hexdump(BIO *bio, const uint8_t *data, size_t len, unsigned indent);
ERR_print_errors prints the current contents of the error stack to bio using human readable strings where possible.
OPENSSL_EXPORT void ERR_print_errors(BIO *bio);
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.
OPENSSL_EXPORT int BIO_read_asn1(BIO *bio, uint8_t **out, size_t *out_len, size_t max_len);
Memory BIOs can be used as a read-only source (with BIO_new_mem_buf) or a writable sink (with BIO_new, BIO_s_mem and BIO_get_mem_buf). Data written to a writable, memory BIO can be recalled by reading from it.
Calling BIO_reset on a read-only BIO resets it to the original contents. On a writable BIO, it clears any data.
If the close flag is set to BIO_NOCLOSE (not the default) then the underlying BUF_MEM will not be freed when the BIO is freed.
BIO_ctrl_pending returns the number of bytes currently stored.
BIO_s_mem returns a BIO_METHOD that uses a in-memory buffer.
OPENSSL_EXPORT const BIO_METHOD *BIO_s_mem(void);
BIO_new_mem_buf creates read-only BIO that reads from len bytes at buf. It does not take ownership of buf. It returns the BIO or NULL on error.
If len is negative, then buf is treated as a NUL-terminated string, but don't depend on this in new code.
OPENSSL_EXPORT BIO *BIO_new_mem_buf(const void *buf, int len);
BIO_mem_contents sets *out_contents to point to the current contents of bio and *out_len to contain the length of that data. It returns one on success and zero otherwise.
OPENSSL_EXPORT int BIO_mem_contents(const BIO *bio, const uint8_t **out_contents, size_t *out_len);
BIO_get_mem_data sets *contents to point to the current contents of bio and returns the length of the data.
WARNING: don't use this, use BIO_mem_contents. A return value of zero from this function can mean either that it failed or that the memory buffer is empty.
OPENSSL_EXPORT long BIO_get_mem_data(BIO *bio, char **contents);
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.
OPENSSL_EXPORT int BIO_get_mem_ptr(BIO *bio, BUF_MEM **out);
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.
OPENSSL_EXPORT int BIO_set_mem_buf(BIO *bio, BUF_MEM *b, int take_ownership);
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.
OPENSSL_EXPORT int BIO_set_mem_eof_return(BIO *bio, int eof_value);
File descriptor BIOs.
File descriptor BIOs are wrappers around the system's read and write functions. If the close flag is set then then close is called on the underlying file descriptor when the BIO is freed.
BIO_reset attempts to seek the file pointer to the start of file using lseek.
BIO_s_fd returns a BIO_METHOD for file descriptor fds.
OPENSSL_EXPORT const BIO_METHOD *BIO_s_fd(void);
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.
OPENSSL_EXPORT BIO *BIO_new_fd(int fd, int close_flag);
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.
OPENSSL_EXPORT int BIO_set_fd(BIO *bio, int fd, int close_flag);
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.
OPENSSL_EXPORT int BIO_get_fd(BIO *bio, int *out_fd);
File BIOs are wrappers around a C FILE object.
BIO_flush on a file BIO calls fflush on the wrapped stream.
BIO_reset attempts to seek the file pointer to the start of file using fseek.
Setting the close flag causes fclose to be called on the stream when the BIO is freed.
BIO_s_file returns a BIO_METHOD that wraps a FILE.
OPENSSL_EXPORT const BIO_METHOD *BIO_s_file(void);
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.
OPENSSL_EXPORT BIO *BIO_new_file(const char *filename, const char *mode);
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.
OPENSSL_EXPORT BIO *BIO_new_fp(FILE *stream, int close_flag);
BIO_get_fp sets *out_file to the current FILE for bio. It returns one on success and zero otherwise.
OPENSSL_EXPORT int BIO_get_fp(BIO *bio, FILE **out_file);
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. It returns one on success and zero otherwise.
OPENSSL_EXPORT int BIO_set_fp(BIO *bio, FILE *file, int close_flag);
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.
OPENSSL_EXPORT int BIO_read_filename(BIO *bio, const char *filename);
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.
OPENSSL_EXPORT int BIO_write_filename(BIO *bio, const char *filename);
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.
OPENSSL_EXPORT int BIO_append_filename(BIO *bio, const char *filename);
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.
OPENSSL_EXPORT int BIO_rw_filename(BIO *bio, const char *filename);
Socket BIOs behave like file descriptor BIOs but, on Windows systems, wrap the system's recv and send functions instead of read and write. On Windows, file descriptors are provided by C runtime and are not interchangeable with sockets.
TODO(davidben): Add separate APIs and fix the internals to use SOCKETs around rather than rely on int casts.
OPENSSL_EXPORT const BIO_METHOD *BIO_s_socket(void);
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.
OPENSSL_EXPORT BIO *BIO_new_socket(int fd, int close_flag);
A connection BIO creates a network connection and transfers data over the resulting socket.
OPENSSL_EXPORT const BIO_METHOD *BIO_s_connect(void);
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.
OPENSSL_EXPORT BIO *BIO_new_connect(const char *host_and_optional_port);
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.
OPENSSL_EXPORT int BIO_set_conn_hostname(BIO *bio, const char *host_and_optional_port);
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.
OPENSSL_EXPORT int BIO_set_conn_port(BIO *bio, const char *port_str);
BIO_set_conn_int_port sets *port as the port that bio will connect to. It returns one on success and zero otherwise.
OPENSSL_EXPORT int BIO_set_conn_int_port(BIO *bio, const int *port);
BIO_set_nbio sets whether bio will use non-blocking I/O operations. It returns one on success and zero otherwise.
OPENSSL_EXPORT int BIO_set_nbio(BIO *bio, int on);
BIO_do_connect connects bio if it has not been connected yet. It returns one on success and <= 0 otherwise.
OPENSSL_EXPORT int BIO_do_connect(BIO *bio);
TODO(fork): not implemented.
#define BIO_CTRL_DGRAM_QUERY_MTU 40 // as kernel for current MTU
#define BIO_CTRL_DGRAM_SET_MTU 42 /* set cached value for MTU. want to use this if asking the kernel fails */
#define BIO_CTRL_DGRAM_MTU_EXCEEDED 43 /* check whether the MTU was exceed in the previous write operation. */
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.
#define BIO_CTRL_DGRAM_GET_PEER 46
#define BIO_CTRL_DGRAM_GET_FALLBACK_MTU 47
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.
OPENSSL_EXPORT int BIO_new_bio_pair(BIO **out1, size_t writebuf1, BIO **out2, size_t writebuf2);
BIO_ctrl_get_read_request returns the number of bytes that the other side of bio tried (unsuccessfully) to read.
OPENSSL_EXPORT size_t BIO_ctrl_get_read_request(BIO *bio);
OPENSSL_EXPORT size_t BIO_ctrl_get_write_guarantee(BIO *bio);
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.
OPENSSL_EXPORT int BIO_shutdown_wr(BIO *bio);
BIO_NOCLOSE and BIO_CLOSE can be used as symbolic arguments when a "close flag" is passed to a BIO function.
#define BIO_NOCLOSE 0
#define BIO_CLOSE 1
These are passed to the BIO callback
#define BIO_CB_FREE 0x01
#define BIO_CB_READ 0x02
#define BIO_CB_WRITE 0x03
#define BIO_CB_PUTS 0x04
#define BIO_CB_GETS 0x05
#define BIO_CB_CTRL 0x06
The callback is called before and after the underling operation, The BIO_CB_RETURN flag indicates if it is after the call
#define BIO_CB_RETURN 0x80
These are values of the cmd argument to BIO_ctrl.
#define BIO_CTRL_RESET 1 // opt - rewind/zero etc
#define BIO_CTRL_EOF 2 // opt - are we at the eof
#define BIO_CTRL_INFO 3 // opt - extra tit-bits
#define BIO_CTRL_SET 4 // man - set the 'IO' type
#define BIO_CTRL_GET 5 // man - get the 'IO' type #define BIO_CTRL_PUSH 6 #define BIO_CTRL_POP 7
#define BIO_CTRL_GET_CLOSE 8 // man - set the 'close' on free
#define BIO_CTRL_SET_CLOSE 9 // man - set the 'close' on free
#define BIO_CTRL_PENDING 10 // opt - is their more data buffered
#define BIO_CTRL_FLUSH 11 // opt - 'flush' buffered output
#define BIO_CTRL_WPENDING 13 // opt - number of bytes still to write
callback is int cb(BIO *bio,state,ret);
#define BIO_CTRL_SET_CALLBACK 14 // opt - set callback function
#define BIO_CTRL_GET_CALLBACK 15 // opt - set callback function
#define BIO_CTRL_SET_FILENAME 30 // BIO_s_file special
BIO_CTRL_DUP is never used, but exists to allow code to compile more easily.
#define BIO_CTRL_DUP 12
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.
OPENSSL_EXPORT const BIO_METHOD *BIO_f_base64(void);
OPENSSL_EXPORT void BIO_set_retry_special(BIO *bio);
BIO_set_write_buffer_size returns zero.
OPENSSL_EXPORT int BIO_set_write_buffer_size(BIO *bio, int buffer_size);