]>
Commit | Line | Data |
---|---|---|
77117f4f MK |
1 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. |
2 | .\" Permission is granted to distribute possibly modified copies | |
3 | .\" of this page provided the header is included verbatim, | |
4 | .\" and in case of nontrivial modification author and date | |
5 | .\" of the modification is added to the header. | |
6 | .\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $ | |
7 | .\" | |
418d8232 | 8 | .TH UDP 7 2008-11-21 "Linux" "Linux Programmer's Manual" |
77117f4f MK |
9 | .SH NAME |
10 | udp \- User Datagram Protocol for IPv4 | |
11 | .SH SYNOPSIS | |
12 | .B #include <sys/socket.h> | |
13 | .br | |
14 | .B #include <netinet/in.h> | |
15 | .sp | |
d4c8c97c | 16 | .B udp_socket = socket(AF_INET, SOCK_DGRAM, 0); |
77117f4f MK |
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 | ||
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) | |
fe10db36 | 33 | is called on the socket, the default destination address is set and |
77117f4f MK |
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). | |
fe10db36 | 44 | In order to receive packets, the socket can be bound to a local |
77117f4f MK |
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 net.ipv4.ip_local_port_range | |
50 | and bind the socket to | |
51 | .BR INADDR_ANY . | |
52 | ||
53 | All receive operations return only one packet. | |
fe10db36 MK |
54 | When the packet is smaller than the passed buffer, only that much |
55 | data is returned; when it is bigger, the packet is truncated and the | |
77117f4f MK |
56 | .B MSG_TRUNC |
57 | flag is set. | |
58 | .B MSG_WAITALL | |
59 | is not supported. | |
60 | ||
61 | IP options may be sent or received using the socket options described in | |
62 | .BR ip (7). | |
5a2ff571 MK |
63 | They are only processed by the kernel when the appropriate |
64 | /proc | |
65 | parameter | |
77117f4f MK |
66 | is enabled (but still passed to the user even when it is turned off). |
67 | See | |
68 | .BR ip (7). | |
69 | ||
70 | When the | |
71 | .B MSG_DONTROUTE | |
93de498a | 72 | flag is set on sending, the destination address must refer to a local |
77117f4f MK |
73 | interface address and the packet is only sent to that interface. |
74 | ||
93de498a | 75 | By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery. |
77117f4f MK |
76 | This means the kernel |
77 | will keep track of the MTU to a specific target IP address and return | |
78 | .B EMSGSIZE | |
79 | when a UDP packet write exceeds it. | |
fe10db36 | 80 | When this happens, the application should decrease the packet size. |
77117f4f MK |
81 | Path MTU discovery can be also turned off using the |
82 | .B IP_MTU_DISCOVER | |
83 | socket option or the | |
5a2ff571 MK |
84 | .I /proc/sys/net/ipv4/ip_no_pmtu_disc |
85 | file; see | |
77117f4f MK |
86 | .BR ip (7) |
87 | for details. | |
fe10db36 | 88 | When turned off, UDP will fragment outgoing UDP packets |
77117f4f | 89 | that exceed the interface MTU. |
fe10db36 | 90 | However, disabling it is not recommended |
77117f4f MK |
91 | for performance and reliability reasons. |
92 | .SS "Address Format" | |
93 | UDP uses the IPv4 | |
94 | .I sockaddr_in | |
95 | address format described in | |
96 | .BR ip (7). | |
97 | .SS "Error Handling" | |
98 | All fatal errors will be passed to the user as an error return even | |
99 | when the socket is not connected. | |
100 | This includes asynchronous errors | |
101 | received from the network. | |
102 | You may get an error for an earlier packet | |
103 | that was sent on the same socket. | |
104 | This behavior differs from many other BSD socket implementations | |
105 | which don't pass any errors unless the socket is connected. | |
106 | Linux's behavior is mandated by | |
107 | .BR RFC\ 1122 . | |
108 | ||
fe10db36 | 109 | For compatibility with legacy code, in Linux 2.0 and 2.2 |
77117f4f MK |
110 | it was possible to set the |
111 | .B SO_BSDCOMPAT | |
112 | .B SOL_SOCKET | |
113 | option to receive remote errors only when the socket has been | |
114 | connected (except for | |
115 | .B EPROTO | |
116 | and | |
117 | .BR EMSGSIZE ). | |
118 | Locally generated errors are always passed. | |
119 | Support for this socket option was removed in later kernels; see | |
120 | .BR socket (7) | |
121 | for further information. | |
122 | ||
123 | When the | |
124 | .B IP_RECVERR | |
fe10db36 | 125 | option is enabled, all errors are stored in the socket error queue, |
77117f4f MK |
126 | and can be received by |
127 | .BR recvmsg (2) | |
128 | with the | |
129 | .B MSG_ERRQUEUE | |
130 | flag set. | |
418d8232 MK |
131 | .SS /proc interfaces |
132 | System-wide UDP parameter settings can be accessed by files in the directory | |
133 | .IR /proc/sys/net/ipv4/ . | |
134 | .TP | |
135 | .IR udp_mem " (since Linux 2.6.25)" | |
136 | This is a vector of three integers governing the number | |
137 | of pages allowed for queueing by all UDP sockets. | |
138 | .RS | |
139 | .TP 10 | |
140 | .I min | |
141 | Below this number of pages, UDP is not bothered about its | |
142 | memory appetite. | |
143 | When the amount of memory allocated by UDP exceeds | |
144 | this number, UDP starts to moderate memory usage. | |
145 | .TP | |
146 | .I pressure | |
147 | This value was introduced to follow the format of | |
a113945f | 148 | .IR tcp_mem |
418d8232 MK |
149 | (see |
150 | .BR tcp (7)). | |
151 | .TP | |
152 | .I max | |
153 | Number of pages allowed for queueing by all UDP sockets. | |
154 | .RE | |
155 | .IP | |
156 | Defaults values for these three items are | |
157 | calculated at boot time from the amount of available memory. | |
158 | .TP | |
159 | .IR udp_rmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" | |
160 | Minimal size, in bites, of receive buffer used by UDP sockets in moderation. | |
161 | Each UDP socket is able to use the size for receiving data, | |
162 | even if total pages of UDP sockets exceed udp_mem pressure. | |
163 | .TP | |
164 | .IR udp_wmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)" | |
165 | Minimal size, in bytes, of send buffer used by UDP sockets in moderation. | |
166 | Each UDP socket is able to use the size for sending data, | |
167 | even if total pages of UDP sockets exceed | |
168 | .I udp_mem | |
169 | pressure. | |
77117f4f MK |
170 | .SS "Socket Options" |
171 | To set or get a UDP socket option, call | |
172 | .BR getsockopt (2) | |
173 | to read or | |
174 | .BR setsockopt (2) | |
175 | to write the option with the option level argument set to | |
176 | .BR IPPROTO_UDP . | |
177 | .TP | |
178 | .BR UDP_CORK " (since Linux 2.5.44)" | |
179 | If this option is enabled, then all data output on this socket | |
180 | is accumulated into a single datagram that is transmitted when | |
181 | the option is disabled. | |
182 | This option should not be used in code intended to be | |
183 | portable. | |
184 | .\" FIXME document UDP_ENCAP (new in kernel 2.5.67) | |
963ca80f MK |
185 | .\" From include/linux/udp.h: |
186 | .\" /* UDP encapsulation types */ | |
187 | .\" #define UDP_ENCAP_ESPINUDP_NON_IKE 1 /* draft-ietf-ipsec-nat-t-ike-00/01 */ | |
188 | .\" #define UDP_ENCAP_ESPINUDP 2 /* draft-ietf-ipsec-udp-encaps-06 */ | |
189 | .\" #define UDP_ENCAP_L2TPINUDP 3 /* rfc2661 */ | |
77117f4f MK |
190 | .SS Ioctls |
191 | These ioctls can be accessed using | |
192 | .BR ioctl (2). | |
193 | The correct syntax is: | |
194 | .PP | |
195 | .RS | |
196 | .nf | |
197 | .BI int " value"; | |
198 | .IB error " = ioctl(" udp_socket ", " ioctl_type ", &" value ");" | |
199 | .fi | |
200 | .RE | |
201 | .TP | |
202 | .BR FIONREAD " (" SIOCINQ ) | |
203 | Gets a pointer to an integer as argument. | |
204 | Returns the size of the next pending datagram in the integer in bytes, | |
205 | or 0 when no datagram is pending. | |
206 | .TP | |
207 | .BR TIOCOUTQ " (" SIOCOUTQ ) | |
208 | Returns the number of data bytes in the local send queue. | |
209 | Only supported with Linux 2.4 and above. | |
210 | .PP | |
211 | In addition all ioctls documented in | |
212 | .BR ip (7) | |
213 | and | |
214 | .BR socket (7) | |
215 | are supported. | |
216 | .SH ERRORS | |
217 | All errors documented for | |
218 | .BR socket (7) | |
219 | or | |
220 | .BR ip (7) | |
221 | may be returned by a send or receive on a UDP socket. | |
222 | ||
223 | .B ECONNREFUSED | |
224 | No receiver was associated with the destination address. | |
225 | This might be caused by a previous packet sent over the socket. | |
226 | .SH VERSIONS | |
dbf6263d MK |
227 | .B IP_RECVERR |
228 | is a new feature in Linux 2.2. | |
77117f4f MK |
229 | .\" .SH CREDITS |
230 | .\" This man page was written by Andi Kleen. | |
231 | .SH "SEE ALSO" | |
232 | .BR ip (7), | |
233 | .BR raw (7), | |
64bfda27 MK |
234 | .BR socket (7), |
235 | .BR udplite (7) | |
77117f4f MK |
236 | |
237 | RFC\ 768 for the User Datagram Protocol. | |
238 | .br | |
239 | RFC\ 1122 for the host requirements. | |
240 | .br | |
241 | RFC\ 1191 for a description of path MTU discovery. |