doc getsockopt, setsockopt

doc getsockopt, setsockopt

[Kevin Ryde]

I'm looking to combine the getsockopt and setsockopt descriptions and
add the available constants, including the new IP_ADD_MEMBERSHIP and
IP_DROP_MEMBERSHIP, especially since you need to know to pass a pair
for those (and for SO_LINGER).

I'm not sure if SOL_IP is meant to be used directly.  You'd think so
from the name, but the getsockopt man page refers to getprotoent().  I
think I'll change socket.c from IPPROTO_IP to SOL_IP.  The two are the
same value, but best to ensure the code matches the docs.


 -- Scheme Procedure: getsockopt sock level optname
 -- Scheme Procedure: setsockopt sock level optname value
 -- C Function: scm_getsockopt (sock, level, optname)
 -- C Function: scm_setsockopt (sock, level, optname, value)
     Get or set an option on socket port SOCK.  `getsockopt' returns
     the current value.  `setsockopt' sets a value and the return is
     unspecified.

     LEVEL is an integer specifying a protocol layer.  The following
     values are defined (when provided by the system),

      -- Variable: SOL_SOCKET
      -- Variable: SOL_IP
      -- Variable: SOL_TCP
      -- Variable: SOL_UDP

     OPTNAME is an integer specifying an option within the protocol
     layer.

     For `SOL_SOCK' level the following OPTNAMEs are defined (when
     provided by the system).  For what they mean see *note
     Socket-Level Options: (libc)Socket-Level Options, or `man 7
     socket'.

      -- Variable: SO_DEBUG
      -- Variable: SO_REUSEADDR
      -- Variable: SO_STYLE
      -- Variable: SO_TYPE
      -- Variable: SO_ERROR
      -- Variable: SO_DONTROUTE
      -- Variable: SO_BROADCAST
      -- Variable: SO_SNDBUF
      -- Variable: SO_RCVBUF
      -- Variable: SO_KEEPALIVE
      -- Variable: SO_OOBINLINE
      -- Variable: SO_NO_CHECK
      -- Variable: SO_PRIORITY
          The VALUE taken or returned is an integer.

      -- Variable: SO_LINGER
          The VALUE taken or returned is a pair of integers `(ENABLE .
          TIMEOUT)'.  On old systems without timeout support (ie.
          without `struct linger'), only ENABLE has an effect, but the
          value in Guile is still a pair.

     For `SOL_IP' level the following options are defined (when
     provided by the system).  See `man 7 ip' for what they mean.

      -- Variable: IP_ADD_MEMBERSHIP
      -- Variable: IP_DROP_MEMBERSHIP
          These can be used only with `setsockopt', not `getsockopt'.
          VALUE is a pair of integer IPv4 addresses `(MULTIADDR .
          INTERFACEADDR)' (*note Network Address Conversion::).


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: doc getsockopt, setsockopt

[Greg Troxel]

Kevin Ryde <user42@zip.com.au> writes:

> I'm looking to combine the getsockopt and setsockopt descriptions and
> add the available constants, including the new IP_ADD_MEMBERSHIP and
> IP_DROP_MEMBERSHIP, especially since you need to know to pass a pair
> for those (and for SO_LINGER).

Thanks (I sent in IP_ADD_MEMBERSHIP without doc fixes...).

> I'm not sure if SOL_IP is meant to be used directly.  You'd think so
> from the name, but the getsockopt man page refers to getprotoent().

I'm guessing you mean 'the man page on some version of Linux', but I
checked on NetBSD-current, and it says the same thing.

I read NetBSD-current kernel sources, and the basic system call checks
against SO_SOCKET, and if so processes the setsockopt.  Otherwise, it
dispatches to the protocol control output routine for the protocol of
the socket.  In the UDP control output routine, it checks against
IPPROTO_UDP and if so handles it there, and if not forwards to
ip_ctloutput.  ip_ctloutput insists on level IPPROTO_IP.

NetBSD does not define SOL_IP.  SOL_SOCKET is 0xffff.  So from the
NetBSD point of view, the right thing to do is define
IPPROTO_{IP,UDP,TCP} as (constant) variables.

NetBSD's Linux compatibility code indicates that SOL_IP is 0, but has
a comment that these values can vary by architecture (details FWIW,
which I think is not much):

in compat/linux/socket.h:

#define LINUX_SOL_IP            0
#define LINUX_SOL_TCP           6
#define LINUX_SOL_UDP           17

src/sys/compat/linux > egrep LINUX_SOL_SOCKET arch/*/*
arch/alpha/linux_socket.h:#define LINUX_SOL_SOCKET      0xffff
arch/amd64/linux_socket.h:#define LINUX_SOL_SOCKET      1
arch/arm/linux_socket.h:#define LINUX_SOL_SOCKET        1
arch/i386/linux_socket.h:#define LINUX_SOL_SOCKET       1
arch/m68k/linux_socket.h:#define LINUX_SOL_SOCKET       1
arch/mips/linux_socket.h:#define LINUX_SOL_SOCKET       0xffff
arch/powerpc/linux_socket.h:#define LINUX_SOL_SOCKET 1

> I think I'll change socket.c from IPPROTO_IP to SOL_IP.  The two are
> the same value, but best to ensure the code matches the docs.

I think the docs are wrong here, and SOL_IP is not defined on NetBSD
and thus may be Linux specific.

After defining IPPRPOTO_{IP,UDP,TCP} as variables, it seems like
removing SOL_IP, SOL_TCP and SOL_UDP is in order, since they aren't
portable and guile should behave the same on all machines to the
extent possible/reasonable.

It would be interesting to hear what variables the Linux kernel
actually compares to - IPPROTO_IP or SOL_IP.

>      For `SOL_IP' level the following options are defined (when
>      provided by the system).  See `man 7 ip' for what they mean.

'man 7 ip' is Linux specific (it's ip(4) on BSD).  Perhaps "Consult
operating system documentation for these calls".

Hmm, I would have thought UDP, but my code (for which I added these)
says '0' for level, which is IPPROTO_IP.

>       -- Variable: IP_ADD_MEMBERSHIP
>       -- Variable: IP_DROP_MEMBERSHIP
>           These can be used only with `setsockopt', not `getsockopt'.
>           VALUE is a pair of integer IPv4 addresses `(MULTIADDR .
>           INTERFACEADDR)' (*note Network Address Conversion::).

How about just adding:

MULTIADDR is the multicast group to be joined or left, and
INTERFACEADDR is an IP adddress by which an interface will be found to
perform the join/leave operation.  INTERFACEADDR may be INADDR_ANY in
which case the default interface will be used. These values are simply
passed to the underlying system call, so extensions on some systems to
specify interface by ifindex may be available.

Or skip the last sentence, or the second half of it.  People who
understand specifying interfaces by ifindex will hopefully realize the
portability issues of that.

-- 
        Greg Troxel <gdt@ir.bbn.com>


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: doc getsockopt, setsockopt

[Kevin Ryde]

Greg Troxel <gdt@ir.bbn.com> writes:
>
> NetBSD does not define SOL_IP.  SOL_SOCKET is 0xffff.  So from the
> NetBSD point of view, the right thing to do is define
> IPPROTO_{IP,UDP,TCP} as (constant) variables.

The posix spec at
http://www.opengroup.org/onlinepubs/007904975/functions/getsockopt.html
gives IPPROTO_TCP as an example, so yep, I'll remove the SOL bits in
favour of IPPROTO.

I'd noticed in the past the gnu/linux "man 5 protocols" says to use
/etc/protocols instead of numbers like IPPROTO, but what posix says
must trump that.

> NetBSD's Linux compatibility code indicates that SOL_IP is 0, but has
> a comment that these values can vary by architecture

That should be ok, we don't care about the actual values as long as
the constants are right.

> It would be interesting to hear what variables the Linux kernel
> actually compares to - IPPROTO_IP or SOL_IP.

Oh, well, there should be a better spec for the programming interface
than digging around the sources :-).

> 'man 7 ip' is Linux specific (it's ip(4) on BSD).  Perhaps "Consult
> operating system documentation for these calls".

Thanks, I'll put "man ip" (there should be only one).

> MULTIADDR is the multicast group to be joined or left, and
> INTERFACEADDR is an IP adddress by which an interface will be found to
> perform the join/leave operation.  INTERFACEADDR may be INADDR_ANY in
> which case the default interface will be used. These values are simply
> passed to the underlying system call, so extensions on some systems to
> specify interface by ifindex may be available.

Sounds fair.

> Or skip the last sentence, or the second half of it.  People who
> understand specifying interfaces by ifindex will hopefully realize the
> portability issues of that.

Do you need to know about host vs network byte order to get it
through?  That would be something to note.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: doc getsockopt, setsockopt

[Greg Troxel]

Kevin Ryde <user42@zip.com.au> writes:

> Greg Troxel <gdt@ir.bbn.com> writes:
>
> I'd noticed in the past the gnu/linux "man 5 protocols" says to use
> /etc/protocols instead of numbers like IPPROTO, but what posix says
> must trump that.

I think getprotobyname is supposed to return IANA-allocated protocol
numbers, so while 'posix rulz' is a great attitude and one I share,
there's no real conflict.

> > NetBSD's Linux compatibility code indicates that SOL_IP is 0, but has
> > a comment that these values can vary by architecture
> 
> That should be ok, we don't care about the actual values as long as
> the constants are right.

True; I was just trying to point out the complexity I found in case it
mattered later.

> Do you need to know about host vs network byte order to get it
> through?  That would be something to note.

Yes, but I think it's the same as all other bind/etc. calls.

I just pass the result of 

(define *ssp-addr* (inet-aton "224.0.x.y")) ;not registered

so it's host order, like all the other calls.  Docs for bind,
connect and send don't mention this though.

-- 
        Greg Troxel <gdt@ir.bbn.com>


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: doc getsockopt, setsockopt

[Kevin Ryde]

Greg Troxel <gdt@ir.bbn.com> writes:
>
> so it's host order, like all the other calls.  Docs for bind,
> connect and send don't mention this though.

There's a note in "Network Address Conversion" where ipv4 addrs are
described.  Hopefully a cross reference to it is enough, unless
there's something especially zany happening.


About IP_ADD_MEMBERSHIP: In linux I see there's a separate imr_ifindex
in struct ip_mreqn for an interface index.  Do you need/want to do
anything with that?  (I've never used this stuff, so I've got no idea
if it's good for anything or what it should look like.)


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: doc getsockopt, setsockopt

[Greg Troxel]

Kevin Ryde <user42@zip.com.au> writes:

> There's a note in "Network Address Conversion" where ipv4 addrs are
> described.  Hopefully a cross reference to it is enough, unless
> there's something especially zany happening.

Sounds good.  These calls aren't odd from the htonl viewpoint.

> About IP_ADD_MEMBERSHIP: In linux I see there's a separate imr_ifindex
> in struct ip_mreqn for an interface index.  Do you need/want to do
> anything with that?  (I've never used this stuff, so I've got no idea
> if it's good for anything or what it should look like.)

It is useful, but complex.  Here's the full story:

 When joining a multicast group, you have to specify the group
(straightforward), and some way to specify the interface.  The struct
ip_mreq dates from BSD long long ago (multicast patches to 4.3 in late
80s I think).  The second IP address is INADDR_ANY for "use the
default interface (found by looking up the group in the routing table,
almost always hitting the default route)", or an address used to find
an interface, usually by it being an address of some interface.  At
some point the BSDs added the convention that 0.0.0.x would refer to
the interface with ifindex x, and this follows RFC1724, which provides
for this method of referring to unnumered interfaces in the RIPv2 MIB.
This was added to NetBSD in early 2001:
  http://mail-index.netbsd.org/tech-net/2001/01/13/0003.html

Specifying by ifindex is useful for unnumbered interfaces, for example
joining the ospf all routers group on a ppp link with no IPv4
addresses, or addresses reused from some other interface.  Normal
programs don't do this - it's typically a routing protocol
implementation  issue.

My understanding is that Linux has an additional field to specify by
ifindex (the imr_ifindex you mention).  So, the right thing to do for
guile is to either

  follow the BSD way, and translate 0.0.0.x/8 in the second arg into
  setting imr_ifindex on Linux.

  follow the Linux way, and make it a vector of 3 and translate back
  into the 0.0.0.x/8 on BSD.

I prefer the first way, since this is orginally a BSD interface and
because it's less burdensome to those who are blissfully unaware of
this complexity, as I suspect you wish you still were.

The code I submitted just puts the two addresses in the two fields;
someone could spiff it up for ifindex support on Linux if they were so
inclined.  I suspect the need will not arise, given how long guile
went without being able to join groups at all.

-- 
        Greg Troxel <gdt@ir.bbn.com>


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: doc getsockopt, setsockopt

[Kevin Ryde]

Greg Troxel <gdt@ir.bbn.com> writes:
>
>   follow the BSD way, and translate 0.0.0.x/8 in the second arg into
>   setting imr_ifindex on Linux.
>
>   follow the Linux way, and make it a vector of 3 and translate back
>   into the 0.0.0.x/8 on BSD.
>
> I prefer the first way, since this is orginally a BSD interface and
> because it's less burdensome

Is there a good reason for linux to split it out?  Some ambiguity
resolved or something?

> those who are blissfully unaware of this complexity, as I suspect
> you wish you still were.

Yep :-).

> The code I submitted just puts the two addresses in the two fields;
> someone could spiff it up for ifindex support on Linux if they were so
> inclined.

Be nice to make sure it worked at least.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel

Re: doc getsockopt, setsockopt

[Greg Troxel]

Kevin Ryde <user42@zip.com.au> writes:

> Greg Troxel <gdt@ir.bbn.com> writes:
> >
> >   follow the BSD way, and translate 0.0.0.x/8 in the second arg into
> >   setting imr_ifindex on Linux.
> >
> >   follow the Linux way, and make it a vector of 3 and translate back
> >   into the 0.0.0.x/8 on BSD.
> >
> > I prefer the first way, since this is orginally a BSD interface and
> > because it's less burdensome
> 
> Is there a good reason for linux to split it out?  Some ambiguity
> resolved or something?

I don't know the reasoning behind the linux decision, or whether it
happened before or after BSD used ifindex.  NetBSD tries very hard to
have binary compatibility, so adding semantics for what are otherwise
wacky addresses was easier than versioning the ioctl so the old one
could still work.  It's perhaps cleaner not to overload the interface
address field, but IMHO the binary compat issues are more important.

> > The code I submitted just puts the two addresses in the two fields;
> > someone could spiff it up for ifindex support on Linux if they were so
> > inclined.
> 
> Be nice to make sure it worked at least.

It's likely that it will work on Linux for joining via interface
addresses, and that's 99% of the likely usage.  But it could use an
memset of the struct ip_mreq to 0.  I didn't realize Linux had added
an ifindex field when I wrote the code.




-- 
        Greg Troxel <gdt@ir.bbn.com>


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-devel