.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "BIO_S_DATAGRAM 3SSL" .TH BIO_S_DATAGRAM 3SSL "2023-10-23" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" BIO_s_datagram, BIO_new_dgram, BIO_ctrl_dgram_connect, BIO_ctrl_set_connected, BIO_dgram_recv_timedout, BIO_dgram_send_timedout, BIO_dgram_get_peer, BIO_dgram_set_peer, BIO_dgram_get_mtu_overhead \- Network BIO with datagram semantics .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& BIO_METHOD *BIO_s_datagram(void); \& BIO *BIO_new_dgram(int fd, int close_flag); \& \& int BIO_ctrl_dgram_connect(BIO *bio, const BIO_ADDR *peer); \& int BIO_ctrl_set_connected(BIO *bio, const BIO_ADDR *peer); \& int BIO_dgram_recv_timedout(BIO *bio); \& int BIO_dgram_send_timedout(BIO *bio); \& int BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer); \& int BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer); \& int BIO_dgram_get_mtu_overhead(BIO *bio); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBBIO_s_datagram()\fR is a \s-1BIO\s0 implementation designed for use with network sockets which provide datagram semantics, such as \s-1UDP\s0 sockets. It is suitable for use with DTLSv1. .PP Because \fBBIO_s_datagram()\fR has datagram semantics, a single \fBBIO_write()\fR call sends a single datagram and a single \fBBIO_read()\fR call receives a single datagram. If the size of the buffer passed to \fBBIO_read()\fR is inadequate, the datagram is silently truncated. .PP When using \fBBIO_s_datagram()\fR, it is important to note that: .IP "\(bu" 4 This \s-1BIO\s0 can be used with either a connected or unconnected network socket. A connected socket is a network socket which has had \fBBIO_connect\fR\|(3) or a similar OS-specific function called on it. Such a socket can only receive datagrams from the specified peer. Any other socket is an unconnected socket and can receive datagrams from any host. .IP "\(bu" 4 Despite their naming, neither \fBBIO_ctrl_dgram_connect()\fR nor \fBBIO_ctrl_set_connected()\fR cause a socket to become connected. These controls are provided to indicate to the \s-1BIO\s0 how the underlying socket is configured and how it is to be used; see below. .IP "\(bu" 4 Use of \fBBIO_s_datagram()\fR with an unconnected network socket is hazardous hecause any successful call to \fBBIO_read()\fR results in the peer address used for any subsequent call to \fBBIO_write()\fR being set to the source address of the datagram received by that call to \fBBIO_read()\fR. Thus, unless the caller calls \&\fBBIO_dgram_set_peer()\fR immediately prior to every call to \fBBIO_write()\fR, or never calls \fBBIO_read()\fR, any host on the network may cause future datagrams written to be redirected to that host. Therefore, it is recommended that users use \&\fBBIO_s_dgram()\fR only with a connected socket. An exception is where \&\fBDTLSv1_listen\fR\|(3) must be used; see \fBDTLSv1_listen\fR\|(3) for further discussion. .PP Various controls are available for configuring the \fBBIO_s_datagram()\fR using \&\fBBIO_ctrl\fR\|(3): .IP "BIO_ctrl_dgram_connect (\s-1BIO_CTRL_DGRAM_CONNECT\s0)" 4 .IX Item "BIO_ctrl_dgram_connect (BIO_CTRL_DGRAM_CONNECT)" This is equivalent to calling \fBBIO_dgram_set_peer\fR\|(3). .Sp Despite its name, this function does not cause the underlying socket to become connected. .IP "BIO_ctrl_set_connected (\s-1BIO_CTRL_SET_CONNECTED\s0)" 4 .IX Item "BIO_ctrl_set_connected (BIO_CTRL_SET_CONNECTED)" This informs the \fBBIO_s_datagram()\fR whether the underlying socket has been connected, and therefore how the \fBBIO_s_datagram()\fR should attempt to use the socket. .Sp If the \fIpeer\fR argument is non-NULL, \fBBIO_s_datagram()\fR assumes that the underlying socket has been connected and will attempt to use the socket using \s-1OS\s0 APIs which do not specify peer addresses (for example, \fBsend\fR\|(3) and \fBrecv\fR\|(3) or similar). The \fIpeer\fR argument should specify the peer address to which the socket is connected. .Sp If the \fIpeer\fR argument is \s-1NULL,\s0 \fBBIO_s_datagram()\fR assumes that the underlying socket is not connected and will attempt to use the socket using an \s-1OS\s0 APIs which specify peer addresses (for example, \fBsendto\fR\|(3) and \fBrecvfrom\fR\|(3)). .IP "BIO_dgram_get_peer (\s-1BIO_CTRL_DGRAM_GET_PEER\s0)" 4 .IX Item "BIO_dgram_get_peer (BIO_CTRL_DGRAM_GET_PEER)" This outputs a \fB\s-1BIO_ADDR\s0\fR which specifies one of the following values, whichever happened most recently: .RS 4 .IP "\(bu" 4 The peer address last passed to \fBBIO_dgram_set_peer()\fR, \fBBIO_ctrl_dgram_connect()\fR or \fBBIO_ctrl_set_connected()\fR. .IP "\(bu" 4 The peer address of the datagram last received by a call to \fBBIO_read()\fR. .RE .RS 4 .RE .IP "BIO_dgram_set_peer (\s-1BIO_CTRL_DGRAM_SET_PEER\s0)" 4 .IX Item "BIO_dgram_set_peer (BIO_CTRL_DGRAM_SET_PEER)" Sets the peer address to be used for subsequent writes to this \s-1BIO.\s0 .Sp Warning: When used with an unconnected network socket, the value set may be modified by future calls to \fBBIO_read\fR\|(3), making use of \fBBIO_s_datagram()\fR hazardous when used with unconnected network sockets; see above. .IP "BIO_dgram_recv_timeout (\s-1BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP\s0)" 4 .IX Item "BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP)" Returns 1 if the last I/O operation performed on the \s-1BIO\s0 (for example, via a call to \fBBIO_read\fR\|(3)) may have been caused by a receive timeout. .IP "BIO_dgram_send_timedout (\s-1BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP\s0)" 4 .IX Item "BIO_dgram_send_timedout (BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP)" Returns 1 if the last I/O operation performed on the \s-1BIO\s0 (for example, via a call to \fBBIO_write\fR\|(3)) may have been caused by a send timeout. .IP "BIO_dgram_get_mtu_overhead (\s-1BIO_CTRL_DGRAM_GET_MTU_OVERHEAD\s0)" 4 .IX Item "BIO_dgram_get_mtu_overhead (BIO_CTRL_DGRAM_GET_MTU_OVERHEAD)" Returns a quantity in bytes which is a rough estimate of the number of bytes of overhead which should typically be added to a datagram payload size in order to estimate the final size of the Layer 3 (e.g. \s-1IP\s0) packet which will contain the datagram. In most cases, the maximum datagram payload size which can be transmitted can be determined by determining the link \s-1MTU\s0 in bytes and subtracting the value returned by this call. .Sp The value returned by this call depends on the network layer protocol being used. .Sp The value returned is not fully reliable because datagram overheads can be higher in atypical network configurations, for example where IPv6 extension headers or IPv4 options are used. .IP "\s-1BIO_CTRL_DGRAM_SET_DONT_FRAG\s0" 4 .IX Item "BIO_CTRL_DGRAM_SET_DONT_FRAG" If \fInum\fR is nonzero, configures the underlying network socket to enable Don't Fragment mode, in which datagrams will be set with the \s-1IP\s0 Don't Fragment (\s-1DF\s0) bit set. If \fInum\fR is zero, Don't Fragment mode is disabled. .IP "\s-1BIO_CTRL_DGRAM_QUERY_MTU\s0" 4 .IX Item "BIO_CTRL_DGRAM_QUERY_MTU" Queries the \s-1OS\s0 for its assessment of the Path \s-1MTU\s0 for the destination to which the underlying network socket, and returns that Path \s-1MTU\s0 in bytes. This control can only be used with a connected socket. .Sp This is not supported on all platforms and depends on \s-1OS\s0 support being available. Returns 0 on failure. .IP "\s-1BIO_CTRL_DGRAM_MTU_DISCOVER\s0" 4 .IX Item "BIO_CTRL_DGRAM_MTU_DISCOVER" This control requests that Path \s-1MTU\s0 discovery be enabled on the underlying network socket. .IP "\s-1BIO_CTRL_DGRAM_GET_FALLBACK_MTU\s0" 4 .IX Item "BIO_CTRL_DGRAM_GET_FALLBACK_MTU" Returns the estimated minimum size of datagram payload which should always be supported on the \s-1BIO.\s0 This size is determined by the minimum \s-1MTU\s0 required to be supported by the applicable underlying network layer. Use of datagrams of this size may lead to suboptimal performance, but should be routable in all circumstances. The value returned is the datagram payload size in bytes and does not include the size of layer 3 or layer 4 protocol headers. .IP "\s-1BIO_CTRL_DGRAM_MTU_EXCEEDED\s0" 4 .IX Item "BIO_CTRL_DGRAM_MTU_EXCEEDED" Returns 1 if the last attempted write to the \s-1BIO\s0 failed due to the size of the attempted write exceeding the applicable \s-1MTU.\s0 .IP "\s-1BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT\s0" 4 .IX Item "BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT" Accepts a pointer to a \fBstruct timeval\fR. If the time specified is zero, disables receive timeouts. Otherwise, configures the specified time interval as the receive timeout for the socket for the purposes of future \fBBIO_read\fR\|(3) calls. .IP "\s-1BIO_CTRL_DGRAM_SET_PEEK_MODE\s0" 4 .IX Item "BIO_CTRL_DGRAM_SET_PEEK_MODE" If \fBnum\fR is nonzero, enables peek mode; otherwise, disables peek mode. Where peek mode is enabled, calls to \fBBIO_read\fR\|(3) read datagrams from the underlying network socket in peek mode, meaning that a future call to \fBBIO_read\fR\|(3) will yield the same datagram until peek mode is disabled. .PP \&\fBBIO_new_dgram()\fR is a helper function which instantiates a \fBBIO_s_datagram()\fR and sets the \s-1BIO\s0 to use the socket given in \fIfd\fR by calling \fBBIO_set_fd()\fR. .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fBBIO_s_datagram()\fR returns a \s-1BIO\s0 method. .PP \&\fBBIO_new_dgram()\fR returns a \s-1BIO\s0 on success and \s-1NULL\s0 on failure. .PP \&\fBBIO_ctrl_dgram_connect()\fR, \fBBIO_ctrl_set_connected()\fR, \&\fBBIO_dgram_get_peer()\fR, \fBBIO_dgram_set_peer()\fR return 1 on success and 0 on failure. .PP \&\fBBIO_dgram_recv_timedout()\fR and \fBBIO_dgram_send_timedout()\fR return 0 or 1 depending on the circumstance; see discussion above. .PP \&\fBBIO_dgram_get_mtu_overhead()\fR returns a value in bytes. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBDTLSv1_listen\fR\|(3), \fBbio\fR\|(7) .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2022\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at .