d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Submitted by: George V. Neville-Neil (gnn at freebsd dot org)

Browse Source 
Reviewed by: Kame Project (including Itojun-san, Jinmei-san and Suzuki-san)
Approved by: Robert Watson (robert at freebsd dot org)
Obtained from:	Kame Project and OpenBSD

Replace manual pages that may have violated the IETF's Copyright.

All come from the Kame tree.

Several were from OpenBSD except for ip6.4, and the inet6* pages which were
rewritten by me.

All of the text is new and drawn from reading the code and
documentation.
This commit is contained in:
George V. Neville-Neil 2005-01-23 16:02:48 +00:00
parent 16417879f1
commit 6617cf5778
9 changed files with 3040 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
lib/libc/net/gai_strerror.3 Normal file
View File

@ -0,0 +1,94 @@
.\" $KAME: gai_strerror.3,v 1.1 2005/01/05 03:04:47 itojun Exp $
.\" $OpenBSD: gai_strerror.3,v 1.4 2004/12/20 23:04:53 millert Exp $
.\" $FreeBSD$
.\"
.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd December 20, 2004
.Dt GAI_STRERROR 3
.Os
.Sh NAME
.Nm gai_strerror
.Nd get error message string from EAI_xxx error code
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Fd #include <netdb.h>
.Ft "const char *"
.Fn gai_strerror "int ecode"
.Sh DESCRIPTION
The
.Fn gai_strerror
function returns an error message string corresponding to the error code
returned by
.Xr getaddrinfo 3
or
.Xr getnameinfo 3 .
.Pp
The following error codes and their meaning are defined in
.Aq Pa netdb.h :
.Pp
.Bl -tag -width "EAI_ADDRFAMILYXX" -offset indent -compact
.It Dv EAI_ADDRFAMILY
address family for
.Fa hostname
not supported
.It Dv EAI_AGAIN
temporary failure in name resolution
.It Dv EAI_BADFLAGS
invalid value for
.Fa ai_flags
.It Dv EAI_BADHINTS
invalid value for
.Fa hints
.It Dv EAI_FAIL
non-recoverable failure in name resolution
.It Dv EAI_FAMILY
.Fa ai_family
not supported.
.It Dv EAI_MEMORY
memory allocation failure
.It Dv EAI_NODATA
no address associated with
.Fa hostname
.It Dv EAI_NONAME
.Fa hostname
or
.Fa servname
not provided, or not known
.It Dv EAI_PROTOCOL
resolved protocol is unknown
.It Dv EAI_SERVICE
.Fa servname
not supported for
.Fa ai_socktype
.It Dv EAI_SOCKTYPE
.Fa ai_socktype
not supported
.It Dv EAI_SYSTEM
system error returned in
.Va errno
.El
.Sh RETURN VALUES
.Fn gai_strerror
returns a pointer to the error message string corresponding to
.Fa ecode .
If
.Fa ecode
is out of range, an implementation-specific error message string is returned.
.Sh SEE ALSO
.Xr getaddrinfo 3 ,
.Xr getnameinfo 3

435
lib/libc/net/getaddrinfo.3 Normal file
View File

@ -0,0 +1,435 @@
.\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
.\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
.\" $FreeBSD$
.\"
.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd December 20, 2004
.Dt GETADDRINFO 3
.Os
.Sh NAME
.Nm getaddrinfo ,
.Nm freeaddrinfo
.Nd socket address structure to host and service name
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Fd #include <netdb.h>
.Ft int
.Fn getaddrinfo "const char *hostname" "const char *servname" \
"const struct addrinfo *hints" "struct addrinfo **res"
.Ft void
.Fn freeaddrinfo "struct addrinfo *ai"
.Sh DESCRIPTION
The
.Fn getaddrinfo
function is used to get a list of
.Tn IP
addresses and port numbers for host
.Fa hostname
and service
.Fa servname .
It is a replacement for and provides more flexibility than the
.Xr gethostbyname 3
and
.Xr getservbyname 3
functions.
.Pp
The
.Fa hostname
and
.Fa servname
arguments are either pointers to NUL-terminated strings or the null pointer.
An acceptable value for
.Fa hostname
is either a valid host name or a numeric host address string consisting
of a dotted decimal IPv4 address or an IPv6 address.
The
.Fa servname
is either a decimal port number or a service name listed in
.Xr services 5 .
At least one of
.Fa hostname
and
.Fa servname
must be non-null.
.Pp
.Fa hints
is an optional pointer to a
.Li struct addrinfo ,
as defined by
.Aq Pa netdb.h :
.Bd -literal
struct addrinfo {
int ai_flags; /* input flags */
int ai_family; /* protocol family for socket */
int ai_socktype; /* socket type */
int ai_protocol; /* protocol for socket */
socklen_t ai_addrlen; /* length of socket-address */
struct sockaddr *ai_addr; /* socket-address for socket */
char *ai_canonname; /* canonical name for service location */
struct addrinfo *ai_next; /* pointer to next in list */
};
.Ed
.Pp
This structure can be used to provide hints concerning the type of socket
that the caller supports or wishes to use.
The caller can supply the following structure elements in
.Fa hints :
.Bl -tag -width "ai_socktypeXX"
.It Fa ai_family
The protocol family that should be used.
When
.Fa ai_family
is set to
.Dv PF_UNSPEC ,
it means the caller will accept any protocol family supported by the
operating system.
.It Fa ai_socktype
Denotes the type of socket that is wanted:
.Dv SOCK_STREAM ,
.Dv SOCK_DGRAM ,
or
.Dv SOCK_RAW .
When
.Fa ai_socktype
is zero the caller will accept any socket type.
.It Fa ai_protocol
Indicates which transport protocol is desired,
.Dv IPPROTO_UDP
or
.Dv IPPROTO_TCP .
If
.Fa ai_protocol
is zero the caller will accept any protocol.
.It Fa ai_flags
.Fa ai_flags
is formed by
.Tn OR Ns 'ing
the following values:
.Bl -tag -width "AI_CANONNAMEXX"
.It Dv AI_CANONNAME
If the
.Dv AI_CANONNAME
bit is set, a successful call to
.Fn getaddrinfo
will return a NUL-terminated string containing the canonical name
of the specified hostname in the
.Fa ai_canonname
element of the first
.Li addrinfo
structure returned.
.It Dv AI_NUMERICHOST
If the
.Dv AI_NUMERICHOST
bit is set, it indicates that
.Fa hostname
should be treated as a numeric string defining an IPv4 or IPv6 address
and no name resolution should be attempted.
.It Dv AI_PASSIVE
If the
.Dv AI_PASSIVE
bit is set it indicates that the returned socket address structure
is intended for use in a call to
.Xr bind 2 .
In this case, if the
.Fa hostname
argument is the null pointer, then the IP address portion of the
socket address structure will be set to
.Dv INADDR_ANY
for an IPv4 address or
.Dv IN6ADDR_ANY_INIT
for an IPv6 address.
.Pp
If the
.Dv AI_PASSIVE
bit is not set, the returned socket address structure will be ready
for use in a call to
.Xr connect 2
for a connection-oriented protocol or
.Xr connect 2 ,
.Xr sendto 2 ,
or
.Xr sendmsg 2
if a connectionless protocol was chosen.
The
.Tn IP
address portion of the socket address structure will be set to the
loopback address if
.Fa hostname
is the null pointer and
.Dv AI_PASSIVE
is not set.
.El
.El
.Pp
All other elements of the
.Li addrinfo
structure passed via
.Fa hints
must be zero or the null pointer.
.Pp
If
.Fa hints
is the null pointer,
.Fn getaddrinfo
behaves as if the caller provided a
.Li struct addrinfo
with
.Fa ai_family
set to
.Dv PF_UNSPEC
and all other elements set to zero or
.Dv NULL .
.Pp
After a successful call to
.Fn getaddrinfo ,
.Fa *res
is a pointer to a linked list of one or more
.Li addrinfo
structures.
The list can be traversed by following the
.Fa ai_next
pointer in each
.Li addrinfo
structure until a null pointer is encountered.
The three members
.Fa ai_family,
.Fa ai_socktype,
and
.Fa ai_protocol
in each returned
.Li addrinfo
structure are suitable for a call to
.Xr socket 2 .
For each
.Li addrinfo
structure in the list, the
.Fa ai_addr
member points to a filled-in socket address structure of length
.Fa ai_addrlen .
.Pp
This implementation of
.Fn getaddrinfo
allows numeric IPv6 address notation with scope identifier,
as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
By appending the percent character and scope identifier to addresses,
one can fill the
.Li sin6_scope_id
field for addresses.
This would make management of scoped addresses easier
and allows cut-and-paste input of scoped addresses.
.Pp
At this moment the code supports only link-local addresses with the format.
The scope identifier is hardcoded to the name of the hardware interface
associated
with the link
.Po
such as
.Li ne0
.Pc .
An example is
.Dq Li fe80::1%ne0 ,
which means
.Do
.Li fe80::1
on the link associated with the
.Li ne0
interface
.Dc .
.Pp
The current implementation assumes a one-to-one relationship between
the interface and link, which is not necessarily true from the specification.
.Pp
All of the information returned by
.Fn getaddrinfo
is dynamically allocated: the
.Li addrinfo
structures themselves as well as the socket address structures and
the canonical host name strings included in the
.Li addrinfo
structures.
.Pp
Memory allocated for the dynamically allocated structures created by
a successful call to
.Fn getaddrinfo
is released by the
.Fn freeaddrinfo
function.
The
.Fa ai
pointer should be a
.Li addrinfo
structure created by a call to
.Fn getaddrinfo .
.Sh RETURN VALUES
.Fn getaddrinfo
returns zero on success or one of the error codes listed in
.Xr gai_strerror 3
if an error occurs.
.Sh EXAMPLES
The following code tries to connect to
.Dq Li www.kame.net
service
.Dq Li http
via a stream socket.
It loops through all the addresses available, regardless of address family.
If the destination resolves to an IPv4 address, it will use an
.Dv AF_INET
socket.
Similarly, if it resolves to IPv6, an
.Dv AF_INET6
socket is used.
Observe that there is no hardcoded reference to a particular address family.
The code works even if
.Fn getaddrinfo
returns addresses that are not IPv4/v6.
.Bd -literal -offset indent
struct addrinfo hints, *res, *res0;
int error;
int s;
const char *cause = NULL;
memset(&hints, 0, sizeof(hints));
hints.ai_family = PF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
error = getaddrinfo("www.kame.net", "http", &hints, &res0);
if (error) {
errx(1, "%s", gai_strerror(error));
/*NOTREACHED*/
}
s = -1;
for (res = res0; res; res = res->ai_next) {
s = socket(res->ai_family, res->ai_socktype,
res->ai_protocol);
if (s < 0) {
cause = "socket";
continue;
}
if (connect(s, res->ai_addr, res->ai_addrlen) < 0) {
cause = "connect";
close(s);
s = -1;
continue;
}
break; /* okay we got one */
}
if (s < 0) {
err(1, "%s", cause);
/*NOTREACHED*/
}
freeaddrinfo(res0);
.Ed
.Pp
The following example tries to open a wildcard listening socket onto service
.Dq Li http ,
for all the address families available.
.Bd -literal -offset indent
struct addrinfo hints, *res, *res0;
int error;
int s[MAXSOCK];
int nsock;
const char *cause = NULL;
memset(&hints, 0, sizeof(hints));
hints.ai_family = PF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags = AI_PASSIVE;
error = getaddrinfo(NULL, "http", &hints, &res0);
if (error) {
errx(1, "%s", gai_strerror(error));
/*NOTREACHED*/
}
nsock = 0;
for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) {
s[nsock] = socket(res->ai_family, res->ai_socktype,
res->ai_protocol);
if (s[nsock] < 0) {
cause = "socket";
continue;
}
if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) {
cause = "bind";
close(s[nsock]);
continue;
}
(void) listen(s[nsock], 5);
nsock++;
}
if (nsock == 0) {
err(1, "%s", cause);
/*NOTREACHED*/
}
freeaddrinfo(res0);
.Ed
.Sh SEE ALSO
.Xr bind 2 ,
.Xr connect 2 ,
.Xr send 2 ,
.Xr socket 2 ,
.Xr gai_strerror 3 ,
.Xr gethostbyname 3 ,
.Xr getnameinfo 3 ,
.Xr getservbyname 3 ,
.Xr resolver 3 ,
.Xr hosts 5 ,
.Xr resolv.conf 5 ,
.Xr services 5 ,
.Xr hostname 7 ,
.Xr named 8
.Rs
.%A R. Gilligan
.%A S. Thomson
.%A J. Bound
.%A J. McCann
.%A W. Stevens
.%T Basic Socket Interface Extensions for IPv6
.%R RFC 3493
.%D February 2003
.Re
.Rs
.%A S. Deering
.%A B. Haberman
.%A T. Jinmei
.%A E. Nordmark
.%A B. Zill
.%T "IPv6 Scoped Address Architecture"
.%R internet draft
.%N draft-ietf-ipv6-scoping-arch-02.txt
.%O work in progress material
.Re
.Rs
.%A Craig Metz
.%T Protocol Independence Using the Sockets API
.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
.%D June 2000
.Re
.Sh STANDARDS
The
.Fn getaddrinfo
function is defined by the
.St -p1003.1g-2000
draft specification and documented in
.Dv "RFC 3493" ,
.Dq Basic Socket Interface Extensions for IPv6 .
.Sh BUGS
The implementation of
.Fn getaddrinfo
is not thread-safe.

