diff options
Diffstat (limited to 'usr/src/man/man7p/udp.7p')
| -rw-r--r-- | usr/src/man/man7p/udp.7p | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/usr/src/man/man7p/udp.7p b/usr/src/man/man7p/udp.7p new file mode 100644 index 0000000000..eac5a26516 --- /dev/null +++ b/usr/src/man/man7p/udp.7p @@ -0,0 +1,265 @@ +'\" 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 7P "4 July 2006" "SunOS 5.11" "Protocols" +.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(7P) or +\fBip6\fR(7P). Additionally, there is one UDP-level option of interest to IPsec +Key Management applications (see \fBipsec\fR(7P)and \fBpf_key\fR(7P)): +.sp +.ne 2 +.mk +.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(7P) and +\fBicmp6\fR(7P). +.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 +\fBread\fR(2), \fBwrite\fR(2), \fBbind\fR(3SOCKET), \fBconnect\fR(3SOCKET), +\fBrecv\fR(3SOCKET), \fBsend\fR(3SOCKET), \fBicmp\fR(7P), \fBicmp6\fR(7P), +\fBinet\fR(7P), \fBinet6\fR(7P), \fBip\fR(7P), \fBipsec\fR(7P), \fBip6\fR(7P), +\fBpf_key\fR(7P), \fBtcp\fR(7P) +.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 +.mk +.na +\fB\fBEISCONN\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBEISCONN\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBENOTCONN\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBEADDRINUSE\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBEADDRNOTAVAIL\fR\fR +.ad +.RS 17n +.rt +A \fBbind()\fR operation was attempted on a socket with a network address for +which no network interface exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 17n +.rt +A \fBsendmsg()\fR operation with a non-NULL \fBmsg_accrights\fR was attempted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 17n +.rt +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 +.mk +.na +\fB\fBENOBUFS\fR\fR +.ad +.RS 17n +.rt +The system ran out of memory for internal data structures. +.RE + |