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 1998-10-02 "Linux Man Page" "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 .br
  16 .B udp_socket = socket(PF_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 an 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 an 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 net.ipv4.ip_local_port_range
  50 and bind the socket to
  51 .IR 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 .I 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 sysctl
  64 is enabled (but still passed to the user even when it is turned off).
  65 See
  66 .BR ip (7).
  67
  68 When the
  69 .B MSG_DONTROUTE
  70 flag is set on sending the destination address must refer to an local
  71 interface address and the packet is only sent to that interface.
  72
  73 By default Linux UDP does path MTU (Maximum Transmission Unit) discovery.
  74 This means the kernel
  75 will keep track of the MTU to a specific target IP address and return
  76 .I EMSGSIZE
  77 when a UDP packet write exceeds it.
  78 When this happens the application should decrease the packet size.
  79 Path MTU discovery can be also turned off using the
  80 .B IP_MTU_DISCOVER
  81 socket option or the
  82 .B ip_no_pmtu_disc
  83 sysctl, see
  84 .BR ip(7)
  85 for details.
  86 When turned off UDP will fragment outgoing UDP packets
  87 that exceed the interface MTU.
  88 However disabling it is not recommended
  89 for performance and reliability reasons.
  90 .SH "ADDRESS FORMAT"
  91 UDP uses the IPv4
  92 .B sockaddr_in
  93 address format described in
  94 .BR ip (7).
  95 .SH "ERROR HANDLING"
  96 All fatal errors will be passed to the user as an error return even
  97 when the socket is not connected.
  98 This includes asynchronous errors
  99 received from the network.
 100 You may get an error for an earlier packet
 101 that was sent on the same socket.
 102 This behaviour differs from many other BSD socket implementations
 103 which don't pass any errors unless the socket is connected.
 104 Linux's behaviour is mandated by
 105 .BR RFC\ 1122 .
 106
 107 For compatibility with legacy code in Linux 2.0 and 2.2
 108 it was possible to set the
 109 .B SO_BSDCOMPAT
 110 SOL_SOCKET option to receive remote errors only when the socket has been
 111 connected (except for
 112 .B EPROTO
 113 and
 114 .BR EMSGSIZE ).
 115 Locally generated errors are always passed.
 116 Support for this socket option was removed in later kernels; see
 117 .BR socket (7)
 118 for further information.
 119
 120 When the
 121 .B IP_RECVERR
 122 option is enabled all errors are stored in the socket error queue
 123 and can be received by
 124 .BR recvmsg (2)
 125 with the
 126 .B MSG_ERRQUEUE
 127 flag set.
 128 .SH "SOCKET OPTIONS"
 129 To set or get a UDP socket option, call
 130 .BR getsockopt (2)
 131 to read or
 132 .BR setsockopt (2)
 133 to write the option with the option level argument set to
 134 .BR IPPROTO_UDP .
 135 .TP
 136 .BR UDP_CORK " (since Linux 2.5.44)"
 137 If this option is enabled, then all data output on this socket
 138 is accumulated into a single datagram that is transmitted when
 139 the option is disabled.
 140 This option should not be used in code intended to be
 141 portable.
 142 .\" FIXME document UDP_ENCAP (new in kernel 2.5.67)
 143 .SH IOCTLS
 144 These ioctls can be accessed using
 145 .BR ioctl (2).
 146 The correct syntax is:
 147 .PP
 148 .RS
 149 .nf
 150 .BI int " value";
 151 .IB error " = ioctl(" udp_socket ", " ioctl_type ", &" value ");"
 152 .fi
 153 .RE
 154 .TP
 155 .BR FIONREAD " (" SIOCINQ )
 156 Gets a pointer to an integer as argument.
 157 Returns the size of the next pending datagram in the integer in bytes,
 158 or 0 when no datagram is pending.
 159 .TP
 160 .BR TIOCOUTQ " (" SIOCOUTQ )
 161 Returns the number of data bytes in the local send queue.
 162 Only supported with Linux 2.4 and above.
 163 .PP
 164 In addition all ioctls documented in
 165 .BR ip (7)
 166 and
 167 .BR socket (7)
 168 are supported.
 169 .SH ERRORS
 170 All errors documented for
 171 .BR socket (7)
 172 or
 173 .BR ip (7)
 174 may be returned by a send or receive on a UDP socket.
 175
 176 .B ECONNREFUSED
 177 No receiver was associated with the destination address.
 178 This might be caused by a previous packet sent over the socket.
 179 .SH VERSIONS
 180 IP_RECVERR is a new feature in Linux 2.2.
 181 .SH CREDITS
 182 This man page was written by Andi Kleen.
 183 .SH "SEE ALSO"
 184 .BR ip (7),
 185 .BR raw (7),
 186 .BR socket (7)
 187
 188 RFC\ 768 for the User Datagram Protocol.
 189 .br
 190 RFC\ 1122 for the host requirements.
 191 .br
 192 RFC\ 1191 for a description of path MTU discovery.