271
lib/libc/net/getnameinfo.3 Normal file
View File

@ -0,0 +1,271 @@
.\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $
.\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc Exp $
.\" $FreeBSD$
.\"
.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd December 20, 2004
.Dt GETNAMEINFO 3
.Os
.Sh NAME
.Nm getnameinfo
.Nd socket address structure to hostname and service name
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Fd #include <netdb.h>
.Ft int
.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" \
"size_t hostlen" "char *serv" "size_t servlen" "int flags"
.Sh DESCRIPTION
The
.Fn getnameinfo
function is used to convert a
.Li sockaddr
structure to a pair of host name and service strings.
It is a replacement for and provides more flexibility than the
.Xr gethostbyaddr 3
and
.Xr getservbyport 3
functions and is the converse of the
.Xr getaddrinfo 3
function.
.Pp
The
.Li sockaddr
structure
.Fa sa
should point to either a
.Li sockaddr_in
or
.Li sockaddr_in6
structure (for IPv4 or IPv6 respectively) that is
.Fa salen
bytes long.
.Pp
The host and service names associated with
.Fa sa
are stored in
.Fa host
and
.Fa serv
which have length parameters
.Fa hostlen
and
.Fa servlen .
The maximum value for
.Fa hostlen
is
.Dv NI_MAXHOST
and
the maximum value for
.Fa servlen
is
.Dv NI_MAXSERV ,
as defined by
.Aq Pa netdb.h .
If a length parameter is zero, no string will be stored.
Otherwise, enough space must be provided to store the
host name or service string plus a byte for the NUL terminator.
.Pp
The
.Fa flags
argument is formed by
.Tn OR Ns 'ing
the following values:
.Bl -tag -width "NI_NUMERICHOSTXX"
.It Dv NI_NOFQDN
A fully qualified domain name is not required for local hosts.
The local part of the fully qualified domain name is returned instead.
.It Dv NI_NUMERICHOST
Return the address in numeric form, as if calling
.Xr inet_ntop 3 ,
instead of a host name.
.It Dv NI_NAMEREQD
A name is required.
If the host name cannot be found in DNS and this flag is set,
a non-zero error code is returned.
If the host name is not found and the flag is not set, the
address is returned in numeric form.
.It NI_NUMERICSERV
The service name is returned as a digit string representing the port number.
.It NI_DGRAM
Specifies that the service being looked up is a datagram
service, and causes
.Xr getservbyport 3
to be called with a second argument of
.Dq udp
instead of its default of
.Dq tcp .
This is required for the few ports (512\-514) that have different services
for
.Tn UDP
and
.Tn TCP .
.El
.Pp
This implementation allows numeric IPv6 address notation with scope identifier,
as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
IPv6 link-local address will appear as a string like
.Dq Li fe80::1%ne0 .
Refer to
.Xr getaddrinfo 3
for more information.
.Sh RETURN VALUES
.Fn getnameinfo
returns zero on success or one of the error codes listed in
.Xr gai_strerror 3
if an error occurs.
.Sh EXAMPLES
The following code tries to get a numeric host name, and service name,
for a given socket address.
Observe that there is no hardcoded reference to a particular address family.
.Bd -literal -offset indent
struct sockaddr *sa; /* input */
char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) {
errx(1, "could not get numeric hostname");
/*NOTREACHED*/
}
printf("host=%s, serv=%s\en", hbuf, sbuf);
.Ed
.Pp
The following version checks if the socket address has a reverse address mapping:
.Bd -literal -offset indent
struct sockaddr *sa; /* input */
char hbuf[NI_MAXHOST];
if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0,
NI_NAMEREQD)) {
errx(1, "could not resolve hostname");
/*NOTREACHED*/
}
printf("host=%s\en", hbuf);
.Ed
.Sh SEE ALSO
.Xr gai_strerror 3 ,
.Xr getaddrinfo 3 ,
.Xr gethostbyaddr 3 ,
.Xr getservbyport 3 ,
.Xr inet_ntop 3 ,
.Xr resolver 3 ,
.Xr hosts 5 ,
.Xr resolv.conf 5 ,
.Xr services 5 ,
.Xr hostname 7 ,
.Xr named 8
.Rs
.%A R. Gilligan
.%A S. Thomson
.%A J. Bound
.%A W. Stevens
.%T Basic Socket Interface Extensions for IPv6
.%R RFC 2553
.%D March 1999
.Re
.Rs
.%A S. Deering
.%A B. Haberman
.%A T. Jinmei
.%A E. Nordmark
.%A B. Zill
.%T "IPv6 Scoped Address Architecture"
.%R internet draft
.%N draft-ietf-ipv6-scoping-arch-02.txt
.%O work in progress material
.Re
.Rs
.%A Craig Metz
.%T Protocol Independence Using the Sockets API
.%B "Proceedings of the freenix track: 2000 USENIX annual technical conference"
.%D June 2000
.Re
.Sh STANDARDS
The
.Fn getnameinfo
function is defined by the
.St -p1003.1g-2000
draft specification and documented in
.Tn "RFC 2553" ,
.Dq Basic Socket Interface Extensions for IPv6 .
.Sh CAVEATS
.Fn getnameinfo
can return both numeric and FQDN forms of the address specified in
.Fa sa .
There is no return value that indicates whether the string returned in
.Fa host
is a result of binary to numeric-text translation (like
.Xr inet_ntop 3 ) ,
or is the result of a DNS reverse lookup.
Because of this, malicious parties could set up a PTR record as follows:
.Bd -literal -offset indent
1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1
.Ed
.Pp
and trick the caller of
.Fn getnameinfo
into believing that
.Fa sa
is
.Li 10.1.1.1
when it is actually
.Li 127.0.0.1 .
.Pp
To prevent such attacks, the use of
.Dv NI_NAMEREQD
is recommended when the result of
.Fn getnameinfo
is used
for access control purposes:
.Bd -literal -offset indent
struct sockaddr *sa;
socklen_t salen;
char addr[NI_MAXHOST];
struct addrinfo hints, *res;
int error;
error = getnameinfo(sa, salen, addr, sizeof(addr),
NULL, 0, NI_NAMEREQD);
if (error == 0) {
memset(&hints, 0, sizeof(hints));
hints.ai_socktype = SOCK_DGRAM; /*dummy*/
hints.ai_flags = AI_NUMERICHOST;
if (getaddrinfo(addr, "0", &hints, &res) == 0) {
/* malicious PTR record */
freeaddrinfo(res);
printf("bogus PTR record\en");
return -1;
}
/* addr is FQDN as a result of PTR lookup */
} else {
/* addr is numeric string */
error = getnameinfo(sa, salen, addr, sizeof(addr),
NULL, 0, NI_NUMERICHOST);
}
.Ed
.Sh BUGS
The implementation of
.Fn getnameinfo
is not thread-safe.
.\".Pp
.\".Ox
.\"intentionally uses a different
.\".Dv NI_MAXHOST
.\"value from what
.\".Tn "RFC 2553"
.\"suggests, to avoid buffer length handling mistakes.

337
lib/libc/net/inet6_opt_init.3 Normal file
View File

