| 1 |
.\" Copyright 1999, Andi Kleen <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-1-para |
| 5 |
.\" |
| 6 |
.TH udp 7 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
udp \- User Datagram Protocol for IPv4 |
| 9 |
.SH SYNOPSIS |
| 10 |
.nf |
| 11 |
.B #include <sys/socket.h> |
| 12 |
.B #include <netinet/in.h> |
| 13 |
.B #include <netinet/udp.h> |
| 14 |
.P |
| 15 |
.IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);" |
| 16 |
.fi |
| 17 |
.SH DESCRIPTION |
| 18 |
This is an implementation of the User Datagram Protocol |
| 19 |
described in RFC\ 768. |
| 20 |
It implements a connectionless, unreliable datagram packet service. |
| 21 |
Packets may be reordered or duplicated before they arrive. |
| 22 |
UDP generates and checks checksums to catch transmission errors. |
| 23 |
.P |
| 24 |
When a UDP socket is created, |
| 25 |
its local and remote addresses are unspecified. |
| 26 |
Datagrams can be sent immediately using |
| 27 |
.BR sendto (2) |
| 28 |
or |
| 29 |
.BR sendmsg (2) |
| 30 |
with a valid destination address as an argument. |
| 31 |
When |
| 32 |
.BR connect (2) |
| 33 |
is called on the socket, the default destination address is set and |
| 34 |
datagrams can now be sent using |
| 35 |
.BR send (2) |
| 36 |
or |
| 37 |
.BR write (2) |
| 38 |
without specifying a destination address. |
| 39 |
It is still possible to send to other destinations by passing an |
| 40 |
address to |
| 41 |
.BR sendto (2) |
| 42 |
or |
| 43 |
.BR sendmsg (2). |
| 44 |
In order to receive packets, the socket can be bound to a local |
| 45 |
address first by using |
| 46 |
.BR bind (2). |
| 47 |
Otherwise, the socket layer will automatically assign |
| 48 |
a free local port out of the range defined by |
| 49 |
.I /proc/sys/net/ipv4/ip_local_port_range |
| 50 |
and bind the socket to |
| 51 |
.BR INADDR_ANY . |
| 52 |
.P |
| 53 |
All receive operations return only one packet. |
| 54 |
When the packet is smaller than the passed buffer, |
| 55 |
only that much data is returned; |
| 56 |
when it is bigger, |
| 57 |
the packet is truncated and the |
| 58 |
.B MSG_TRUNC |
| 59 |
flag is set. |
| 60 |
.B MSG_WAITALL |
| 61 |
is not supported. |
| 62 |
.P |
| 63 |
IP options may be sent or received using the socket options described in |
| 64 |
.BR ip (7). |
| 65 |
They are processed by the kernel only when the appropriate |
| 66 |
.I /proc |
| 67 |
parameter |
| 68 |
is enabled (but still passed to the user even when it is turned off). |
| 69 |
See |
| 70 |
.BR ip (7). |
| 71 |
.P |
| 72 |
When the |
| 73 |
.B MSG_DONTROUTE |
| 74 |
flag is set on sending, the destination address must refer to a local |
| 75 |
interface address and the packet is sent only to that interface. |
| 76 |
.P |
| 77 |
By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery. |
| 78 |
This means the kernel |
| 79 |
will keep track of the MTU to a specific target IP address and return |
| 80 |
.B EMSGSIZE |
| 81 |
when a UDP packet write exceeds it. |
| 82 |
When this happens, the application should decrease the packet size. |
| 83 |
Path MTU discovery can be also turned off using the |
| 84 |
.B IP_MTU_DISCOVER |
| 85 |
socket option or the |
| 86 |
.I /proc/sys/net/ipv4/ip_no_pmtu_disc |
| 87 |
file; |
| 88 |
see |
| 89 |
.BR ip (7) |
| 90 |
for details. |
| 91 |
When turned off, UDP will fragment outgoing UDP packets |
| 92 |
that exceed the interface MTU. |
| 93 |
However, disabling it is not recommended |
| 94 |
for performance and reliability reasons. |
| 95 |
.SS Address format |
| 96 |
UDP uses the IPv4 |
| 97 |
.I sockaddr_in |
| 98 |
address format described in |
| 99 |
.BR ip (7). |
| 100 |
.SS Error handling |
| 101 |
All fatal errors will be passed to the user as an error return even |
| 102 |
when the socket is not connected. |
| 103 |
This includes asynchronous errors |
| 104 |
received from the network. |
| 105 |
You may get an error for an earlier packet |
| 106 |
that was sent on the same socket. |
| 107 |
This behavior differs from many other BSD socket implementations |
| 108 |
which don't pass any errors unless the socket is connected. |
| 109 |
Linux's behavior is mandated by |
| 110 |
.BR RFC\ 1122 . |
| 111 |
.P |
| 112 |
For compatibility with legacy code, in Linux 2.0 and 2.2 |
| 113 |
it was possible to set the |
| 114 |
.B SO_BSDCOMPAT |
| 115 |
.B SOL_SOCKET |
| 116 |
option to receive remote errors only when the socket has been |
| 117 |
connected (except for |
| 118 |
.B EPROTO |
| 119 |
and |
| 120 |
.BR EMSGSIZE ). |
| 121 |
Locally generated errors are always passed. |
| 122 |
Support for this socket option was removed in later kernels; |
| 123 |
see |
| 124 |
.BR socket (7) |
| 125 |
for further information. |
| 126 |
.P |
| 127 |
When the |
| 128 |
.B IP_RECVERR |
| 129 |
option is enabled, all errors are stored in the socket error queue, |
| 130 |
and can be received by |
| 131 |
.BR recvmsg (2) |
| 132 |
with the |
| 133 |
.B MSG_ERRQUEUE |
| 134 |
flag set. |
| 135 |
.SS /proc interfaces |
| 136 |
System-wide UDP parameter settings can be accessed by files in the directory |
| 137 |
.IR /proc/sys/net/ipv4/ . |
| 138 |
.TP |
| 139 |
.IR udp_mem " (since Linux 2.6.25)" |
| 140 |
This is a vector of three integers governing the number |
| 141 |
of pages allowed for queueing by all UDP sockets. |
| 142 |
.RS |
| 143 |
.TP |
| 144 |
.I min |
| 145 |
Below this number of pages, UDP is not bothered about its |
| 146 |
memory appetite. |
| 147 |
When the amount of memory allocated by UDP exceeds |
| 148 |
this number, UDP starts to moderate memory usage. |
| 149 |
.TP |
| 150 |
.I pressure |
| 151 |
This value was introduced to follow the format of |
| 152 |
.I tcp_mem |
| 153 |
(see |
| 154 |
.BR tcp (7)). |
| 155 |
.TP |
| 156 |
.I max |
| 157 |
Number of pages allowed for queueing by all UDP sockets. |
| 158 |
.RE |
| 159 |
.IP |
| 160 |
Defaults values for these three items are |
| 161 |
calculated at boot time from the amount of available memory. |
| 162 |
.TP |
| 163 |
.IR udp_rmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" |
| 164 |
Minimal size, in bytes, of receive buffers used by UDP sockets in moderation. |
| 165 |
Each UDP socket is able to use the size for receiving data, |
| 166 |
even if total pages of UDP sockets exceed |
| 167 |
.I udp_mem |
| 168 |
pressure. |
| 169 |
.TP |
| 170 |
.IR udp_wmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" |
| 171 |
Minimal size, in bytes, of send buffer used by UDP sockets in moderation. |
| 172 |
Each UDP socket is able to use the size for sending data, |
| 173 |
even if total pages of UDP sockets exceed |
| 174 |
.I udp_mem |
| 175 |
pressure. |
| 176 |
.SS Socket options |
| 177 |
To set or get a UDP socket option, call |
| 178 |
.BR getsockopt (2) |
| 179 |
to read or |
| 180 |
.BR setsockopt (2) |
| 181 |
to write the option with the option level argument set to |
| 182 |
.BR IPPROTO_UDP . |
| 183 |
Unless otherwise noted, |
| 184 |
.I optval |
| 185 |
is a pointer to an |
| 186 |
.IR int . |
| 187 |
.P |
| 188 |
Following is a list of UDP-specific socket options. |
| 189 |
For details of some other socket options that are also applicable |
| 190 |
for UDP sockets, see |
| 191 |
.BR socket (7). |
| 192 |
.TP |
| 193 |
.BR UDP_CORK " (since Linux 2.5.44)" |
| 194 |
If this option is enabled, then all data output on this socket |
| 195 |
is accumulated into a single datagram that is transmitted when |
| 196 |
the option is disabled. |
| 197 |
This option should not be used in code intended to be |
| 198 |
portable. |
| 199 |
.\" FIXME document UDP_ENCAP (new in Linux 2.5.67) |
| 200 |
.\" From include/linux/udp.h: |
| 201 |
.\" UDP_ENCAP_ESPINUDP_NON_IKE draft-ietf-ipsec-nat-t-ike-00/01 |
| 202 |
.\" UDP_ENCAP_ESPINUDP draft-ietf-ipsec-udp-encaps-06 |
| 203 |
.\" UDP_ENCAP_L2TPINUDP rfc2661 |
| 204 |
.\" FIXME Document UDP_NO_CHECK6_TX and UDP_NO_CHECK6_RX, added in Linux 3.16 |
| 205 |
.TP |
| 206 |
.BR UDP_SEGMENT " (since Linux 4.18)" |
| 207 |
Enables UDP segmentation offload. |
| 208 |
Segmentation offload reduces |
| 209 |
.BR send (2) |
| 210 |
cost by transferring multiple datagrams worth of data |
| 211 |
as a single large packet through the kernel transmit path, |
| 212 |
even when that exceeds MTU. |
| 213 |
As late as possible, |
| 214 |
the large packet is split by segment size into a series of datagrams. |
| 215 |
This segmentation offload step is deferred to hardware if supported, |
| 216 |
else performed in software. |
| 217 |
This option takes a value in the range |
| 218 |
.RB [ 0 ,\~ USHRT_MAX ] |
| 219 |
that sets the segment size: |
| 220 |
the size of datagram payload, |
| 221 |
excluding the UDP header. |
| 222 |
The segment size must be chosen such that |
| 223 |
at most 64 datagrams are sent in a single call |
| 224 |
and that the datagrams after segmentation meet |
| 225 |
the same MTU rules that apply to datagrams sent without this option. |
| 226 |
Segmentation offload depends on checksum offload, |
| 227 |
as datagram checksums are computed after segmentation. |
| 228 |
The option may also be set for individual |
| 229 |
.BR sendmsg (2) |
| 230 |
calls by passing it as a |
| 231 |
.BR cmsg (3). |
| 232 |
A value of zero disables the feature. |
| 233 |
This option should not be used in code intended to be portable. |
| 234 |
.TP |
| 235 |
.BR UDP_GRO " (since Linux 5.0)" |
| 236 |
Enables UDP receive offload. |
| 237 |
If enabled, |
| 238 |
the socket may receive multiple datagrams worth of data |
| 239 |
as a single large buffer, |
| 240 |
together with a |
| 241 |
.BR cmsg (3) |
| 242 |
that holds the segment size. |
| 243 |
This option is the inverse of segmentation offload. |
| 244 |
It reduces receive cost by handling multiple datagrams worth of data |
| 245 |
as a single large packet in the kernel receive path, |
| 246 |
even when that exceeds MTU. |
| 247 |
This option should not be used in code intended to be portable. |
| 248 |
.SS Ioctls |
| 249 |
These ioctls can be accessed using |
| 250 |
.BR ioctl (2). |
| 251 |
The correct syntax is: |
| 252 |
.P |
| 253 |
.RS |
| 254 |
.nf |
| 255 |
.BI int " value"; |
| 256 |
.IB error " = ioctl(" udp_socket ", " ioctl_type ", &" value ");" |
| 257 |
.fi |
| 258 |
.RE |
| 259 |
.TP |
| 260 |
.BR FIONREAD " (" SIOCINQ ) |
| 261 |
Gets a pointer to an integer as argument. |
| 262 |
Returns the size of the next pending datagram in the integer in bytes, |
| 263 |
or 0 when no datagram is pending. |
| 264 |
.B Warning: |
| 265 |
Using |
| 266 |
.BR FIONREAD , |
| 267 |
it is impossible to distinguish the case where no datagram is pending |
| 268 |
from the case where the next pending datagram contains zero bytes of data. |
| 269 |
It is safer to use |
| 270 |
.BR select (2), |
| 271 |
.BR poll (2), |
| 272 |
or |
| 273 |
.BR epoll (7) |
| 274 |
to distinguish these cases. |
| 275 |
.\" See http://www.securiteam.com/unixfocus/5KP0I15IKO.html |
| 276 |
.\" "GNUnet DoS (UDP Socket Unreachable)", 14 May 2006 |
| 277 |
.TP |
| 278 |
.BR TIOCOUTQ " (" SIOCOUTQ ) |
| 279 |
Returns the number of data bytes in the local send queue. |
| 280 |
Supported only with Linux 2.4 and above. |
| 281 |
.P |
| 282 |
In addition, all ioctls documented in |
| 283 |
.BR ip (7) |
| 284 |
and |
| 285 |
.BR socket (7) |
| 286 |
are supported. |
| 287 |
.SH ERRORS |
| 288 |
All errors documented for |
| 289 |
.BR socket (7) |
| 290 |
or |
| 291 |
.BR ip (7) |
| 292 |
may be returned by a send or receive on a UDP socket. |
| 293 |
.TP |
| 294 |
.B ECONNREFUSED |
| 295 |
No receiver was associated with the destination address. |
| 296 |
This might be caused by a previous packet sent over the socket. |
| 297 |
.SH VERSIONS |
| 298 |
.B IP_RECVERR |
| 299 |
is a new feature in Linux 2.2. |
| 300 |
.\" .SH CREDITS |
| 301 |
.\" This man page was written by Andi Kleen. |
| 302 |
.SH SEE ALSO |
| 303 |
.BR ip (7), |
| 304 |
.BR raw (7), |
| 305 |
.BR socket (7), |
| 306 |
.BR udplite (7) |
| 307 |
.P |
| 308 |
The kernel source file |
| 309 |
.IR Documentation/networking/ip\-sysctl.rst . |
| 310 |
.P |
| 311 |
RFC\ 768 for the User Datagram Protocol. |
| 312 |
.br |
| 313 |
RFC\ 1122 for the host requirements. |
| 314 |
.br |
| 315 |
RFC\ 1191 for a description of path MTU discovery. |