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