Debian Codegraph @

upstream/debian-unstable/man7/udp.7

raw
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.