[src/trunk]: src/lib/libc/net document the scopeid functions

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/cd255f9bd800
branches:  trunk
changeset: 790721:cd255f9bd800
user:      christos <christos%NetBSD.org@localhost>
date:      Sat Oct 19 19:56:56 2013 +0000

description:
document the scopeid functions

diffstat:

 lib/libc/net/Makefile.inc       |   5 +-
 lib/libc/net/inet6_getscopeid.3 |  83 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+), 2 deletions(-)

diffs (111 lines):

diff -r f0ea9e51d4ed -r cd255f9bd800 lib/libc/net/Makefile.inc
--- a/lib/libc/net/Makefile.inc Sat Oct 19 19:47:55 2013 +0000
+++ b/lib/libc/net/Makefile.inc Sat Oct 19 19:56:56 2013 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile.inc,v 1.84 2013/10/19 00:08:34 christos Exp $
+#      $NetBSD: Makefile.inc,v 1.85 2013/10/19 19:56:56 christos Exp $
 #      @(#)Makefile.inc        8.2 (Berkeley) 9/5/93
 
 # net sources
@@ -120,12 +120,13 @@
 # IPv6
 MAN+=  gai_strerror.3 getaddrinfo.3 getnameinfo.3 if_indextoname.3 \
        inet6_option_space.3 inet6_rthdr_space.3 \
-       inet6_opt_init.3 inet6_rth_space.3
+       inet6_opt_init.3 inet6_rth_space.3 inet6_getscopeid.3
 MLINKS+=getaddrinfo.3 freeaddrinfo.3 \
        getaddrinfo.3 allocaddrinfo.3 \
        getifaddrs.3 freeifaddrs.3 \
        if_indextoname.3 if_nametoindex.3 if_indextoname.3 if_nameindex.3 \
        if_indextoname.3 if_freenameindex.3 \
+       inet6_getscopeid.3 inet6_putscopeid.3 \
        inet6_option_space.3 inet6_option_init.3 \
        inet6_option_space.3 inet6_option_append.3 \
        inet6_option_space.3 inet6_option_alloc.3 \
diff -r f0ea9e51d4ed -r cd255f9bd800 lib/libc/net/inet6_getscopeid.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/net/inet6_getscopeid.3   Sat Oct 19 19:56:56 2013 +0000
@@ -0,0 +1,83 @@
+.\"    $NetBSD: inet6_getscopeid.3,v 1.1 2013/10/19 19:56:56 christos Exp $
+.\"-
+.\" Copyright (c) 2003 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Christos Zoulas.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\"
+.Dd October 19, 2013
+.Dt INET6_GETSCOPEID 3
+.Os
+.\"
+.Sh NAME
+.Nm inet6_getscopeid ,
+.Nm inet6_putscopeid 
+.Nd IPv6 scope id encoding and decoding functions
+.\"
+.Sh SYNOPSIS
+.In netinet/in.h
+.Ft void
+.Fn inet6_getscopeid "struct sockaddr_in6 *sin6" "int flags"
+.Ft void
+.Fn inet6_putscopeid "struct sockaddr_in6 *sin6" "int flags"
+.\"
+.Sh DESCRIPTION
+These functions implement a KAME-specific extension that encodes and
+decodes the scope id inside in the 3rd and 4th byte of the address,
+for link-local, site-local, and multicast-link-local addresses.
+Typically those two bytes are
+.Dv 0
+for these kinds of addresses.
+The scope id is stored in network byte order.
+.Pp
+The
+.Fn inet6_getscopeid
+function retrieves the scope id from the 3rd and the 4th address bytes,
+and sets the
+.Ft sin6_scope_id
+from them.
+It then clears the two address bytes.
+.Pp
+The
+.Fn inet6putscopeid
+function stores the scope id found in
+.Ft sin6_scope_id
+into the 3rd and 4th byte of the address.
+It then clears the
+.Ft sin6_scope_id
+.Pp
+The
+.Fa flags
+argument controls for which addresses this action is performed. It
+can be a combination of:
+.Bl -tag -width "INET6_IS_ADDR_MC_LINKLOCAL"
+.It Dv INET6_IS_ADDR_LINKLOCAL
+.It Dv INET6_IS_ADDR_MC_LINKLOCAL
+.It Dv INET6_IS_ADDR_SITELOCAL
+.El
+.Sh HISTORY
+These functions first appeared in
+.Nx 7 .