'\" te
.\" Copyright 2006 AT&T
.\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH UDP 4P "Jul 4, 2006"
.SH NAME
udp, UDP \- Internet User Datagram Protocol
.SH SYNOPSIS
.LP
.nf
\fB#include <sys/socket.h>\fR
.fi

.LP
.nf
\fB#include <netinet/in.h>\fR
.fi

.LP
.nf
\fBs = socket(AF_INET, SOCK_DGRAM, 0);\fR
.fi

.LP
.nf
\fBs = socket(AF_INET6, SOCK_DGRAM, 0);\fR
.fi

.LP
.nf
\fBt = t_open("/dev/udp", O_RDWR);\fR
.fi

.LP
.nf
\fBt = t_open("/dev/udp6", O_RDWR);\fR
.fi

.SH DESCRIPTION
.sp
.LP
\fBUDP\fR is a simple datagram protocol which is layered directly above the
Internet Protocol ("\fBIP\fR") or the Internet Protocol Version 6 ("IPv6").
Programs may access  \fBUDP\fR using the socket interface, where it supports
the \fB\fR\fBSOCK_DGRAM\fR\fB\fR socket type, or using the Transport Level
Interface ("\fBTLI\fR"), where it supports the connectionless (\fBT_CLTS\fR)
service type.
.sp
.LP
Within the socket interface, \fBUDP\fR is normally used with the
\fBsendto()\fR, \fBsendmsg()\fR, \fBrecvfrom()\fR, and \fBrecvmsg()\fR calls
(see \fBsend\fR(3SOCKET) and \fBrecv\fR(3SOCKET)). If the
\fBconnect\fR(3SOCKET) call is used to fix the destination for future packets,
then the \fBrecv\fR(3SOCKET) or \fBread\fR(2) and \fBsend\fR(3SOCKET) or
\fBwrite\fR(2) calls may be used.
.sp
.LP
\fBUDP\fR address formats are identical to those used by the Transmission
Control Protocol ("\fBTCP\fR"). Like \fBTCP,\fR \fBUDP\fR uses a port number
along with an \fBIP\fRor IPv6 address to identify the endpoint of
communication. The \fBUDP\fR port number space is separate from the \fBTCP\fR
port number space, that is, a \fBUDP\fR port may not be "connected" to a
\fBTCP\fR port. The \fBbind\fR(3SOCKET) call can be used to set the local
address and port number of a \fBUDP\fR socket. The local \fBIP\fR or IPv6
address may be left unspecified in the \fBbind()\fR call by using the special
value \fBINADDR_ANY\fR for \fBIP\fR, or the unspecified address (all zeroes)
for IPv6. If the \fBbind()\fR call is not done, a local \fBIP\fR or IPv6
address and port number will be assigned to  the endpoint when the first packet
is sent. Broadcast packets may be sent, assuming the underlying network
supports this, by using a reserved "broadcast address" This address is network
interface dependent. Broadcasts may only be sent by the privileged user.
.sp
.LP
Note that no two UDP sockets can be bound to the same port unless the bound IP
addresses are different. IPv4 \fBINADDR_ANY\fR and IPv6 unspecified addresses
compare as equal to any IPv4 or IPv6 address. For example, if a socket is bound
to \fBINADDR_ANY\fR or unspecified address and port X, no other socket can bind
to port X, regardless of the binding address.  This special consideration of
\fBINADDR_ANY\fR and unspecified address can be changed using the
\fBSO_REUSEADDR\fR socket option.  If \fBSO_REUSEADDR\fR is set on a socket
doing a bind, IPv4 \fBINADDR_ANY\fR and IPv6 unspecified address do not compare
as equal to any IP address. This means that as long as the two sockets are not
both bound to \fBINADDR_ANY\fR/unspecified address or the same IP address, the
two sockets can be bound to the same port.
.sp
.LP
If an application does not want to allow another socket using the
\fBSO_REUSEADDR\fR option to bind to a port its socket is bound to, the
application can set the socket level option \fBSO_EXCLBIND\fR on a socket. The
option values of 0 and 1 represent enabling and disabling the option,
respectively.  Once this option is enabled on a socket, no other socket can be
bound to the same port.
.sp
.LP
IPv6 does not support broadcast addresses; their function is supported by IPv6
multicast addresses.
.sp
.LP
Options at the \fBIP\fR level may be used with \fBUDP\fR. See \fBip\fR(4P) or
\fBip6\fR(4P). Additionally, there is one UDP-level option of interest to IPsec
Key Management applications (see \fBipsec\fR(4P)and \fBpf_key\fR(4P)):
.sp
.ne 2
.na
\fBUDP_NAT_T_ENDPOINT\fR
.ad
.sp .6
.RS 4n
If this boolean option is set, datagrams sent via this socket will have a
non-ESP marker inserted between the UDP header and the data. Likewise, inbound
packets that match the endpoint's local-port will be demultiplexed between ESP
or the endpoint itself if a non-ESP marker is present. This option is only
available on IPv4 sockets (AF_INET), and the application must have sufficient
privilege to use PF_KEY sockets to also enable this option.
.RE

