.\" $OpenBSD: BIO_s_datagram.3,v 1.3 2023/04/28 16:49:00 schwarze Exp $
.\"
.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: April 28 2023 $
.Dt BIO_S_DATAGRAM 3
.Os
.Sh NAME
.Nm BIO_s_datagram ,
.Nm BIO_new_dgram ,
.Nm BIO_dgram_set_peer ,
.Nm BIO_ctrl_dgram_connect ,
.Nm BIO_dgram_get_peer ,
.Nm BIO_ctrl_set_connected ,
.Nm BIO_dgram_recv_timedout ,
.Nm BIO_dgram_send_timedout ,
.Nm BIO_dgram_non_fatal_error
.\" .Nm BIO_CTRL_DGRAM_QUERY_MTU and
.\" .Nm BIO_CTRL_DGRAM_MTU_DISCOVER are intentionally undocumented.
.\" They are almost unused, and OpenBSD does not appear to support them.
.Nd datagram socket BIO
.Sh SYNOPSIS
.In openssl/bio.h
.Ft const BIO_METHOD *
.Fn BIO_s_datagram void
.Ft BIO *
.Fo BIO_new_dgram
.Fa "int fd"
.Fa "int close_flag"
.Fc
.Ft int
.Fo BIO_dgram_set_peer
.Fa "BIO *b"
.Fa "struct sockaddr *sa"
.Fc
.Ft int
.Fo BIO_ctrl_dgram_connect
.Fa "BIO *b"
.Fa "struct sockaddr *sa"
.Fc
.Ft int
.Fo BIO_dgram_get_peer
.Fa "BIO *b"
.Fa "struct sockaddr *sa"
.Fc
.Ft int
.Fo BIO_ctrl_set_connected
.Fa "BIO *b"
.Fa "long argl"
.Fa "struct sockaddr *sa"
.Fc
.Ft int
.Fn BIO_dgram_recv_timedout "BIO *b"
.Ft int
.Fn BIO_dgram_send_timedout "BIO *b"
.Ft int
.Fn BIO_dgram_non_fatal_error "int errnum"
.Sh DESCRIPTION
.Fn BIO_s_datagram
returns the datagram socket BIO method.
The usual application is to transmit data using the IPv4 or IPv6
.Xr udp 4
protocol.
.Pp
When called on a datagram socket BIO object,
.Xr BIO_method_type 3
returns the constant
.Dv BIO_TYPE_DGRAM
and
.Xr BIO_method_name 3
returns a pointer to the static string
.Qq datagram socket .
.Ss Constructors and destructors
.Xr 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
.Xr 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.
.Pp
.Fn BIO_new_dgram
allocates and initializes a new datagram socket BIO object with
.Xr BIO_new 3 ,
sets the datagram socket file descriptor and the close flag
according to its arguments, and sets the init flag to 1.
.Pp
If the reference count reaches 0 in
.Xr BIO_free 3
and the close and init flags are set,
.Xr shutdown 2
and
.Xr close 2
are called on the datagram socket file descriptor before freeing the
storage used by the BIO object.
.Pp
When a chain containing a datagram socket BIO is copied with
.Xr BIO_dup_chain 3 ,
the datagram socket file descriptor, the init flag, the close flag,
the flags accessible with
.Xr BIO_test_flags 3 ,
and any data that was set with
.Xr 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.
.Ss Initialization and configuration
If the close flag is set in
.Fa b ,
.Xr BIO_set_fd 3
clears all flags that are set in
.Fa b
and if the init flag was set, it calls
.Xr shutdown 2
and
.Xr close 2
on the previously assigned file descriptor.
In any case,
.Xr 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.
.Pp
If the init flag is set in
.Fa b ,
.Xr BIO_get_fd 3
returns its datagram socket file descriptor, and unless the
.Fa c
argument is a
.Dv NULL
pointer, it also stores the file descriptor in
.Pf * Fa c .
If the init flag is not set,
.Xr BIO_get_fd 3
fails and returns \-1.
.Pp
.Xr BIO_set_close 3
sets the close flag in
.Fa b
to the
.Fa flag
argument.
.Xr BIO_get_close 3
returns the value of the close flag from
.Fa b .
.Pp
For datagram socket BIO objects,
the shutdown flag is the same flag as the close flag.
Consequently,
.Xr BIO_set_shutdown 3
has the same effect as
.Xr BIO_set_close 3
and
.Xr BIO_get_shutdown 3
has the same effect as
.Xr BIO_get_close 3 .
.Pp
.Fn BIO_dgram_set_peer
copies
.Fa sa
as the peer address into
.Fa b .
.Pp
.Fn BIO_ctrl_dgram_connect
does exactly the same as
.Fn BIO_dgram_set_peer .
Its name is even more misleading than the name of
.Fn BIO_ctrl_set_connected .
In addition to what is said there,
.Fn BIO_ctrl_dgram_connect
does not even set the connected flag in
.Fa b .
.Pp
.Fn BIO_dgram_get_peer
copies the peer address from
.Fa b
to
.Pf * Fa sa .
Before calling this function, the caller has to make sure
that the peer address is indeed set in
.Fa b
and that sufficient memory is available starting at
.Fa sa
to copy a complete
.Vt struct sockaddr ,
.Vt struct sockaddr_in ,
or
.Vt struct sockaddr_in6
to that place, depending on which address family
.Fa b
is currently used for.
.Pp
Unless
.Fa sa
is
.Dv NULL ,
.Fn BIO_ctrl_set_connected
sets the connected flag in
.Fa b
and copies
.Fa sa
as the peer address into
.Fa b .
If
.Fa sa
is
.Dv NULL ,
.Fn BIO_ctrl_set_connected
clears the connected flag and the peer address in
.Fa 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
.Fa argl
argument is passed through to the callbacks documented in
.Xr BIO_set_callback 3
if any such callbacks are installed, but it is otherwise ignored.
.Pp
.Xr BIO_ctrl 3
with a
.Fa cmd
of
.Dv BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT
interprets the
.Fa parg
argument as a pointer to a
.Vt struct timeval
and sets the read timeout to the specified absolute UTC time.
.Pp
.Xr BIO_ctrl 3
with a
.Fa cmd
of
.Dv BIO_CTRL_DGRAM_SET_RECV_TIMEOUT ,
.Dv BIO_CTRL_DGRAM_GET_RECV_TIMEOUT ,
.Dv BIO_CTRL_DGRAM_SET_SEND_TIMEOUT ,
or
.Dv BIO_CTRL_DGRAM_GET_SEND_TIMEOUT
interprets the
.Fa parg
argument as a pointer to a
.Vt struct timeval
and calls
.Xr setsockopt 2
or
.Xr getsockopt 2
on the datagram socket file descriptor of
.Fa b
with an argument of
.Dv SO_RCVTIMEO
or
.Dv SO_SNDTIMEO ,
respectively.
.Dv BIO_CTRL_DGRAM_SET_RECV_TIMEOUT
and
.Dv BIO_CTRL_DGRAM_SET_SEND_TIMEOUT
return 1 on success,
.Dv BIO_CTRL_DGRAM_GET_RECV_TIMEOUT
and
.Dv BIO_CTRL_DGRAM_GET_SEND_TIMEOUT
the number of bytes written to
.Pf * Fa parg .
All four return \-1 on failure.
Remember that
.Xr BIO_read 3
may actually use a shorter timeout when
.Dv BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT
is in effect.
.Pp
.Xr BIO_ctrl 3
with a
.Fa cmd
of
.Dv 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.
.Pp
.Xr BIO_ctrl 3
with a
.Fa cmd
of
.Dv BIO_CTRL_DGRAM_SET_MTU
sets the MTU attribute of
.Fa b
to the value of the
.Fa larg
argument and also returns that argument.
.Xr BIO_ctrl 3
with a
.Fa cmd
of
.Dv BIO_CTRL_DGRAM_GET_MTU
returns the MTU attribute of
.Fa b
or 0 if it was not set.
.Pp
.Xr BIO_ctrl 3
with a
.Fa cmd
of
.Dv BIO_CTRL_DGRAM_MTU_EXCEEDED
returns 1 if the most recent non-fatal failure of
.Xr BIO_read 3
or
.Xr BIO_write 3
was caused by
.Er EMSGSIZE
or 0 otherwise.
This command also clears the
.Xr errno 2
value that was saved internally for this particular purpose, so that
issuing the same command again will return 0 until the next
.Er EMSGSIZE
failure occurs.
.Pp
.Fn BIO_dgram_recv_timedout
and
.Fn BIO_dgram_send_timedout
check whether the most recent non-fatal failure of
.Xr BIO_read 3
or
.Xr BIO_write 3
was caused by
.Er 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
.Xr errno 2
value that was saved internally for this particular purpose,
so that calling these functions again will return 0 until the next
.Er EAGAIN
failure occurs.
.Pp
Datagram socket BIOs do not support
.Xr BIO_eof 3 ,
.Xr BIO_get_mem_data 3 ,
.Xr BIO_pending 3 ,
.Xr BIO_reset 3 ,
.Xr BIO_seek 3 ,
.Xr BIO_tell 3 ,
and
.Xr BIO_wpending 3 ,
and attempting any such operation results in failure
and returns a value of 0.
.Pp
Control commands correspond to accessor functions as follows:
.Pp
.Bl -tag -width BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP -compact
.It Dv BIO_C_GET_FD
.Xr BIO_get_fd 3
.It Dv BIO_C_SET_FD
.Xr BIO_set_fd 3
.It Dv BIO_CTRL_DGRAM_CONNECT
.Fn BIO_ctrl_dgram_connect Pq deprecated
.It Dv BIO_CTRL_DGRAM_GET_PEER
.Fn BIO_dgram_get_peer
.It BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP
.Fn BIO_dgram_recv_timedout
.It BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP
.Fn BIO_dgram_send_timedout
.It Dv BIO_CTRL_DGRAM_SET_CONNECTED
.Fn BIO_ctrl_set_connected
.It Dv BIO_CTRL_DGRAM_SET_PEER
.Fn BIO_dgram_set_peer
.It Dv BIO_CTRL_GET_CLOSE
.Xr BIO_get_close 3
.It Dv BIO_CTRL_SET_CLOSE
.Xr BIO_set_close 3
.El
.Ss Input and output operations
.Xr BIO_read 3
attempts to read up to
.Fa len
bytes into
.Fa buf
from the datagram socket file descriptor using
.Xr recvfrom 2 .
If a read timeout is set,
.Xr setsockopt 2
is used with an argument of
.Dv SO_RCVTIMEO
to temporarily shorten the timeout on the datagram socket during the
.Xr recvfrom 2
call such that it returns before the read timeout expires.
.Pp
If
.Xr recvfrom 2
succeeds and the connected flag is not yet set,
.Xr BIO_read 3
also copies the peer address received from
.Xr recvfrom 2
into
.Fa b .
.Pp
If
.Xr recvfrom 2
is attempted,
.Xr BIO_read 3
clears the flags
.Dv BIO_FLAGS_WRITE
and
.Dv BIO_FLAGS_IO_SPECIAL
in
.Fa b
and clears or sets the flags
.Dv BIO_FLAGS_READ
and
.Dv BIO_FLAGS_SHOULD_RETRY
as appropriate.
.Pp
If the connected flag is set in
.Fa b ,
.Xr BIO_write 3
attempts to
.Xr write 2
.Fa len
bytes from
.Fa buf
to the datagram socket file descriptor.
If the connected flag is not set, it attempts to transmit
.Fa len
bytes from
.Fa buf
to the peer using
.Xr sendto 2 .
.Pp
If
.Xr write 2
or
.Xr sendto 2
is attempted,
.Xr BIO_write 3
clears the flags
.Dv BIO_FLAGS_READ
and
.Dv BIO_FLAGS_IO_SPECIAL
in
.Fa b
and clears or sets the flags
.Dv BIO_FLAGS_WRITE
and
.Dv BIO_FLAGS_SHOULD_RETRY
as appropriate.
.Pp
The effect of
.Xr BIO_puts 3
is similar to the effect of
.Xr BIO_write 3
with a
.Fa len
argument of
.Fn strlen string .
.Pp
Datagram socket BIOs do not support
.Xr BIO_gets 3 .
Calling this function fails and returns \-2.
.Pp
.Xr BIO_flush 3
has no effect on a datagram socket BIO.
It always succeeds and returns 1.
.Sh RETURN VALUES
.Fn BIO_s_datagram
returns the datagram socket BIO method.
.Pp
.Fn BIO_new_dgram
returns a newly allocated datagram socket BIO object or
.Dv NULL
on failure.
.Pp
.Fn BIO_dgram_set_peer ,
.Fn BIO_ctrl_dgram_connect ,
and
.Fn BIO_ctrl_set_connected
return 1 on success or a value less than or equal to zero on failure.
They can only fail if
.Fa b
is not a datagram socket BIO object.
.Pp
.Fn BIO_dgram_get_peer
returns the number of bytes copied to
.Fa sa
or a value less than or equal to zero on failure.
It can only fail if
.Fa b
is not a datagram socket BIO object.
.Pp
.Fn BIO_dgram_recv_timedout
and
.Fn BIO_dgram_send_timedout
return 1 if the most recent non-fatal I/O error was caused by
.Er EAGAIN
or 0 otherwise.
.Pp
.Fn BIO_dgram_non_fatal_error
returns 1 if
.Fa errnum
is
.Er EAGAIN ,
.Er EALREADY ,
.Er EINPROGRESS ,
or
.Er EINTR
or 0 otherwise, even if
.Fa errnum
is 0.
.Sh SEE ALSO
.Xr close 2 ,
.Xr getsockopt 2 ,
.Xr recvfrom 2 ,
.Xr sendto 2 ,
.Xr shutdown 2 ,
.Xr BIO_ctrl 3 ,
.Xr BIO_get_init 3 ,
.Xr BIO_new 3 ,
.Xr BIO_read 3 ,
.Xr BIO_s_connect 3 ,
.Xr BIO_set_fd 3 ,
.Xr BIO_should_retry 3 ,
.Xr udp 4
.Sh HISTORY
.Fn BIO_s_datagram ,
.Fn BIO_new_dgram ,
.Fn BIO_dgram_set_peer ,
.Fn BIO_ctrl_dgram_connect ,
.Fn BIO_ctrl_set_connected ,
.Fn BIO_dgram_recv_timedout ,
.Fn BIO_dgram_send_timedout ,
and
.Fn BIO_dgram_non_fatal_error
first appeared in OpenSSL 0.9.8 and have been available since
.Ox 4.5 .
.Pp
.Fn BIO_dgram_get_peer
first appeared in OpenSSL 0.9.8m and has been available since
.Ox 4.9 .
.Sh BUGS
If
.Xr getsockopt 2
or
.Xr setsockopt 2
fails during
.Xr BIO_read 3 ,
the library prints an error message to standard error output
but otherwise ignores the problem, thus possibly using unintended
timeout values.
.Pp
.Xr BIO_read 3
and
.Xr BIO_write 3
may clear the global variable
.Xr errno 2
before attempting the
.Xr recvfrom 2
or
.Xr sendto 2
system call but may not clear it if they fail before reaching this point.