@ -0,0 +1,337 @@
.\" $KAME: inet6_opt_init.3,v 1.7 2004/12/27 05:08:23 itojun Exp $
.\" $FreeBSD$
.\"
.\" Copyright (C) 2004 WIDE Project.
.\" All rights reserved.
.\"
.\" 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.
.\" 3. Neither the name of the project nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 December 23, 2004
.Dt INET6_OPT_INIT 3
.Os
.\"
.Sh NAME
.Nm inet6_opt_init ,
.Nm inet6_opt_append ,
.Nm inet6_opt_finish ,
.Nm inet6_opt_set_val ,
.Nm inet6_opt_next ,
.Nm inet6_opt_find ,
.Nm inet6_opt_get_val
.Nd IPv6 Hop-by-Hop and Destination Options manipulation
.\"
.Sh SYNOPSIS
.In netinet/in.h
.Ft "int"
.Fn inet6_opt_init "void *extbuf" "socklen_t extlen"
.Ft "int"
.Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t len" "u_int8_t align" "void **databufp"
.Ft "int"
.Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset"
.Ft "int"
.Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen"
.Ft "int"
.Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t *typep" "socklen_t *lenp" "void **databufp"
.Ft "int"
.Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t *lenp" "void **databufp"
.Ft "int"
.Fn inet6_opt_get_val "void *databuf" "socklen_t offset" "void *val" "socklen_t vallen"
.\"
.Sh DESCRIPTION
Building and parsing the Hop-by-Hop and Destination options is
complicated.
The advanced sockets API defines a set of functions to
help applications create and manipulate Hop-by-Hope and Destination
options.
.\"This man page describes the functions specified in
.\"IETF Draft RFC3542 while the
.\".Xr inet6_options_space 3
.\"man page documents the functions defined in RFC 2292.
.\"It is expected
.\"that this set of functions will supersede those in RFC 2292 but for
.\"the time being both APIs are retained.
These functions use the
formatting rules specified in Appendix B in RFC2460, i.e., that the
largest field is placed last in the option.
The function prototypes
for these functions are all contained in the
.In netinet/in.h
header file.
.\"
.Ss inet6_opt_init
The
.Fn inet6_opt_init
function
returns the number of bytes needed for an empty
extension header, one without any options.
If the
.Va extbuf
argument points to a valid section of memory
then the
.Fn inet6_opt_init
function also initializes the extension header's length field.
When attempting to initialize an extension buffer passed in the
.Va extbuf argument
.Fa extlen
must be a positive multiple of 8 or else the function fails and
returns \-1 to the caller.
.\"
.Ss inet6_opt_append
The
.Fn inet6_opt_append
function can perform to different jobs.
When a valid
.Fa extbuf
argument is supplied it appends an option to the extension buffer and
returns the updated total length as well as a pointer to the newly
created option in
.Fa databufp .
If the value
of
.Fa extbuf
is
.Dv NULL
then the
.Fn inet6_opt_append function only reports what the total length would
be if the option were actually appended.
The
.Fa len
and
.Fa align
arguments specify the length of the option and the required data
alignment which must be used when appending the option.
The
.Fa offset
argument should be the length returned by the
.Fn inet6_opt_init
function or a previous call to
.Fn inet6_opt_append .
.Pp
The
.Fa type
argument is the 8-bit option type.
.Pp
After
.Fn inet6_opt_append
has been called, the application can use the buffer pointed to by
.Fa databufp
directly, or use
.Fn inet6_opt_set_val
to specify the data to be contained in the option.
.Pp
Option types of
.Li 0
and
.Li 1
are reserved for the
.Li Pad1
and
.Li PadN
options.
All other values from 2 through 255 may be used by applications.
.Pp
The length of the option data is contained in an 8-bit value and so
may contain any value from 0 through 255.
.Pp
The
.Fa align
parameter must have a value of 1, 2, 4, or 8 and cannot exceed the
value of
.Fa len .
The alignment values represent no alignment, 16 bit, 32 bit and 64 bit
alignments respectively.
.\"
.Ss inet6_opt_finish
The
.Fn inet6_opt_finish
calculates the final padding necessary to make the extension header a
multiple of 8 bytes, as required by the IPv6 extension header
specification, and returns the extension header's updated total
length.
The
.Fa offset
argument should be the length returned by
.Fn inet6_opt_init
or
.Fn inet6_opt_append .
When
.Fa extbuf
is not
.Dv NULL
the function also sets up the appropriate padding bytes by inserting a
Pad1 or PadN option of the proper length.
.Pp
If the extension header is too small to contain the proper padding
then an error of \-1 is returned to the caller.
.\"
.Ss inet6_opt_set_val
The
.Fn inet6_opt_set_val
function inserts data items of various sizes into the data portion of
the option.
The
.Fa databuf
argument is a pointer to memory that was returned by the
.Fn inet6_opt_append
call and the
.Fa offset argument specifies where the option should be placed in the
data buffer.
The
.Fa val
argument points to an area of memory containing the data to be
inserted into the extension header, and the
.Fa vallen
argument indicates how much data to copy.
.Pp
The caller should ensure that each field is aligned on its natural
boundaries as described in Appendix B of RFC2460.
.Pp
The function returns the offset for the next field which is calculated as
.Fa offset
+
.Fa vallen
and is used when composing options with multiple fields.
.\"
.Ss inet6_opt_next
The
.Fn inet6_opt_next
function parses received extension headers.
The
.Fa extbuf
and
.Fa extlen
arguments specify the location and length of the extension header
being parsed.
The
.Fa offset
argument should either be zero, for the first option, or the length value
returned by a previous call to
.Fn inet6_opt_next
or
.Fn inet6_opt_find .
The return value specifies the position where to continue scanning the
extension buffer.
The option is returned in the arguments
.Fa typep , lenp ,
and
.Fa databufp .
.Fa typep, lenp,
and
.Fa databufp
point to the 8-bit option type, the 8-bit option length and the option
data respectively.
This function does not return any PAD1 or PADN options.
When an error occurs or there are no more options the return
value is \-1.
.\"
.Ss inet6_opt_find
The
.Fn inet6_opt_find
function searches the extension buffer for a particular option type,
passed in through the
.Fa type
argument.
If the option is found then the
.Fa lenp
and
.Fa databufp
arguments are updated to point to the option's length and data
respectively.
.Fa extbuf
and
.Fa extlen
must point to a valid extension buffer and give its length.
The
.Fa offset
argument can be used to search from a location anywhere in the
extension header.
.Ss inet6_opt_get_val
The
.Fn inet6_opt_get_val
function extracts data items of various sizes in the data portion of
the option.
The
.Fa databuf
is a pointer returned by the
.Fn inet6_opt_next
or
.Fn inet6_opt_find
functions.
The
.Fa val
argument points where the data will be extracted.
The
.Fa offset
argument specifies from where in the data portion of the option the
value should be extracted; the first byte of option data is specified
by an offset of zero.
.Pp
It is expected that each field is aligned on its natural boundaries as
described in Appendix B of RFC2460.
.Pp
The function returns the offset for the next field
by calculating
.Fa offset
+
.Fa vallen
which can be used when extracting option content with multiple fields.
Robust receivers must verify alignment before calling this function.
.\"
.Sh DIAGNOSTICS
All the functions return
\-1
on an error.
.\"
.Sh EXAMPLES
RFC3542 gives comprehensive examples in Section 23.
.Pp
KAME also provides examples in the
.Pa advapitest
directory of its kit.
.\"
.Sh SEE ALSO
.Rs
.%A W. Stevens
.%A M. Thomas
.%A E. Nordmark
.%A T. Jinmei
.%T "Advanced Sockets API for IPv6"
.%N RFC3542
.%D October 2002
.Re
.Rs
.%A S. Deering
.%A R. Hinden
.%T "Internet Protocol, Version 6 (IPv6) Specification"
.%N RFC2460
.%D December 1998
.Re
.Sh HISTORY
The implementation first appeared in KAME advanced networking kit.
.Sh STANDARDS
The functions are documented in
.Dq Advanced Sockets API for IPv6
.Pq RFC3542 .
.\"

434
lib/libc/net/inet6_option_space.3 Normal file
View File

