udp(7) - f7

1UDP(7)                     Linux Programmer's Manual                    UDP(7)
2
3
4

NAME

6       udp - User Datagram Protocol for IPv4
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <netinet/in.h>
11       udp_socket = socket(PF_INET, SOCK_DGRAM, 0);
12

DESCRIPTION

14       This  is  an  implementation of the User Datagram Protocol described in
15       RFC 768.  It implements a connectionless,  unreliable  datagram  packet
16       service.   Packets  may  be reordered or duplicated before they arrive.
17       UDP generates and checks checksums to catch transmission errors.
18
19       When a UDP socket is  created,  its  local  and  remote  addresses  are
20       unspecified.   Datagrams  can  be  sent  immediately using sendto(2) or
21       sendmsg(2) with a valid destination address as an argument.  When  con‐
22       nect(2)  is called on the socket the default destination address is set
23       and datagrams can now be sent using send(2) or write(2) without  speci‐
24       fying  an  destination  address.  It is still possible to send to other
25       destinations by passing an address  to  sendto(2)  or  sendmsg(2).   In
26       order  to  receive  packets the socket can be bound to an local address
27       first by using bind(2).  Otherwise the socket layer will  automatically
28       assign   a   free   local   port   out   of   the   range   defined  by
29       net.ipv4.ip_local_port_range and bind the socket to INADDR_ANY.
30
31       All receive operations return only one  packet.   When  the  packet  is
32       smaller than the passed buffer only that much data is returned, when it
33       is bigger the packet is  truncated  and  the  MSG_TRUNC  flag  is  set.
34       MSG_WAITALL is not supported.
35
36       IP  options  may be sent or received using the socket options described
37       in ip(7).  They are only processed by the kernel when  the  appropriate
38       sysctl  is enabled (but still passed to the user even when it is turned
39       off).  See ip(7).
40
41       When the MSG_DONTROUTE flag is set on sending the  destination  address
42       must refer to an local interface address and the packet is only sent to
43       that interface.
44
45       By default Linux UDP does path MTU (Maximum Transmission Unit)  discov‐
46       ery.   This  means  the kernel will keep track of the MTU to a specific
47       target IP address and return EMSGSIZE when a UDP packet  write  exceeds
48       it.  When this happens the application should decrease the packet size.
49       Path MTU discovery can be also turned  off  using  the  IP_MTU_DISCOVER
50       socket  option  or  the  ip_no_pmtu_disc sysctl, see ip(7) for details.
51       When turned off UDP will fragment outgoing UDP packets that exceed  the
52       interface MTU.  However disabling it is not recommended for performance
53       and reliability reasons.
54
55

ADDRESS FORMAT

57       UDP uses the IPv4 sockaddr_in address format described in ip(7).
58
59

ERROR HANDLING

61       All fatal errors will be passed to the user as  an  error  return  even
62       when  the  socket  is  not connected. This includes asynchronous errors
63       received from the network. You may get an error for an  earlier  packet
64       that  was  sent  on  the same socket.  This behaviour differs from many
65       other BSD socket implementations which don't pass any errors unless the
66       socket is connected.  Linux's behaviour is mandated by RFC 1122.
67
68       For compatibility with legacy code in Linux 2.0 and 2.2 it was possible
69       to set the SO_BSDCOMPAT SOL_SOCKET option to receive remote errors only
70       when  the  socket  has been connected (except for EPROTO and EMSGSIZE).
71       Locally generated errors are always passed.  Support  for  this  socket
72       option was removed in later kernels; see socket(7) for further informa‐
73       tion.
74
75       When the IP_RECVERR option is enabled all  errors  are  stored  in  the
76       socket  error  queue  and  can  be  received  by  recvmsg(2)  with  the
77       MSG_ERRQUEUE flag set.
78

SOCKET OPTIONS

80       To set or get a UDP socket option, call getsockopt(2) to read  or  set‐
81       sockopt(2)  to  write  the option with the option level argument set to
82       IPPROTO_UDP.
83
84       UDP_CORK (since Linux 2.5.44)
85              If this option is enabled, then all data output on  this  socket
86              is  accumulated  into a single datagram that is transmitted when
87              the option is disabled.  This option should not be used in  code
88              intended to be portable.
89

IOCTLS

91       These ioctls can be accessed using ioctl(2).  The correct syntax is:
92
93              int value;
94              error = ioctl(udp_socket, ioctl_type, &value);
95
96       FIONREAD (SIOCINQ)
97              Gets  a  pointer to an integer as argument.  Returns the size of
98              the next pending datagram in the integer in bytes, or 0 when  no
99              datagram is pending.
100
101       TIOCOUTQ (SIOCOUTQ)
102              Returns  the number of data bytes in the local send queue.  Only
103              supported with Linux 2.4 and above.
104
105       In addition all ioctls documented in ip(7) and socket(7) are supported.
106

ERRORS

108       All errors documented for socket(7) or ip(7) may be returned by a  send
109       or receive on a UDP socket.
110
111       ECONNREFUSED  No  receiver was associated with the destination address.
112       This might be caused by a previous packet sent over the socket.
113
114

VERSIONS

116       IP_RECVERR is a new feature in Linux 2.2.
117
118

CREDITS

120       This man page was written by Andi Kleen.
121
122