OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

Compare Revisions

  • This comparison shows the changes necessary to convert path 
    /openrisc/trunk/rtos/ecos-2.0/packages/net/common/v2_0/doc/manpages/net
    from Rev 27 to Rev 174
    ↔ Reverse comparison
  •

Rev 27 → Rev 174

/ns.3
0,0 → 1,131
.\" $OpenBSD: ns.3,v 1.7 2001/08/02 20:37:35 hugh Exp $
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 June 4, 1993
.Dt NS 3
.Os
.Sh NAME
.Nm ns_addr ,
.Nm ns_ntoa
.Nd Xerox
.Tn NS Ns (tm)
address conversion routines
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <netns/ns.h>
.Ft struct ns_addr
.Fn ns_addr "char *cp"
.Ft char *
.Fn ns_ntoa "struct ns_addr ns"
.Sh DESCRIPTION
The routine
.Fn ns_addr
interprets character strings representing
.Tn XNS
addresses, returning binary information suitable
for use in system calls.
The routine
.Fn ns_ntoa
takes
.Tn XNS
addresses and returns
.Tn ASCII
strings representing the address in a
notation in common use in the Xerox Development Environment:
.Bd -filled -offset indent
<network number>.<host number>.<port number>
.Ed
.Pp
Trailing zero fields are suppressed, and each number is printed in hexadecimal,
in a format suitable for input to
.Fn ns_addr .
Any fields lacking super-decimal digits will have a
trailing
.Sq H
appended.
.Pp
Unfortunately, no universal standard exists for representing
.Tn XNS
addresses.
An effort has been made to ensure that
.Fn ns_addr
be compatible with most formats in common use.
It will first separate an address into 1 to 3 fields using a single delimiter
chosen from
period
.Pq Ql \&. ,
colon
.Pq Ql \&: ,
or pound-sign
.Ql # .
Each field is then examined for byte separators (colon or period).
If there are byte separators, each subfield separated is taken to be
a small hexadecimal number, and the entirety is taken as a network-byte-ordered
quantity to be zero extended in the high-network-order bytes.
Next, the field is inspected for hyphens, in which case
the field is assumed to be a number in decimal notation
with hyphens separating the millenia.
Next, the field is assumed to be a number:
It is interpreted
as hexadecimal if there is a leading
.Ql 0x
(as in C),
a trailing
.Sq H
(as in Mesa), or there are any super-decimal digits present.
It is interpreted as octal is there is a leading
.Ql 0
and there are no super-octal digits.
Otherwise, it is converted as a decimal number.
.Sh RETURN VALUES
None.
(See
.Sx BUGS . )
.Sh SEE ALSO
.Xr hosts 5 ,
.Xr networks 5
.Sh HISTORY
The
.Fn ns_addr
and
.Fn ns_toa
functions appeared in
.Bx 4.3 .
.Sh BUGS
The string returned by
.Fn ns_ntoa
resides in a static memory area.
The function
.Fn ns_addr
should diagnose improperly formed input, and there should be an unambiguous
way to recognize this.
/net_addrcmp.3
0,0 → 1,91
.\" $OpenBSD: net_addrcmp.3,v 1.3 2001/08/07 06:53:27 deraadt Exp $
.\"
.\" Copyright (c) 1999 Theo de Raadt
.\"
.\" 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 AUTHOR ``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 AUTHOR 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 July 3, 1999
.Dt NET_ADDRCMP 3
.Os
.Sh NAME
.Nm net_addrcmp
.Nd compare socket address structures
.Sh SYNOPSIS
.Fd #include <netdb.h>
.Ft int
.Fn net_addrcmp "struct sockaddr *sa1" "struct sockaddr *sa2"
.Sh DESCRIPTION
The
.Fn net_addrcmp
function compares two socket address structures,
.Fa sa1
and
.Fa sa2 .
.Sh RETURN VALUES
If
.Fa sa1
and
.Fa sa2
are for the same address,
.Fn net_addrcmp
returns 0.
.Pp
The
.Fa sa_len
fields are compared first.
If they do not match,
.Fn net_addrcmp
returns \-1 or 1 if
.Li sa1->sa_len
is less than or greater than
.Li sa2->sa_len ,
respectively.
.Pp
Next, the
.Fa sa_family
members are compared.
If they do not match,
.Fn net_addrcmp
returns \-1 or 1 if
.Li sa1->sa_family
is less than or greater than
.Li sa2->sa_family ,
respectively.
.Pp
Lastly, if each socket address structure's
.Fa sa_len
and
.Fa sa_family
fields match,
the protocol-specific data (the
.Fa sa_data
field) is compared.
If there's a match, both
.Fa sa1
and
.Fa sa2
must refer to the same address, and 0 is returned; otherwise, a value >0
or <0 is returned.
.Sh HISTORY
A
.Fn net_addrcmp
function was added in
.Ox 2.5 .
/iso_addr.3
0,0 → 1,111
.\" $OpenBSD: iso_addr.3,v 1.4 1999/07/05 06:08:05 aaron Exp $
.\"
.\" Copyright (c) 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 June 4, 1993
.Dt ISO_ADDR 3
.Os
.Sh NAME
.Nm iso_addr ,
.Nm iso_ntoa
.Nd "network address conversion routines for Open System Interconnection"
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <netiso/iso.h>
.Ft struct iso_addr *
.Fn iso_addr "char *cp"
.Ft char *
.Fn iso_ntoa "struct iso_addr *isoa"
.Sh DESCRIPTION
The routine
.Fn iso_addr
interprets character strings representing
.Tn OSI
addresses, returning binary information suitable
for use in system calls.
The routine
.Fn iso_ntoa
takes
.Tn OSI
addresses and returns
.Tn ASCII
strings representing NSAPs (network service
access points) in a
notation inverse to that accepted by
.Fn iso_addr .
.Pp
Unfortunately, no universal standard exists for representing
.Tn OSI
network addresses.
.Pp
The format employed by
.Fn iso_addr
is a sequence of hexadecimal
.Dq digits
(optionally separated by periods),
of the form:
.Bd -filled -offset indent
<hex digits>.<hex digits>.<hex digits>
.Ed
.Pp
Each pair of hexadecimal digits represents a byte
with the leading digit indicating the higher-ordered bits.
A period following an even number of bytes has no
effect (but may be used to increase legibility).
A period following an odd number of bytes has the
effect of causing the byte of address being translated
to have its higher order bits filled with zeros.
.Sh RETURN VALUES
.Fn iso_ntoa
always returns a null terminated string.
.Fn iso_addr
always returns a pointer to a
.Li struct iso_addr .
(See
.Sx BUGS . )
.Sh SEE ALSO
.Xr iso 4
.Sh HISTORY
The
.Fn iso_addr
and
.Fn iso_ntoa
functions appeared in
.Bx 4.3 Reno .
.Sh BUGS
The returned values
reside in a static memory area.
.Pp
The function
.Fn iso_addr
should diagnose improperly formed input, and there should be an unambiguous
way to recognize this.
/getaddrinfo.3
0,0 → 1,581
.\" $OpenBSD: getaddrinfo.3,v 1.19 2001/08/06 10:42:26 mpech Exp $
.\" $KAME: getaddrinfo.3,v 1.29 2001/02/12 09:24:45 itojun Exp $
.\"
.\" Copyright (c) 1983, 1987, 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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.
.\"
.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
.\"
.Dd May 25, 1995
.Dt GETADDRINFO 3
.Os
.\"
.Sh NAME
.Nm getaddrinfo ,
.Nm freeaddrinfo ,
.Nm gai_strerror
.Nd nodename-to-address translation in protocol-independent manner
.\"
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Fd #include <netdb.h>
.Ft int
.Fn getaddrinfo "const char *nodename" "const char *servname" \
"const struct addrinfo *hints" "struct addrinfo **res"
.Ft void
.Fn freeaddrinfo "struct addrinfo *ai"
.Ft "char *"
.Fn gai_strerror "int ecode"
.\"
.Sh DESCRIPTION
The
.Fn getaddrinfo
function is defined for protocol-independent nodename-to-address translation.
It performs the functionality of
.Xr gethostbyname 3
and
.Xr getservbyname 3 ,
but in a more sophisticated manner.
.Pp
The
.Li addrinfo
structure is defined as a result of including the
.Aq Pa netdb.h
header:
.Bd -literal -offset
struct addrinfo { *
int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
int ai_family; /* PF_xxx */
int ai_socktype; /* SOCK_xxx */
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
size_t ai_addrlen; /* length of ai_addr */
char *ai_canonname; /* canonical name for nodename */
struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */
};
.Ed
.Pp
The
.Fa nodename
and
.Fa servname
arguments are pointers to NUL-terminated strings or
.Dv NULL .
One or both of these two arguments must be a non-null pointer.
In the normal client scenario, both the
.Fa nodename
and
.Fa servname
are specified.
In the normal server scenario, only the
.Fa servname
is specified.
A non-null
.Fa nodename
string can be either a node name or a numeric host address string
(i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
A non-null
.Fa servname
string can be either a service name or a decimal port number.
.Pp
The caller can optionally pass an
.Li addrinfo
structure, pointed to by the third argument,
to provide hints concerning the type of socket that the caller supports.
In this
.Fa hints
structure all members other than
.Fa ai_flags ,
.Fa ai_family ,
.Fa ai_socktype ,
and
.Fa ai_protocol
must be zero or a null pointer.
A value of
.Dv PF_UNSPEC
for
.Fa ai_family
means the caller will accept any protocol family.
A value of 0 for
.Fa ai_socktype
means the caller will accept any socket type.
A value of 0 for
.Fa ai_protocol
means the caller will accept any protocol.
For example, if the caller handles only TCP and not UDP, then the
.Fa ai_socktype
member of the hints structure should be set to
.Dv SOCK_STREAM
when
.Fn getaddrinfo
is called.
If the caller handles only IPv4 and not IPv6, then the
.Fa ai_family
member of the
.Fa hints
structure should be set to
.Dv PF_INET
when
.Fn getaddrinfo
is called.
If the third argument to
.Fn getaddrinfo
is a null pointer, this is the same as if the caller had filled in an
.Li addrinfo
structure initialized to zero with
.Fa ai_family
set to
.Dv PF_UNSPEC .
.Pp
Upon successful return a pointer to a linked list of one or more
.Li addrinfo
structures is returned through the final argument.
The caller can process each
.Li addrinfo
structure in this list by following the
.Fa ai_next
pointer, until a null pointer is encountered.
In each returned
.Li addrinfo
structure the three members
.Fa ai_family ,
.Fa ai_socktype ,
and
.Fa ai_protocol
are the corresponding arguments for a call to the
.Fn socket
function.
In each
.Li addrinfo
structure the
.Fa ai_addr
member points to a filled-in socket address structure whose length is
specified by the
.Fa ai_addrlen
member.
.Pp
If the
.Dv AI_PASSIVE
bit is set in the
.Fa ai_flags
member of the
.Fa hints
structure, then the caller plans to use the returned socket address
structure in a call to
.Fn bind .
In this case, if the
.Fa nodename
argument is a 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 in the
.Fa ai_flags
member of the
.Fa hints
structure, then the returned socket address structure will be ready for a
call to
.Fn connect
.Pq for a connection-oriented protocol
or either
.Fn connect ,
.Fn sendto ,
or
.Fn sendmsg
.Pq for a connectionless protocol .
In this case, if the
.Fa nodename
argument is a null pointer, then the IP address portion of the
socket address structure will be set to the loopback address.
.Pp
If the
.Dv AI_CANONNAME
bit is set in the
.Fa ai_flags
member of the
.Fa hints
structure, then upon successful return the
.Fa ai_canonname
member of the first
.Li addrinfo
structure in the linked list will point to a NUL-terminated string
containing the canonical name of the specified
.Fa nodename .
.Pp
If the
.Dv AI_NUMERICHOST
bit is set in the
.Fa ai_flags
member of the
.Fa hints
structure, then a non-null
.Fa nodename
string must be a numeric host address string.
Otherwise an error of
.Dv EAI_NONAME
is returned.
This flag prevents any type of name resolution service (e.g., the DNS)
from being called.
.Pp
The arguments to
.Fn getaddrinfo
must sufficiently be consistent and unambiguous.
Here are pitfall cases you may encounter:
.Bl -bullet
.It
.Fn getaddrinfo
will raise an error if members of the
.Fa hints
structure are not consistent.
For example, for internet address families,
.Fn getaddrinfo
will raise an error if you specify
.Dv SOCK_STREAM
to
.Fa ai_socktype
while you specify
.Dv IPPROTO_UDP
to
.Fa ai_protocol .
.It
If you specify a
.Fa servname
which is defined only for certain
.Fa ai_socktype ,
.Fn getaddrinfo
will raise an error because the arguments are not consistent.
For example,
.Fn getaddrinfo
will raise an error if you ask for
.Dq Li tftp
service on
.Dv SOCK_STREAM .
.It
For internet address families, if you specify
.Fa servname
while you set
.Fa ai_socktype
to
.Dv SOCK_RAW ,
.Fn getaddrinfo
will raise an error, because service names are not defined for the internet
.Dv SOCK_RAW
space.
.It
If you specify a numeric
.Fa servname ,
while leaving
.Fa ai_socktype
and
.Fa ai_protocol
unspecified,
.Fn getaddrinfo
will raise an error.
This is because the numeric
.Fa servname
does not identify any socket type, and
.Fn getaddrinfo
is not allowed to glob the argument in such case.
.El
.Pp
All of the information returned by
.Fn getaddrinfo
is dynamically allocated:
the
.Li addrinfo
structures, the socket address structures, and canonical node name
strings pointed to by the addrinfo structures.
To return this information to the system the function
.Fn freeaddrinfo
is called.
The
.Fa addrinfo
structure pointed to by the
.Fa ai argument
is freed, along with any dynamic storage pointed to by the structure.
This operation is repeated until a
.Dv NULL
.Fa ai_next
pointer is encountered.
.Pp
To aid applications in printing error messages based on the
.Dv EAI_xxx
codes returned by
.Fn getaddrinfo ,
.Fn gai_strerror
is defined.
The argument is one of the
.Dv EAI_xxx
values defined earlier and the return value points to a string describing
the error.
If the argument is not one of the
.Dv EAI_xxx
values, the function still returns a pointer to a string whose contents
indicate an unknown error.
.\"
.Ss Extension for scoped IPv6 address
The implementation allows experimental numeric IPv6 address notation with
scope identifier.
By appending the percent character and scope identifier to addresses,
you can fill
.Li sin6_scope_id
field for addresses.
This would make management of scoped address easier,
and allows cut-and-paste input of scoped address.
.Pp
At this moment the code supports only link-local addresses with the format.
Scope identifier is hardcoded to name of hardware interface associated
with the link.
.Po
such as
.Li ne0
.Pc .
Example would be like
.Dq Li fe80::1%ne0 ,
which means
.Do
.Li fe80::1
on the link associated with
.Li ne0
interface
.Dc .
.Pp
The implementation is still very experimental and non-standard.
The current implementation assumes one-by-one relationship between
interface and link, which is not necessarily true from the specification.
.\"
.Sh EXAMPLES
The following code tries to connect to
.Dq Li www.kame.net
service
.Dq Li http .
via stream socket.
It loops through all the addresses available, regardless from address family.
If the destination resolves to IPv4 address, it will use
.Dv AF_INET
socket.
Similarly, if it resolves to IPv6,
.Dv AF_INET6
socket is used.
Observe that there is no hardcoded reference to particular address family.
The code works even if
.Nm 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, 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, cause);
/*NOTREACHED*/
}
freeaddrinfo(res0);
.Ed
.\"
.Sh DIAGNOSTICS
Error return status from
.Fn getaddrinfo
is zero on success and non-zero on errors.
Non-zero error codes are defined in
.Aq Pa netdb.h ,
and as follows:
.Pp
.Bl -tag -width EAI_ADDRFAMILY -compact
.It Dv EAI_ADDRFAMILY
Address family for
.Fa nodename
not supported.
.It Dv EAI_AGAIN
Temporary failure in name resolution.
.It Dv EAI_BADFLAGS
Invalid value for
.Fa ai_flags .
.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 nodename .
.It Dv EAI_NONAME
.Fa nodename
nor
.Fa servname
provided, or not known.
.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
.Pp
If called with proper argument,
.Fn gai_strerror
returns a pointer to a string describing the given error code.
If the argument is not one of the
.Dv EAI_xxx
values, the function still returns a pointer to a string whose contents
indicate an unknown error.
.\"
.Sh SEE ALSO
.Xr getnameinfo 3 ,
.Xr gethostbyname 3 ,
.Xr getservbyname 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 RFC2553
.%D March 1999
.Re
.Rs
.%A Tatsuya Jinmei
.%A Atsushi Onoe
.%T "An Extension of Format for IPv6 Scoped Addresses"
.%R internet draft
.%N draft-ietf-ipngwg-scopedaddr-format-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 HISTORY
The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
.\"
.Sh STANDARDS
The
.Fn getaddrinfo
function is defined in IEEE POSIX 1003.1g draft specification,
and documented in
.Dq Basic Socket Interface Extensions for IPv6
.Pq RFC2553 .
.\"
.Sh BUGS
The current implementation is not thread-safe.
.Pp
The text was shamelessly copied from RFC2553.
/getservent.3
0,0 → 1,141
.\" $OpenBSD: getservent.3,v 1.11 2000/12/24 00:30:56 aaron Exp $
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 January 12, 1994
.Dt GETSERVENT 3
.Os
.Sh NAME
.Nm getservent ,
.Nm getservbyport ,
.Nm getservbyname ,
.Nm setservent ,
.Nm endservent
.Nd get service entry
.Sh SYNOPSIS
.Fd #include <netdb.h>
.Ft struct servent *
.Fn getservent "void"
.Ft struct servent *
.Fn getservbyname "char *name" "char *proto"
.Ft struct servent *
.Fn getservbyport "int port" "char *proto"
.Ft void
.Fn setservent "int stayopen"
.Ft void
.Fn endservent "void"
.Sh DESCRIPTION
The
.Fn getservent ,
.Fn getservbyname ,
and
.Fn getservbyport
functions each return a pointer to an object with the following structure
containing the broken-out fields of a line in the network services database,
.Pa /etc/services .
.Bd -literal -offset indent
struct servent {
char *s_name; /* official name of service */
char **s_aliases; /* alias list */
int s_port; /* port service resides at */
char *s_proto; /* protocol to use */
};
.Ed
.Pp
The members of this structure are:
.Bl -tag -width s_aliases
.It Fa s_name
The official name of the service.
.It Fa s_aliases
A zero-terminated list of alternate names for the service.
.It Fa s_port
The port number at which the service resides.
Port numbers are returned in network byte order.
.It Fa s_proto
The name of the protocol to use when contacting the service.
.El
.Pp
The
.Fn getservent
function reads the next line of the file, opening the file if necessary.
.Pp
The
.Fn setservent
function opens and rewinds the file.
If the
.Fa stayopen
flag is non-zero,
the net database will not be closed after each call to
.Fn getservbyname
or
.Fn getservbyport .
.Pp
The
.Fn endservent
function closes the file.
.Pp
The
.Fn getservbyname
and
.Fn getservbyport
functions sequentially search from the beginning of the file until a
matching protocol name or port number (specified in network byte order)
is found, or until
.Dv EOF
is encountered.
If a protocol name is also supplied (non-null),
searches must also match the protocol.
.Sh FILES
.Bl -tag -width /etc/services -compact
.It Pa /etc/services
.El
.Sh DIAGNOSTICS
Null pointer (0) returned on
.Dv EOF
or error.
.Sh SEE ALSO
.Xr getprotoent 3 ,
.Xr services 5
.Sh HISTORY
The
.Fn getservent ,
.Fn getservbyport ,
.Fn getservbyname ,
.Fn setservent ,
and
.Fn endservent
functions appeared in
.Bx 4.2 .
.Sh BUGS
These functions use static data storage; if the data is needed for future use,
it should be copied before any subsequent calls overwrite it.
Expecting port numbers to fit in a 32-bit quantity is probably naive.
/link_addr.3
0,0 → 1,131
.\" $OpenBSD: link_addr.3,v 1.7 2000/04/18 03:01:32 aaron Exp $
.\"
.\" Copyright (c) 1993
.\" The Regents of the University of California. All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Donn Seeley at BSDI.
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 July 28, 1993
.Dt LINK_ADDR 3
.Os
.Sh NAME
.Nm link_addr ,
.Nm link_ntoa
.Nd elementary address specification routines for link level access
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Fd #include <net/if_dl.h>
.Ft void
.Fn link_addr "const char *addr" "struct sockaddr_dl *sdl"
.Ft char *
.Fn link_ntoa "const struct sockaddr_dl *sdl"
.Sh DESCRIPTION
The
.Fn link_addr
function interprets character strings representing
link-level addresses, returning binary information suitable
for use in system calls.
.Fn link_ntoa
takes
a link-level
address and returns an
.Tn ASCII
string representing some of the information present,
including the link level address itself, and the interface name
or number, if present.
This facility is experimental and is
still subject to change.
.Pp
For
.Fn link_addr ,
the string
.Fa addr
may contain
an optional network interface identifier of the form
.Dq name unit-number ,
suitable for the first argument to
.Xr ifconfig 8 ,
followed in all cases by a colon and
an interface address in the form of
groups of hexadecimal digits
separated by periods.
Each group represents a byte of address;
address bytes are filled left to right from
low order bytes through high order bytes.
.Pp
.\" A regular expression may make this format clearer:
.\" .Bd -literal -offset indent
.\" ([a-z]+[0-9]+:)?[0-9a-f]+(\e.[0-9a-f]+)*
.\" .Ed
.\" .Pp
Thus
.Li le0:8.0.9.13.d.30
represents an Ethernet address
to be transmitted on the first Lance Ethernet interface.
.Sh RETURN VALUES
.Fn link_ntoa
always returns a null-terminated string.
.Fn link_addr
has no return value.
(See
.Sx BUGS . )
.Sh SEE ALSO
.Xr iso 4 ,
.Xr ifconfig 8
.Sh HISTORY
The
.Fn link_addr
and
.Fn link_ntoa
functions appeared in
.Bx 4.3 Reno .
.Sh BUGS
The returned values for link_ntoa
reside in a static memory area.
.Pp
The function
.Fn link_addr
should diagnose improperly formed input, and there should be an unambiguous
way to recognize this.
.Pp
If the
.Fa sdl_len
field of the link socket address
.Fa sdl
is 0,
.Fn link_ntoa
will not insert a colon before the interface address bytes.
If this translated address is given to
.Fn link_addr
without inserting an initial colon,
the latter will not interpret it correctly.
/inet6_option_space.3
0,0 → 1,452
.\" $OpenBSD: inet6_option_space.3,v 1.8 2001/06/23 05:57:04 deraadt Exp $
.\" $KAME: inet6_option_space.3,v 1.7 2000/05/17 14:32:13 itojun Exp $
.\"
.\" Copyright (c) 1983, 1987, 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 10, 1999
.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 Options manipulation
.\"
.Sh SYNOPSIS
.Fd #include <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
.\"
Building and parsing the Hop-by-Hop and Destination options is
complicated due to alignment constranints, padding and
ancillary data manipulation.
RFC2292 defines a set of functions to help the application.
The function prototypes for
these functions are all in the
.Aq Li netinet/in.h
header.
.\"
.Ss inet6_option_space
.Fn inet6_option_space
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 padding at the end
.Po
to make its size a multiple of 8 bytes
.Pc .
The argument is the size of the structure defining the option,
which must include any pad bytes at the beginning
.Po
the value
.Li y
in the alignment term
.Dq Li xn + y
.Pc ,
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, this 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.
This is of little consequence, since it is assumed that most
Hop-by-Hop option headers and Destination option headers carry only
one option
.Pq appendix B of [RFC-2460] .
.\"
.Ss inet6_option_init
.Fn inet6_option_init
is called once per ancillary data object that will
contain either Hop-by-Hop or Destination options.
It returns
.Li 0
on success or
.Li -1
on an error.
.Pp
.Fa bp
is a pointer to previously allocated space that will contain the
ancillary data object.
It must be large enough to contain all the
individual options to be added by later calls to
.Fn inet6_option_append
and
.Fn inet6_option_alloc .
.Pp
.Fa cmsgp
is a pointer to a pointer to a
.Li cmsghdr
structure.
.Fa *cmsgp
is initialized by this function to point to the
.Li cmsghdr
structure constructed by this function in the buffer pointed to by
.Fa bp .
.Pp
.Fa type
is either
.Dv IPV6_HOPOPTS
or
.Dv IPV6_DSTOPTS .
This
.Fa type
is stored in the
.Li cmsg_type
member of the
.Li cmsghdr
structure pointed to by
.Fa *cmsgp .
.\"
.Ss inet6_option_append
This function appends a Hop-by-Hop option or a Destination option
into an ancillary data object that has been initialized by
.Fn inet6_option_init .
This function returns
.Li 0
if it succeeds or
.Li -1
on an error.
.Pp
.Fa cmsg
is a pointer to the
.Li cmsghdr
structure that must have been
initialized by
.Fn inet6_option_init .
.Pp
.Fa typep
is a pointer to the 8-bit option type.
It is assumed that this
field is immediately followed by the 8-bit option data length field,
which is then followed immediately by the option data.
The caller
initializes these three fields
.Pq the type-length-value, or TLV
before calling this function.
.Pp
The option type must have a value from
.Li 2
to
.Li 255 ,
inclusive.
.Po
.Li 0
and
.Li 1
are reserved for the
.Li Pad1
and
.Li PadN
options, respectively.
.Pc
.Pp
The option data length must have a value between
.Li 0
and
.Li 255 ,
inclusive, and is the length of the option data that follows.
.Pp
.Fa multx
is the value
.Li x
in the alignment term
.Dq Li xn + y .
It must have a value of
.Li 1 ,
.Li 2 ,
.Li 4 ,
or
.Li 8 .
.Pp
.Fa plusy
is the value
.Li y
in the alignment term
.Dq Li xn + y .
It must have a value between
.Li 0
and
.Li 7 ,
inclusive.
.\"
.Ss inet6_option_alloc
This function appends a Hop-by-Hop option or a Destination option
into an ancillary data object that has been initialized by
.Fn inet6_option_init .
This function returns a pointer to the 8-bit
option type field that starts the option on success, or
.Dv NULL
on an error.
.Pp
The difference between this function and
.Fn inet6_option_append
is that the latter copies the contents of a previously built option into
the ancillary data object while the current function returns a
pointer to the space in the data object where the option's TLV must
then be built by the caller.
.Pp
.Fa cmsg
is a pointer to the
.Li cmsghdr
structure that must have been
initialized by
.Fn inet6_option_init .
.Pp
.Fa datalen
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.
.Po
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.
.Pc
.Pp
.Fa multx
is the value
.Li x
in the alignment term
.Dq Li xn + y .
It must have a value of
.Li 1 ,
.Li 2 ,
.Li 4 ,
or
.Li 8 .
.Pp
.Fa plusy
is the value
.Li y
in the alignment term
.Dq Li xn + y .
It must have a value between
.Li 0
and
.Li 7 ,
inclusive.
.\"
.Ss inet6_option_next
This function processes the next Hop-by-Hop option or Destination
option in an ancillary data object.
If another option remains to be
processed, the return value of the function is
.Li 0
and
.Fa *tptrp
points to
the 8-bit option type field
.Po
which is followed by the 8-bit option
data length, followed by the option data
.Pc .
If no more options remain
to be processed, the return value is
.Li -1
and
.Fa *tptrp
is
.Dv NULL .
If an error occurs, the return value is
.Li -1
and
.Fa *tptrp
is not
.Dv NULL .
.Pp
.Fa cmsg
is a pointer to
.Li cmsghdr
structure of which
.Li cmsg_level
equals
.Dv IPPROTO_IPV6
and
.Li cmsg_type
equals either
.Dv IPV6_HOPOPTS
or
.Dv IPV6_DSTOPTS .
.Pp
.Fa tptrp
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.
The first time this function is
called for a given ancillary data object,
.Fa *tptrp
must be set to
.Dv NULL .
.Pp
Each time this function returns success,
.Fa *tptrp
points to the 8-bit
option type field for the next option to be processed.
.\"
.Ss inet6_option_find
This function is similar to the previously described
.Fn inet6_option_next
function, except this function lets the caller
specify the option type to be searched for, instead of always
returning the next option in the ancillary data object.
.Fa cmsg
is a
pointer to
.Li cmsghdr
structure of which
.Li cmsg_level
equals
.Dv IPPROTO_IPV6
and
.Li cmsg_type
equals either
.Dv IPV6_HOPOPTS
or
.Dv IPV6_DSTOPTS .
.Pp
.Fa tptrp
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.
The first time this function is
called for a given ancillary data object,
.Fa *tptrp
must be set to
.Dv NULL .
.Pa
This function starts searching for an option of the specified type
beginning after the value of
.Fa *tptrp .
If an option of the specified
type is located, this function returns
.Li 0
and
.Fa *tptrp
points to the 8-
bit option type field for the option of the specified type.
If an
option of the specified type is not located, the return value is
.Li -1
and
.Fa *tptrp
is
.Dv NULL .
If an error occurs, the return value is
.Li -1
and
.Fa *tptrp
is not
.Dv NULL .
.\"
.Sh DIAGNOSTICS
.Fn inet6_option_init
and
.Fn inet6_option_append
return
.Li 0
on success or
.Li -1
on an error.
.Pp
.Fn inet6_option_alloc
returns
.Dv NULL
on an error.
.Pp
On errors,
.Fn inet6_option_next
and
.Fn inet6_option_find
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
.Pq RFC2292 .
.\"
.Sh BUGS
The text was shamelessly copied from RFC2292.
/if_indextoname.3
0,0 → 1,137
.\" $OpenBSD: if_indextoname.3,v 1.4 2000/03/01 17:31:23 todd Exp $
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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.
.\"
.\" From: @(#)rcmd.3 8.1 (Berkeley) 6/4/93
.\"
.Dd May 21, 1998
.Dt IF_NAMETOINDEX 3
.Os
.Sh NAME
.Nm if_nametoindex ,
.Nm if_indextoname ,
.Nm if_nameindex ,
.Nm if_freenameindex
.Nd convert interface index to name, and vice versa
.Sh SYNOPSIS
.Fd #include <net/if.h>
.Ft "unsigned int"
.Fn if_nametoindex "const char *ifname"
.Ft "char *"
.Fn if_indextoname "unsigned int ifindex" "char *ifname"
.Ft "struct if_nameindex *"
.Fn if_nameindex "void"
.Ft "void"
.Fn if_freenameindex "struct if_nameindex *ptr"
.Sh DESCRIPTION
These functions map interface indexes to interface names (such as
.Dq lo0 ) ,
and vice versa.
.Pp
The
.Fn if_nametoindex
function converts an interface name specified by the
.Fa ifname
argument to an interface index (positive integer value).
If the specified interface does not exist, 0 will be returned.
.Pp
.Fn if_indextoname
converts an interface index specified by the
.Fa ifindex
argument to an interface name.
The
.Fa ifname
argument must point to a buffer of at least
.Dv IF_NAMESIZE
bytes into which the interface name corresponding to the specified index is
returned.
.Pf ( Dv IF_NAMESIZE
is also defined in
.Aq Pa net/if.h
and its value includes a terminating null byte at the end of the
interface name.)
This pointer is also the return value of the function.
If there is no interface corresponding to the specified index,
.Dv NULL
is returned.
.Pp
.Fn if_nameindex
returns an array of
.Fa if_nameindex
structures.
.Fa if_nametoindex
is also defined in
.Aq Pa net/if.h ,
and is as follows:
.Bd -literal -offset
struct if_nameindex {
unsigned int if_index; /* 1, 2, ... */
char *if_name; /* null terminated name: "le0", ... */
};
.Ed
.Pp
The end of the array of structures is indicated by a structure with
an
.Fa if_index
of 0 and an
.Fa if_name
of
.Dv NULL .
The function returns a null pointer on error.
The memory used for this array of structures along with the interface
names pointed to by the
.Fa if_name
members is obtained dynamically.
This memory is freed by the
.Fn if_freenameindex
function.
.Pp
.Fn if_freenameindex
takes a pointer that was returned by
.Fn if_nameindex
as argument
.Pq Fa ptr ,
and it reclaims the region allocated.
.Sh DIAGNOSTICS
.Fn if_nametoindex
returns 0 on error, positive integer on success.
.Fn if_indextoname
and
.Fn if_nameindex
return
.Dv NULL
on errors.
.Sh SEE ALSO
R. Gilligan, S. Thomson, J. Bound, and W. Stevens,
``Basic Socket Interface Extensions for IPv6,'' RFC2553, March 1999.
.Sh STANDARDS
These functions are defined in ``Basic Socket Interface Extensions for IPv6''
.Pq RFC2533 .
/ethers.3
0,0 → 1,119
.\" $OpenBSD: ethers.3,v 1.14 2001/08/06 10:42:26 mpech Exp $
.\"
.\" Written by roland@frob.com. Public domain.
.\"
.Dd December 16, 1993
.Dt ETHERS 3
.Os
.Sh NAME
.Nm ether_aton ,
.Nm ether_ntoa ,
.Nm ether_addr ,
.Nm ether_ntohost ,
.Nm ether_hostton ,
.Nm ether_line
.Nd get ethers entry
.Sh SYNOPSIS
.Fd #include <netinet/if_ether.h>
.Ft char *
.Fn ether_ntoa "struct ether_addr *e"
.Ft struct ether_addr *
.Fn ether_aton "char *s"
.Ft int
.Fn ether_ntohost "char *hostname" "struct ether_addr *e"
.Ft int
.Fn ether_hostton "char *hostname" "struct ether_addr *e"
.Ft int
.Fn ether_line "char *l" "struct ether_addr *e" "char *hostname"
.Sh DESCRIPTION
Ethernet addresses are represented by the
following structure:
.Bd -literal -offset indent
struct ether_addr {
u_int8_t ether_addr_octet[6];
};
.Ed
.Pp
The
.Fn ether_ntoa
function converts this structure into an
.Tn ASCII
string of the form
.Dq xx:xx:xx:xx:xx:xx ,
consisting of 6 hexadecimal numbers separated
by colons.
It returns a pointer to a static buffer that is reused for each call.
The
.Fn ether_aton
converts an
.Tn ASCII
string of the same form and to a structure
containing the 6 octets of the address.
It returns a pointer to a static structure that is reused for each call.
.Pp
The
.Fn ether_ntohost
and
.Fn ether_hostton
functions interrogate the database mapping host names to Ethernet
addresses,
.Pa /etc/ethers .
The
.Fn ether_ntohost
function looks up the given Ethernet address and writes the associated
host name into the character buffer passed.
This buffer should be
.Dv MAXHOSTNAMELEN
characters in size.
The
.Fn ether_hostton
function looks up the given host name and writes the associated
Ethernet address into the structure passed.
Both functions return
zero if they find the requested host name or address, and \-1 if not.
.Pp
Each call reads
.Pa /etc/ethers
from the beginning; if a
.Ql +
appears alone on a line in the file, then
.Fn ether_hostton
will consult the
.Pa ethers.byname
YP map, and
.Fn ether_ntohost
will consult the
.Pa ethers.byaddr
YP map.
.Pp
The
.Fn ether_line
function parses a line from the
.Pa /etc/ethers
file and fills in the passed
.Li struct ether_addr
and character buffer with the Ethernet address and host name on the line.
It returns zero if the line was successfully parsed and \-1 if not.
The character buffer should be
.Dv MAXHOSTNAMELEN
characters in size.
.Sh FILES
.Bl -tag -width /etc/ethers -compact
.It Pa /etc/ethers
.El
.Sh SEE ALSO
.Xr ethers 5
.Sh HISTORY
The
.Fn ether_ntoa ,
.Fn ether_aton ,
.Fn ether_ntohost ,
.Fn ether_hostton ,
and
.Fn ether_line
functions were adopted from SunOS and appeared in
.Nx 0.9 b.
.Sh BUGS
The data space used by these functions is static; if future use
requires the data, it should be copied before any subsequent calls to
these functions overwrite it.
/getrrsetbyname.3
0,0 → 1,163
.\" $OpenBSD: getrrsetbyname.3,v 1.4 2001/08/08 16:28:43 jakob Exp $
.\"
.\" 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 INTERNET SOFTWARE CONSORTIUM
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
.\" INTERNET SOFTWARE CONSORTIUM 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 Oct 18, 2000
.Dt GETRRSETBYNAME 3
.Os
.Sh NAME
.Nm getrrsetbyname
.Nd retrieve DNS records
.Sh SYNOPSIS
.Fd #include <netdb.h>
.Ft int
.Fn getrrsetbyname "const char *hostname" "unsigned int rdclass" \
"unsigned int rdtype" "unsigned int flags" "struct rrsetinfo **res"
.Ft int
.Fn freerrset "struct rrsetinfo **rrset"
.Sh DESCRIPTION
.Fn getrrsetbyname
gets a set of resource records associated with a
.Fa hostname ,
.Fa class
and
.Fa type .
.Fa hostname
is a pointer a to null-terminated string.
The
.Fa flags
field is currently unused and must be zero.
.Pp
After a successful call to
.Fn getrrsetbyname ,
.Fa *res
is a pointer to an
.Li rrsetinfo
structure, containing a list of one or more
.Li rdatainfo
structures containing resource records and potentially another list of
.Li rdatainfo
structures containing SIG resource records associated with those records.
The members
.Li rri_rdclass
and
.Li rri_rdtype
are copied from the parameters.
.Li rri_ttl
and
.Li rri_name
are properties of the obtained rrset.
The resource records contained in
.Li rri_rdatas
and
.Li rri_sigs
are in uncompressed DNS wire format.
Properties of the rdataset are represented in the
.Li rri_flags
bitfield. If the
.Dv RRSET_VALIDATED
bit is set, the data has been DNSSEC
validated and the signatures verified.
.Pp
The following structures are used:
.Bd -literal -offset
struct rdatainfo {
unsigned int rdi_length; /* length of data */
unsigned char *rdi_data; /* record data */
};
 
