Constructors and destructors

BIO_new(3) allocates a new datagram socket BIO object and initializes all its data to zero, including the datagram socket file descriptor, the peer address, the init flag that can be retrieved with BIO_get_init(3), the connected flag, the MTU, and all timeout and error information. The reference count and the close flag are set to 1.

BIO_new_dgram() allocates and initializes a new datagram socket BIO object with BIO_new(3), sets the datagram socket file descriptor and the close flag according to its arguments, and sets the init flag to 1.

If the reference count reaches 0 in BIO_free(3) and the close and init flags are set, shutdown(2) and close(2) are called on the datagram socket file descriptor before freeing the storage used by the BIO object.

When a chain containing a datagram socket BIO is copied with BIO_dup_chain(3), the datagram socket file descriptor, the init flag, the close flag, the flags accessible with BIO_test_flags(3), and any data that was set with BIO_set_ex_data(3) are automatically copied from the original BIO object to the new one, but the peer address, the connected flag, the MTU and all timeout and error information are not copied but instead initialized to zero.

Initialization and configuration

If the close flag is set in b, BIO_set_fd(3) clears all flags that are set in b and if the init flag was set, it calls shutdown(2) and close(2) on the previously assigned file descriptor. In any case, BIO_set_fd(3) then sets the new file descriptor and the new close flag according to its arguments and sets the init flag to 1.

If the init flag is set in b, BIO_get_fd(3) returns its datagram socket file descriptor, and unless the c argument is a NULL pointer, it also stores the file descriptor in *c. If the init flag is not set, BIO_get_fd(3) fails and returns -1.

BIO_set_close(3) sets the close flag in b to the flag argument. BIO_get_close(3) returns the value of the close flag from b.

For datagram socket BIO objects, the shutdown flag is the same flag as the close flag. Consequently, BIO_set_shutdown(3) has the same effect as BIO_set_close(3) and BIO_get_shutdown(3) has the same effect as BIO_get_close(3).

BIO_dgram_set_peer() copies sa as the peer address into b.

BIO_ctrl_dgram_connect() does exactly the same as BIO_dgram_set_peer(). Its name is even more misleading than the name of BIO_ctrl_set_connected(). In addition to what is said there, BIO_ctrl_dgram_connect() does not even set the connected flag in b.

BIO_dgram_get_peer() copies the peer address from b to *sa. Before calling this function, the caller has to make sure that the peer address is indeed set in b and that sufficient memory is available starting at sa to copy a complete struct sockaddr, struct sockaddr_in, or struct sockaddr_in6 to that place, depending on which address family b is currently used for.

Unless sa is NULL, BIO_ctrl_set_connected() sets the connected flag in b and copies sa as the peer address into b. If sa is NULL, BIO_ctrl_set_connected() clears the connected flag and the peer address in b. Considering that communication using a datagram protocol is connectionless, the name of this function is misleading. It is neither establishing or terminating a connection nor changing anything with respect to the state of the datagram socket, but merely modifying some purely informational data in the wrapping BIO object. The additional argl argument is passed through to the callbacks documented in BIO_set_callback(3) if any such callbacks are installed, but it is otherwise ignored.

BIO_ctrl(3) with a cmd of BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT interprets the parg argument as a pointer to a struct timeval and sets the read timeout to the specified absolute UTC time.

BIO_ctrl(3) with a cmd of BIO_CTRL_DGRAM_SET_RECV_TIMEOUT, BIO_CTRL_DGRAM_GET_RECV_TIMEOUT, BIO_CTRL_DGRAM_SET_SEND_TIMEOUT, or BIO_CTRL_DGRAM_GET_SEND_TIMEOUT interprets the parg argument as a pointer to a struct timeval and calls setsockopt(2) or getsockopt(2) on the datagram socket file descriptor of b with an argument of SO_RCVTIMEO or SO_SNDTIMEO, respectively. BIO_CTRL_DGRAM_SET_RECV_TIMEOUT and BIO_CTRL_DGRAM_SET_SEND_TIMEOUT return 1 on success, BIO_CTRL_DGRAM_GET_RECV_TIMEOUT and BIO_CTRL_DGRAM_GET_SEND_TIMEOUT the number of bytes written to *parg. All four return -1 on failure. Remember that BIO_read(3) may actually use a shorter timeout when BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT is in effect.

