Bug 18132

Summary: ipv6(7) describes IP_PKTINFO, but should be IP_RECVPKTINFO instead
Product: Documentation Reporter: Cameron Kerr (cameron)
Component: man-pagesAssignee: documentation_man-pages (documentation_man-pages)
Status: RESOLVED CODE_FIX    
Severity: high CC: alan, cameron, mtk.manpages, xerofoify
Priority: P1    
Hardware: All   
OS: Linux   
Kernel Version: 2.6.32 Subsystem:
Regression: No Bisected commit-id:
Attachments: Small wrapper library around recvmsg

Description Cameron Kerr 2010-09-09 06:26:37 UTC
Created attachment 29412 [details]
Small wrapper library around recvmsg

According to the ipv6(7) manual page:

       IPV6_PKTINFO
              Set delivery of the IPV6_PKTINFO  control  message  on  incoming
              datagrams.   Only  allowed  for  SOCK_DGRAM or SOCK_RAW sockets.
              Argument is a pointer to a boolean value in an integer.

COLOPHON
       This page is part of release 3.23 of the Linux  man-pages  project.   A
       description  of  the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.

(This is on Ubuntu 10.04, 32-bit)

Thus, the following code should work, assuming an IPv6 UDP socket has been created:

int on = 1
setsockopt(sock, IPPROTO_IPV6, IPV6_PKTINFO, &on, sizeof on)

Yet, instead we see that the system call fails, with errno saying EINVAL. Here is strace output demonstrating this:

socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDP) = 3
bind(3, {sa_family=AF_INET6, sin6_port=htons(8421), inet_pton(AF_INET6, "::", &sin6_addr), sin6_flowinfo=0, sin6_scope_id=0}, 28) = 0
setsockopt(3, SOL_IPV6, IPV6_PKTINFO, [1], 4) = -1 EINVAL (Invalid argument)

According to Steven's Unix Network Programming, volume 1 (third ed.), in section 7.2, which lists a set of socket options, there is an IPV6_RECVPKTINFO, as well as things like IPV6_RECVHOPLIMIT and others, which are different to the ones without the RECV sub-prefix. From the description therein, it would appear that IPV6_PKTINFO is a "sticky" option (I haven't read much into that).

cscope verifies that they are indeed different on this system:

(in netinet/in.h)

#define IPV6_RECVPKTINFO        49
#define IPV6_PKTINFO            50
#define IPV6_RECVHOPLIMIT       51
#define IPV6_HOPLIMIT           52

Using IPV6_RECVPKTINFO, we get the following strace

socket(PF_INET6, SOCK_DGRAM, IPPROTO_UDP) = 3
bind(3, {sa_family=AF_INET6, sin6_port=htons(8421), inet_pton(AF_INET6, "::", &sin6_addr), sin6_flowinfo=0, sin6_scope_id=0}, 28) = 0
setsockopt(3, SOL_IPV6, 0x31 /* IPV6_??? */, [1], 4) = 0
recvmsg(3, {msg_name(28)={sa_family=AF_INET6, sin6_port=htons(41202), inet_pton(AF_INET6, "::1", &sin6_addr), sin6_flowinfo=0, sin6_scope_id=0}, msg_iov(1)=[{"hi\n\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0"..., 128}], msg_controllen=32, {cmsg_len=32, cmsg_level=SOL_IPV6, cmsg_type=, ...}, msg_flags=0}, 0) = 3


recvfrom_detailed returned value 3
  source family 10 address ::1 port 41202
  destination family 10 address ::1
Comment 1 Cameron Kerr 2010-09-09 06:47:45 UTC
RFC3542 explains this newer API, so I guess the bugs section of the ipv6 manual page needs to be updated also. Particularly, the "2.2 kernel" makes it seem very out-dated; should it say "since the 2.2 kernel"?

BUGS
       The  IPv6  extended  API as in RFC 2292 is currently only partly impleā€
       mented; although the 2.2 kernel has near complete support for receiving
       options,  the  macros  for generating IPv6 options are missing in glibc
       2.1.


RFC3542 Section 4.2, "UDP and Raw Socket Implications", gives a description of the IPV6_RECVxxx options and the rationale for the "sticky" options.


It would seem that strace is also outdated in this respect.
Comment 3 Michael Kerrisk 2015-05-05 19:43:41 UTC
This issue has been address by a seaparate fix, some time ago

man-pages commit d796c68d5ab6dc10c3737e40305b1ee23d7b0adc
Author: Bert Hubert <bert.hubert@netherlabs.nl>
Date:   Sun Oct 21 12:51:33 2012 +0200

    ipv6.7: Document IPV6_RECVPKTINFO

I believe the man page nowadays addresses the concerns of this bug report, so I'm closing. Please reopen, if you believe otherwise.