@ -0,0 +1,434 @@
.\" $KAME: inet6_option_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
.\" $FreeBSD$
.\"
.\" Copyright (C) 2004 WIDE Project.
.\" All rights reserved.
.\"
.\" 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.
.\" 3. Neither the name of the project nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 December 23, 2004
.Dt INET6_OPTION_SPACE 3
.Os
.\"
.Sh NAME
.Nm inet6_option_space ,
.Nm inet6_option_init ,
.Nm inet6_option_append ,
.Nm inet6_option_alloc ,
.Nm inet6_option_next ,
.Nm inet6_option_find
.Nd IPv6 Hop-by-Hop and Destination Option Manipulation
.\"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/types.h
.In netinet/in.h
.Ft "int"
.Fn inet6_option_space "int nbytes"
.Ft "int"
.Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
.Ft "int"
.Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
.Ft "u_int8_t *"
.Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
.Ft "int"
.Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
.Ft "int"
.Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
.\"
.Sh DESCRIPTION
.\"
Manipulating and parsing IPv6's Hop-by-Hop and Destination options is
complicated by the need to properly align and pad data as well as the
need to manipulate ancillary information that is not part of the data
stream.
RFC2292 defines a set of functions, which are implemented as
part of the Kame libraries, to support help developers create, change,
and parse Hop-by-Hope and Destination options.
All of the prototypes
for the option functions are defined in the
.In netinet/in.h
header file.
.\"
.Ss inet6_option_space
In order to determine the amount of space necessary to hold any option
the
.Fn inet6_option_space
function is called.
It returns the number of bytes required to hold
an option when it is stored as ancillary data, including the
.Li cmsghdr
structure at the beginning, and any necessary padding at the end.
The
.Li nbytes
argument indicates the size of the structure defining the option,
and must include any pad bytes at the beginning (the value
.Li y
in the alignment term
.Dq Li "xn + y" ) ,
the type byte, the length byte, and the option data.
.Pp
Note: If multiple options are stored in a single ancillary data
object, which is the recommended technique, the
.Fn inet6_option_space
function overestimates the amount of space required by the size of
.Li N-1
.Li cmsghdr
structures, where
.Li N
is the number of options to be stored in the object.
Usually this has
no impact because it is assumed that most Hop-by-Hop and Destination
option headers carry only one option as indicated in appendix B of RFC2460.
.\"
.Ss inet6_option_init
The
.Fn inet6_option_init
function is called to initialize any ancillary data object that will contain
a Hop-by-Hop or Destination option.
It returns
.Li 0
on success and
.Li -1
when an error occurs.
.Pp
The
.Fa bp
argument points to a previously allocated area of memory which must be
large enough to contain all the arguments that the application indents
to add later via
.Fn inet6_option_append
and
.Fn inet6_option_alloc
routines.
.Pp
The
.Fa cmsgp
argument is a pointer to a pointer to a
.Li cmsghdr
structure.
The
.Fa *cmsgp
argument
points to a
.Li cmsghdr
structure which is constructed by this function and stored in the
area of memory pointed to by
.Fa bp .
.Pp
The
.Fa type
is either
.Dv IPV6_HOPOPTS
or
.Dv IPV6_DSTOPTS
and is stored in the
.Li cmsg_type
member of the
.Li cmsghdr
structure mentioned above.
.\"
.Ss inet6_option_append
This function appends a Hop-by-Hop option or a Destination option into
an ancillary data object previously initialized by a call to
.Fn inet6_option_init .
The
.Fn inet6_option_append function returns
.Li 0
if it succeeds or
.Li -1
when an error occurs.
.Pp
The
.Fa cmsg
argument is a pointer to the
.Li cmsghdr
structure that was initialized by a call to
.Fn inet6_option_init .
.Pp
The
.Fa typep
argument is a pointer to the 8-bit option type.
All options are
encoded as type-length-value tuples and it is assumed that
the
.Fa typep
field is immediately followed by the 8-bit option data length field,
which is then followed by the option data.
.Pp
The option types of
.Li 0
and
.Li 1 are reserved for the
.Li Pad1
and
.Li PadN
options respectively.
All other values from
.Li 2
through
.Li 255
are available for applications to use.
.Pp
The option data length, since it is stored in 8 bites, must have a
value between
.Li 0
and
.Li 255 ,
inclusive.
.Pp
The
.Fa multx
argument
is the value
.Li x
in the alignment term
.Dq Li xn + y
and indicates the byte alignment necessary for the data.
Alignments may be specified as
.Li 1 ,
.Li 2 ,
.Li 4 ,
or
.Li 8
bytes, which is no alignment, 16 bit, 32 bit and 64 bit alignments
respectively.
.Pp
The
.Fa plusy
argument
is the value
.Li y
in the alignment term
.Dq Li xn + y
and must have a value between
.Li 0
and
.Li 7 ,
inclusive, indicating the amount of padding that is necessary for an
option.
.\"
.Ss inet6_option_alloc
The
.Fn inet6_option_alloc
function appends a Hop-by-Hop option or a Destination option into an
ancillary data object that has previously been initialized by a call to
.Fn inet6_option_init .
The
.Fn inet6_option_alloc
function returns a pointer to the 8-bit option type field that at the
beginning of the allocated the option on success, or
.Dv NULL
on an error.
.Pp
The difference between the
.Fn inet6_option_alloc
and
.Fn inet6_option_append
functions is that the latter copies the contents of a previously built
option into the ancillary data object while the former returns a
pointer to the place in the data object where the option's TLV must
then be built by the application.
.Pp
The
.Fa cmsg
argument is a pointer to a
.Li cmsghdr
structure that was initialized by
.Fn inet6_option_init .
.Pp
The
.Fa datalen
argument is the value of the option data length byte for this option.
This value is required as an argument to allow the function to
determine if padding must be appended at the end of the option.
(The
.Fn inet6_option_append
function does not need a data length argument
since the option data length must already be stored by the caller)
.Pp
The
.Fa multx
and
.Fa plusy
arguments
are identical to the arguments of the same name described in the
.Fn inet6_option_init
function above.
.\"
.Ss inet6_option_next
The
.Fn inet6_option_next
function is used to process Hop-by-Hop and Destination options that
are present in an ancillary data object.
When an option remains to
be processed, the return value of the
.Fn inet6_option_next
function is
.Li 0
and the
.Fa *tptrp
argument points to the 8-bit option type field, which is followed by
the 8-bit option data length, and then the option data.
When no more
options remain to be processed, the return value is
.Li -1
and
.Fa *tptrp
is
.Dv NULL
and when an error occurs, the return value is
.Li -1
but the
.Fa *tptrp
argument is not
.Dv NULL .
This set of return values allows a program to easily loop through all
the options in an ancillary data object, checking for the error and
end of stream conditions along the way.
.Pp
When a valid option is returned the
.Fa cmsg
argument points to a
.Li cmsghdr
where the
.Li cmsg_level
equals
.Dv IPPROTO_IPV6
and
.Li cmsg_type
is either
.Dv IPV6_HOPOPTS
or
.Dv IPV6_DSTOPTS .
.Pp
The
.Fa tptrp
argument is a pointer to a pointer to an 8-bit byte and
.Fa *tptrp
is used by the function to remember its place in the ancillary data
object each time the function is called.
When the
.Fn inet6_option_next
function is called for the first time on a given ancillary data object,
.Fa *tptrp
must be set to
.Dv NULL .
.Pp
Each time the function returns success,
the
.Fa *tptrp
argument points to the 8-bit option type field for the next option to
be processed.
.\"
.Ss inet6_option_find
The
.Fn inet6_option_find
function allows an application to search for a particular option type
in an ancillary data object.
The
.Fa cmsg
argument is a pointer to
.Li cmsghdr
structure in which the
.Li cmsg_level
element equals
.Dv IPPROTO_IPV6
and the
.Li cmsg_type
element is either
.Dv IPV6_HOPOPTS
or
.Dv IPV6_DSTOPTS .
.Pp
The
.Fa tptrp
argument is handled exactly as in the
.Fn inet6_option_next
function described above.
.Pa
The
.fn inet6_option_find
function starts searching for an option of the specified type
beginning after the value of
.Fa *tptrp .
.\"
.Sh DIAGNOSTICS
The
.Fn inet6_option_init
and
.Fn inet6_option_append
functions return
.Li 0
on success or
.Li -1
on an error.
.Pp
The
.Fn inet6_option_alloc
function returns
.Dv NULL
on an error.
.Pp
When
.Fn inet6_option_next
or
.Fn inet6_option_find
detect an error they return
.Li -1
setting
.Fa *tptrp
to non
.Dv NULL
value.
.\"
.Sh EXAMPLES
RFC2292 gives comprehensive examples in chapter 6.
.\"
.Sh SEE ALSO
.Rs
.%A W. Stevens
.%A M. Thomas
.%T "Advanced Sockets API for IPv6"
.%N RFC2292
.%D February 1998
.Re
.Rs
.%A S. Deering
.%A R. Hinden
.%T "Internet Protocol, Version 6 (IPv6) Specification"
.%N RFC2460
.%D December 1998
.Re
.\"
.Sh HISTORY
The implementation first appeared in KAME advanced networking kit.
.\"
.Sh STANDARDS
The functions are documented in
.Dq Advanced Sockets API for IPv6
(RFC2292).
.\"

223
lib/libc/net/inet6_rth_space.3 Normal file
View File

@ -0,0 +1,223 @@
.\" $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 itojun Exp $
.\" $FreeBSD$
.\"
.\" Copyright (C) 2004 WIDE Project.
.\" All rights reserved.
.\"
.\" 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.
.\" 3. Neither the name of the project nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 December 24, 2004
.Dt INET6_RTH_SPACE 3
.Os
.\"
.Sh NAME
.Nm inet6_rth_space ,
.Nm inet6_rth_init ,
.Nm inet6_rth_add ,
.Nm inet6_rth_reverse ,
.Nm inet6_rth_segments ,
.Nm inet6_rth_getaddr
.Nd IPv6 Routing Header Options manipulation
.\"
.Sh SYNOPSIS
.In netinet/in.h
.Ft socklen_t
.Fn inet6_rth_space "int" "int"
.Ft "void *"
.Fn inet6_rth_init "void *" "socklen_t" "int" "int"
.Ft int
.Fn inet6_rth_add "void *" "const struct in6_addr *"
.Ft int
.Fn inet6_rth_reverse "const void *" "void *"
.Ft int
.Fn inet6_rth_segments "const void *"
.Ft "struct in6_addr *"
.Fn inet6_rth_getaddr "const void *" "int"
.\"
.Sh DESCRIPTION
The IPv6 Advanced API, RFC 3542, defines the functions that an
application calls to build and examine IPv6 Routing headers.
Routing headers are used to perform source routing in IPv6 networks.
The RFC uses the word
.Dq segments
to describe addresses and that is the term used here as well.
All of the functions are defined in the
.In netinet/in.h
header file.
The functions described in this manual page all operate
on routing header structures which are defined in
.In netinet/ip6.h
but which should not need to be modified outside the use of this API.
The size and shape of the route header structures may change, so using
the APIs is a more portable, long term, solution.
.Pp
The functions in the API are split into two groups, those that build a
routing header and those that parse a received routing header.
We will describe the builder functions followed by the parser functions.
.Ss inet6_rth_space
The
.Fn inet6_rth_space
function returns the number of bytes required to hold a Routing Header
of the type, specified in the
.Fa type
argument and containing the number of addresses specified in the
.Fa segments
argumment.
When the type is
.Dv IPV6_RTHDR_TYPE_0
the number of segments must be from 0 through 127.
Routing headers of type
.Dv IPV6_RTHDR_TYPE_2
contain only one segment, and are only used with Mobile IPv6.
The return value from this function is the number of bytes required to
store the routing header.
If the value 0 is returned then either the
route header type was not recognized or another error occurred.
.Ss inet6_rth_init
The
.Fn inet6_rth_init
function initializes the pre-allocated buffer pointed to by
.Fa bp
to contain a routing header of the specified type The
.Fa bp_len
argument is used to verify that the buffer is large enough.
The caller must allocate the buffer pointed to by bp.
The necessary buffer size should be determined by calling
.Fn inet6_rth_space
described in the previous sections.
.Pp
The
.Fn inet6_rth_init
function returns a pointer to
.Fa bp
on success and
.Dv NULL
when there is an error.
.Ss inet6_rth_add
The
.Fn inet6_rth_add
function adds the IPv6 address pointed to by
.Fa addr
to the end of the routing header being constructed.
.Pp
A successful addition results in the function returning 0, otherwise
\-1 is returned.
.Ss inet6_rth_reverse
The
.Fn inet6_rth_reverse
function takes a routing header, pointed to by the
argument
.Fa in ,
and writes a new routing header into the argument pointed to by
.Fa out .
The routing header at that sends datagrams along the reverse of that
route.
Both arguments are allowed to point to the same buffer meaning
that the reversal can occur in place.
.Pp
The return value of the function is 0 on success, or \-1 when
there is an error.
.\"
.Pp
The next set of functions operate on a routing header that the
application wants to parse.
In the usual case such a routing header
is received from the network, although these functions can also be
used with routing headers that the application itself created.
.Ss inet6_rth_segments
The
.Fn inet6_rth_segments
function returns the number of segments contained in the
routing header pointed to by
.Fa bp .
The return value is the number of segments contained in the routing
header, or \-1 if an error occurred.
It is not an error for 0 to be
returned as a routing header may contain 0 segments.
.\"
.Ss inet6_rth_getaddr
The
.Fn inet6_rth_getaddr
function is used to retrieve a single address from a routing header.
The
.Fa index
is the location in the routing header from which the application wants
to retrieve an address.
The
.Fa index
parameter must have a value between 0 and one less than the number of
segments present in the routing header.
The
.Fn inet6_rth_segments
function, described in the last section, should be used to determine
the total number of segments in the routing header.
The
.Fn inet6_rth_getaddr
function returns a pointer to an IPv6 address on success or
.Dv NULL
when an error has occurred.
.\"
.Sh DIAGNOSTICS
The
.Fn inet6_rth_space
and
.Fn inet6_rth_getaddr
functions return 0 on errors.
.Pp
The
.Fn inet6_rthdr_init
function returns
.Dv NULL
on error.
The
.Fn inet6_rth_add
and
.Fn inet6_rth_reverse
functions return 0 on success, or \-1 upon an error.
.\"
.Sh EXAMPLES
RFC 3542 gives extensive examples in Section 21, Appendix B.
.Pp
KAME also provides examples in the advapitest directory of its kit.
.\"
.Sh SEE ALSO
.Rs
.%A W. Stevens
.%A M. Thomas
.%A E. Nordmark
.%A T. Jinmei
.%T "Advanced Sockets API for IPv6"
.%N RFC 3542
.%D May 2003
.Re
.Rs
.%A S. Deering
.%A R. Hinden
.%T "Internet Protocol, Version 6 (IPv6) Specification"
.%N RFC2460
.%D December 1998
.Re
.Sh HISTORY
The implementation first appeared in KAME advanced networking kit.

