original/man7/udp.7

   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 .\"
   8 .TH UDP  7 2010-06-13 "Linux" "Linux Programmer's Manual"
   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
  16 .B udp_socket = socket(AF_INET, SOCK_DGRAM, 0);
  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)
  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
  53 All receive operations return only one packet.
  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
  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).
  63 They are only processed by the kernel when the appropriate
  64 .I /proc
  65 parameter
  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
  72 flag is set on sending, the destination address must refer to a local
  73 interface address and the packet is only sent to that interface.
  74
  75 By default, Linux UDP does path MTU (Maximum Transmission Unit) discovery.
  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.
  80 When this happens, the application should decrease the packet size.
  81 Path MTU discovery can be also turned off using the
  82 .B IP_MTU_DISCOVER
  83 socket option or the
  84 .I /proc/sys/net/ipv4/ip_no_pmtu_disc
  85 file; see
  86 .BR ip (7)
  87 for details.
  88 When turned off, UDP will fragment outgoing UDP packets
  89 that exceed the interface MTU.
  90 However, disabling it is not recommended
  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
 109 For compatibility with legacy code, in Linux 2.0 and 2.2
 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
 125 option is enabled, all errors are stored in the socket error queue,
 126 and can be received by
 127 .BR recvmsg (2)
 128 with the
 129 .B MSG_ERRQUEUE
 130 flag set.
 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
 148 .IR tcp_mem
 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 bytes, of receive buffers 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
 163 .I udp_mem
 164 pressure.
 165 .TP
 166 .IR udp_wmem_min " (integer; default value: PAGE_SIZE; since Linux 2.6.25)"
 167 Minimal size, in bytes, of send buffer used by UDP sockets in moderation.
 168 Each UDP socket is able to use the size for sending data,
 169 even if total pages of UDP sockets exceed
 170 .I udp_mem
 171 pressure.
 172 .SS "Socket Options"
 173 To set or get a UDP socket option, call
 174 .BR getsockopt (2)
 175 to read or
 176 .BR setsockopt (2)
 177 to write the option with the option level argument set to
 178 .BR IPPROTO_UDP .
 179 .TP
 180 .BR UDP_CORK " (since Linux 2.5.44)"
 181 If this option is enabled, then all data output on this socket
 182 is accumulated into a single datagram that is transmitted when
 183 the option is disabled.
 184 This option should not be used in code intended to be
 185 portable.
 186 .\" FIXME document UDP_ENCAP (new in kernel 2.5.67)
 187 .\" From include/linux/udp.h:
 188 .\" /* UDP encapsulation types */
 189 .\" #define UDP_ENCAP_ESPINUDP_NON_IKE      1 /* draft-ietf-ipsec-nat-t-ike-00/01 */
 190 .\" #define UDP_ENCAP_ESPINUDP      2 /* draft-ietf-ipsec-udp-encaps-06 */
 191 .\" #define UDP_ENCAP_L2TPINUDP     3 /* rfc2661 */
 192 .SS Ioctls
 193 These ioctls can be accessed using
 194 .BR ioctl (2).
 195 The correct syntax is:
 196 .PP
 197 .RS
 198 .nf
 199 .BI int " value";
 200 .IB error " = ioctl(" udp_socket ", " ioctl_type ", &" value ");"
 201 .fi
 202 .RE
 203 .TP
 204 .BR FIONREAD " (" SIOCINQ )
 205 Gets a pointer to an integer as argument.
 206 Returns the size of the next pending datagram in the integer in bytes,
 207 or 0 when no datagram is pending.
 208 .B Warning:
 209 Using
 210 .BR FIONREAD ,
 211 it is impossible to distinguish the case where no datagram is pending
 212 from the case where the next pending datagram contains zero bytes of data.
 213 It is safer to use
 214 .BR select (2),
 215 .BR poll (2),
 216 or
 217 .BR epoll (7)
 218 to distinguish these cases.
 219 .\" See http://www.securiteam.com/unixfocus/5KP0I15IKO.html
 220 .\" "GNUnet DoS (UDP Socket Unreachable)", 14 May 2006
 221 .TP
 222 .BR TIOCOUTQ " (" SIOCOUTQ )
 223 Returns the number of data bytes in the local send queue.
 224 Only supported with Linux 2.4 and above.
 225 .PP
 226 In addition all ioctls documented in
 227 .BR ip (7)
 228 and
 229 .BR socket (7)
 230 are supported.
 231 .SH ERRORS
 232 All errors documented for
 233 .BR socket (7)
 234 or
 235 .BR ip (7)
 236 may be returned by a send or receive on a UDP socket.
 237 .TP
 238 .B ECONNREFUSED
 239 No receiver was associated with the destination address.
 240 This might be caused by a previous packet sent over the socket.
 241 .SH VERSIONS
 242 .B IP_RECVERR
 243 is a new feature in Linux 2.2.
 244 .\" .SH CREDITS
 245 .\" This man page was written by Andi Kleen.
 246 .SH "SEE ALSO"
 247 .BR ip (7),
 248 .BR raw (7),
 249 .BR socket (7),
 250 .BR udplite (7)
 251
 252 RFC\ 768 for the User Datagram Protocol.
 253 .br
 254 RFC\ 1122 for the host requirements.
 255 .br
 256 RFC\ 1191 for a description of path MTU discovery.