mirror of https://github.com/mkerrisk/man-pages
Document the Linux implementation of the UDP-Lite protocol,
new in Linux 2.6.20.
This commit is contained in:
parent
64bfda2738
commit
1dd4e8b006
|
@ -0,0 +1,152 @@
|
|||
.\" Copyright (c) 2008 by Gerrit Renker <gerrit@erg.abdn.ac.uk>
|
||||
.\"
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
.\" preserved on all copies.
|
||||
.\"
|
||||
.\" Permission is granted to copy and distribute modified versions of this
|
||||
.\" manual under the conditions for verbatim copying, provided that the
|
||||
.\" entire resulting derived work is distributed under the terms of a
|
||||
.\" permission notice identical to this one.
|
||||
.\"
|
||||
.\" Since the Linux kernel and libraries are constantly changing, this
|
||||
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
||||
.\" responsibility for errors or omissions, or for damages resulting from
|
||||
.\" the use of the information contained herein. The author(s) may not
|
||||
.\" have taken the same level of care in the production of this manual,
|
||||
.\" which is licensed free of charge, as they might when working
|
||||
.\" professionally.
|
||||
.\"
|
||||
.\" Formatted or processed versions of this manual, if unaccompanied by
|
||||
.\" the source, must acknowledge the copyright and authors of this work.
|
||||
.\"
|
||||
.\" $Id: udplite.7,v 1.12 2008/07/23 15:22:22 gerrit Exp gerrit $
|
||||
.\"
|
||||
.TH UDPLITE 7 2008-08-08 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
udplite \- Lightweight User Datagram Protocol
|
||||
.SH SYNOPSIS
|
||||
.B #include <sys/socket.h>
|
||||
.br
|
||||
.\" FIXME . see #defines under `BUGS',
|
||||
.\" when glibc supports this, add
|
||||
.\" #include <netinet/udplite.h>
|
||||
.sp
|
||||
.B s = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE);
|
||||
.SH DESCRIPTION
|
||||
This is an implementation of the Lightweight User Datagram Protocol
|
||||
(UDP-Lite), as described in RFC\ 3828.
|
||||
|
||||
UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length
|
||||
checksums.
|
||||
This has advantages for some types of multimedia transport that
|
||||
may be able to make use of slightly damaged datagrams,
|
||||
rather than having them discarded by lower-layer protocols.
|
||||
|
||||
The variable-length checksum coverage is set via a
|
||||
.BR setsockopt (2)
|
||||
option.
|
||||
If this option is not set, the only difference to UDP is
|
||||
in using a different IP protocol identifier (IANA number 136).
|
||||
|
||||
The UDP-Lite implementation is a full extension of
|
||||
.BR udp (7),
|
||||
i.e., it shares the same API and API behaviour, and in addition
|
||||
offers two socket options to control the checksum coverage.
|
||||
.SS "Address Format"
|
||||
UDP-Litev4 uses the
|
||||
.I sockaddr_in
|
||||
address format described in
|
||||
.BR ip (7).
|
||||
UDP-Litev6 uses the
|
||||
.I sockaddr_in6
|
||||
address format described in
|
||||
.BR ipv6 (7).
|
||||
.SS "Socket Options"
|
||||
To set or get a UDP-Lite socket option, call
|
||||
.BR getsockopt (2)
|
||||
to read or
|
||||
.BR setsockopt (2)
|
||||
to write the option with the option level argument set to
|
||||
.BR IPPROTO_UDPLITE .
|
||||
In addition, all
|
||||
.B IPPROTO_UDP
|
||||
socket options are valid on a UDP-Lite socket.
|
||||
See
|
||||
.BR udp (7)
|
||||
for more information.
|
||||
|
||||
The following two options are specific to UDP-Lite.
|
||||
.TP
|
||||
.BR UDPLITE_SEND_CSCOV
|
||||
This option sets the sender checksum coverage and takes an
|
||||
.I int
|
||||
as argument, with a checksum coverage value in the range 0..2^16-1.
|
||||
|
||||
A value of 0 means that the entire datagram is always covered.
|
||||
Values from 1-7 are illegal (RFC\ 3828, 3.1) and are rounded up to
|
||||
the minimum coverage of 8.
|
||||
|
||||
With regard to IPv6 jumbograms (RFC\ 2675), the UDP-Litev6 checksum
|
||||
coverage is limited to the first 2^16-1 octets, as per RFC\ 3828, 3.5.
|
||||
Higher values are therefore silently truncated to 2^16-1.
|
||||
If in doubt, the current coverage value can always be queried using
|
||||
.BR getsockopt (2).
|
||||
.TP
|
||||
.BR UDPLITE_RECV_CSCOV
|
||||
This is the receiver-side analogue and uses uses the same argument format
|
||||
and value range as
|
||||
.BR UDPLITE_SEND_CSCOV .
|
||||
This option is not required to enable traffic with partial checksum
|
||||
coverage.
|
||||
Its function is that of a traffic filter: when enabled, it
|
||||
instructs the kernel to drop all packets which have a coverage
|
||||
.I less
|
||||
than the specified coverage value.
|
||||
|
||||
When the value of
|
||||
.B UDPLITE_RECV_CSCOV
|
||||
exceeds the actual packet coverage, incoming packets are silently dropped,
|
||||
but may generate a warning message in the system log.
|
||||
.\" SO_NO_CHECK exists and is supported by UDPv4, but is
|
||||
.\" commented out in socket(7), hence also commented out here
|
||||
.\".PP
|
||||
.\"Since UDP-Lite mandates checksums, checksumming can not be disabled
|
||||
.\"via the
|
||||
.\".B SO_NO_CHECK
|
||||
.\"option from
|
||||
.\".BR socket (7).
|
||||
.SH ERRORS
|
||||
All errors documented for
|
||||
.BR udp (7)
|
||||
may be returned.
|
||||
UDP-Lite does not add further errors.
|
||||
.SH BUGS
|
||||
.\" FIXME . remove this section once glibc supports UDP-Lite
|
||||
Where glibc support is missing, the following definitions are needed:
|
||||
.in +4n
|
||||
.nf
|
||||
|
||||
#define IPPROTO_UDPLITE 136
|
||||
.\" The following two are defined in the kernel in linux/net/udplite.h
|
||||
#define UDPLITE_SEND_CSCOV 10
|
||||
#define UDPLITE_RECV_CSCOV 11
|
||||
.fi
|
||||
.in
|
||||
.SH FILES
|
||||
.I /proc/net/snmp
|
||||
\- basic UDP-Litev4 statistics counters.
|
||||
.br
|
||||
.I /proc/net/snmp6
|
||||
\- basic UDP-Litev6 statistics counters.
|
||||
.SH VERSIONS
|
||||
UDP-Litev4/v6 first appeared in Linux 2.6.20.
|
||||
.SH "SEE ALSO"
|
||||
.BR udp (7),
|
||||
.BR ip (7),
|
||||
.BR ipv6 (7),
|
||||
.BR socket (7)
|
||||
|
||||
RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite)
|
||||
.br
|
||||
.I Documentation/networking/udplite.txt
|
Loading…
Reference in New Issue