305
lib/libc/net/inet6_rthdr_space.3 Normal file
View File

@ -0,0 +1,305 @@
.\" $KAME: inet6_rthdr_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $
.\" $FreeBSD$
.\"
.\" Copyright (C) 2004 WIDE Project.
.\" All rights reserved.
.\"
.\" 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.
.\" 3. Neither the name of the project nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 December 27, 2004
.Dt INET6_RTHDR_SPACE 3
.Os
.\"
.Sh NAME
.Nm inet6_rthdr_space ,
.Nm inet6_rthdr_init ,
.Nm inet6_rthdr_add ,
.Nm inet6_rthdr_lasthop ,
.Nm inet6_rthdr_reverse ,
.Nm inet6_rthdr_segments ,
.Nm inet6_rthdr_getaddr ,
.Nm inet6_rthdr_getflags
.Nd IPv6 Routing Header Options Manipulation
.\"
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/types.h
.In netinet/in.h
.Ft size_t
.Fn inet6_rthdr_space "int type" "int segments"
.Ft "struct cmsghdr *"
.Fn inet6_rthdr_init "void *bp" "int type"
.Ft int
.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags"
.Ft int
.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags"
.Ft int
.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out"
.Ft int
.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg"
.Ft "struct in6_addr *"
.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index"
.Ft int
.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index"
.\"
.Sh DESCRIPTION
.\"The RFC 2292 IPv6 Advanced API has been deprecated in favor of the
.\"newer, RFC 3542 APIs.
.\"On platforms that support it, currently only
.\"FreeBSD, please use the newer API to manipulate routing header
.\"options.
.\".Pp
The RFC 2292 IPv6 Advanced API defined eight functions for
applications to use for building and parsing routing headers.
The
eight functions are split into two groups, the first of which builds
the header and the second of which can parse it.
The function prototypes for these functions are all in the
.In netinet/in.h
header.
Although direct manipulation of a routing header is possible
this set of APIs make it unnecessary and such direct manipulation
should be avoided so that changes to the underlying structures do not
break applications.
.Pp
Please note that RFC 2292 uses the term
.Dq segments
instead of the term
.Dq addresses
but they are considered equivalent for this manual page.
.\"
.Ss inet6_rthdr_space
The
.Fn inet6_rthdr_space
function returns the number of bytes required to hold a routing header
of the specified
.Fa type
and containing the specified number of
.Fa segments .
Only one
.Fa type
is supported,
.Dv IPV6_RTHDR_TYPE_0 ,
and it can hold from 1 to 23 segments.
The return value includes the
size of the cmsghdr structure that precedes the routing header, and
any required padding.
.Pp
A return value of 0 indicates an error.
Either the type was specified
incorrectly, or the number of segments was less than one or greater
than 23.
.Pp
Note: The
.Fn inet6_rthdr_space
function only returns the size required by the routing header and does
not allocate memory for the caller.
.\"
.Ss inet6_rthdr_init
The
.Fn inet6_rthdr_init
function initializes a buffer, pointed to by
.Fa bp
with an appropriate
.Li cmsghdr
structure followed by a routing header of the specified
.Fa type .
.Pp
The caller must use the
.Fn inet6_rthdr_space
function to determine the size of the buffer, and then allocate that
buffer before calling
.Fn inet6_rthdr_init .
.Pp
The return value is a pointer to a
.Li cmsghdr
structure, which is used as the first argument to the
.Fn inet6_rthdr_add
and
.Fn inet6_rthdr_lasthop
functions in order to construct the routing header.
When an error occurs the return value is
.Dv NULL .
.\"
.Ss inet6_rthdr_add
The
.Fn inet6_rthdr_add
function adds the IPv6 address pointed to by
.Fa addr
to the end of the
routing header being constructed and sets the type of this address to the
value of
.Fa flags .
The
.Fa flags
must be either
.Dv IPV6_RTHDR_LOOSE
or
.Dv IPV6_RTHDR_STRICT
indicating whether loose or strict source routing is required.
.Pp
When the function succeeds it returns 0, otherwise \-1 is returned.
.\"
.Ss inet6_rthdr_lasthop
The
.Fn inet6_rthdr_lasthop
function specifies the strict or loose flag for the final hop of a
routing header.
The
.Fa flags
must be either
.Dv IPV6_RTHDR_LOOSE
or
.Dv IPV6_RTHDR_STRICT .
.Pp
The return value of the function is 0 upon success, and \-1 when an
error has occurred.
.Pp
Please note that a routing header specifying
.Li N
intermediate nodes requires
.Li N+1
strict or loose flags meaning that
.Fn inet6_rthdr_add
must be called
.Li N
times and then
.Fn inet6_rthdr_lasthop
must be called once.
.\"
.Ss inet6_rthdr_reverse
This function was never implemented.
.Pp
The following four functions provide an API for parsing a received
routing header.
.\"
.Ss inet6_rthdr_segments
The
.Fn inet6_rthdr_segments
function returns the number of segments contained in the Routing
header pointed to by the
.Fa cmsg
argument.
On success the return value is from 1 to 23.
When an error occurs \-1 is returned.
.\"
.Ss inet6_rthdr_getaddr
The
.Fn inet6_rthdr_getaddr
function returns a pointer to the IPv6 address specified by the
.Fa index
argument from the routing header pointed to by
.Fa cmsg .
The index must be between 1 and the number returned by
.Fn inet6_rthdr_segments
described above.
An application must call
.Fn inet6_rthdr_segments
to obtain the number of segments in the routing header.
.Pp
If an error occurs the
.Dv NULL
is returned.
.\"
.Ss inet6_rthdr_getflags
The
.Fn inet6_rthdr_getflags
function returns the flags value of the segment specified by
.Fa index
of the routing header pointed to by
.Fa cmsg .
The
.Fa index
argument must be between 0 and the value returned by
.Fn inet6_rthdr_segments .
The return value will be either
.Dv IPV6_RTHDR_LOOSE
or
.Dv IPV6_RTHDR_STRICT
indicating whether loose or strict source routing was requested for
that segment.
.Pp
When an error occurs \-1 is returned.
.Pp
Note: Flags begin at index 0 while segments begin at index 1, to
maintain consistency with the terminology and figures in RFC2460.
.\"
.Sh DIAGNOSTICS
The
.Fn inet6_rthdr_space
function returns 0 when an error occurs.
.Pp
The
.Fn inet6_rthdr_add ,
.Fn inet6_rthdr_lasthop
functions return 0 on success, and \-1 on error.
.Pp
The
.Fn inet6_rthdr_init
and
.Fn inet6_rthdr_getaddr
functions
return
.Dv NULL
on error.
.Pp
The
.Fn inet6_rthdr_segments
and
.Fn inet6_rthdr_getflags
functions return -1 on error.
.\"
.Sh EXAMPLES
RFC2292 gives comprehensive examples in chapter 8.
.\"
.Sh SEE ALSO
.Rs
.%A W. Stevens
.%A M. Thomas
.%T "Advanced Sockets API for IPv6"
.%N RFC2292
.%D February 1998
.Re
.Rs
.%A S. Deering
.%A R. Hinden
.%T "Internet Protocol, Version 6 (IPv6) Specification"
.%N RFC2460
.%D December 1998
.Re
.\"
.Sh HISTORY
The implementation first appeared in KAME advanced networking kit.
.\"
.Sh BUGS
The
.Fn inet6_rthdr_reverse
function was never implemented.
.\".Pp
.\"This API is deprecated in favor of
.\".Xr inet6_rth_space 3
.\".Sh SEE ALSO
.\".Xr inet6_rth_space 3

255
share/man/man4/icmp6.4 Normal file
View File