.sp
.LP
There are a variety of ways that a \fBUDP\fR packet can be lost or corrupted,
including a failure of the underlying communication mechanism. \fBUDP\fR
implements a checksum over the data portion of the packet. If the checksum of a
received packet is in error, the packet will be dropped with no indication
given to the user. A queue of received packets is provided for each \fBUDP\fR
socket. This queue has a limited capacity. Arriving datagrams which will not
fit within its \fIhigh-water\fR capacity are silently discarded.
.sp
.LP
\fBUDP\fR processes Internet Control Message Protocol ("\fBICMP\fR") and
Internet Control Message Protocol Version 6 ("\fBICMP6\fR") error messages
received in response to \fBUDP\fR packets it has sent. See \fBicmp\fR(4P) and
\fBicmp6\fR(4P).
.sp
.LP
\fBICMP\fR "source quench" messages are ignored. \fBICMP\fR "destination
unreachable," "time exceeded" and "parameter problem" messages disconnect the
socket from its peer so that subsequent attempts to send packets using that
socket will return an error. \fBUDP\fR will not guarantee that packets are
delivered in the order they were sent. As well, duplicate packets may be
generated in the communication process.
.sp
.LP
\fBICMP6\fR "destination unreachable" packets are ignored unless the enclosed
code indicates that the port is not in use on the target host, in which case,
the application is notified. \fBICMP6\fR "parameter problem" notifications are
similarly passed upstream. All other \fBICMP6\fR messages are ignored.
.SH SEE ALSO
.sp
.LP
.BR read (2),
.BR write (2),
.BR bind (3SOCKET),
.BR connect (3SOCKET),
.BR recv (3SOCKET),
.BR send (3SOCKET),
.BR icmp (4P),
.BR icmp6 (4P),
.BR inet (4P),
.BR inet6 (4P),
.BR ip (4P),
.BR ip6 (4P),
.BR ipsec (4P),
.BR pf_key (4P),
.BR tcp (4P)
.sp
.LP
Postel, Jon, \fIRFC 768, User Datagram Protocol\fR, Network Information Center,
SRI International, Menlo Park, Calif., August 1980
.sp
.LP
Huttunen, A., Swander, B., Volpe, V., DiBurro, L., Stenberg, \fIM., RFC 3948,
UDP Encapsulation of IPsec ESP Packets\fR, The Internet Society, 2005.
.SH DIAGNOSTICS
.sp
.LP
A socket operation may fail if:
.sp
.ne 2
.na
\fB\fBEISCONN\fR\fR
.ad
.RS 17n
A \fBconnect()\fR operation was attempted on a socket on which a
\fBconnect()\fR operation had already been performed, and the socket could not
be successfully disconnected before making the new connection.
.RE

.sp
.ne 2
.na
\fB\fBEISCONN\fR\fR
.ad
.RS 17n
A \fBsendto()\fR or \fBsendmsg()\fR operation specifying an address to which
the message should be sent was attempted on a socket on which a \fBconnect()\fR
operation had already been performed.
.RE

.sp
.ne 2
.na
\fB\fBENOTCONN\fR\fR
.ad
.RS 17n
A \fBsend()\fR or \fBwrite()\fR operation, or a \fBsendto()\fR or
\fBsendmsg()\fR operation not specifying an address to which the message should
be sent, was attempted on a socket on which a \fBconnect()\fR operation had not
already been performed.
.RE

.sp
.ne 2
.na
\fB\fBEADDRINUSE\fR\fR
.ad
.RS 17n
A \fBbind()\fR operation was attempted on a socket with a network address/port
pair that has already been bound to another socket.
.RE

.sp
.ne 2
.na
\fB\fBEADDRNOTAVAIL\fR\fR
.ad
.RS 17n
A \fBbind()\fR operation was attempted on a socket with a network address for
which no network interface exists.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 17n
A \fBsendmsg()\fR operation with a non-NULL \fBmsg_accrights\fR was attempted.
.RE

.sp
.ne 2
.na
\fB\fBEACCES\fR\fR
.ad
.RS 17n
A \fBbind()\fR operation was attempted with a "reserved" port number and the
effective user \fBID\fR of the process was not the privileged user.
.RE

.sp
.ne 2
.na
\fB\fBENOBUFS\fR\fR
.ad
.RS 17n
The system ran out of memory for internal data structures.
.RE