struct rrsetinfo {
unsigned int rri_flags; /* RRSET_VALIDATED ... */
unsigned int rri_rdclass; /* class number */
unsigned int rri_rdtype; /* RR type number */
unsigned int rri_ttl; /* time to live */
unsigned int rri_nrdatas; /* size of rdatas array */
unsigned int rri_nsigs; /* size of sigs array */
char *rri_name; /* canonical name */
struct rdatainfo *rri_rdatas; /* individual records */
struct rdatainfo *rri_sigs; /* individual signatures */
};
.Ed
.Pp
All of the information returned by
.Fn getrrsetbyname
is dynamically allocated: the
.Li rrsetinfo
and
.Li rdatainfo
structures,
and the canonical host name strings pointed to by the
.Li rrsetinfostructure.
Memory allocated for the dynamically allocated structures created by
a successful call to
.Fn getrrsetbyname
is released by
.Fn freerrset .
.Li rrset
is a pointer to a
.Li struct rrset
created by a call to
.Fn getrrsetbyname .
.Pp
If the EDNS0 option is activated in
.Xr resolv.conf 3 ,
.Fn getrrsetbyname
will request DNSSEC authentication using the EDNS0 DNSSEC OK (DO) bit.
.Sh "RETURN VALUES"
.Fn getrrsetbyname
returns zero on success, and one of the following error
codes if an error occurred:
.Pp
.Bl -tag -width ERRSET_NOMEMORY -compact
.It Dv ERRSET_NONAME
the name does not exist
.It Dv ERRSET_NODATA
the name exists, but does not have data of the desired type
.It Dv ERRSET_NOMEMORY
memory could not be allocated
.It Dv ERRSET_INVAL
a parameter is invalid
.It Dv ERRSET_FAIL
other failure
.El
.Sh SEE ALSO
.Xr resolver 3 ,
.Xr resolv.conf 5 ,
.Xr named 8
.Sh AUTHORS
Jakob Schlyter
.Aq jakob@openbsd.org
.Sh HISTORY
.Fn getrrsetbyname
first appeared in
.Ox 3.0 .
The API first appeared in ISC BIND version 9.
.Sh BUGS
The data in
.Li *rdi_data
should be returned in uncompressed wire format.
Currently, the data is in compressed format and the caller can't
uncompress since it doesn't have the full message.
.Sh CAVEATS
The
.Dv RRSET_VALIDATED
flag in
.Li rri_flags
is set if the AD (autenticated data) bit in the DNS answer is
set. This flag
.Em should not
be trusted unless the transport between the nameserver and the resolver
is secure (e.g. IPsec, trusted network, loopback communication).
/getnameinfo.3
0,0 → 1,302
.\" $OpenBSD: getnameinfo.3,v 1.16 2001/08/06 10:42:26 mpech Exp $
.\" $KAME: getnameinfo.3,v 1.20 2001/01/05 13:37:37 itojun Exp $
.\"
.\" Copyright (c) 1983, 1987, 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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.
.\"
.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
.\"
.Dd May 25, 1995
.Dt GETNAMEINFO 3
.Os
.\"
.Sh NAME
.Nm getnameinfo
.Nd address-to-nodename translation in protocol-independent manner
.\"
.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 defined for protocol-independent address-to-nodename translation.
Its functionality is a reverse conversion of
.Xr getaddrinfo 3 ,
and implements similar functionality with
.Xr gethostbyaddr 3
and
.Xr getservbyport 3
in more sophisticated manner.
.Pp
This function looks up an IP address and port number provided by the
caller in the DNS and system-specific database, and returns text
strings for both in buffers provided by the caller.
The function indicates successful completion by a zero return value;
a non-zero return value indicates failure.
.Pp
The first argument,
.Fa sa ,
points to either a
.Li sockaddr_in
structure (for IPv4) or a
.Li sockaddr_in6
structure (for IPv6) that holds the IP address and port number.
The
.Fa salen
argument gives the length of the
.Li sockaddr_in
or
.Li sockaddr_in6
structure.
.Pp
The function returns the nodename associated with the IP address in
the buffer pointed to by the
.Fa host
argument.
The caller provides the size of this buffer via the
.Fa hostlen
argument.
The service name associated with the port number is returned in the buffer
pointed to by
.Fa serv ,
and the
.Fa servlen
argument gives the length of this buffer.
The caller specifies not to return either string by providing a zero
value for the
.Fa hostlen
or
.Fa servlen
arguments.
Otherwise, the caller must provide buffers large enough to hold the
nodename and the service name, including the terminating null characters.
.Pp
Unfortunately most systems do not provide constants that specify the
maximum size of either a fully-qualified domain name or a service name.
Therefore to aid the application in allocating buffers for these two
returned strings the following constants are defined in
.Aq Pa netdb.h :
.Bd -literal -offset
#define NI_MAXHOST MAXHOSTNAMELEN
#define NI_MAXSERV 32
.Ed
.Pp
The first value is actually defined as the constant
.Dv MAXDNAME
in recent versions of BIND's
.Aq Pa arpa/nameser.h
header (older versions of BIND define this constant to be 256)
and the second is a guess based on the services listed in the current
Assigned Numbers RFC.
.Pp
The final argument is a
.Fa flag
that changes the default actions of this function.
By default the fully-qualified domain name (FQDN) for the host is
looked up in the DNS and returned.
If the flag bit
.Dv NI_NOFQDN
is set, only the nodename portion of the FQDN is returned for local hosts.
.Pp
If the
.Fa flag
bit
.Dv NI_NUMERICHOST
is set, or if the host's name cannot be located in the DNS,
the numeric form of the host's address is returned instead of its name
.Po
e.g., by calling
.Fn inet_ntop
instead of
.Fn gethostbyaddr
.Pc .
If the
.Fa flag
bit
.Dv NI_NAMEREQD
is set, an error is returned if the host's name cannot be located in the DNS.
.Pp
If the flag bit
.Dv NI_NUMERICSERV
is set, the numeric form of the service address is returned
.Pq e.g., its port number
instead of its name.
The two
.Dv NI_NUMERICxxx
flags are required to support the
.Fl n
flag that many commands provide.
.Pp
A fifth flag bit,
.Dv NI_DGRAM ,
specifies that the service is a datagram service, and causes
.Fn getservbyport
to be called with a second argument of
.Qq udp
instead of its default of
.Qq tcp .
This is required for the few ports (512-514)
that have different services for UDP and TCP.
.Pp
These
.Dv NI_xxx
flags are defined in
.Aq Pa netdb.h .
.\"
.Ss Extension for scoped IPv6 address
The implementation allows experimental numeric IPv6 address notation with
scope identifier.
IPv6 link-local address will appear as string like
.Dq Li fe80::1%ne0 ,
if
.Dv NI_WITHSCOPEID
bit is enabled in
.Ar flags
argument.
Refer to
.Xr getaddrinfo 3
for the notation.
.\"
.Sh EXAMPLES
The following code tries to get numeric hostname, and service name,
for given socket address.
Observe that there is no hardcoded reference to 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 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 DIAGNOSTICS
The function indicates successful completion by a zero return value;
a non-zero return value indicates failure.
Error codes are as below:
.Bl -tag -width Er
.It Dv EAI_AGAIN
The name could not be resolved at this time.
Future attempts may succeed.
.It Dv EAI_BADFLAGS
The flags had an invalid value.
.It Dv EAI_FAIL
A non-recoverable error occurred.
.It Dv EAI_FAMILY
The address family was not recognized or the address length was invalid
for the specified family.
.It Dv EAI_MEMORY
There was a memory allocation failure.
.It Dv EAI_NONAME
The name does not resolve for the supplied parameters.
.Dv NI_NAMEREQD
is set and the host's name cannot be located,
or both nodename and servname were null.
.It Dv EAI_SYSTEM
A system error occurred.
The error code can be found in errno.
.El
.\"
.Sh SEE ALSO
.Xr getaddrinfo 3 ,
.Xr gethostbyaddr 3 ,
.Xr getservbyport 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 RFC2553
.%D March 1999
.Re
.Rs
.%A Tatsuya Jinmei
.%A Atsushi Onoe
.%T "An Extension of Format for IPv6 Scoped Addresses"
.%R internet draft
.%N draft-ietf-ipngwg-scopedaddr-format-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 HISTORY
The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.
.\"
.Sh STANDARDS
The
.Fn getaddrinfo
function is defined IEEE POSIX 1003.1g draft specification,
and documented in
.Dq Basic Socket Interface Extensions for IPv6
.Pq RFC2553 .
.\"
.Sh BUGS
The current implementation is not thread-safe.
.Pp
The text was shamelessly copied from RFC2553.
.Pp
.Ox
intentionally uses different
.Dv NI_MAXHOST
value from what RFC2553 suggests, to avoid buffer length handling mistakes.
/getnetent.3
0,0 → 1,144
.\" $OpenBSD: getnetent.3,v 1.11 2000/12/24 00:30:56 aaron Exp $
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 March 13, 1997
.Dt GETNETENT 3
.Os
.Sh NAME
.Nm getnetent ,
.Nm getnetbyaddr ,
.Nm getnetbyname ,
.Nm setnetent ,
.Nm endnetent
.Nd get network entry
.Sh SYNOPSIS
.Fd #include <netdb.h>
.Ft struct netent *
.Fn getnetent "void"
.Ft struct netent *
.Fn getnetbyname "char *name"
.Ft struct netent *
.Fn getnetbyaddr "in_addr_t net" "int type"
.Ft void
.Fn setnetent "int stayopen"
.Ft void
.Fn endnetent "void"
.Sh DESCRIPTION
The
.Fn getnetent ,
.Fn getnetbyname ,
and
.Fn getnetbyaddr
functions each return a pointer to an object with the following structure
containing the broken-out fields of a line in the network database,
.Pa /etc/networks .
.Bd -literal -offset indent
struct netent {
char *n_name; /* official name of net */
char **n_aliases; /* alias list */
int n_addrtype; /* net number type */
in_addr_t n_net; /* net number */
};
.Ed
.Pp
The members of this structure are:
.Bl -tag -width n_addrtype
.It Fa n_name
The official name of the network.
.It Fa n_aliases
A zero-terminated list of alternate names for the network.
.It Fa n_addrtype
The type of the network number returned; currently only
.Dv AF_INET .
.It Fa n_net
The network number.
Network numbers are returned in machine byte order.
.El
.Pp
The
.Fn getnetent
function reads the next line of the file, opening the file if necessary.
.Pp
The
.Fn setnetent
function opens and rewinds the file.
If the
.Fa stayopen
flag is non-zero,
the net database will not be closed after each call to
.Fn getnetbyname
or
.Fn getnetbyaddr .
.Pp
The
.Fn endnetent
function closes the file.
.Pp
The
.Fn getnetbyname
and
.Fn getnetbyaddr
functions search the domain name server if the system is configured to use one.
If the search fails, or no name server is configured, they sequentially
search from the beginning of the file until a matching net name or
net address and type is found, or until
.Dv EOF
is encountered.
Network numbers are supplied in host order.
.Sh FILES
.Bl -tag -width /etc/networks -compact
.It Pa /etc/networks
.El
.Sh DIAGNOSTICS
Null pointer (0) returned on
.Dv EOF
or error.
.Sh SEE ALSO
.Xr resolver 3 ,
.Xr networks 5
.Sh HISTORY
The
.Fn getnetent ,
.Fn getnetbyaddr ,
.Fn getnetbyname ,
.Fn setnetent ,
and
.Fn endnetent
functions appeared in
.Bx 4.2 .
.Sh BUGS
The data space used by these functions is static; if future use
requires the data, it should be copied before any subsequent calls
to these functions overwrite it.
Only Internet network numbers are currently understood.
Expecting network numbers to fit in no more than 32 bits is naive.
/inet.3
0,0 → 1,349
.\" $OpenBSD: inet.3,v 1.13 2001/02/17 23:13:26 pjanzen Exp $
.\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem Exp $
.\"
.\" Copyright (c) 1983, 1990, 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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.
.\"
.\" @(#)inet.3 8.1 (Berkeley) 6/4/93
.\"
.Dd June 18, 1997
.Dt INET 3
.Os
.Sh NAME
.Nm inet_addr ,
.Nm inet_aton ,
.Nm inet_lnaof ,
.Nm inet_makeaddr ,
.Nm inet_netof ,
.Nm inet_network ,
.Nm inet_ntoa ,
.Nm inet_ntop ,
.Nm inet_pton
.Nd Internet address manipulation routines
.Sh SYNOPSIS
.Fd #include <sys/socket.h>
.Fd #include <netinet/in.h>
.Fd #include <arpa/inet.h>
.Ft in_addr_t
.Fn inet_addr "const char *cp"
.Ft int
.Fn inet_aton "const char *cp" "struct in_addr *addr"
.Ft in_addr_t
.Fn inet_lnaof "struct in_addr in"
.Ft struct in_addr
.Fn inet_makeaddr "unsigned long net" "unsigned long lna"
.Ft in_addr_t
.Fn inet_netof "struct in_addr in"
.Ft in_addr_t
.Fn inet_network "const char *cp"
.Ft char *
.Fn inet_ntoa "struct in_addr in"
.Ft const char *
.Fn inet_ntop "int af" "const void *src" "char *dst" "size_t size"
.Ft int
.Fn inet_pton "int af" "const char *src" "void *dst"
.Sh DESCRIPTION
The routines
.Fn inet_aton ,
.Fn inet_addr
and
.Fn inet_network
interpret character strings representing
numbers expressed in the Internet standard
.Ql \&.
notation.
The
.Fn inet_pton
function converts a presentation format address (that is, printable form
as held in a character string) to network format (usually a
.Li struct in_addr
or some other internal binary representation, in network byte order).
It returns 1 if the address was valid for the specified address family, or
0 if the address wasn't parseable in the specified address family, or \-1
if some system error occurred (in which case
.Va errno
will have been set).
This function is presently valid for
.Dv AF_INET
and
.Dv AF_INET6 .
The
.Fn inet_aton
routine interprets the specified character string as an Internet address,
placing the address into the structure provided.
It returns 1 if the string was successfully interpreted,
or 0 if the string was invalid.
The
.Fn inet_addr
and
.Fn inet_network
functions return numbers suitable for use
as Internet addresses and Internet network
numbers, respectively.
.Pp
The function
.Fn inet_ntop
converts an address from network format (usually a
.Li struct in_addr
or some other binary form, in network byte order) to presentation format
(suitable for external display purposes).
It returns
.Dv NULL
if a system
error occurs (in which case,
.Va errno
will have been set), or it returns a pointer to the destination string.
The routine
.Fn inet_ntoa
takes an Internet address and returns an
.Tn ASCII
string representing the address in
.Ql \&.
notation.
The routine
.Fn inet_makeaddr
takes an Internet network number and a local
network address and constructs an Internet address
from it.
The routines
.Fn inet_netof
and
.Fn inet_lnaof
break apart Internet host addresses, returning
the network number and local network address part,
respectively.
.Pp
All Internet addresses are returned in network
order (bytes ordered from left to right).
All network numbers and local address parts are
returned as machine format integer values.
.Sh INTERNET ADDRESSES (IP VERSION 4)
Values specified using the
.Ql \&.
notation take one
of the following forms:
.Bd -literal -offset indent
a.b.c.d
a.b.c
a.b
a
.Ed
.Pp
When four parts are specified, each is interpreted
as a byte of data and assigned, from left to right,
to the four bytes of an Internet address.
Note that when an Internet address is viewed as a 32-bit
integer quantity on a system that uses little-endian
byte order (such as the
.Tn Intel 386, 486
and
.Tn Pentium
processors) the bytes referred to above appear as
.Dq Li d.c.b.a .
That is, little-endian bytes are ordered from right to left.
.Pp
When a three part address is specified, the last
part is interpreted as a 16-bit quantity and placed
in the rightmost two bytes of the network address.
This makes the three part address format convenient
for specifying Class B network addresses as
.Dq Li 128.net.host .
.Pp
When a two part address is supplied, the last part
is interpreted as a 24-bit quantity and placed in
the rightmost three bytes of the network address.
This makes the two part address format convenient
for specifying Class A network addresses as
.Dq Li net.host .
.Pp
When only one part is given, the value is stored
directly in the network address without any byte
rearrangement.
.Pp
All numbers supplied as
.Dq parts
in a
.Ql \&.
notation
may be decimal, octal, or hexadecimal, as specified
in the C language (i.e., a leading 0x or 0X implies
hexadecimal; otherwise, a leading 0 implies octal;
otherwise, the number is interpreted as decimal).
.Sh INTERNET ADDRESSES (IP VERSION 6)
In order to support scoped IPv6 addresses,
.Xr getaddrinfo 3
and
.Xr getnameinfo 3
are recommended rather than the functions presented here.
.Pp
The presentation format of an IPv6 address is given in [RFC1884 2.2]:
.Pp
There are three conventional forms for representing IPv6 addresses as
text strings:
.Bl -enum
.It
The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the
hexadecimal values of the eight 16-bit pieces of the address.
Examples:
.Bd -literal -offset indent
FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
1080:0:0:0:8:800:200C:417A
.Ed
.Pp
Note that it is not necessary to write the leading zeros in an
individual field, but there must be at least one numeral in
every field (except for the case described in 2.).
.It
Due to the method of allocating certain styles of IPv6
addresses, it will be common for addresses to contain long
strings of zero bits.
In order to make writing addresses
.Pp
containing zero bits easier a special syntax is available to
compress the zeros.
The use of
.Dq \&:\&:
indicates multiple groups
of 16 bits of zeros.
The
.Dq \&:\&:
can only appear once in an
address.
The
.Dq \&:\&:
can also be used to compress the leading and/or trailing zeros in an address.
.Pp
For example the following addresses:
.Bd -literal -offset indent
1080:0:0:0:8:800:200C:417A a unicast address
FF01:0:0:0:0:0:0:43 a multicast address
0:0:0:0:0:0:0:1 the loopback address
0:0:0:0:0:0:0:0 the unspecified addresses
.Ed
.Pp
may be represented as:
.Bd -literal -offset indent
1080::8:800:200C:417A a unicast address
FF01::43 a multicast address
::1 the loopback address
:: the unspecified addresses
.Ed
.It
An alternative form that is sometimes more convenient when
dealing with a mixed environment of IPv4 and IPv6 nodes is
x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values
of the six high-order 16-bit pieces of the address, and the 'd's
are the decimal values of the four low-order 8-bit pieces of the
address (standard IPv4 representation).
Examples:
.Bd -literal -offset indent
0:0:0:0:0:0:13.1.68.3
0:0:0:0:0:FFFF:129.144.52.38
.Ed
.Pp
or in compressed form:
.Bd -literal -offset indent
::13.1.68.3
::FFFF:129.144.52.38
.Ed
.El
.Sh DIAGNOSTICS
The constant
.Dv INADDR_NONE
is returned by
.Fn inet_addr
and
.Fn inet_network
for malformed requests.
.Sh SEE ALSO
.Xr byteorder 3 ,
.Xr gethostbyname 3 ,
.Xr getnetent 3 ,
.Xr inet_net 3 ,
.Xr hosts 5 ,
.Xr networks 5
.Sh STANDARDS
The
.Nm inet_ntop
and
.Nm inet_pton
functions conforms to the IETF IPv6 BSD API and address formatting
specifications.
Note that
.Nm inet_pton
does not accept 1-, 2-, or 3-part dotted addresses; all four parts
must be specified.
This is a narrower input set than that accepted by
.Nm inet_aton .
.Sh HISTORY
The
.Nm inet_addr ,
.Nm inet_network ,
.Nm inet_makeaddr ,
.Nm inet_lnaof
and
.Nm inet_netof
functions appeared in
.Bx 4.2 .
The
.Nm inet_aton
and
.Nm inet_ntoa
functions appeared in
.Bx 4.3 .
The
.Nm inet_pton
and
.Nm inet_ntop
functions appeared in BIND 4.9.4.
.Sh BUGS
The value
.Dv INADDR_NONE
(0xffffffff) is a valid broadcast address, but
.Fn inet_addr
cannot return that value without indicating failure.
Also,
.Fn inet_addr
should have been designed to return a
.Li struct in_addr .
The newer
.Fn inet_aton
function does not share these problems, and almost all existing code
should be modified to use
.Fn inet_aton
instead.
.Pp
The problem of host byte ordering versus network byte ordering is
confusing.
.Pp
The string returned by
.Fn inet_ntoa
resides in a static memory area.
/byteorder.3
0,0 → 1,183
.\" $OpenBSD: byteorder.3,v 1.8 2000/04/18 03:01:30 aaron Exp $
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 June 4, 1993
.Dt BYTEORDER 3
.Os
.Sh NAME
.Nm htonl ,
.Nm htons ,
.Nm ntohl ,
.Nm ntohs ,
.Nm htobe32 ,
.Nm htobe16 ,
.Nm betoh32 ,
.Nm betoh16 ,
.Nm htole32 ,
.Nm htole16 ,
.Nm letoh32 ,
.Nm letoh16 ,
.Nm swap32 ,
.Nm swap16
.Nd convert values between different byte orderings
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <machine/endian.h>
.Ft u_int32_t
.Fn htonl "u_int32_t host32"
.Ft u_int16_t
.Fn htons "u_int16_t host16"
.Ft u_int32_t
.Fn ntohl "u_int32_t net32"
.Ft u_int16_t
.Fn ntohs "u_int16_t net16"
.Ft u_int32_t
.Fn htobe32 "u_int32_t host32"
.Ft u_int16_t
.Fn htobe16 "u_int16_t host16"
.Ft u_int32_t
.Fn betoh32 "u_int32_t big32"
.Ft u_int16_t
.Fn betoh16 "u_int16_t big16"
.Ft u_int32_t
.Fn htole32 "u_int32_t host32"
.Ft u_int16_t
.Fn htole16 "u_int16_t host16"
.Ft u_int32_t
.Fn letoh32 "u_int32_t little32"
.Ft u_int16_t
.Fn letoh16 "u_int16_t little16"
.Ft u_int32_t
.Fn swap32 "u_int32_t val32"
.Ft u_int16_t
.Fn swap16 "u_int16_t val16"
.Sh DESCRIPTION
These routines convert 16- and 32-bit quantities between different
byte orderings.
The
.Dq swap
functions reverse the byte ordering of
the given quantity, the others converts either from/to the native
byte order used by the host to/from either little- or big-endian (a.k.a
network) order.
.Pp
Apart from the swap functions, the names can be described by this form:
{src-order}to{dst-order}{size}.
Both {src-order} and {dst-order} can take the following forms:
.Pp
.Bl -tag -width "be " -offset indent -compact
.It h
Host order.
.It n
Network order (big-endian).
.It be
Big-endian (most significant byte first).
.It le
Little-endian (least significant byte first).
.El
.Pp
One of the specified orderings must be
.Sq h .
{size} will take these forms:
.Pp
.Bl -tag -width "32 " -offset indent -compact
.It l
Long (32-bit, used in conjunction with forms involving
.Sq n ) .
.It s
Short (16-bit, used in conjunction with forms involving
.Sq n ) .
.It 16
16-bit.
.It 32
32-bit.
.El
.Pp
The swap functions are of the form: swap{size}.
.Pp
Names involving
.Sq n
convert quantities between network
byte order and host byte order.
The last letter
.Pf ( Sq s
or
.Sq l )
is a mnemonic
for the traditional names for such quantities,
.Li short
and
.Li long ,
respectively.
Today, the C concept of
.Li short
and
.Li long
integers need not coincide with this traditional misunderstanding.
On machines which have a byte order which is the same as the network
order, routines are defined as null macros.
.Pp
The functions involving either
.Dq be ,
.Dq le ,
or
.Dq swap
use the numbers
16 and 32 for specifying the bitwidth of the quantities they operate on.
Currently all supported architectures are either big- or little-endian
so either the
.Dq be
or
.Dq le
variants are implemented as null macros.
.Pp
The routines mentioned above which have either {src-order} or {dst-order}
set to
.Sq n
are most often used in
conjunction with Internet addresses and ports as returned by
.Xr gethostbyname 3
and
.Xr getservent 3 .
.Sh SEE ALSO
.Xr gethostbyname 3 ,
.Xr getservent 3
.Sh HISTORY
The
.Nm byteorder
functions appeared in
.Bx 4.2 .
.Sh BUGS
On the vax, alpha, i386, and so far mips,
bytes are handled backwards from most everyone else in the world.
This is not expected to be fixed in the near future.
/ipx.3
0,0 → 1,127
.\" $OpenBSD: ipx.3,v 1.8 2001/08/02 20:37:35 hugh Exp $
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 June 4, 1993
.Dt IPX 3
.Os
.Sh NAME
.Nm ipx_addr ,
.Nm ipx_ntoa
.Nd IPX address conversion routines
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <netipx/ipx.h>
.Ft struct ipx_addr
.Fn ipx_addr "const char *cp"
.Ft char *
.Fn ipx_ntoa "struct ipx_addr ipx"
.Sh DESCRIPTION
The routine
.Fn ipx_addr
interprets character strings representing
.Tn IPX
addresses, returning binary information suitable
for use in system calls.
The routine
.Fn ipx_ntoa
takes
.Tn IPX
addresses and returns
.Tn ASCII
strings representing the address in a
notation in common use:
.Bd -filled -offset indent
<network number>.<host number>.<port number>
.Ed
.Pp
Trailing zero fields are suppressed, and each number is printed in hexadecimal,
in a format suitable for input to
.Fn ipx_addr .
Any fields lacking super-decimal digits will have a
trailing
.Sq H
appended.
.Pp
An effort has been made to ensure that
.Fn ipx_addr
be compatible with most formats in common use.
It will first separate an address into 1 to 3 fields using a single delimiter
chosen from
period
.Pq Ql \&. ,
colon
.Pq Ql \&: ,
or pound-sign
.Pq Ql # .
Each field is then examined for byte separators (colon or period).
If there are byte separators, each subfield separated is taken to be
a small hexadecimal number, and the entirety is taken as a network-byte-ordered
quantity to be zero extended in the high-network-order bytes.
Next, the field is inspected for hyphens, in which case
the field is assumed to be a number in decimal notation
with hyphens separating the millenia.
Next, the field is assumed to be a number:
It is interpreted
as hexadecimal if there is a leading
.Ql 0x
(as in C),
a trailing
.Sq H
(as in Mesa), or there are any super-decimal digits present.
It is interpreted as octal is there is a leading
.Ql 0
and there are no super-octal digits.
Otherwise, it is converted as a decimal number.
.Sh RETURN VALUES
None.
(See
.Sx BUGS . )
.Sh SEE ALSO
.Xr ns 4 ,
.Xr hosts 5 ,
.Xr networks 5
.Sh HISTORY
The precursor
.Fn ns_addr
and
.Fn ns_ntoa
functions appeared in
.Bx 4.3 .
.Sh BUGS
The string returned by
.Fn ipx_ntoa
resides in a static memory area.
The function
.Fn ipx_addr
should diagnose improperly formed input, and there should be an unambiguous
way to recognize this.
/resolver.3
0,0 → 1,345
.\" $OpenBSD: resolver.3,v 1.15 2001/04/03 20:09:08 aaron Exp $
.\"
.\" Copyright (c) 1985, 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 June 4, 1993
.Dt RESOLVER 3
.Os
.Sh NAME
.Nm res_query ,
.Nm res_search ,
.Nm res_mkquery ,
.Nm res_send ,
.Nm res_init ,
.Nm dn_comp ,
.Nm dn_expand
.Nd resolver routines
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <netinet/in.h>
.Fd #include <arpa/nameser.h>
.Fd #include <resolv.h>
.Ft int
.Fo res_query
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "u_char *answer"
.Fa "int anslen"
.Fc
.Ft int
.Fo res_search
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "u_char *answer"
.Fa "int anslen"
.Fc
.Ft int
.Fo res_mkquery
.Fa "int op"
.Fa "char *dname"
.Fa "int class"
.Fa "int type"
.Fa "char *data"
.Fa "int datalen"
.Fa "struct rrec *newrr"
.Fa "char *buf"
.Fa "int buflen"
.Fc
.Ft int
.Fo res_send
.Fa "char *msg"
.Fa "int msglen"
.Fa "char *answer"
.Fa "int anslen"
.Fc
.Ft int
.Fn res_init "void"
.Ft int
.Fo dn_comp
.Fa "char *exp_dn"
.Fa "char *comp_dn"
.Fa "int length"
.Fa "char **dnptrs"
.Fa "char **lastdnptr"
.Fc
.Ft int
.Fo dn_expand
.Fa "u_char *msg"
.Fa "u_char *eomorig"
.Fa "u_char *comp_dn"
.Fa "u_char *exp_dn"
.Fa "int length"
.Fc
.Sh DESCRIPTION
These routines are used for making, sending, and interpreting
query and reply messages with Internet domain name servers.
.Pp
Global configuration and state information that is used by the
resolver routines is kept in the structure
.Li _res .
Most of the values have reasonable defaults and can be ignored.
Options stored in
.Li _res.options
are defined in
.Aq Pa resolv.h
and are as follows.
Options are stored as a simple bit mask containing the bitwise
.Tn OR
of the options enabled.
.Bl -tag -width RES_USE_INET6
.It Dv RES_INIT
True if the initial name server address and default domain name are
initialized (i.e.,
.Fn res_init
has been called).
.It Dv RES_DEBUG
Print debugging messages.
.It Dv RES_AAONLY
Accept authoritative answers only.
With this option,
.Fn res_send
should continue until it finds an authoritative answer or finds an error.
Currently this is not implemented.
.It Dv RES_USEVC
Use
.Tn TCP
connections for queries instead of
.Tn UDP
datagrams.
.It Dv RES_STAYOPEN
Used with
.Dv RES_USEVC
to keep the
.Tn TCP
connection open between queries.
This is useful only in programs that regularly do many queries.
.Tn UDP
should be the normal mode used.
.It Dv RES_IGNTC
Unused currently (ignore truncation errors, i.e., don't retry with
.Tn TCP ) .
.It Dv RES_RECURSE
Set the recursion-desired bit in queries.
This is the default.
.Pf ( Fn res_send
does not do iterative queries and expects the name server
to handle recursion.)
.It Dv RES_DEFNAMES
If set,
.Fn res_search
will append the default domain name to single-component names
(those that do not contain a dot).
This option is enabled by default.
.It Dv RES_DNSRCH
If this option is set,
.Fn res_search
will search for host names in the current domain and in parent domains; see
.Xr hostname 7 .
This is used by the standard host lookup routine
.Xr gethostbyname 3 .
This option is enabled by default.
.It Dv RES_USE_INET6
Enables support for IPv6-only applications.
This causes IPv4 addresses to be returned as an IPv4 mapped address.
For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1.
The option is not meaningful on
.Ox .
.El
.Pp
The
.Fn res_init
routine reads the configuration file (if any; see
.Xr resolv.conf 5 )
to get the default domain name, search list, and the Internet address
of the local name server(s).
If no server is configured, the host running
the resolver is tried.
The current domain name is defined by the hostname
if not specified in the configuration file;
it can be overridden by the environment variable
.Ev LOCALDOMAIN .
This environment variable may contain several blank-separated
tokens if you wish to override the
.Fa search list
on a per-process basis.
This is similar to the
.Fa search
command in the configuration file.
Another environment variable
.Ev RES_OPTIONS
can be set to override certain internal resolver options which
are otherwise set by changing fields in the
.Fa _res
structure or are inherited from the configuration file's
.Fa options
command.
The syntax of the
.Ev RES_OPTIONS
environment variable is explained in
.Xr resolv.conf 5 .
Initialization normally occurs on the first call
to one of the following routines.
.Pp
The
.Fn res_query
function provides an interface to the server query mechanism.
It constructs a query, sends it to the local server,
awaits a response, and makes preliminary checks on the reply.
The query requests information of the specified
.Fa type
and
.Fa class
for the specified fully qualified domain name
.Fa dname .
The reply message is left in the
.Fa answer
buffer with length
.Fa anslen
supplied by the caller.
.Pp
The
.Fn res_search
routine makes a query and awaits a response like
.Fn res_query ,
but in addition, it implements the default and search rules controlled by the
.Dv RES_DEFNAMES
and
.Dv RES_DNSRCH
options.
It returns the first successful reply.
.Pp
The remaining routines are lower-level routines used by
.Fn res_query .
The
.Fn res_mkquery
function constructs a standard query message and places it in
.Fa buf .
It returns the size of the query, or \-1 if the query is larger than
.Fa buflen .
The query type
.Fa op
is usually
.Dv QUERY ,
but can be any of the query types defined in
.Aq Pa arpa/nameser.h .
The domain name for the query is given by
.Fa dname .
.Fa newrr
is currently unused but is intended for making update messages.
.Pp
The
.Fn res_send
routine sends a pre-formatted query and returns an answer.
It will call
.Fn res_init
if
.Dv RES_INIT
is not set, send the query to the local name server, and
handle timeouts and retries.
The length of the reply message is returned, or \-1 if there were errors.
.Pp
The
.Fn dn_comp
function compresses the domain name
.Fa exp_dn
and stores it in
.Fa comp_dn .
The size of the compressed name is returned or \-1 if there were errors.
The size of the array pointed to by
.Fa comp_dn
is given by
.Fa length .
The compression uses an array of pointers
.Fa dnptrs
to previously compressed names in the current message.
The first pointer points
to the beginning of the message and the list ends with
.Dv NULL .
The limit to the array is specified by
.Fa lastdnptr .
A side effect of
.Fn dn_comp
is to update the list of pointers for labels inserted into the message
as the name is compressed.
If
.Em dnptr
is
.Dv NULL ,
names are not compressed.
If
.Fa lastdnptr
is
.Dv NULL ,
the list of labels is not updated.
.Pp
The
.Fn dn_expand
entry expands the compressed domain name
.Fa comp_dn
to a full domain name
The compressed name is contained in a query or reply message;
.Fa msg
is a pointer to the beginning of the message.
The uncompressed name is placed in the buffer indicated by
.Fa exp_dn
which is of size
.Fa length .
The size of compressed name is returned or \-1 if there was an error.
.Sh FILES
.Bl -tag -width Pa
/etc/resolv.conf
configuration file
see
.Xr resolv.conf 5 .
.El
.Sh SEE ALSO
.Xr gethostbyname 3 ,
.Xr resolv.conf 5 ,
.Xr hostname 7 ,
.Xr named 8
.Pp
.%T RFC1032 ,
.%T RFC1033 ,
.%T RFC1034 ,
.%T RFC1035 ,
.%T RFC1535 ,
.%T RFC974
.Rs
.%T "Name Server Operations Guide for BIND"
.Re
.Sh HISTORY
The
.Nm
function appeared in
.Bx 4.3 .
/inet6_rthdr_space.3
0,0 → 1,325
.\" $OpenBSD: inet6_rthdr_space.3,v 1.8 2001/06/23 05:57:04 deraadt Exp $
.\" $KAME: inet6_rthdr_space.3,v 1.8 2000/05/17 14:30:15 itojun Exp $
.\"
.\" Copyright (c) 1983, 1987, 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 10, 1999
.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 SYNOPSIS
.Fd #include <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
RFC2292 IPv6 advanced API defines eight
functions that the application calls to build and examine a Routing
header.
Four functions build a Routing header:
.Bl -hang
.It Fn inet6_rthdr_space
return #bytes required for ancillary data
.It Fn inet6_rthdr_init
initialize ancillary data for Routing header
.It Fn inet6_rthdr_add
add IPv6 address & flags to Routing header
.It Fn inet6_rthdr_lasthop
specify the flags for the final hop
.El
.Pp
Four functions deal with a returned Routing header:
.Bl -hang
.It Fn inet6_rthdr_reverse
reverse a Routing header
.It Fn inet6_rthdr_segments
return #segments in a Routing header
.It Fn inet6_rthdr_getaddr
fetch one address from a Routing header
.It Fn inet6_rthdr_getflags
fetch one flag from a Routing header
.El
.Pp
The function prototypes for these functions are all in the
.Aq Li netinet/in.h
header.
.\"
.Ss inet6_rthdr_space
This function returns the number of bytes required to hold a Routing
header of the specified
.Fa type
containing the specified number of
.Fa segments
.Pq addresses .
For an IPv6 Type 0 Routing header, the number
of segments must be between 1 and 23, inclusive.
The return value
includes the size of the cmsghdr structure that precedes the Routing
header, and any required padding.
.Pp
If the return value is 0, then either the type of the Routing header
is not supported by this implementation or the number of segments is
invalid for this type of Routing header.
.Pp
Note: This function returns the size but does not allocate the space
required for the ancillary data.
This allows an application to
allocate a larger buffer, if other ancillary data objects are
desired, since all the ancillary data objects must be specified to
.Xr sendmsg 2
as a single
.Li msg_control
buffer.
.\"
.Ss inet6_rthdr_init
This function initializes the buffer pointed to by
.Fa bp
to contain a
.Li cmsghdr
structure followed by a Routing header of the specified
.Fa type .
The
.Li cmsg_len
member of the
.Li cmsghdr
structure is initialized to the
size of the structure plus the amount of space required by the
Routing header.
The
.Li cmsg_level
and
.Li cmsg_type
members are also initialized as required.
.Pp
The caller must allocate the buffer and its size can be determined by
calling
.Fn inet6_rthdr_space .
.Pp
Upon success the return value is the pointer to the
.Li cmsghdr
structure, and this is then used as the first argument to the next
two functions.
Upon an error the return value is
.Dv NULL .
.\"
.Ss inet6_rthdr_add
This function adds the address pointed to by
.Fa addr
to the end of the
Routing header being constructed and sets the type of this hop to the
value of
.Fa flags .
For an IPv6 Type 0 Routing header,
.Fa flags
must be
either
.Dv IPV6_RTHDR_LOOSE
or
.Dv IPV6_RTHDR_STRICT .
.Pp
If successful, the
.Li cmsg_len
member of the
.Li cmsghdr
structure is
updated to account for the new address in the Routing header and the
return value of the function is 0.
Upon an error the return value of
the function is -1.
.\"
.Ss inet6_rthdr_lasthop
This function specifies the Strict/Loose flag for the final hop of a
Routing header.
For an IPv6 Type 0 Routing header,
.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, or -1 upon an error.
.Pp
Notice that a Routing header specifying
.Li N
intermediate nodes requires
.Li N+1
Strict/Loose flags.
This requires
.Li N
calls to
.Fn inet6_rthdr_add
followed by one call to
.Fn inet6_rthdr_lasthop .
.\"
.Ss inet6_rthdr_reverse
This function takes a Routing header that was received as ancillary
data
.Po
pointed to by the first argument,
.Fa in
.Pc
and writes a new Routing
header that sends datagrams along the reverse of that route.
Both
arguments are allowed to point to the same buffer
.Pq that is, the reversal can occur in place .
.Pp
The return value of the function is 0 on success, or -1 upon an
error.
.\"
.Ss inet6_rthdr_segments
This function returns the number of segments
.Pq addresses
contained in
the Routing header described by
.Fa cmsg .
On success the return value is
between 1 and 23, inclusive.
The return value of the function is -1 upon an error.
.\"
.Ss inet6_rthdr_getaddr
This function returns a pointer to the IPv6 address specified by
.Fa index
.Po
which must have a value between 1 and the value returned by
.Fn inet6_rthdr_segments
.Pc
in the Routing header described by
.Fa cmsg .
An
application should first call
.Fn inet6_rthdr_segments
to obtain the number of segments in the Routing header.
.Pp
Upon an error the return value of the function is
.Dv NULL .
.\"
.Ss inet6_rthdr_getflags
This function returns the flags value specified by
.Fa index
.Po
which must
have a value between 0 and the value returned by
.Fn inet6_rthdr_segments
.Pc
in the Routing header described by
.Fa cmsg .
For an IPv6 Type 0 Routing header the return value will be either
.Dv IPV6_RTHDR_LOOSE
or
.Dv IPV6_RTHDR_STRICT .
.Pp
Upon an error the return value of the function is -1.
.Pp
Note: Addresses are indexed starting at 1, and flags starting at 0,
to maintain consistency with the terminology and figures in RFC2460.
.\"
.Sh DIAGNOSTICS
.Fn inet6_rthdr_space
returns 0 on errors.
.Pp
.Fn inet6_rthdr_add ,
.Fn inet6_rthdr_lasthop
and
.Fn inet6_rthdr_reverse
return 0 on success, and returns -1 on error.
.Pp
.Fn inet6_rthdr_init
and
.Fn inet6_rthdr_getaddr
return
.Dv NULL
on error.
.Pp
.Fn inet6_rthdr_segments
and
.Fn inet6_rthdr_getflags
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 STANDARDS
The functions
are documented in
.Dq Advanced Sockets API for IPv6
.Pq RFC2292 .
.\"
.Sh BUGS
The text was shamelessly copied from RFC2292.
.Pp
.Fn inet6_rthdr_reverse
is not implemented yet.
/inet_net.3
0,0 → 1,148
.\" $OpenBSD: inet_net.3,v 1.6 2000/04/21 15:38:17 aaron Exp $
.\" $NetBSD: inet_net.3,v 1.1 1997/06/18 02:25:27 lukem Exp $
.\"
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Luke Mewburn.
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the NetBSD
.\" Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation 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 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 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 June 18, 1997
.Dt INET_NET 3
.Os
.Sh NAME
.Nm inet_net_ntop ,
.Nm inet_net_pton
.Nd Internet network number manipulation routines
.Sh SYNOPSIS
.Fd #include <sys/socket.h>
.Fd #include <netinet/in.h>
.Fd #include <arpa/inet.h>
.Ft char *
.Fn inet_net_ntop "int af" "const void *src" "int bits" "char *dst" "size_t size"
.Ft int
.Fn inet_net_pton "int af" "const char *src" "void *dst" "size_t size"
.Sh DESCRIPTION
The
.Fn inet_net_ntop
function converts an Internet network number from network format (usually a
.Li struct in_addr
or some other binary form, in network byte order) to CIDR presentation format
(suitable for external display purposes).
.Fa bits
is the number of bits in
.Fa src
that are the network number.
It returns
.Dv NULL
if a system error occurs (in which case,
.Va errno
will have been set), or it returns a pointer to the destination string.
.Pp
The
.Fn inet_net_pton
function converts a presentation format Internet network number (that is,
printable form as held in a character string) to network format (usually a
.Li struct in_addr
or some other internal binary representation, in network byte order).
It returns the number of bits (either computed based on the class, or
specified with /CIDR), or \-1 if a failure occurred
(in which case
.Va errno
will have been set.
It will be set to
.Er ENOENT
if the Internet network number was not valid).
.Pp
The only value for
.Fa af
currently supported is
.Dv AF_INET .
.Fa size
is the size of the result buffer
.Fa dst .
.Sh NETWORK NUMBERS (IP VERSION 4)
Internet network numbers may be specified in one of the following forms:
.Bd -literal -offset indent
a.b.c.d/bits
a.b.c.d
a.b.c
a.b
a
.Ed
.Pp
When four parts are specified, each is interpreted
as a byte of data and assigned, from left to right,
to the four bytes of an Internet network number.
Note that when an Internet network number is viewed as a 32-bit
integer quantity on a system that uses little-endian
byte order (such as the Intel 386, 486, and Pentium processors)
the bytes referred to above appear as
.Dq Li d.c.b.a .
That is, little-endian bytes are ordered from right to left.
.Pp
When a three part number is specified, the last
part is interpreted as a 16-bit quantity and placed
in the rightmost two bytes of the Internet network number.
This makes the three part number format convenient
for specifying Class B network numbers as
.Dq Li 128.net.host .
.Pp
When a two part number is supplied, the last part
is interpreted as a 24-bit quantity and placed in
the rightmost three bytes of the Internet network number.
This makes the two part number format convenient
for specifying Class A network numbers as
.Dq Li net.host .
.Pp
When only one part is given, the value is stored
directly in the Internet network number without any byte
rearrangement.
.Pp
All numbers supplied as
.Dq parts
in a
.Ql \&.
notation
may be decimal, octal, or hexadecimal, as specified
in the C language (i.e., a leading 0x or 0X implies
hexadecimal; otherwise, a leading 0 implies octal;
otherwise, the number is interpreted as decimal).
.Sh SEE ALSO
.Xr byteorder 3 ,
.Xr inet 3 ,
.Xr networks 5
.Sh HISTORY
The
.Nm inet_net_ntop
and
.Nm inet_net_pton
functions first appeared in BIND 4.9.4.
/gethostbyname.3
0,0 → 1,275
.\" $OpenBSD: gethostbyname.3,v 1.16 2000/12/24 00:30:56 aaron Exp $
.\"
.\" Copyright (c) 1983, 1987, 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 March 13, 1997
.Dt GETHOSTBYNAME 3
.Os
.Sh NAME
.Nm gethostbyname ,
.Nm gethostbyname2 ,
.Nm gethostbyaddr ,
.Nm gethostent ,
.Nm sethostent ,
.Nm endhostent ,
.Nm hstrerror ,
.Nm herror
.Nd get network host entry
.Sh SYNOPSIS
.Fd #include <netdb.h>
.Fd extern int h_errno;
.Ft struct hostent *
.Fn gethostbyname "const char *name"
.Ft struct hostent *
.Fn gethostbyname2 "const char *name" "int af"
.Ft struct hostent *
.Fn gethostbyaddr "const char *addr" "int len" "int af"
.Ft struct hostent *
.Fn gethostent void
.Ft void
.Fn sethostent "int stayopen"
.Ft void
.Fn endhostent void
.Ft void
.Fn herror "const char *string"
.Ft const char *
.Fn hstrerror "int err"
.Sh DESCRIPTION
The
.Fn gethostbyname
and
.Fn gethostbyaddr
functions each return a pointer to an object with the following structure
describing an internet host referenced by name or by address, respectively.
This structure contains either information obtained from the name server (i.e.,
.Xr resolver 3
and
.Xr named 8 ) ,
broken-out fields from a line in
.Pa /etc/hosts ,
or database entries supplied by the
.Xr yp 8
system.
.Xr resolv.conf 5
describes how the particular database is chosen.
.Bd -literal
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses from name server */
};
#define h_addr h_addr_list[0] /* address, for backward compatibility */
.Ed
.Pp
The members of this structure are:
.Bl -tag -width h_addr_list
.It Fa h_name
Official name of the host.
.It Fa h_aliases
A zero-terminated array of alternate names for the host.
.It Fa h_addrtype
The type of address being returned.
.It Fa h_length
The length, in bytes, of the address.
.It Fa h_addr_list
A zero-terminated array of network addresses for the host.
Host addresses are returned in network byte order.
.It Fa h_addr
The first address in
.Fa h_addr_list ;
this is for backward compatibility.
.El
.Pp
The function
.Fn gethostbyname
will search for the named host in the current domain and its parents
using the search lookup semantics detailed in
.Xr resolv.conf 5
and
.Xr hostname 7 .
.Pp
.Fn gethostbyname2
is an advanced form of
.Fn gethostbyname
which allows lookups in address families other than
.Dv AF_INET ,
for example
.Dv AF_INET6 .
.Pp
The
.Fn gethostbyaddr
function will search for the specified address of length
.Fa len
in the address family
.Fa af .
The only address family currently supported is
.Dv AF_INET .
.Pp
The
.Fn sethostent
function may be used to request the use of a connected
.Tn TCP
socket for queries.
If the
.Fa stayopen
flag is non-zero,
this sets the option to send all queries to the name server using
.Tn TCP
and to retain the connection after each call to
.Fn gethostbyname
or
.Fn gethostbyaddr .
Otherwise, queries are performed using
.Tn UDP
datagrams.
.Pp
The
.Fn endhostent
function closes the
.Tn TCP
connection.
.Pp
The
.Fn herror
function prints an error message describing the failure.
If its argument
.Fa string
is non-null,
it is prepended to the message string and separated from it by a colon
.Pq Ql \&:
and a space.
The error message is printed with a trailing newline.
The contents of the error message is the same as that returned by
.Fn hstrerror
with argument
.Fa h_errno .
.Sh FILES
.Bl -tag -width /etc/resolv.conf -compact
.It Pa /etc/hosts
.It Pa /etc/resolv.conf
.El
.Sh DIAGNOSTICS
Error return status from
.Fn gethostbyname ,
.Fn gethostbyname2 ,
and
.Fn gethostbyaddr
is indicated by return of a null pointer.
The external integer
.Va h_errno
may then be checked to see whether this is a temporary failure
or an invalid or unknown host.
.Pp
The variable
.Va h_errno
can have the following values:
.Bl -tag -width HOST_NOT_FOUND
.It Dv HOST_NOT_FOUND
No such host is known.
.It Dv TRY_AGAIN
This is usually a temporary error
and means that the local server did not receive
a response from an authoritative server.
A retry at some later time may succeed.
.It Dv NO_RECOVERY
Some unexpected server failure was encountered.
This is a non-recoverable error.
.It Dv NO_DATA
The requested name is valid but does not have an IP address;
this is not a temporary error.
This means that the name is known to the name server but there is no address
associated with this name.
Another type of request to the name server using this domain name
will result in an answer;
for example, a mail-forwarder may be registered for this domain.
.El
.Sh SEE ALSO
.Xr resolver 3 ,
.Xr getaddrinfo 3 ,
.Xr getnameinfo 3 ,
.Xr hosts 5 ,
.Xr resolv.conf 5 ,
.Xr hostname 7 ,
.Xr named 8
.Sh CAVEAT
If the search routines in
.Xr resolv.conf 5
decide to read the
.Pa /etc/hosts
file,
.Fn gethostent
and other functions will
read the next line of the file,
re-opening the file if necessary.
.Pp
The
.Fn sethostent
function opens and/or rewinds the file
.Pa /etc/hosts .
If the
.Fa stayopen
argument is non-zero, the file will not be closed after each call to
.Fn gethostbyname ,
.Fn gethostbyname2 ,
or
.Fn gethostbyaddr .
.Pp
The
.Fn endhostent
function closes the file.
.Sh HISTORY
The
.Fn herror
function appeared in
.Bx 4.3 .
The
.Fn endhostent ,
.Fn gethostbyaddr ,
.Fn gethostbyname ,
.Fn gethostent ,
and
.Fn sethostent
functions appeared in
.Bx 4.2 .
.Sh BUGS
These functions use static data storage;
if the data is needed for future use, it should be
copied before any subsequent calls overwrite it.
Only the Internet
address formats are currently understood.
.Pp
YP does not support any address families other than
.Dv AF_INET
and uses
the traditional database format.
/getprotoent.3
0,0 → 1,134
.\" $OpenBSD: getprotoent.3,v 1.8 2000/12/24 00:30:56 aaron Exp $
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. 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 June 4, 1993
.Dt GETPROTOENT 3
.Os
.Sh NAME
.Nm getprotoent ,
.Nm getprotobynumber ,
.Nm getprotobyname ,
.Nm setprotoent ,
.Nm endprotoent
.Nd get protocol entry
.Sh SYNOPSIS
.Fd #include <netdb.h>
.Ft struct protoent *
.Fn getprotoent "void"
.Ft struct protoent *
.Fn getprotobyname "char *name"
.Ft struct protoent *
.Fn getprotobynumber "int proto"
.Ft void
.Fn setprotoent "int stayopen"
.Ft void
.Fn endprotoent "void"
.Sh DESCRIPTION
The
.Fn getprotoent ,
.Fn getprotobyname ,
and
.Fn getprotobynumber
functions each return a pointer to an object with the following structure
containing the broken-out fields of a line in the network protocol database,
.Pa /etc/protocols .
.Bd -literal -offset indent
.Pp
struct protoent {
char *p_name; /* official name of protocol */
char **p_aliases; /* alias list */
int p_proto; /* protocol number */
};
.Ed
.Pp
The members of this structure are:
.Bl -tag -width p_aliases
.It Fa p_name
The official name of the protocol.
.It Fa p_aliases
A zero-terminated list of alternate names for the protocol.
.It Fa p_proto
The protocol number.
.El
.Pp
The
.Fn getprotoent
function reads the next line of the file, opening the file if necessary.
.Pp
The
.Fn setprotoent
function opens and rewinds the file.
If the
.Fa stayopen
flag is non-zero,
the net database will not be closed after each call to
.Fn getprotobyname
or
.Fn getprotobynumber .
.Pp
The
.Fn endprotoent
function closes the file.
.Pp
The
.Fn getprotobyname
and
.Fn getprotobynumber
functions sequentially search from the beginning of the file until a
matching protocol name or protocol number is found, or until
.Dv EOF
is encountered.
.Sh RETURN VALUES
Null pointer (0) returned on
.Dv EOF
or error.
.Sh FILES
.Bl -tag -width /etc/protocols -compact
.It Pa /etc/protocols
.El
.Sh SEE ALSO
.Xr protocols 5
.Sh HISTORY
The
.Fn getprotoent ,
.Fn getprotobynumber ,
.Fn getprotobyname ,
.Fn setprotoent ,
and
.Fn endprotoent
functions appeared in
.Bx 4.2 .
.Sh BUGS
These functions use a static data space; if the data is needed for future use,
it should be copied before any subsequent calls overwrite it.
Only the Internet protocols are currently understood.
/getifaddrs.3
0,0 → 1,158
.\" $OpenBSD: getifaddrs.3,v 1.7 2001/10/01 21:58:53 millert Exp $
.\" BSDI getifaddrs.3,v 2.5 2000/02/23 14:51:59 dab Exp
.\"
.\" Copyright (c) 1995, 1999
.\" Berkeley Software Design, Inc. 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``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 Berkeley Software Design, Inc. 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 12, 1995"
.Dt GETIFADDRS 3
.Sh NAME
.Nm getifaddrs
.Nd get interface addresses
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Fd #include <ifaddrs.h>
.Ft int
.Fn getifaddrs "struct ifaddrs **ifap"
.Ft void
.Fn freeifaddrs "struct ifaddrs *ifap"
.Sh DESCRIPTION
The
.Fn getifaddrs
function stores a reference to a linked list of the network interfaces
on the local machine in the memory referenced by
.Fa ifap .
The list consists of
.Nm ifaddrs
structures, as defined in the include file
.Aq Pa ifaddrs.h .
The
.Nm ifaddrs
structure contains at least the following entries:
.Bd -literal
struct ifaddrs *ifa_next; /* Pointer to next struct */
char *ifa_name; /* Interface name */
u_int ifa_flags; /* Interface flags */
struct sockaddr *ifa_addr; /* Interface address */
struct sockaddr *ifa_netmask; /* Interface netmask */
struct sockaddr *ifa_broadaddr; /* Interface broadcast address */
struct sockaddr *ifa_dstaddr; /* P2P interface destination */
void *ifa_data; /* Address specific data */
.Ed
.Pp
.Bl -tag -width Ds
.It Fa ifa_next
Contains a pointer to the next structure on the list.
This field is set to
.Dv NULL
in last structure on the list.
.It Fa ifa_name
Contains the interface name.
.It Fa ifa_flags
Contains the interface flags, as set by
.Xr ifconfig 8 .
.It Fa ifa_addr
References either the address of the interface or the link level
address of the interface, if one exists, otherwise it is
.Dv NULL .
(The
.Fa sa_family
field of the
.Fa ifa_addr
field should be consulted to determine the format of the
.Fa ifa_addr
address.)
.It Fa ifa_netmask
References the netmask associated with
.Fa ifa_addr ,
if one is set, otherwise it is
.Dv NULL .
.It Fa ifa_broadaddr
This field, which should only be referenced for non-P2P interfaces,
references the broadcast address associated with
.Fa ifa_addr ,
if one exists, otherwise it is
.Dv NULL .
.It Fa ifa_dstaddr
References the destination address on a P2P interface,
if one exists, otherwise it is
.Dv NULL .
.It Fa ifa_data
References address family specific data.
For
.Dv AF_LINK
addresses it contains a pointer to the
.Li struct if_data
(as defined in include file
.Aq Pa net/if.h )
which contains various interface attributes and statistics.
For all other address families, it contains a pointer to the
.Li struct ifa_data
(as defined in include file
.Aq Pa net/if.h )
which contains per-address interface statistics.
.El
.Pp
The data returned by
.Fn getifaddrs
is dynamically allocated and should be freed using
.Fn freeifaddrs
when no longer needed.
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, a value of \-1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn getifaddrs
may fail and set
.Va errno
for any of the errors specified for the library routines
.Xr ioctl 2 ,
.Xr socket 2 ,
.Xr malloc 3 ,
or
.Xr sysctl 3 .
.Sh BUGS
If both
.Aq Pa net/if.h
and
.Aq Pa ifaddrs.h
are being included,
.Aq Pa net/if.h
.Em must
be included before
.Aq Pa ifaddrs.h .
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr socket 2 ,
.Xr sysctl 3 ,
.Xr networking 4 ,
.Xr ifconfig 8
.Sh HISTORY
The
.Fn getifaddrs
function first appeared in BSDI BSD/OS.
The function is supplied on
.Ox
since
.Ox 2.7 .

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.