usr/src/man/man7p/udp.7p

   1 '\" te
   2 .\" Copyright 2006 AT&T
   3 .\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH UDP 7P "Jul 4, 2006"
   8 .SH NAME
   9 udp, UDP \- Internet User Datagram Protocol
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB#include <sys/socket.h>\fR
  14 .fi
  15
  16 .LP
  17 .nf
  18 \fB#include <netinet/in.h>\fR
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBs = socket(AF_INET, SOCK_DGRAM, 0);\fR
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBs = socket(AF_INET6, SOCK_DGRAM, 0);\fR
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBt = t_open("/dev/udp", O_RDWR);\fR
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBt = t_open("/dev/udp6", O_RDWR);\fR
  39 .fi
  40
  41 .SH DESCRIPTION
  42 .sp
  43 .LP
  44 \fBUDP\fR is a simple datagram protocol which is layered directly above the
  45 Internet Protocol ("\fBIP\fR") or the Internet Protocol Version 6 ("IPv6").
  46 Programs may access  \fBUDP\fR using the socket interface, where it supports
  47 the \fB\fR\fBSOCK_DGRAM\fR\fB\fR socket type, or using the Transport Level
  48 Interface ("\fBTLI\fR"), where it supports the connectionless (\fBT_CLTS\fR)
  49 service type.
  50 .sp
  51 .LP
  52 Within the socket interface, \fBUDP\fR is normally used with the
  53 \fBsendto()\fR, \fBsendmsg()\fR, \fBrecvfrom()\fR, and \fBrecvmsg()\fR calls
  54 (see \fBsend\fR(3SOCKET) and \fBrecv\fR(3SOCKET)). If the
  55 \fBconnect\fR(3SOCKET) call is used to fix the destination for future packets,
  56 then the \fBrecv\fR(3SOCKET) or \fBread\fR(2) and \fBsend\fR(3SOCKET) or
  57 \fBwrite\fR(2) calls may be used.
  58 .sp
  59 .LP
  60 \fBUDP\fR address formats are identical to those used by the Transmission
  61 Control Protocol ("\fBTCP\fR"). Like \fBTCP,\fR \fBUDP\fR uses a port number
  62 along with an \fBIP\fRor IPv6 address to identify the endpoint of
  63 communication. The \fBUDP\fR port number space is separate from the \fBTCP\fR
  64 port number space, that is, a \fBUDP\fR port may not be "connected" to a
  65 \fBTCP\fR port. The \fBbind\fR(3SOCKET) call can be used to set the local
  66 address and port number of a \fBUDP\fR socket. The local \fBIP\fR or IPv6
  67 address may be left unspecified in the \fBbind()\fR call by using the special
  68 value \fBINADDR_ANY\fR for \fBIP\fR, or the unspecified address (all zeroes)
  69 for IPv6. If the \fBbind()\fR call is not done, a local \fBIP\fR or IPv6
  70 address and port number will be assigned to  the endpoint when the first packet
  71 is sent. Broadcast packets may be sent, assuming the underlying network
  72 supports this, by using a reserved "broadcast address" This address is network
  73 interface dependent. Broadcasts may only be sent by the privileged user.
  74 .sp
  75 .LP
  76 Note that no two UDP sockets can be bound to the same port unless the bound IP
  77 addresses are different. IPv4 \fBINADDR_ANY\fR and IPv6 unspecified addresses
  78 compare as equal to any IPv4 or IPv6 address. For example, if a socket is bound
  79 to \fBINADDR_ANY\fR or unspecified address and port X, no other socket can bind
  80 to port X, regardless of the binding address.  This special consideration of
  81 \fBINADDR_ANY\fR and unspecified address can be changed using the
  82 \fBSO_REUSEADDR\fR socket option.  If \fBSO_REUSEADDR\fR is set on a socket
  83 doing a bind, IPv4 \fBINADDR_ANY\fR and IPv6 unspecified address do not compare
  84 as equal to any IP address. This means that as long as the two sockets are not
  85 both bound to \fBINADDR_ANY\fR/unspecified address or the same IP address, the
  86 two sockets can be bound to the same port.
  87 .sp
  88 .LP
  89 If an application does not want to allow another socket using the
  90 \fBSO_REUSEADDR\fR option to bind to a port its socket is bound to, the
  91 application can set the socket level option \fBSO_EXCLBIND\fR on a socket. The
  92 option values of 0 and 1 represent enabling and disabling the option,
  93 respectively.  Once this option is enabled on a socket, no other socket can be
  94 bound to the same port.
  95 .sp
  96 .LP
  97 IPv6 does not support broadcast addresses; their function is supported by IPv6
  98 multicast addresses.
  99 .sp
 100 .LP
 101 Options at the \fBIP\fR level may be used with \fBUDP\fR. See \fBip\fR(7P) or
 102 \fBip6\fR(7P). Additionally, there is one UDP-level option of interest to IPsec
 103 Key Management applications (see \fBipsec\fR(7P)and \fBpf_key\fR(7P)):
 104 .sp
 105 .ne 2
 106 .na
 107 \fBUDP_NAT_T_ENDPOINT\fR
 108 .ad
 109 .sp .6
 110 .RS 4n
 111 If this boolean option is set, datagrams sent via this socket will have a
 112 non-ESP marker inserted between the UDP header and the data. Likewise, inbound
 113 packets that match the endpoint's local-port will be demultiplexed between ESP
 114 or the endpoint itself if a non-ESP marker is present. This option is only
 115 available on IPv4 sockets (AF_INET), and the application must have sufficient
 116 privilege to use PF_KEY sockets to also enable this option.
 117 .RE
 118
 119 .sp
 120 .LP
 121 There are a variety of ways that a \fBUDP\fR packet can be lost or corrupted,
 122 including a failure of the underlying communication mechanism. \fBUDP\fR
 123 implements a checksum over the data portion of the packet. If the checksum of a
 124 received packet is in error, the packet will be dropped with no indication
 125 given to the user. A queue of received packets is provided for each \fBUDP\fR
 126 socket. This queue has a limited capacity. Arriving datagrams which will not
 127 fit within its \fIhigh-water\fR capacity are silently discarded.
 128 .sp
 129 .LP
 130 \fBUDP\fR processes Internet Control Message Protocol ("\fBICMP\fR") and
 131 Internet Control Message Protocol Version 6 ("\fBICMP6\fR") error messages
 132 received in response to \fBUDP\fR packets it has sent. See \fBicmp\fR(7P) and
 133 \fBicmp6\fR(7P).
 134 .sp
 135 .LP
 136 \fBICMP\fR "source quench" messages are ignored. \fBICMP\fR "destination
 137 unreachable," "time exceeded" and "parameter problem" messages disconnect the
 138 socket from its peer so that subsequent attempts to send packets using that
 139 socket will return an error. \fBUDP\fR will not guarantee that packets are
 140 delivered in the order they were sent. As well, duplicate packets may be
 141 generated in the communication process.
 142 .sp
 143 .LP
 144 \fBICMP6\fR "destination unreachable" packets are ignored unless the enclosed
 145 code indicates that the port is not in use on the target host, in which case,
 146 the application is notified. \fBICMP6\fR "parameter problem" notifications are
 147 similarly passed upstream. All other \fBICMP6\fR messages are ignored.
 148 .SH SEE ALSO
 149 .sp
 150 .LP
 151 \fBread\fR(2), \fBwrite\fR(2), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET),
 152 \fBrecv\fR(3SOCKET), \fBsend\fR(3SOCKET), \fBicmp\fR(7P), \fBicmp6\fR(7P),
 153 \fBinet\fR(7P), \fBinet6\fR(7P), \fBip\fR(7P), \fBipsec\fR(7P), \fBip6\fR(7P),
 154 \fBpf_key\fR(7P), \fBtcp\fR(7P)
 155 .sp
 156 .LP
 157 Postel, Jon, \fIRFC 768, User Datagram Protocol\fR, Network Information Center,
 158 SRI International, Menlo Park, Calif., August 1980
 159 .sp
 160 .LP
 161 Huttunen, A., Swander, B., Volpe, V., DiBurro, L., Stenberg, \fIM., RFC 3948,
 162 UDP Encapsulation of IPsec ESP Packets\fR, The Internet Society, 2005.
 163 .SH DIAGNOSTICS
 164 .sp
 165 .LP
 166 A socket operation may fail if:
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBEISCONN\fR\fR
 171 .ad
 172 .RS 17n
 173 A \fBconnect()\fR operation was attempted on a socket on which a
 174 \fBconnect()\fR operation had already been performed, and the socket could not
 175 be successfully disconnected before making the new connection.
 176 .RE
 177
 178 .sp
 179 .ne 2
 180 .na
 181 \fB\fBEISCONN\fR\fR
 182 .ad
 183 .RS 17n
 184 A \fBsendto()\fR or \fBsendmsg()\fR operation specifying an address to which
 185 the message should be sent was attempted on a socket on which a \fBconnect()\fR
 186 operation had already been performed.
 187 .RE
 188
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBENOTCONN\fR\fR
 193 .ad
 194 .RS 17n
 195 A \fBsend()\fR or \fBwrite()\fR operation, or a \fBsendto()\fR or
 196 \fBsendmsg()\fR operation not specifying an address to which the message should
 197 be sent, was attempted on a socket on which a \fBconnect()\fR operation had not
 198 already been performed.
 199 .RE
 200
 201 .sp
 202 .ne 2
 203 .na
 204 \fB\fBEADDRINUSE\fR\fR
 205 .ad
 206 .RS 17n
 207 A \fBbind()\fR operation was attempted on a socket with a network address/port
 208 pair that has already been bound to another socket.
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fBEADDRNOTAVAIL\fR\fR
 215 .ad
 216 .RS 17n
 217 A \fBbind()\fR operation was attempted on a socket with a network address for
 218 which no network interface exists.
 219 .RE
 220
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBEINVAL\fR\fR
 225 .ad
 226 .RS 17n
 227 A \fBsendmsg()\fR operation with a non-NULL \fBmsg_accrights\fR was attempted.
 228 .RE
 229
 230 .sp
 231 .ne 2
 232 .na
 233 \fB\fBEACCES\fR\fR
 234 .ad
 235 .RS 17n
 236 A \fBbind()\fR operation was attempted with a "reserved" port number and the
 237 effective user \fBID\fR of the process was not the privileged user.
 238 .RE
 239
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fBENOBUFS\fR\fR
 244 .ad
 245 .RS 17n
 246 The system ran out of memory for internal data structures.
 247 .RE
 248