@ -0,0 +1,255 @@
.\" $KAME: icmp6.4,v 1.6 2004/12/27 05:30:56 itojun Exp $
.\" $OpenBSD: icmp6.4,v 1.19 2004/12/23 20:33:03 jaredy Exp $
.\" $FreeBSD$
.\"
.\" Copyright (c) 1986, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" 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.
.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 December 20, 2004
.Dt ICMP6 4
.Os
.Sh NAME
.Nm icmp6
.Nd Internet Control Message Protocol for IPv6
.Sh SYNOPSIS
.In sys/socket.h
.In netinet/in.h
.In netinet/icmp6.h
.Ft int
.Fn socket AF_INET6 SOCK_RAW IPPROTO_ICMPV6
.Sh DESCRIPTION
ICMPv6 is the error and control message protocol used by IPv6 and the
IPv6 protocol family (see
.Xr ip6 4
and
.Xr inet6 4 ) .
It may be accessed through a
.Dq raw socket
for network monitoring and diagnostic functions.
.Pp
The
.Fa proto
parameter to the
.Xr socket 2
call to create an ICMPv6 socket may be obtained from
.Xr getprotobyname 3 .
ICMPv6 sockets are connectionless, and are normally used with the
.Xr sendto 2
and
.Xr recvfrom 2
calls, though the
.Xr connect 2
call may also be used to fix the destination for future packets
(in which case
.Xr read 2
or
.Xr recv 2
and
.Xr write 2
or
.Xr send 2
system calls may be used).
.Pp
Outgoing packets automatically have an IPv6 header prepended to them
(based on the destination address).
Incoming packets on the socket are received with the IPv6 header and any
extension headers removed.
.Ss Types
ICMPv6 messages are classified according to the type and code fields
present in the ICMPv6 header.
The abbreviations for the types and codes may be used in rules in
.Xr pf.conf 5 .
The following types are defined:
.Bl -column x xxxxxxxxxxxx -offset indent
.It Sy Num Ta Sy Abbrev. Ta Sy Description
.It 1 Ta unreach Ta "Destination unreachable"
.It 2 Ta toobig Ta "Packet too big"
.It 3 Ta timex Ta "Time exceeded"
.It 4 Ta paramprob Ta "Invalid IPv6 header"
.It 128 Ta echoreq Ta "Echo service request"
.It 129 Ta echorep Ta "Echo service reply"
.It 130 Ta groupqry Ta "Group membership query"
.It 130 Ta listqry Ta "Multicast listener query"
.It 131 Ta grouprep Ta "Group membership report"
.It 131 Ta listenrep Ta "Multicast listener report"
.It 132 Ta groupterm Ta "Group membership termination"
.It 132 Ta listendone Ta "Multicast listerner done"
.It 133 Ta routersol Ta "Router solicitation"
.It 134 Ta routeradv Ta "Router advertisement"
.It 135 Ta neighbrsol Ta "Neighbor solicitation"
.It 136 Ta neighbradv Ta "Neighbor advertisement"
.It 137 Ta redir Ta "Shorter route exists"
.It 138 Ta routrrenum Ta "Route renumbering"
.It 139 Ta fqdnreq Ta "FQDN query"
.It 139 Ta niqry Ta "Node information query"
.It 139 Ta wrureq Ta "Who-are-you request"
.It 140 Ta fqdnrep Ta "FQDN reply"
.It 140 Ta nirep Ta "Node information reply"
.It 140 Ta wrurep Ta "Who-are-you reply"
.It 200 Ta mtraceresp Ta "mtrace response"
.It 201 Ta mtrace Ta "mtrace messages"
.El
.Pp
The following codes are defined:
.Bl -column x xxxxxxxxxxxx xxxxxxxx -offset indent
.It Sy Num Ta Sy Abbrev. Ta Sy Type Ta
.Sy Description
.It 0 Ta noroute-unr Ta unreach Ta "No route to destination"
.It 1 Ta admin-unr Ta unreach Ta "Administratively prohibited"
.It 2 Ta beyond-unr Ta unreach Ta "Beyond scope of source address"
.It 2 Ta notnbr-unr Ta unreach Ta "Not a neighbor (obselete)"
.It 3 Ta addr-unr Ta unreach Ta "Address unreachable"
.It 4 Ta port-unr Ta unreach Ta "Port unreachable"
.It 0 Ta transit Ta timex Ta "Time exceeded in transit"
.It 1 Ta reassemb Ta timex Ta "Time exceeded in reassembly"
.It 0 Ta badhead Ta paramprob Ta "Erroneous header field"
.It 1 Ta nxthdr Ta paramprob Ta "Unrecognized next header"
.It 2 Ta "" Ta redir Ta "Unrecognized option"
.It 0 Ta redironlink Ta redir Ta "Redirection to on-link node"
.It 1 Ta redirrouter Ta redir Ta "Redirection to better router"
.El
.Ss Headers
All ICMPv6 messages are prefixed with an ICMPv6 header.
This header corresponds to the
.Vt icmp6_hdr
structure and has the following definition:
.Bd -literal -offset indent
struct icmp6_hdr {
u_int8_t icmp6_type; /* type field */
u_int8_t icmp6_code; /* code field */
u_int16_t icmp6_cksum; /* checksum field */
union {
u_int32_t icmp6_un_data32[1]; /* type-specific */
u_int16_t icmp6_un_data16[2]; /* type-specific */
u_int8_t icmp6_un_data8[4]; /* type-specific */
} icmp6_dataun;
} __packed;
#define icmp6_data32 icmp6_dataun.icmp6_un_data32
#define icmp6_data16 icmp6_dataun.icmp6_un_data16
#define icmp6_data8 icmp6_dataun.icmp6_un_data8
#define icmp6_pptr icmp6_data32[0] /* parameter prob */
#define icmp6_mtu icmp6_data32[0] /* packet too big */
#define icmp6_id icmp6_data16[0] /* echo request/reply */
#define icmp6_seq icmp6_data16[1] /* echo request/reply */
#define icmp6_maxdelay icmp6_data16[0] /* mcast group membership*/
.Ed
.Pp
.Va icmp6_type
describes the type of the message.
Suitable values are defined in
.Aq Pa netinet/icmp6.h .
.Va icmp6_code
describes the sub-type of the message and depends on
.Va icmp6_type .
.Va icmp6_cksum
contains the checksum for the message and is filled in by the
kernel on outgoing messages.
The other fields are used for type-specific purposes.
.Ss Filters
Because of the extra functionality of ICMPv6 in comparison to ICMPv4,
a larger number of messages may be potentially received on an ICMPv6
socket.
Input filters may therefore be used to restrict input to a subset of the
incoming ICMPv6 messages so only interesting messages are returned by the
.Xr recv 2
family of calls to an application.
.Pp
The
.Vt icmp6_filter
structure may be used to refine the input message set according to the
ICMPv6 type.
By default, all messages types are allowed on newly created raw ICMPv6
sockets.
The following macros may be used to refine the input set:
.Bl -tag -width Ds
.It Fn "void ICMP6_FILTER_SETPASSALL" "struct icmp6_filter *filterp"
Allow all incoming messages.
.Va filterp
is modified to allow all message types.
.It Fn "void ICMP6_FILTER_SETBLOCKALL" "struct icmp6_filter *filterp"
Ignore all incoming messages.
.Va filterp
is modified to ignore all message types.
.It Fn "void ICMP6_FILTER_SETPASS" "int type" \
"struct icmp6_filter *filterp"
Allow ICMPv6 messages with the given
.Fa type .
.Va filterp
is modified to allow such messages.
.It Fn "void ICMP6_FILTER_SETBLOCK" "int type" \
"struct icmp6_filter *filterp"
Ignore ICMPv6 messages with the given
.Fa type .
.Va filterp
is modified to ignore such messages.
.It Fn "int ICMP6_FILTER_WILLPASS" "int type" \
"const struct icmp6_filter *filterp"
Determine if the given filter will allow an ICMPv6 message of the given
type.
.It Fn "int ICMP6_FILTER_WILLBLOCK" "int type" \
"const struct icmp6_filter *filterp"
Determine if the given filter will ignore an ICMPv6 message of the given
type.
.El
.Pp
The
.Xr getsockopt 2
and
.Xr setsockopt 2
calls may be used to obtain and install the filter on ICMPv6 sockets at
option level
.Dv IPPROTO_ICMPV6
and name
.Dv ICMPV6_FILTER
with a pointer to the
.Vt icmp6_filter
structure as the option value.
.Sh SEE ALSO
.Xr getsockopt 2 ,
.Xr recv 2 ,
.Xr send 2 ,
.Xr setsockopt 2 ,
.Xr socket 2 ,
.Xr getprotobyname 3 ,
.Xr inet6 4 ,
.Xr ip6 4 ,
.Xr netintro 4
.Rs
.%A W. Stevens
.%A M. Thomas
.%T Advanced Sockets API for IPv6
.%N RFC 2292
.%D February 1998
.Re
.Rs
.%A A. Conta
.%A S. Deering
.%T "Internet Control Message Protocol (ICMPv6) for the Internet" \
"Protocol Version 6 (IPv6) Specification"
.%N RFC 2463
.%D December 1998
.Re

686
share/man/man4/ip6.4 Normal file
View File

