original/man7/udp.7

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