BIO_ctrl(3) with a cmd of BIO_CTRL_DGRAM_GET_FALLBACK_MTU returns 1232 if the peer address is an IPv6 address that is not IPv4 mapped or 548 otherwise. Making sure that a peer address is set before issuing this command is the responsibility of the caller.

BIO_ctrl(3) with a cmd of BIO_CTRL_DGRAM_SET_MTU sets the MTU attribute of b to the value of the larg argument and also returns that argument. BIO_ctrl(3) with a cmd of BIO_CTRL_DGRAM_GET_MTU returns the MTU attribute of b or 0 if it was not set.

BIO_ctrl(3) with a cmd of BIO_CTRL_DGRAM_MTU_EXCEEDED returns 1 if the most recent non-fatal failure of BIO_read(3) or BIO_write(3) was caused by EMSGSIZE or 0 otherwise. This command also clears the errno(2) value that was saved internally for this particular purpose, so that issuing the same command again will return 0 until the next EMSGSIZE failure occurs.

BIO_dgram_recv_timedout() and BIO_dgram_send_timedout() check whether the most recent non-fatal failure of BIO_read(3) or BIO_write(3) was caused by EAGAIN. Despite having different names, both functions do exactly the same, and both inspect the most recent non-fatal I/O failure, no matter whether it occurred during a receive or send operation. Both functions also clear the errno(2) value that was saved internally for this particular purpose, so that calling these functions again will return 0 until the next EAGAIN failure occurs.

Datagram socket BIOs do not support BIO_eof(3), BIO_get_mem_data(3), BIO_pending(3), BIO_reset(3), BIO_seek(3), BIO_tell(3), and BIO_wpending(3), and attempting any such operation results in failure and returns a value of 0.

Control commands correspond to accessor functions as follows:

BIO_C_GET_FD

BIO_get_fd(3)

BIO_C_SET_FD

BIO_set_fd(3)

BIO_CTRL_DGRAM_CONNECT

BIO_ctrl_dgram_connect() (deprecated)

BIO_CTRL_DGRAM_GET_PEER

BIO_dgram_get_peer()

BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP

BIO_dgram_recv_timedout()

BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP

BIO_dgram_send_timedout()

BIO_CTRL_DGRAM_SET_CONNECTED

BIO_ctrl_set_connected()

BIO_CTRL_DGRAM_SET_PEER

BIO_dgram_set_peer()

BIO_CTRL_GET_CLOSE

BIO_get_close(3)

BIO_CTRL_SET_CLOSE

BIO_set_close(3)

Input and output operations

BIO_read(3) attempts to read up to len bytes into buf from the datagram socket file descriptor using recvfrom(2). If a read timeout is set, setsockopt(2) is used with an argument of SO_RCVTIMEO to temporarily shorten the timeout on the datagram socket during the recvfrom(2) call such that it returns before the read timeout expires.

If recvfrom(2) succeeds and the connected flag is not yet set, BIO_read(3) also copies the peer address received from recvfrom(2) into b.

If recvfrom(2) is attempted, BIO_read(3) clears the flags BIO_FLAGS_WRITE and BIO_FLAGS_IO_SPECIAL in b and clears or sets the flags BIO_FLAGS_READ and BIO_FLAGS_SHOULD_RETRY as appropriate.

If the connected flag is set in b, BIO_write(3) attempts to write(2) len bytes from buf to the datagram socket file descriptor. If the connected flag is not set, it attempts to transmit len bytes from buf to the peer using sendto(2).

If write(2) or sendto(2) is attempted, BIO_write(3) clears the flags BIO_FLAGS_READ and BIO_FLAGS_IO_SPECIAL in b and clears or sets the flags BIO_FLAGS_WRITE and BIO_FLAGS_SHOULD_RETRY as appropriate.

The effect of BIO_puts(3) is similar to the effect of BIO_write(3) with a len argument of strlen(string).

Datagram socket BIOs do not support BIO_gets(3). Calling this function fails and returns -2.

BIO_flush(3) has no effect on a datagram socket BIO. It always succeeds and returns 1.