--- name: "libressl-BIO_s_datagram" section: "3" platform: "linux" package: "libressl" version: "4.4.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libressl-BIO_s_datagram" --- # libressl-BIO\_s\_datagram(3) datagram socket BIO ## NAME **BIO\_s\_datagram**, **BIO\_new\_dgram**, **BIO\_dgram\_set\_peer**, **BIO\_ctrl\_dgram\_connect**, **BIO\_dgram\_get\_peer**, **BIO\_ctrl\_set\_connected**, **BIO\_dgram\_recv\_timedout**, **BIO\_dgram\_send\_timedout**, **BIO\_dgram\_non\_fatal\_error** – datagram socket BIO ## SYNOPSIS Crypto Library (libcrypto, -lcrypto) **#include \** *const* *BIO\_METHOD* *\**\ **BIO\_s\_datagram**(*void*); *BIO* *\**\ **BIO\_new\_dgram**(*int fd*, *int close\_flag*); *int*\ **BIO\_dgram\_set\_peer**(*BIO \*b*, *struct sockaddr \*sa*); *int*\ **BIO\_ctrl\_dgram\_connect**(*BIO \*b*, *struct sockaddr \*sa*); *int*\ **BIO\_dgram\_get\_peer**(*BIO \*b*, *struct sockaddr \*sa*); *int*\ **BIO\_ctrl\_set\_connected**(*BIO \*b*, *long argl*, *struct sockaddr \*sa*); *int*\ **BIO\_dgram\_recv\_timedout**(*BIO \*b*); *int*\ **BIO\_dgram\_send\_timedout**(*BIO \*b*); *int*\ **BIO\_dgram\_non\_fatal\_error**(*int errnum*); ## DESCRIPTION **BIO\_s\_datagram**() returns the datagram socket BIO method. The usual application is to transmit data using the IPv4 or IPv6 [udp(4)](/udp/4.md) protocol. When called on a datagram socket BIO object, BIO\_method\_type(3) returns the constant BIO\_TYPE\_DGRAM and BIO\_method\_name(3) returns a pointer to the static string "datagram socket". ### 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)](/shutdown/2.md) and [close(2)](/close/2.md) 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)](/shutdown/2.md) and [close(2)](/close/2.md) 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)](/setsockopt/2.md) or [getsockopt(2)](/getsockopt/2.md) 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)](/errno/2.md) 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)](/errno/2.md) 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**(*Pq*, *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)](/recvfrom/2.md). If a read timeout is set, [setsockopt(2)](/setsockopt/2.md) is used with an argument of SO\_RCVTIMEO to temporarily shorten the timeout on the datagram socket during the [recvfrom(2)](/recvfrom/2.md) call such that it returns before the read timeout expires. If [recvfrom(2)](/recvfrom/2.md) succeeds and the connected flag is not yet set, BIO\_read(3) also copies the peer address received from [recvfrom(2)](/recvfrom/2.md) into *b*. If [recvfrom(2)](/recvfrom/2.md) 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)](/write/2.md) *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)](/sendto/2.md). If [write(2)](/write/2.md) or [sendto(2)](/sendto/2.md) 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. ## RETURN VALUES **BIO\_s\_datagram**() returns the datagram socket BIO method. **BIO\_new\_dgram**() returns a newly allocated datagram socket BIO object or NULL on failure. **BIO\_dgram\_set\_peer**(), **BIO\_ctrl\_dgram\_connect**(), and **BIO\_ctrl\_set\_connected**() return 1 on success or a value less than or equal to zero on failure. They can only fail if *b* is not a datagram socket BIO object. **BIO\_dgram\_get\_peer**() returns the number of bytes copied to *sa* or a value less than or equal to zero on failure. It can only fail if *b* is not a datagram socket BIO object. **BIO\_dgram\_recv\_timedout**() and **BIO\_dgram\_send\_timedout**() return 1 if the most recent non-fatal I/O error was caused by EAGAIN or 0 otherwise. **BIO\_dgram\_non\_fatal\_error**() returns 1 if *errnum* is EAGAIN, EALREADY, EINPROGRESS, or EINTR or 0 otherwise, even if *errnum* is 0. ## SEE ALSO [close(2)](/close/2.md), [getsockopt(2)](/getsockopt/2.md), [recvfrom(2)](/recvfrom/2.md), [sendto(2)](/sendto/2.md), [shutdown(2)](/shutdown/2.md), BIO\_ctrl(3), BIO\_get\_init(3), BIO\_new(3), BIO\_read(3), BIO\_s\_connect(3), BIO\_set\_fd(3), BIO\_should\_retry(3), [udp(4)](/udp/4.md) ## HISTORY **BIO\_s\_datagram**(), **BIO\_new\_dgram**(), **BIO\_dgram\_set\_peer**(), **BIO\_ctrl\_dgram\_connect**(), **BIO\_ctrl\_set\_connected**(), **BIO\_dgram\_recv\_timedout**(), **BIO\_dgram\_send\_timedout**(), and **BIO\_dgram\_non\_fatal\_error**() first appeared in OpenSSL 0.9.8 and have been available since OpenBSD 4.5. **BIO\_dgram\_get\_peer**() first appeared in OpenSSL 0.9.8m and has been available since OpenBSD 4.9. ## BUGS If [getsockopt(2)](/getsockopt/2.md) or [setsockopt(2)](/setsockopt/2.md) fails during BIO\_read(3), the library prints an error message to standard error output but otherwise ignores the problem, thus possibly using unintended timeout values. BIO\_read(3) and BIO\_write(3) may clear the global variable [errno(2)](/errno/2.md) before attempting the [recvfrom(2)](/recvfrom/2.md) or [sendto(2)](/sendto/2.md) system call but may not clear it if they fail before reaching this point.