mirror of https://github.com/mkerrisk/man-pages
163 lines
4.6 KiB
Groff
163 lines
4.6 KiB
Groff
.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
|
|
.\" Permission is granted to distribute possibly modified copies
|
|
.\" of this page provided the header is included verbatim,
|
|
.\" and in case of nontrivial modification author and date
|
|
.\" of the modification is added to the header.
|
|
.\" $Id: udp.7,v 1.7 2000/01/22 01:55:05 freitag Exp $
|
|
.\" FIXME Document UDP_CORK
|
|
.TH UDP 7 1998-10-02 "Linux Man Page" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
udp \- User Datagram Protocol for IPv4
|
|
.SH SYNOPSIS
|
|
.B #include <sys/socket.h>
|
|
.br
|
|
.B #include <netinet/in.h>
|
|
.br
|
|
.B udp_socket = socket(PF_INET, SOCK_DGRAM, 0);
|
|
.SH DESCRIPTION
|
|
This is an implemention of the User Datagram Protocol described in RFC\ 768. It
|
|
implements a connectionless, unreliable datagram packet service.
|
|
Packets may be reordered or duplicated before they arrive. UDP
|
|
generates and checks checksums to catch transmission errors.
|
|
|
|
When a UDP socket is created, its local and remote addresses are unspecified.
|
|
Datagrams can be sent immediately using
|
|
.BR sendto (2)
|
|
or
|
|
.BR sendmsg (2)
|
|
with a valid destination address as an argument. When
|
|
.BR connect (2)
|
|
is called on the socket the default destination address is set and datagrams
|
|
can now be sent using
|
|
.BR send (2)
|
|
or
|
|
.BR write (2)
|
|
without specifying an destination address.
|
|
It is still possible to send to other destinations by passing an address to
|
|
.BR sendto (2)
|
|
or
|
|
.BR sendmsg (2).
|
|
In order to receive packets the socket can be bound to an local
|
|
address first by using
|
|
.BR bind (2).
|
|
Otherwise the socket layer will automatically assign
|
|
a free local port out of the range defined by
|
|
.I net.ipv4.ip_local_port_range
|
|
and bind the socket to
|
|
.IR INADDR_ANY .
|
|
|
|
All receive operations return only one packet. When the packet is smaller
|
|
than the passed buffer only that much data is returned, when it is bigger
|
|
the packet is truncated and the
|
|
.B MSG_TRUNC
|
|
flag is set.
|
|
.I MSG_WAITALL
|
|
is not supported.
|
|
|
|
IP options may be sent or received using the socket options described in
|
|
.BR ip (7).
|
|
They are only processed by the kernel when the appropriate sysctl
|
|
is enabled (but still passed to the user even when it is turned off). See
|
|
.BR ip (7).
|
|
|
|
When the
|
|
.B MSG_DONTROUTE
|
|
flag is set on sending the destination address must refer to an local
|
|
interface address and the packet is only sent to that interface.
|
|
|
|
UDP fragments a packet when its total length exceeds the interface MTU
|
|
(Maximum Transmission Unit).
|
|
A more network friendly alternative is to use path MTU discovery
|
|
as described in the
|
|
.B IP_MTU_DISCOVER
|
|
section of
|
|
.BR ip (7).
|
|
|
|
.SH "ADDRESS FORMAT"
|
|
UDP uses the IPv4
|
|
.B sockaddr_in
|
|
address format described in
|
|
.BR ip (7).
|
|
|
|
.SH "ERROR HANDLING"
|
|
All fatal errors will be passed to the user as an error return even
|
|
when the socket is not connected. This includes asynchronous errors
|
|
received from the network. You may get an error for an earlier packet
|
|
that was sent on the same socket.
|
|
This behaviour differs from many other BSD socket implementations
|
|
which don't pass any errors unless the socket is connected.
|
|
Linux's behaviour is mandated by
|
|
.BR RFC\ 1122 .
|
|
|
|
For compatibility with legacy code it is possible to set the
|
|
.B SO_BSDCOMPAT
|
|
SOL_SOCKET option to receive remote errors only when the socket has been
|
|
connected (except for
|
|
.B EPROTO
|
|
and
|
|
.BR EMSGSIZE ).
|
|
It is better to fix the
|
|
code to handle errors properly than to enable this option.
|
|
Locally generated errors are always passed.
|
|
|
|
When the
|
|
.B IP_RECVERR
|
|
option is enabled all errors are stored in the socket error queue
|
|
and can be received by
|
|
.BR recvmsg (2)
|
|
with the
|
|
.B MSG_ERRQUEUE
|
|
flag set.
|
|
.SH IOCTLS
|
|
These ioctls can be accessed using
|
|
.BR ioctl (2).
|
|
The correct syntax is:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
.BI int " value";
|
|
.IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");"
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.BR FIONREAD " (" SIOCINQ )
|
|
Gets a pointer to an integer as argument. Returns the size of the next
|
|
pending datagram in the integer in bytes, or 0 when no datagram is pending.
|
|
.TP
|
|
.BR TIOCOUTQ " (" SIOCOUTQ )
|
|
Returns the number of data bytes in the local send queue. Only supported
|
|
with Linux 2.4 and above.
|
|
.PP
|
|
In addition all ioctls documented in
|
|
.BR ip (7)
|
|
and
|
|
.BR socket (7)
|
|
are supported.
|
|
.SH ERRORS
|
|
All errors documented for
|
|
.BR socket (7)
|
|
or
|
|
.BR ip (7)
|
|
may be returned by a send or receive on a UDP socket.
|
|
|
|
.B ECONNREFUSED
|
|
No receiver was associated with the destination address. This might be
|
|
caused by a previous packet sent over the socket.
|
|
|
|
.SH VERSIONS
|
|
IP_RECVERR is a new feature in Linux 2.2.
|
|
|
|
.SH CREDITS
|
|
This man page was written by Andi Kleen.
|
|
|
|
.SH "SEE ALSO"
|
|
.BR ip (7),
|
|
.BR raw (7),
|
|
.BR socket (7)
|
|
|
|
RFC\ 768 for the User Datagram Protocol.
|
|
.br
|
|
RFC\ 1122 for the host requirements.
|
|
.br
|
|
RFC\ 1191 for a description of path MTU discovery.
|