@ -0,0 +1,686 @@
.\" $KAME: ip6.4,v 1.23 2005/01/11 05:56:25 itojun Exp $
.\" $OpenBSD: ip6.4,v 1.21 2005/01/06 03:50:46 itojun Exp $
.\" $FreeBSD$
.\"
.\" Copyright (c) 1983, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" 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.
.\" 3. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 December 29, 2004
.Dt IP6 4
.Os
.Sh NAME
.Nm ip6
.Nd Internet Protocol version 6 (IPv6) network layer
.Sh SYNOPSIS
.In sys/socket.h
.In netinet/in.h
.Ft int
.Fn socket AF_INET6 SOCK_RAW proto
.Sh DESCRIPTION
The IPv6 network layer is used by the IPv6 protocol family for
transporting data.
IPv6 packets contain an IPv6 header that is not provided as part of the
payload contents when passed to an application.
IPv6 header options affect the behavior of this protocol and may be used
by high-level protocols (such as the
.Xr tcp 4
and
.Xr udp 4
protocols) as well as directly by
.Dq raw sockets ,
which process IPv6 messages at a lower-level and may be useful for
developing new protocols and special-purpose applications.
.Ss Header
All IPv6 packets begin with an IPv6 header.
When data received by the kernel are passed to the application, this
header is not included in buffer, even when raw sockets are being used.
Likewise, when data are sent to the kernel for transmit from the
application, the buffer is not examined for an IPv6 header:
the kernel always constructs the header.
To directly access IPv6 headers from received packets and specify them
as part of the buffer passed to the kernel, link-level access
.Po
.Xr bpf 4 ,
for example
.Pc
must instead be utilized.
.Pp
The header has the following definition:
.Bd -literal -offset indent
struct ip6_hdr {
union {
struct ip6_hdrctl {
u_int32_t ip6_un1_flow; /* 20 bits of flow ID */
u_int16_t ip6_un1_plen; /* payload length */
u_int8_t ip6_un1_nxt; /* next header */
u_int8_t ip6_un1_hlim; /* hop limit */
} ip6_un1;
u_int8_t ip6_un2_vfc; /* version and class */
} ip6_ctlun;
struct in6_addr ip6_src; /* source address */
struct in6_addr ip6_dst; /* destination address */
} __packed;
#define ip6_vfc ip6_ctlun.ip6_un2_vfc
#define ip6_flow ip6_ctlun.ip6_un1.ip6_un1_flow
#define ip6_plen ip6_ctlun.ip6_un1.ip6_un1_plen
#define ip6_nxt ip6_ctlun.ip6_un1.ip6_un1_nxt
#define ip6_hlim ip6_ctlun.ip6_un1.ip6_un1_hlim
#define ip6_hops ip6_ctlun.ip6_un1.ip6_un1_hlim
.Ed
.Pp
All fields are in network-byte order.
Any options specified (see
.Sx Options
below) must also be specified in network-byte order.
.Pp
.Va ip6_flow
specifies the flow ID.
.Va ip6_plen
specifies the payload length.
.Va ip6_nxt
specifies the type of the next header.
.Va ip6_hlim
specifies the hop limit.
.Pp
The top 4 bits of
.Va ip6_vfc
specify the class and the bottom 4 bits specify the version.
.Pp
.Va ip6_src
and
.Va ip6_dst
specify the source and destination addresses.
.Pp
The IPv6 header may be followed by any number of extension headers that start
with the following generic definition:
.Bd -literal -offset indent
struct ip6_ext {
u_int8_t ip6e_nxt;
u_int8_t ip6e_len;
} __packed;
.Ed
.Ss Options
IPv6 allows header options on packets to manipulate the behavior of the
protocol.
These options and other control requests are accessed with the
.Xr getsockopt 2
and
.Xr setsockopt 2
system calls at level
.Dv IPPROTO_IPV6
and by using ancillary data in
.Xr recvmsg 2
and
.Xr sendmsg 2 .
They can be used to access most of the fields in the IPv6 header and
extension headers.
.Pp
The following socket options are supported:
.Bl -tag -width Ds
.\" .It Dv IPV6_OPTIONS
.It Dv IPV6_UNICAST_HOPS Fa "int *"
Get or set the default hop limit header field for outgoing unicast
datagrams sent on this socket.
A value of \-1 resets to the default value.
.\" .It Dv IPV6_RECVOPTS Fa "int *"
.\" Get or set the status of whether all header options will be
.\" delivered along with the datagram when it is received.
.\" .It Dv IPV6_RECVRETOPTS Fa "int *"
.\" Get or set the status of whether header options will be delivered
.\" for reply.
.\" .It Dv IPV6_RECVDSTADDR Fa "int *"
.\" Get or set the status of whether datagrams are received with
.\" destination addresses.
.\" .It Dv IPV6_RETOPTS
.\" Get or set IPv6 options.
.It Dv IPV6_MULTICAST_IF Fa "u_int *"
Get or set the interface from which multicast packets will be sent.
For hosts with multiple interfaces, each multicast transmission is sent
from the primary network interface.
The interface is specified as its index as provided by
.Xr if_nametoindex 3 .
A value of zero specifies the default interface.
.It Dv IPV6_MULTICAST_HOPS Fa "int *"
Get or set the default hop limit header field for outgoing multicast
datagrams sent on this socket.
This option controls the scope of multicast datagram transmissions.
.Pp
Datagrams with a hop limit of 1 are not forwarded beyond the local
network.
Multicast datagrams with a hop limit of zero will not be transmitted on
any network but may be delivered locally if the sending host belongs to
the destination group and if multicast loopback (see below) has not been
disabled on the sending socket.
Multicast datagrams with a hop limit greater than 1 may be forwarded to
the other networks if a multicast router (such as
.Xr mrouted 8 )
is attached to the local network.
.It Dv IPV6_MULTICAST_LOOP Fa "u_int *"
Get or set the status of whether multicast datagrams will be looped back
for local delivery when a multicast datagram is sent to a group to which
the sending host belongs.
.Pp
This option improves performance for applications that may have no more
than one instance on a single host (such as a router daemon) by
eliminating the overhead of receiving their own transmissions.
It should generally not be used by applications for which there may be
more than one instance on a single host (such as a conferencing program)
or for which the sender does not belong to the destination group
(such as a time-querying program).
.Pp
A multicast datagram sent with an initial hop limit greater than 1 may
be delivered to the sending host on a different interface from that on
which it was sent if the host belongs to the destination group on that
other interface.
The multicast loopback control option has no effect on such delivery.
.It Dv IPV6_JOIN_GROUP Fa "struct ipv6_mreq *"
Join a multicast group.
A host must become a member of a multicast group before it can receive
datagrams sent to the group.
.Bd -literal
struct ipv6_mreq {
struct in6_addr ipv6mr_multiaddr;
unsigned int ipv6mr_interface;
};
.Ed
.Pp
.Va ipv6mr_interface
may be set to zeroes to choose the default multicast interface or to the
index of a particular multicast-capable interface if the host is
multihomed.
Membership is associated with a single interface; programs running on
multihomed hosts may need to join the same group on more than one
interface.
.Pp
If the multicast address is unspecified (i.e., all zeroes), messages
from all multicast addresses will be accepted by this group.
Note that setting to this value requires superuser privileges.
.It Dv IPV6_LEAVE_GROUP Fa "struct ipv6_mreq *"
Drop membership from the associated multicast group.
Memberships are automatically dropped when the socket is closed or when
the process exits.
.It Dv IPV6_PORTRANGE Fa "int *"
Get or set the allocation policy of ephemeral ports for when the kernel
automatically binds a local address to this socket.
The following values are available:
.Pp
.Bl -tag -width IPV6_PORTRANGE_DEFAULT -compact
.It Dv IPV6_PORTRANGE_DEFAULT
Use the regular range of non-reserved ports (varies, see
.Xr sysctl 8 ) .
.It Dv IPV6_PORTRANGE_HIGH
Use a high range (varies, see
.Xr sysctl 8 ) .
.It Dv IPV6_PORTRANGE_LOW
Use a low, reserved range (600\-1023).
.El
.It Dv IPV6_PKTINFO Fa "int *"
Get or set whether additional information about subsequent packets will
be provided as ancillary data along with the payload in subsequent
.Xr recvmsg 2
calls.
The information is stored in the following structure in the ancillary
data returned:
.Bd -literal
struct in6_pktinfo {
struct in6_addr ipi6_addr; /* src/dst IPv6 address */
unsigned int ipi6_ifindex; /* send/recv if index */
};
.Ed
.It Dv IPV6_HOPLIMIT Fa "int *"
Get or set whether the hop limit header field from subsequent packets
will be provided as ancillary data along with the payload in subsequent
.Xr recvmsg 2
calls.
The value is stored as an
.Vt int
in the ancillary data returned.
.\" .It Dv IPV6_NEXTHOP Fa "int *"
.\" Get or set whether the address of the next hop for subsequent
.\" packets will be provided as ancillary data along with the payload in
.\" subsequent
.\" .Xr recvmsg 2
.\" calls.
.\" The option is stored as a
.\" .Vt sockaddr
.\" structure in the ancillary data returned.
.\" .Pp
.\" This option requires superuser privileges.
.It Dv IPV6_HOPOPTS Fa "int *"
Get or set whether the hop-by-hop options from subsequent packets will be
provided as ancillary data along with the payload in subsequent
.Xr recvmsg 2
calls.
The option is stored in the following structure in the ancillary data
returned:
.Bd -literal
struct ip6_hbh {
u_int8_t ip6h_nxt; /* next header */
u_int8_t ip6h_len; /* length in units of 8 octets */
/* followed by options */
} __packed;
.Ed
.Pp
The
.Fn inet6_option_space
routine and family of routines may be used to manipulate this data.
.Pp
This option requires superuser privileges.
.It Dv IPV6_DSTOPTS Fa "int *"
Get or set whether the destination options from subsequent packets will
be provided as ancillary data along with the payload in subsequent
.Xr recvmsg 2
calls.
The option is stored in the following structure in the ancillary data
returned:
.Bd -literal
struct ip6_dest {
u_int8_t ip6d_nxt; /* next header */
u_int8_t ip6d_len; /* length in units of 8 octets */
/* followed by options */
} __packed;
.Ed
.Pp
The
.Fn inet6_option_space
routine and family of routines may be used to manipulate this data.
.Pp
This option requires superuser privileges.
.It Dv IPV6_RTHDR Fa "int *"
Get or set whether the routing header from subsequent packets will be
provided as ancillary data along with the payload in subsequent
.Xr recvmsg 2
calls.
The header is stored in the following structure in the ancillary data
returned:
.Bd -literal
struct ip6_rthdr {
u_int8_t ip6r_nxt; /* next header */
u_int8_t ip6r_len; /* length in units of 8 octets */
u_int8_t ip6r_type; /* routing type */
u_int8_t ip6r_segleft; /* segments left */
/* followed by routing-type-specific data */
} __packed;
.Ed
.Pp
The
.Fn inet6_option_space
routine and family of routines may be used to manipulate this data.
.Pp
This option requires superuser privileges.
.It Dv IPV6_PKTOPTIONS Fa "struct cmsghdr *"
Get or set all header options and extension headers at one time on the
last packet sent or received on the socket.
All options must fit within the size of an mbuf (see
.Xr mbuf 9 ) .
Options are specified as a series of
.Vt cmsghdr
structures followed by corresponding values.
.Va cmsg_level
is set to
.Dv IPPROTO_IPV6 ,
.Va cmsg_type
to one of the other values in this list, and trailing data to the option
value.
When setting options, if the length
.Va optlen
to
.Xr setsockopt 2
is zero, all header options will be reset to their default values.
Otherwise, the length should specify the size the series of control
messages consumes.
.Pp
Instead of using
.Xr sendmsg 2
to specify option values, the ancillary data used in these calls that
correspond to the desired header options may be directly specified as
the control message in the series of control messages provided as the
argument to
.Xr setsockopt 2 .
.It Dv IPV6_CHECKSUM Fa "int *"
Get or set the byte offset into a packet where the 16-bit checksum is
located.
When set, this byte offset is where incoming packets will be expected
to have checksums of their data stored and where outgoing packets will
have checksums of their data computed and stored by the kernel.
A value of \-1 specifies that no checksums will be checked on incoming
packets and that no checksums will be computed or stored on outgoing
packets.
The offset of the checksum for ICMPv6 sockets cannot be relocated or
turned off.
.It Dv IPV6_V6ONLY Fa "int *"
Get or set whether only IPv6 connections can be made to this socket.
For wildcard sockets, this can restrict connections to IPv6 only.
.\"With
.\".Ox
.\"IPv6 sockets are always IPv6-only, so the socket option is read-only
.\"(not modifiable).
.It Dv IPV6_FAITH Fa "int *"
Get or set the status of whether
.Xr faith 4
connections can be made to this socket.
.It Dv IPV6_USE_MIN_MTU Fa "int *"
Get or set whether the minimal IPv6 maximum transmission unit (MTU) size
will be used to avoid fragmentation from occurring for subsequent
outgoing datagrams.
.It Dv IPV6_AUTH_LEVEL Fa "int *"
Get or set the
.Xr ipsec 4
authentication level.
.It Dv IPV6_ESP_TRANS_LEVEL Fa "int *"
Get or set the ESP transport level.
.It Dv IPV6_ESP_NETWORK_LEVEL Fa "int *"
Get or set the ESP encapsulation level.
.It Dv IPV6_IPCOMP_LEVEL Fa "int *"
Get or set the
.Xr ipcomp 4
level.
.El
.Pp
The
.Dv IPV6_PKTINFO ,
.\" .Dv IPV6_NEXTHOP ,
.Dv IPV6_HOPLIMIT ,
.Dv IPV6_HOPOPTS ,
.Dv IPV6_DSTOPTS ,
and
.Dv IPV6_RTHDR
options will return ancillary data along with payload contents in subsequent
.Xr recvmsg 2
calls with
.Va cmsg_level
set to
.Dv IPPROTO_IPV6
and
.Va cmsg_type
set to respective option name value (e.g.,
.Dv IPV6_HOPTLIMIT ) .
These options may also be used directly as ancillary
.Va cmsg_type
values in
.Xr sendmsg 2
to set options on the packet being transmitted by the call.
The
.Va cmsg_level
value must be
.Dv IPPROTO_IPV6 .
For these options, the ancillary data object value format is the same
as the value returned as explained for each when received with
.Xr recvmsg 2 .
.Pp
Note that using
.Xr sendmsg 2
to specify options on particular packets works only on UDP and raw sockets.
To manipulate header options for packets on TCP sockets, only the socket
options may be used.
.Pp
In some cases, there are multiple APIs defined for manipulating an IPv6
header field.
A good example is the outgoing interface for multicast datagrams, which
can be set by the
.Dv IPV6_MULTICAST_IF
socket option, through the
.Dv IPV6_PKTINFO
option, and through the
.Va sin6_scope_id
field of the socket address passed to the
.Xr sendto 2
system call.
.Pp
Resolving these conflicts is implementation dependent.
This implementation determines the value in the following way:
options specified by using ancillary data (i.e.,
.Xr sendmsg 2 )
are considered first,
options specified by using
.Dv IPV6_PKTOPTIONS
to set
.Dq sticky
options are considered second,
options specified by using the individual, basic, and direct socket
options (e.g.,
.Dv IPV6_UNICAST_HOPS )
are considered third,
and options specified in the socket address supplied to
.Xr sendto 2
are the last choice.
.Ss Multicasting
IPv6 multicasting is supported only on
.Dv AF_INET6
sockets of type
.Dv SOCK_DGRAM
and
.Dv SOCK_RAW ,
and only on networks where the interface driver supports
multicasting.
Socket options (see above) that manipulate membership of
multicast groups and other multicast options include
.Dv IPV6_MULTICAST_IF ,
.Dv IPV6_MULTICAST_HOPS ,
.Dv IPV6_MULTICAST_LOOP ,
.Dv IPV6_LEAVE_GROUP ,
and
.Dv IPV6_JOIN_GROUP .
.Ss Raw Sockets
Raw IPv6 sockets are connectionless and are normally used with the
.Xr sendto 2
and
.Xr recvfrom 2
calls, although the
.Xr connect 2
call may be used to fix the destination address for future outgoing
packets so that
.Xr send 2
may instead be used and the
.Xr bind 2
call may be used to fix the source address for future outgoing
packets instead of having the kernel choose a source address.
.Pp
By using
.Xr connect 2
or
.Xr bind 2 ,
raw socket input is constrained to only packets with their
source address matching the socket destination address if
.Xr connect 2
was used and to packets with their destination address
matching the socket source address if
.Xr bind 2
was used.
.Pp
If the
.Ar proto
argument to
.Xr socket 2
is zero, the default protocol
.Pq Dv IPPROTO_RAW
is used for outgoing packets.
For incoming packets, protocols recognized by kernel are
.Sy not
passed to the application socket (e.g.,
.Xr tcp 4
and
.Xr udp 4 )
except for some ICMPv6 messages.
The ICMPv6 messages not passed to raw sockets include echo, timestamp,
and address mask requests.
If
.Ar proto
is non-zero, only packets with this protocol will be passed to the
socket.
.Pp
IPv6 fragments are also not passed to application sockets until
they have been reassembled.
If reception of all packets is desired, link-level access (such as
.Xr bpf 4 )
must be used instead.
.Pp
Outgoing packets automatically have an IPv6 header prepended to them
(based on the destination address and the protocol number the socket
was created with).
Incoming packets are received by an application without the IPv6 header
or any extension headers.
.Pp
Outgoing packets will be fragmented automatically by the kernel if they
are too large.
Incoming packets will be reassembled before being sent to the raw socket,
so packet fragments or fragment headers will never be seen on a raw socket.
.Sh EXAMPLES
The following determines the hop limit on the next packet received:
.Bd -literal
struct iovec iov[2];
u_char buf[BUFSIZ];
struct cmsghdr *cm;
struct msghdr m;
int found, optval;
u_char data[2048];
/* Create socket. */
(void)memset(&m, 0, sizeof(m));
(void)memset(&iov, 0, sizeof(iov));
iov[0].iov_base = data; /* buffer for packet payload */
iov[0].iov_len = sizeof(data); /* expected packet length */
m.msg_name = &from; /* sockaddr_in6 of peer */
m.msg_namelen = sizeof(from);
m.msg_iov = iov;
m.msg_iovlen = 1;
m.msg_control = (caddr_t)buf; /* buffer for control messages */
m.msg_controllen = sizeof(buf);
/*
* Enable the hop limit value from received packets to be
* returned along with the payload.
*/
optval = 1;
if (setsockopt(s, IPPROTO_IPV6, IPV6_HOPLIMIT, &optval,
sizeof(optval)) == -1)
err(1, "setsockopt");
found = 0;
while (!found) {
if (recvmsg(s, &m, 0) == -1)
err(1, "recvmsg");
for (cm = CMSG_FIRSTHDR(&m); cm != NULL;
cm = CMSG_NXTHDR(&m, cm)) {
if (cm->cmsg_level == IPPROTO_IPV6 &&
cm->cmsg_type == IPV6_HOPLIMIT &&
cm->cmsg_len == CMSG_LEN(sizeof(int))) {
found = 1;
(void)printf("hop limit: %d\en",
*(int *)CMSG_DATA(cm));
break;
}
}
}
.Ed
.Sh DIAGNOSTICS
A socket operation may fail with one of the following errors returned:
.Bl -tag -width EADDRNOTAVAILxx
.It Bq Er EISCONN
when trying to establish a connection on a socket which
already has one or when trying to send a datagram with the destination
address specified and the socket is already connected.
.It Bq Er ENOTCONN
when trying to send a datagram, but
no destination address is specified, and the socket hasn't been
connected.
.It Bq Er ENOBUFS
when the system runs out of memory for
an internal data structure.
.It Bq Er EADDRNOTAVAIL
when an attempt is made to create a
socket with a network address for which no network interface
exists.
.It Bq Er EACCES
when an attempt is made to create
a raw IPv6 socket by a non-privileged process.
.El
.Pp
The following errors specific to IPv6 may occur when setting or getting
header options:
.Bl -tag -width EADDRNOTAVAILxx
.It Bq Er EINVAL
An unknown socket option name was given.
.It Bq Er EINVAL
An ancillary data object was improperly formed.
.El
.Sh SEE ALSO
.Xr getsockopt 2 ,
.Xr recv 2 ,
.Xr send 2 ,
.Xr setsockopt 2 ,
.Xr socket 2 ,
.\" .Xr inet6_option_space 3 ,
.\" .Xr inet6_rthdr_space 3 ,
.Xr if_nametoindex 3 ,
.Xr bpf 4 ,
.Xr icmp6 4 ,
.Xr inet6 4 ,
.Xr netintro 4 ,
.Xr tcp 4 ,
.Xr udp 4
.Rs
.%A W. Stevens
.%A M. Thomas
.%T Advanced Sockets API for IPv6
.%R RFC 2292
.%D February 1998
.Re
.Rs
.%A S. Deering
.%A R. Hinden
.%T Internet Protocol, Version 6 (IPv6) Specification
.%R RFC 2460
.%D December 1998
.Re
.Rs
.%A R. Gilligan
.%A S. Thomson
.%A J. Bound
.%A W. Stevens
.%T Basic Socket Interface Extensions for IPv6
.%R RFC 2553
.%D March 1999
.Re
.Rs
.%A W. Stevens
.%A B. Fenner
.%A A. Rudoff
.%T UNIX Network Programming, third edition
.Re
.Sh STANDARDS
Most of the socket options are defined in RFC 2292 or RFC 2553.
The
.Dv IPV6_V6ONLY
socket option is defined in RFC 3542.
The
.Dv IPV6_PORTRANGE
socket option and the conflict resolution rule are not defined in the
RFCs and should be considered implementation dependent.