[manpages]: First stab at a udplite(7) manpage

[manpages]: First stab at a udplite(7) manpage

[Gerrit Renker]

[-- Attachment #1: Type: text/plain, Size: 382 bytes --]

Hi Michael (cc-ed to list),

as per earlier conversation, I have sat down and assembled a udplite.7
manpage. I have checked it against the conventions (in particular spelling)
mentioned in man-pages(7) and it seems ok.

Since I am rather a groff-newbie, I'd welcome suggestions to improve the
format, the content seems now stable (after a few iterations).

With best regards
Gerrit

[-- Attachment #2: udplite.7 --]
[-- Type: text/plain, Size: 3625 bytes --]

.TH UDPLITE  7 2008-06-23 "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(PF_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,
as it allows to reuse partly damaged frames (with few bit errors).

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 
.B int
as argument, with a checksum coverage value in the range 0..2^16-1.

A value of 0 means that always the entire datagram is 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 not supported.
.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.
.\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
.\" commented out in socket(7), hence also 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. When the value of
.B UDPLITE_RECV_CSCOV
exceeds the actual coverage, incoming packets are silently dropped,
but may generate a warning message in the system log.
.SH BUGS
.\" FIXME: remove this section once glibc supports UDP-Lite
Where glibc support is missing, the following defintions are needed:
.sp
.br
#define IPPROTO_UDPLITE     136
.br
.\" The following two are defined in the kernel in linux/net/udplite.h
#define UDPLITE_SEND_CSCOV  10
.br
#define UDPLITE_RECV_CSCOV  11
.SH FILES
.I /proc/net/snmp 
.br
.IR /proc/net/snmp6
.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

Re: [manpages]: First stab at a udplite(7) manpage

[Michael Kerrisk]

Hi Gerrit,

On Tue, Jun 24, 2008 at 3:36 PM, Gerrit Renker <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org> wrote:
> Hi Michael (cc-ed to list),
>
> as per earlier conversation, I have sat down and assembled a udplite.7
> manpage.

Thanks for that!

> I have checked it against the conventions (in particular spelling)
> mentioned in man-pages(7) and it seems ok.

Yes, it looks good.

> Since I am rather a groff-newbie, I'd welcome suggestions to improve the
> format, the content seems now stable (after a few iterations).

The groff was fine.  I made a few light edits to the page.  I also
added some comments to the page with some "FIXME(gr)" pointing to
places where I think some work is needed.  (I will later pick up the
FIXMEs you had already put in the page, when the glibc support
appears.)  Could you take a look at these?  The modified page is
inline below.

Thanks,

Michael

==============
.\" FIXME(gr) we need a license for this page.
.\" The one I tend to favor is shown in the capabilities.7 page,
.\" but others are also used in man-pages (e.g., GPL, BSD).
.TH UDPLITE  7 2008-06-23 "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(PF_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,
since it makes it possible to reuse partly damaged frames
(with few bit errors).
.\" FIXME(gr) is "reuse" the right word in the previous sentence?
.\" Reading the RFC suggests to me that a better wording might be:
.\"
.\" 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
.B 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 not supported.
.\" FIXME(gr) If higher values are specified, what happens?
.\" If they are silently ignored, probably we should explicitly
.\" say so here.
.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.
.\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
.\" commented out in socket(7), hence also 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.
When the value of
.B UDPLITE_RECV_CSCOV
exceeds the actual coverage, incoming packets are silently dropped,
but may generate a warning message in the system log.
.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
.br
.IR /proc/net/snmp6
.\" FIXME(gr)
.\" Could you add some discussion of the UDPLITE-specific
.\" info in these files?
.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
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [manpages]: First stab at a udplite(7) manpage

[Gerrit Renker]

| 
| The groff was fine.  I made a few light edits to the page.  I also
| added some comments to the page with some "FIXME(gr)" pointing to
| places where I think some work is needed.  
Thanks a lot for the review. It was particularly useful since it brought
to light an unresolved issue: when the coverage > 65535, then unexpected
things will happen since the internal fields are u16 and the
setsockopt() argument is `int'.

Will submit a bug-fix to netdev and resubmit the updated manpage when this
issue has been resolved.

Gerrit

| 
| ==============
| .\" FIXME(gr) we need a license for this page.
| .\" The one I tend to favor is shown in the capabilities.7 page,
| .\" but others are also used in man-pages (e.g., GPL, BSD).
| .TH UDPLITE  7 2008-06-23 "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(PF_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,
| since it makes it possible to reuse partly damaged frames
| (with few bit errors).
| .\" FIXME(gr) is "reuse" the right word in the previous sentence?
| .\" Reading the RFC suggests to me that a better wording might be:
| .\"
| .\" 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
| .B 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 not supported.
| .\" FIXME(gr) If higher values are specified, what happens?
| .\" If they are silently ignored, probably we should explicitly
| .\" say so here.
| .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.
| .\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
| .\" commented out in socket(7), hence also 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.
| When the value of
| .B UDPLITE_RECV_CSCOV
| exceeds the actual coverage, incoming packets are silently dropped,
| but may generate a warning message in the system log.
| .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
| .br
| .IR /proc/net/snmp6
| .\" FIXME(gr)
| .\" Could you add some discussion of the UDPLITE-specific
| .\" info in these files?
| .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
| 

-- 
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [manpages]: First stab at a udplite(7) manpage

[Michael Kerrisk]

On Mon, Jun 30, 2008 at 1:27 PM, Gerrit Renker <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org> wrote:
> |
> | The groff was fine.  I made a few light edits to the page.  I also
> | added some comments to the page with some "FIXME(gr)" pointing to
> | places where I think some work is needed.
> Thanks a lot for the review. It was particularly useful since it brought
> to light an unresolved issue: when the coverage > 65535, then unexpected
> things will happen since the internal fields are u16 and the
> setsockopt() argument is `int'.

Writing man pages tends to turn up bugs pretty often, I find.

> Will submit a bug-fix to netdev and resubmit the updated manpage when this
> issue has been resolved.

Thanks.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [manpages]: First stab at a udplite(7) manpage

[Michael Kerrisk]

Hi Gerrit,

[...]

>> Will submit a bug-fix to netdev and resubmit the updated manpage when this
>> issue has been resolved.

Where are we with udplite.7 then?

Cheers,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [manpages]: First stab at a udplite(7) manpage

[Gerrit Renker]

Quoting Michael Kerrisk:
| Hi Gerrit,
| 
| [...]
| 
| >> Will submit a bug-fix to netdev and resubmit the updated manpage when this
| >> issue has been resolved.
| 
| Where are we with udplite.7 then?
| 
Not forgotten. Patch was submitted to netdev@vger on Monday 30th June, which 
tried to handle the illegal values consistently, i.e. return EINVAL for
 * values between 1..7 (illegal as per RFC 3828, 3.1);
 * values greater than 65535 (since IPv6 jumbograms are not supported as
   per RFC 3828, 3.5 and since the u16 value internally wraps around to 1..7).

The reply came back on Sat 5 July asking not to return EINVAL in the first case.

I haven't submitted a new patch so far since I was asking for input regarding 
these cases. Maybe someone has a good suggestion regarding this?

I will either re-post this on netdev very soon or work on a new patch.
But can't submit manpage while the API is still not clear.

Copy of email posted to netdev on Mon 7 July:
> Can I just clarify illegal checksum values, as there are two different cases:
> 
>  (a) Values between 1..7 
>      The specification marks these as illegal in RFC 3828, sec. 3.1.
>      The Linux UDP-Lite API allowed the user to get away with these illegal 
>      coverage values and documented this fact in udplite.txt. Since I am guilty
>      of having written this file, I can add that I am not aware that the same 
>      behaviour is specified in another place -- other than RFC 3828.
> 
>  (b) Values greater than 0xFFFF
>      The UDP-Lite checksum coverage field has the same u16 size as the
>      UDP Length field but, in contrast, IPv6 jumbograms are not supported
>      (RFC 3828, 3.5). This means that checksum coverage values greater than
>      65535 are undefined. 
>      Since the internal field is u16 and since the setsockopt() argument
>      is `int', there is a need to protect against this range, not only 
>      since the wrap-around can again cause values in the range 1..7.
>        
> Can you and/or other people please provide input what to do API-wise in
> the two above cases, since this information is needed for the manpage also?
> 
> These options come to mind:
> 
>   (1) Keep behaviour for (a), return EINVAL for (b).
>   (2) Keep behaviour for (a) and silently ignore values > 0xffff by
>       replacing these with "full coverage" (0) - problematic if 
>       negative values were supplied.
>   (3) Return EINVAL in both cases (as sketched by the patch).
>   (4) Other alternative?

Regards
Gerrit
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[manpages]: Version 2 of a udplite(7) manpage

[Gerrit Renker]

[-- Attachment #1: Type: text/plain, Size: 491 bytes --]

Michael,

can you please have a look at the revised version of the udplite(7) manpage?

The main changes are:
 * the patch correcting the behaviour for large checksum coverages (> 0xffff)
   has been accepted by Dave Miller into the netdev-2.6 tree and pushed to -stable;
 * this behaviour has been documented (truncation to maximum value);
 * also attached is an rcsdiff where the responses to your Fixme's are good to see;
 * the rest is minor editorial changes.

With best regards
Gerrit

[-- Attachment #2: rcsdiff_udplite.7_since_review.diff --]
[-- Type: text/x-diff, Size: 4832 bytes --]

--- udplite.7	2008/06/27 19:09:22	1.6
+++ udplite.7	2008/07/23 15:22:34
@@ -1,7 +1,28 @@
-.\" FIXME(gr) we need a license for this page.
-.\" The one I tend to favor is shown in the capabilities.7 page,
-.\" but others are also used in man-pages (e.g., GPL, BSD).
-.TH UDPLITE  7 2008-06-23 "Linux" "Linux Programmer's Manual"
+.\" Copyright (c) 2008 by Gerrit Renker <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org>
+.\"
+.\" 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-07-23 "Linux" "Linux Programmer's Manual"
 .SH NAME
 udplite \- Lightweight User Datagram Protocol
 .SH SYNOPSIS
@@ -18,15 +39,9 @@
 
 UDP-Lite is an extension of UDP (RFC\ 768) to support variable-length
 checksums.
-This has advantages for some types of multimedia transport,
-since it makes it possible to reuse partly damaged frames
-(with few bit errors).
-.\" FIXME(gr) is "reuse" the right word in the previous sentence?
-.\" Reading the RFC suggests to me that a better wording might be:
-.\"
-.\" 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.
+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)
@@ -68,16 +83,15 @@
 .B 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
+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 not supported.
-.\" FIXME(gr) If higher values are specified, what happens?
-.\" If they are silently ignored, probably we should explicitly
-.\" say so here.
+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
@@ -89,6 +103,11 @@
 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.
 .\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
 .\" commented out in socket(7), hence also here ???
 .\".PP
@@ -102,10 +121,6 @@
 .BR udp (7)
 may be returned.
 UDP-Lite does not add further errors.
-When the value of
-.B UDPLITE_RECV_CSCOV
-exceeds the actual coverage, incoming packets are silently dropped,
-but may generate a warning message in the system log.
 .SH BUGS
 .\" FIXME: remove this section once glibc supports UDP-Lite
 Where glibc support is missing, the following definitions are needed:
@@ -120,11 +135,10 @@
 .in
 .SH FILES
 .I /proc/net/snmp
+\- basic UDP-Litev4 statistics counters.
 .br
-.IR /proc/net/snmp6
-.\" FIXME(gr)
-.\" Could you add some discussion of the UDPLITE-specific
-.\" info in these files?
+.I /proc/net/snmp6
+\- basic UDP-Litev6 statistics counters.
 .SH VERSIONS
 UDP-Litev4/v6 first appeared in Linux 2.6.20.
 .SH "SEE ALSO"
@@ -136,4 +150,3 @@
 RFC\ 3828 for the Lightweight User Datagram Protocol (UDP-Lite)
 .br
 .I Documentation/networking/udplite.txt
-

[-- Attachment #3: udplite.7 --]
[-- Type: text/plain, Size: 5075 bytes --]

.\" Copyright (c) 2008 by Gerrit Renker <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org>
.\"
.\" 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-07-23 "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(PF_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
.B 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.
.\" FIXME: SO_NO_CHECK exists and is supported by UDPv4, but is
.\" commented out in socket(7), hence also 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

Re: [manpages]: Version 2 of a udplite(7) manpage

[Michael Kerrisk]

Gerrit,

Gerrit Renker wrote:
> Michael,
> 
> can you please have a look at the revised version of the udplite(7) manpage?
> 
> The main changes are:
>  * the patch correcting the behaviour for large checksum coverages (> 0xffff)
>    has been accepted by Dave Miller into the netdev-2.6 tree and pushed to -stable;
>  * this behaviour has been documented (truncation to maximum value);

Okay.

>  * also attached is an rcsdiff where the responses to your Fixme's are good to see;

Thanks for that -- much easier to see what you did in response to my comments.

>  * the rest is minor editorial changes.

Yep.

Thanks for this revision.  I made one or two small edits.  The most notable
is that I changed PF_INET to AF_INET in the SYNOPSIS.  (As fas as POSIX.1
is concerned, the PF_* constants are obsolete, in favour of the AF_*
constants with the same value.)  I think we're good to go otherwise, and
I'll include this page in man-pages-3.07, unless you think some further work
still needs to be done.

Cheers,

Michael

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [manpages]: Version 2 of a udplite(7) manpage

[Michael Kerrisk]

[Restored linux-man to CC]

Hi Gerrit,

On Fri, Aug 8, 2008 at 1:05 PM,  <gerrit-VsoRXqaLlyfQzY9nttDBhA@public.gmane.org> wrote:
> Hi Michael,
>
>> I made one or two small edits.  The most notable
>> is that I changed PF_INET to AF_INET in the SYNOPSIS.  (As fas as POSIX.1
>> is concerned, the PF_* constants are obsolete, in favour of the AF_*
>> constants with the same value.)  I think we're good to go otherwise, and
>> I'll include this page in man-pages-3.07, unless you think some further
>> work still needs to be done.
>>
> I can't think of further work items at the moment.

Good.  udplite.7 will be in man-pages-3.07.  Thanks for writing it!

> Thank you for the AF/PF
> clarification, something which continues to confuse me (and likely others).
>
> Since I copied the example from udp(7), would it make sense to extend this
> update to that manpage as well? A quick check in tcp(7) and ip(7), raw(7),
> socket(7) showed that somehow the AF/PF ambiguity appears in other places
> as well (netlink(7) is likely not Posix).

Yes, it's been one of those nagging little tasks I've been meaning to
do for a while.  (My reluctance has been in part about whether I
should "erase history" -- the pseudo-distinction between AF_ and PF_
is longstanding, but has also been meaningless since the beginning.)
So, you're comment finally prompted me to do it.  In man-pages-3.07,
everything is now AF_*.

Thanks

Michael




-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html
Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html