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
    from Rev 27 to Rev 174
    ↔ Reverse comparison
  •

Rev 27 → Rev 174

/net/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/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 .
/net/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.
/net/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.
/net/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.
/net/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.
/net/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.
/net/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 .
/net/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.
/net/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).
/net/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.
/net/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.
/net/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.
/net/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.
/net/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.
/net/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 .
/net/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.
/net/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.
/net/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.
/net/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.
/net/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 .
/gen/gethostname.3
0,0 → 1,114
.\" $OpenBSD: gethostname.3,v 1.18 2001/01/21 23:30:04 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 GETHOSTNAME 3
.Os
.Sh NAME
.Nm gethostname ,
.Nm sethostname
.Nd get/set name of current host
.Sh SYNOPSIS
.Fd #include <unistd.h>
.Ft int
.Fn gethostname "char *name" "size_t namelen"
.Ft int
.Fn sethostname "const char *name" "size_t namelen"
.Sh DESCRIPTION
The
.Fn gethostname
function returns the standard host name for the current
processor, as previously set by
.Fn sethostname .
The parameter
.Fa namelen
specifies the size of the
.Fa name
array.
If insufficient space is provided, the returned name is truncated.
The returned name is always null terminated.
.Pp
.Fn sethostname
sets the name of the host machine to be
.Fa name ,
which has length
.Fa namelen .
This call is restricted to the superuser and
is normally used only when the system is bootstrapped.
.Sh RETURN VALUES
If the call succeeds a value of 0 is returned.
If the call fails, a value of \-1 is returned and an error code is
placed in the global variable
.Va errno .
.Sh ERRORS
The following errors may be returned by these calls:
.Bl -tag -width Er
.It Bq Er EFAULT
The
.Fa name
or
.Fa namelen
parameter gave an invalid address.
.It Bq Er EPERM
The caller tried to set the hostname and was not the superuser.
.El
.Sh SEE ALSO
.Xr hostname 1 ,
.Xr getdomainname 3 ,
.Xr gethostid 3 ,
.Xr sysctl 3 ,
.Xr sysctl 8 ,
.Xr yp 8
.Sh STANDARDS
The
.Fn gethostname
function call conforms to
.St -xpg4.2 .
.Sh HISTORY
The
.Fn gethostname
function call appeared in
.Bx 4.2 .
.Sh BUGS
Host names are limited to
.Dv MAXHOSTNAMELEN
(from
.Ao Pa sys/param.h Ac )
characters, currently 256.
This includes the terminating NUL character.
.Pp
If the buffer passed to
.Fn gethostname
is smaller than
.Dv MAXHOSTNAMELEN ,
other operating systems may not guarantee termination with NUL.
/gen/getdomainname.3
0,0 → 1,108
.\" $OpenBSD: getdomainname.3,v 1.18 2000/12/24 00:30:48 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 May 6, 1994
.Dt GETDOMAINNAME 3
.Os
.Sh NAME
.Nm getdomainname ,
.Nm setdomainname
.Nd get/set YP domain name of current host
.Sh SYNOPSIS
.Fd #include <unistd.h>
.Ft int
.Fn getdomainname "char *name" "size_t namelen"
.Ft int
.Fn setdomainname "const char *name" "size_t namelen"
.Sh DESCRIPTION
The
.Fn getdomainname
function returns the YP domain name for the current processor, as
previously set by
.Fn setdomainname .
The parameter
.Fa namelen
specifies the size of the
.Fa name
array.
If insufficient space is provided, the returned name is truncated.
The returned name is always null terminated.
.Pp
.Fn setdomainname
sets the domain name of the host machine to be
.Fa name ,
which has length
.Fa namelen .
This call is restricted to the superuser and
is normally used only when the system is bootstrapped.
.Sh RETURN VALUES
If the call succeeds a value of 0 is returned.
If the call fails, a value of \-1 is returned and an error code is
placed in the global variable
.Va errno .
.Sh ERRORS
The following errors may be returned by these calls:
.Bl -tag -width Er
.It Bq Er EFAULT
The
.Fa name
or
.Fa namelen
parameter gave an
invalid address.
.It Bq Er EPERM
The caller tried to set the domain name and was not the superuser.
.El
.Sh SEE ALSO
.Xr domainname 1 ,
.Xr gethostid 3 ,
.Xr gethostname 3 ,
.Xr sysctl 3 ,
.Xr sysctl 8 ,
.Xr yp 8
.Sh BUGS
Domain names are limited to
.Dv MAXHOSTNAMELEN
(from
.Ao Pa sys/param.h Ac )
characters, currently 256.
This includes the terminating NUL character.
.Pp
If the buffer passed to
.Fn getdomainname
is too small, other operating systems may not guarantee termination with NUL.
.Sh HISTORY
The
.Nm
function call appeared in
SunOS 3.x.
/sys/select.2
0,0 → 1,260
.\" $OpenBSD: select.2,v 1.20 2001/09/04 08:04:08 deraadt Exp $
.\" $NetBSD: select.2,v 1.5 1995/06/27 22:32:28 cgd 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.
.\"
.\" @(#)select.2 8.2 (Berkeley) 3/25/94
.\"
.Dd March 25, 1994
.Dt SELECT 2
.Os
.Sh NAME
.Nm select
.Nd synchronous I/O multiplexing
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/time.h>
.Fd #include <unistd.h>
.Ft int
.Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout"
.Fn FD_SET fd &fdset
.Fn FD_CLR fd &fdset
.Fn FD_ISSET fd &fdset
.Fn FD_ZERO &fdset
.Sh DESCRIPTION
.Fn select
examines the I/O descriptor sets whose addresses are passed in
.Fa readfds ,
.Fa writefds ,
and
.Fa exceptfds
to see if some of their descriptors
are ready for reading, are ready for writing, or have an exceptional
condition pending, respectively.
The first
.Fa nfds
descriptors are checked in each set;
i.e., the descriptors from 0 through
.Fa nfds Ns No -1
in the descriptor sets are examined.
On return,
.Fn select
replaces the given descriptor sets
with subsets consisting of those descriptors that are ready
for the requested operation.
.Fn select
returns the total number of ready descriptors in all the sets.
.Pp
The descriptor sets are stored as bit fields in arrays of integers.
The following macros are provided for manipulating such descriptor sets:
.Fn FD_ZERO &fdset
initializes a descriptor set
.Fa fdset
to the null set.
.Fn FD_SET fd &fdset
includes a particular descriptor
.Fa fd
in
.Fa fdset .
.Fn FD_CLR fd &fdset
removes
.Fa fd
from
.Fa fdset .
.Fn FD_ISSET fd &fdset
is non-zero if
.Fa fd
is a member of
.Fa fdset ,
zero otherwise.
The behavior of these macros is undefined if
a descriptor value is less than zero or greater than or equal to
.Dv FD_SETSIZE ,
which is normally at least equal
to the maximum number of descriptors supported by the system.
.Pp
If
.Fa timeout
is a non-null pointer, it specifies a maximum interval to wait for the
selection to complete.
If
.Fa timeout
is a null pointer, the select blocks indefinitely.
To effect a poll, the
.Fa timeout
argument should be non-null, pointing to a zero-valued timeval structure.
.Fa timeout
is not changed by
.Fn select ,
and may be reused on subsequent calls; however, it is good style to
re-initialize it before each invocation of
.Fn select .
.Pp
Any of
.Fa readfds ,
.Fa writefds ,
and
.Fa exceptfds
may be given as null pointers if no descriptors are of interest.
.Sh RETURN VALUES
.Fn select
returns the number of ready descriptors that are contained in
the descriptor sets, or \-1 is an error occurred.
If the time limit expires,
.Fn select
returns 0.
If
.Fn select
returns with an error, including one due to an interrupted call,
the descriptor sets will be unmodified.
.Sh ERRORS
An error return from
.Fn select
indicates:
.Bl -tag -width Er
.It Bq Er EFAULT
One or more of
.Fa readfds ,
.Fa writefds ,
or
.Fa exceptfds
points outside the process's allocated address space.
.It Bq Er EBADF
One of the descriptor sets specified an invalid descriptor.
.It Bq Er EINTR
A signal was delivered before the time limit expired and
before any of the selected events occurred.
.It Bq Er EINVAL
The specified time limit is invalid.
One of its components is negative or too large.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr connect 2 ,
.Xr gettimeofday 2 ,
.Xr poll 2 ,
.Xr read 2 ,
.Xr recv 2 ,
.Xr send 2 ,
.Xr write 2 ,
.Xr getdtablesize 3
.Sh BUGS
Although the provision of
.Xr getdtablesize 3
was intended to allow user programs to be written independent
of the kernel limit on the number of open files, the dimension
of a sufficiently large bit field for select remains a problem.
The default bit size of
.Ft fd_set
is based on the symbol
.Dv FD_SETSIZE
(currently 256),
but that is somewhat smaller than the current kernel limit
to the number of open files.
However, in order to accommodate programs which might potentially
use a larger number of open files with select, it is possible
to increase this size within a program by providing
a larger definition of
.Dv FD_SETSIZE
before the inclusion of
.Aq Pa sys/types.h .
The kernel will cope, and the userland libraries provided with the
system are also ready for large numbers of file descriptors.
.Pp
Alternatively, to be really safe, it is possible to allocate
.Ft fd_set
bit-arrays dynamically.
The idea is to permit a program to work properly even if it is
.Xr execve 2 Ns 'd
with 4000 file descriptors pre-allocated.
The following illustrates the technique which is used by
userland libraries:
.Pp
.Bd -literal -offset indent -compact
fd_set *fdsr;
int max = fd;
 
fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS),
sizeof(fd_mask));
if (fdsr == NULL) {
...
return (-1);
}
FD_SET(fd, fdsr);
n = select(max+1, fdsr, NULL, NULL, &tv);
...
free(fdsr);
.Ed
.Pp
Alternatively, it is possible to use the
.Xr poll 2
interface.
.Xr poll 2
is more efficient when the size of
.Fn select Ns 's
.Ft fd_set
bit-arrays are very large, and for fixed numbers of
file descriptors one need not size and dynamically allocate a
memory object.
.Pp
.Fn select
should probably have been designed to return the time remaining from the
original timeout, if any, by modifying the time value in place.
Even though some systems stupidly act in this different way, it is
unlikely this semantic will ever be commonly implemented, as the
change causes massive source code compatibility problems.
Furthermore, recent new standards have dictated the current behaviour.
In general, due to the existence of those brain-damaged
non-conforming systems, it is unwise to assume that the timeout
value will be unmodified by the
.Fn select
call, and the caller should reinitialize it on each invocation.
Calculating the delta is easily done by calling
.Xr gettimeofday 2
before and after the call to
.Fn select Ns ,
and using
.Fn timersub
(as described in
.Xr getitimer 2 ) .
.Pp
Internally to the kernel,
.Fn select
works poorly if multiple processes wait on the same file descriptor.
Given that, it is rather surprising to see that many daemons are
written that way (i.e.,
.Xr httpd 8 ) .
.Sh HISTORY
The
.Fn select
function call appeared in
.Bx 4.2 .
/sys/accept.2
0,0 → 1,173
.\" $OpenBSD: accept.2,v 1.12 2001/03/11 05:02:29 aaron Exp $
.\" $NetBSD: accept.2,v 1.7 1996/01/31 20:14:42 mycroft 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.
.\"
.\" @(#)accept.2 8.2 (Berkeley) 12/11/93
.\"
.Dd February 15, 1999
.Dt ACCEPT 2
.Os
.Sh NAME
.Nm accept
.Nd accept a connection on a socket
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn accept "int s" "struct sockaddr *addr" "socklen_t *addrlen"
.Sh DESCRIPTION
The argument
.Fa s
is a socket that has been created with
.Xr socket 2 ,
bound to an address with
.Xr bind 2 ,
and is listening for connections after a
.Xr listen 2 .
The
.Fn accept
argument extracts the first connection request on the queue of pending
connections, creates a new socket with the same properties of
.Fa s ,
and allocates a new file descriptor for the socket.
If no pending connections are present on the queue,
and the socket is not marked as non-blocking,
.Fn accept
blocks the caller until a connection is present.
If the socket is marked non-blocking and no pending
connections are present on the queue,
.Fn accept
returns an error as described below.
The accepted socket may not be used to accept more connections.
The original socket
.Fa s
remains open.
.Pp
The argument
.Fa addr
is a result parameter that is filled in with the address of the connecting
entity as known to the communications layer.
The exact format of the
.Fa addr
parameter is determined by the domain in which the communication
is occurring.
The
.Fa addrlen
is a value-result parameter; it should initially contain the
amount of space pointed to by
.Fa addr ;
on return it will contain the actual length (in bytes) of the
address returned.
This call is used with connection-based socket types, currently with
.Dv SOCK_STREAM .
.Pp
It is possible to
.Xr select 2
or
.Xr poll 2
a socket for the purposes of doing an
.Fn accept
by selecting it for read.
.Pp
For certain protocols which require an explicit confirmation, such as
.Tn ISO
or
.Tn DATAKIT ,
.Fn accept
can be thought of as merely dequeuing the next connection
request and not implying confirmation.
Confirmation can be implied by a normal read or write on the new file
descriptor, and rejection can be implied by closing the new socket.
.Pp
One can obtain user connection request data without confirming
the connection by issuing a
.Xr recvmsg 2
call with an
.Fa msg_iovlen
of 0 and a non-zero
.Fa msg_controllen ,
or by issuing a
.Xr getsockopt 2
request.
Similarly, one can provide user connection rejection information
by issuing a
.Xr sendmsg 2
call with providing only the control information, or by calling
.Xr setsockopt 2 .
.Sh RETURN VALUES
The call returns \-1 on error.
If it succeeds, it returns a non-negative integer that is a descriptor
for the accepted socket.
.Sh ERRORS
The
.Fn accept
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
The descriptor is invalid.
.It Bq Er ENOTSOCK
The descriptor references a file, not a socket.
.It Bq Er EOPNOTSUPP
The referenced socket is not of type
.Dv SOCK_STREAM .
.It Bq Er EINVAL
The referenced socket is not listening for connections (that is,
.Xr listen 2
has not yet been called).
.It Bq Er EFAULT
The
.Fa addr
parameter is not in a writable part of the user address space.
.It Bq Er EWOULDBLOCK
The socket is marked non-blocking and no connections
are present to be accepted.
.It Bq Er EMFILE
The per-process descriptor table is full.
.It Bq Er ENFILE
The system file table is full.
.It Bq Er ECONNABORTED
A connection has been aborted.
.El
.Sh SEE ALSO
.Xr bind 2 ,
.Xr connect 2 ,
.Xr listen 2 ,
.Xr poll 2 ,
.Xr select 2 ,
.Xr poll 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn accept
function appeared in
.Bx 4.2 .
/sys/getsockname.2
0,0 → 1,164
.\" $OpenBSD: getsockname.2,v 1.16 2001/08/06 10:42:26 mpech Exp $
.\" $NetBSD: getsockname.2,v 1.6 1995/10/12 15:41:00 jtc 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.
.\"
.\" @(#)getsockname.2 8.1 (Berkeley) 6/4/93
.\"
.Dd July 17, 1999
.Dt GETSOCKNAME 2
.Os
.Sh NAME
.Nm getsockname
.Nd get socket name
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn getsockname "int s" "struct sockaddr *name" "socklen_t *namelen"
.Sh DESCRIPTION
.Fn getsockname
returns the locally bound address information for a specified socket.
.Pp
Common uses of this function are as follows:
.Bl -bullet
.It
When
.Xr bind 2
is called with a port number of 0 (indicating the kernel should pick
an ephemeral port)
.Fn getsockname
is used to retrieve the kernel-assigned port number.
.It
When a process calls
.Xr bind 2
on a wildcard IP address,
.Fn getsockname
is used to retrieve the local IP address for the connection.
.It
When a function wishes to know the address family of a socket,
.Fn getsockname
can be used.
.El
.Pp
.Fn getsockname
takes three parameters:
.Pp
.Fa s ,
Contains the file desriptor for the socket to be looked up.
.Pp
.Fa name
points to a
.Li sockaddr
structure which will hold the resulting address information.
Normal use requires one to use a structure
specific to the protocol family in use, such as
.Li sockaddr_in
(IPv4) or
.Li sockaddr_in6
(IPv6), cast to a (struct sockaddr *).
.Pp
For greater portability (such as newer protocol families) the new
structure sockaddr_storage exists.
.Li sockaddr_storage
is large enough to hold any of the other sockaddr_* variants.
On return, it should be cast to the correct sockaddr type,
according to the current protocol family.
.Pp
.Fa namelen
Indicates the amount of space pointed to by
.Fa name ,
in bytes.
Upon return,
.Fa namelen
is set to the actual size of the returned address information.
.Pp
If the address of the destination socket for a given socket connection is
needed, the
.Xr getpeername 2
function should be used instead.
.Pp
If
.Fa name
does not point to enough space to hold the entire socket address, the
result will be truncated to
.Fa namelen
bytes.
.Sh RETURN VALUES
On success,
.Fn getsockname
returns a 0, and
.Fa namelen
is set to the actual size of the socket address returned in
.Fa name .
Otherwise,
.Va errno
is set, and a value of \-1 is returned.
.Sh ERRORS
If
.Fn getsockname
fails,
.Va errno
is set to one of the following:
.Bl -tag -width Er
.It Bq Er EBADF
The argument
.Fa s
is not a valid descriptor.
.It Bq Er ENOTSOCK
The argument
.Fa s
is a file, not a socket.
.It Bq Er ENOBUFS
Insufficient resources were available in the system
to perform the operation.
.It Bq Er EFAULT
The
.Fa name
parameter points to memory not in a valid part of the
process address space.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr bind 2 ,
.Xr getpeername 2 ,
.Xr getpeereid 2 ,
.Xr socket 2
.Sh BUGS
Names bound to sockets in the UNIX domain are inaccessible;
.Nm getsockname
returns a zero length name.
.Sh HISTORY
The
.Fn getsockname
function call appeared in
.Bx 4.2 .
/sys/getsockopt.2
0,0 → 1,348
.\" $OpenBSD: getsockopt.2,v 1.16 2000/10/18 05:12:10 aaron Exp $
.\" $NetBSD: getsockopt.2,v 1.7 1995/02/27 12:33:29 cgd 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.
.\"
.\" @(#)getsockopt.2 8.3 (Berkeley) 4/19/94
.\"
.Dd February 15, 1999
.Dt GETSOCKOPT 2
.Os
.Sh NAME
.Nm getsockopt ,
.Nm setsockopt
.Nd get and set options on sockets
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn getsockopt "int s" "int level" "int optname" "void *optval" "socklen_t *optlen"
.Ft int
.Fn setsockopt "int s" "int level" "int optname" "const void *optval" "socklen_t optlen"
.Sh DESCRIPTION
.Fn getsockopt
and
.Fn setsockopt
manipulate the
.Em options
associated with a socket.
Options may exist at multiple protocol levels;
they are always present at the uppermost
.Dq socket
level.
.Pp
When manipulating socket options the level at which the
option resides and the name of the option must be specified.
To manipulate options at the socket level,
.Fa level
is specified as
.Dv SOL_SOCKET .
To manipulate options at any other level the protocol number of the
appropriate protocol controlling the option is supplied.
For example, to indicate that an option is to be interpreted by the
.Tn TCP
protocol,
.Fa level
should be set to the protocol number of
.Tn TCP ;
see
.Xr getprotoent 3 .
.Pp
The parameters
.Fa optval
and
.Fa optlen
are used to access option values for
.Fn setsockopt .
For
.Fn getsockopt
they identify a buffer in which the value for the
requested option(s) are to be returned.
For
.Fn getsockopt ,
.Fa optlen
is a value-result parameter, initially containing the
size of the buffer pointed to by
.Fa optval ,
and modified on return to indicate the actual size of the value returned.
If no option value is to be supplied or returned,
.Fa optval
may be
.Dv NULL .
.Pp
.Fa optname
and any specified options are passed uninterpreted to the appropriate
protocol module for interpretation.
The include file
.Ao Pa sys/socket.h Ac
contains definitions for socket level options, described below.
Options at other protocol levels vary in format and name;
consult the appropriate entries in section 4 of the manual.
.Pp
Most socket-level options utilize an
.Li int
parameter for
.Fa optval .
For
.Fn setsockopt ,
the parameter should be non-zero to enable a boolean option,
or zero if the option is to be disabled.
.Dv SO_LINGER
uses a
.Li struct linger
parameter, defined in
.Aq Pa sys/socket.h ,
which specifies the desired state of the option and the
linger interval (see below).
.Dv SO_SNDTIMEO
and
.Dv SO_RCVTIMEO
use a
.Li struct timeval
parameter, defined in
.Aq Pa sys/time.h .
.Pp
The following options are recognized at the socket level.
Except as noted, each may be examined with
.Fn getsockopt
and set with
.Fn setsockopt .
.Bl -column SO_OOBINLINE -offset indent
.It Dv SO_DEBUG Ta "enables recording of debugging information"
.It Dv SO_REUSEADDR Ta "enables local address reuse"
.It Dv SO_REUSEPORT Ta "enables duplicate address and port bindings"
.It Dv SO_KEEPALIVE Ta "enables keep connections alive"
.It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages"
.It Dv SO_LINGER Ta "linger on close if data present"
.It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages"
.It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band"
.It Dv SO_SNDBUF Ta "set buffer size for output"
.It Dv SO_RCVBUF Ta "set buffer size for input"
.It Dv SO_SNDLOWAT Ta "set minimum count for output"
.It Dv SO_RCVLOWAT Ta "set minimum count for input"
.It Dv SO_SNDTIMEO Ta "set timeout value for output"
.It Dv SO_RCVTIMEO Ta "set timeout value for input"
.It Dv SO_TYPE Ta "get the type of the socket (get only)"
.It Dv SO_ERROR Ta "get and clear error on the socket (get only)"
.El
.Pp
.Dv SO_DEBUG
enables debugging in the underlying protocol modules.
.Dv SO_REUSEADDR
indicates that the rules used in validating addresses supplied in a
.Xr bind 2
call should allow reuse of local addresses.
.Dv SO_REUSEPORT
allows completely duplicate bindings by multiple processes if they all set
.Dv SO_REUSEPORT
before binding the port.
This option permits multiple instances of a program to each
receive UDP/IP multicast or broadcast datagrams destined for the bound port.
.Dv SO_KEEPALIVE
enables the periodic transmission of messages on a connected socket.
Should the connected party fail to respond to these messages, the connection
is considered broken and processes using the socket are notified via a
.Dv SIGPIPE
signal when attempting to send data.
.Dv SO_DONTROUTE
indicates that outgoing messages should
bypass the standard routing facilities.
Instead, messages are directed to the appropriate network interface
according to the network portion of the destination address.
.Pp
.Dv SO_LINGER
controls the action taken when unsent messages
are queued on socket and a
.Xr close 2
is performed.
If the socket promises reliable delivery of data and
.Dv SO_LINGER
is set, the system will block the process on the
.Xr close 2
attempt until it is able to transmit the data or until it decides it
is unable to deliver the information (a timeout period measured in seconds,
termed the linger interval, is specified in the
.Fn setsockopt
call when
.Dv SO_LINGER
is requested).
If
.Dv SO_LINGER
is disabled and a
.Xr close 2
is issued, the system will process the close in a manner that allows
the process to continue as quickly as possible.
.Pp
The option
.Dv SO_BROADCAST
requests permission to send broadcast datagrams
on the socket.
Broadcast was a privileged operation in earlier versions of the system.
With protocols that support out-of-band data, the
.Dv SO_OOBINLINE
option requests that out-of-band data be placed in the normal data input
queue as received; it will then be accessible with
.Xr recv 2
or
.Xr read 2
calls without the
.Dv MSG_OOB
flag.
Some protocols always behave as if this option is set.
.Dv SO_SNDBUF
and
.Dv SO_RCVBUF
are options to adjust the normal
buffer sizes allocated for output and input buffers, respectively.
The buffer size may be increased for high-volume connections,
or may be decreased to limit the possible backlog of incoming data.
The system places an absolute limit on these values.
.Pp
.Dv SO_SNDLOWAT
is an option to set the minimum count for output operations.
Most output operations process all of the data supplied
by the call, delivering data to the protocol for transmission
and blocking as necessary for flow control.
Nonblocking output operations will process as much data as permitted
subject to flow control without blocking, but will process no data
if flow control does not allow the smaller of the low water mark value
or the entire request to be processed.
A
.Xr select 2
or
.Xr poll 2
operation testing the ability to write to a socket will return true
only if the low water mark amount could be processed.
The default value for
.Dv SO_SNDLOWAT
is set to a convenient size for network efficiency, often 1024.
.Dv SO_RCVLOWAT
is an option to set the minimum count for input operations.
In general, receive calls will block until any (non-zero) amount of data
is received, then return with the smaller of the amount available or the amount
requested.
The default value for
.Dv SO_RCVLOWAT
is 1.
If
.Dv SO_RCVLOWAT
is set to a larger value, blocking receive calls normally
wait until they have received the smaller of the low water mark value
or the requested amount.
Receive calls may still return less than the low water mark if an error
occurs, a signal is caught, or the type of data next in the receive queue
is different than that returned.
.Pp
.Dv SO_SNDTIMEO
is an option to set a timeout value for output operations.
It accepts a
.Li struct timeval
parameter with the number of seconds and microseconds
used to limit waits for output operations to complete.
If a send operation has blocked for this much time,
it returns with a partial count or with the error
.Er EWOULDBLOCK
if no data was sent.
In the current implementation, this timer is restarted each time additional
data are delivered to the protocol,
implying that the limit applies to output portions ranging in size
from the low water mark to the high water mark for output.
.Dv SO_RCVTIMEO
is an option to set a timeout value for input operations.
It accepts a
.Li struct timeval
parameter with the number of seconds and microseconds
used to limit waits for input operations to complete.
In the current implementation, this timer is restarted each time additional
data are received by the protocol,
and thus the limit is in effect an inactivity timer.
If a receive operation has been blocked for this much time without
receiving additional data, it returns with a short count
or with the error
.Er EWOULDBLOCK
if no data were received.
.Pp
Finally,
.Dv SO_TYPE
and
.Dv SO_ERROR
are options used only with
.Fn getsockopt .
.Dv SO_TYPE
returns the type of the socket, such as
.Dv SOCK_STREAM ;
it is useful for servers that inherit sockets on startup.
.Dv SO_ERROR
returns any pending error on the socket and clears the error status.
It may be used to check for asynchronous errors on connected
datagram sockets or for other asynchronous errors.
.Sh RETURN VALUES
A 0 is returned if the call succeeds, \-1 if it fails.
.Sh ERRORS
The call succeeds unless:
.Bl -tag -width Er
.It Bq Er EBADF
The argument
.Fa s
is not a valid descriptor.
.It Bq Er ENOTSOCK
The argument
.Fa s
is a file, not a socket.
.It Bq Er ENOPROTOOPT
The option is unknown at the level indicated.
.It Bq Er EFAULT
The address pointed to by
.Fa optval
is not in a valid part of the process address space.
For
.Fn getsockopt ,
this error may also be returned if
.Fa optlen
is not in a valid part of the process address space.
.El
.Sh SEE ALSO
.Xr connect 2 ,
.Xr ioctl 2 ,
.Xr poll 2 ,
.Xr select 2 ,
.Xr poll 2 ,
.Xr socket 2 ,
.Xr getprotoent 3 ,
.Xr protocols 5
.Sh BUGS
Several of the socket options should be handled at lower levels of the system.
.Sh HISTORY
The
.Fn getsockopt
system call appeared in
.Bx 4.2 .
/sys/socketpair.2
0,0 → 1,109
.\" $OpenBSD: socketpair.2,v 1.10 1999/07/06 18:21:04 deraadt Exp $
.\" $NetBSD: socketpair.2,v 1.5 1995/02/27 12:38:00 cgd 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.
.\"
.\" @(#)socketpair.2 8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt SOCKETPAIR 2
.Os
.Sh NAME
.Nm socketpair
.Nd create a pair of connected sockets
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn socketpair "int d" "int type" "int protocol" "int *sv"
.Sh DESCRIPTION
The
.Fn socketpair
call creates an unnamed pair of connected sockets in
the specified domain
.Fa d ,
of the specified
.Fa type ,
and using the optionally specified
.Fa protocol .
The descriptors used in referencing the new sockets
are returned in
.Fa sv Ns [0]
and
.Fa sv Ns [1] .
The two sockets are indistinguishable.
.Sh RETURN VALUES
A 0 is returned if the call succeeds, \-1 if it fails.
.Sh ERRORS
The call succeeds unless:
.Bl -tag -width Er
.It Bq Er EMFILE
Too many descriptors are in use by this process.
.It Bq Er EAFNOSUPPORT
The specified address family is not supported on this machine.
.It Bq Er EPROTONOSUPPORT
The specified protocol is not supported on this machine.
.It Bq Er EOPNOTSUPP
The specified protocol does not support creation of socket pairs.
.It Bq Er EFAULT
The address
.Fa sv
does not specify a valid part of the
process address space.
.It Bq Er ENFILE
The system file table is full.
.El
.Sh SEE ALSO
.Xr pipe 2 ,
.Xr read 2 ,
.Xr write 2
.Sh BUGS
This call is currently implemented only for the
.Tn LOCAL
domain.
Many operating systems only accept a
.Ar protocol
of
.Ev PF_UNSPEC ,
so that should be used instead of
.Ev PF_LOCAL
for maximal portability.
.Sh STANDARDS
The
.Fn socketpair
function conforms to
.St -xpg4.2 .
.Sh HISTORY
The
.Fn socketpair
function call appeared in
.Bx 4.2 .
/sys/poll.2
0,0 → 1,203
.\" $OpenBSD: poll.2,v 1.11 2001/08/11 08:13:18 fgsch Exp $
.\"
.\" Copyright (c) 1994 Jason R. Thorpe
.\" 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 Jason R. Thorpe.
.\" 4. The name of the author may not be used to endorse or promote products
.\" derived from this software without specific prior written permission.
.\"
.\" 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
.\"
.Dd December 13, 1994
.Dt POLL 2
.Os
.Sh NAME
.Nm poll
.Nd synchronous I/O multiplexing
.Sh SYNOPSIS
.Fd #include <poll.h>
.Ft int
.Fn poll "struct pollfd *fds" "int nfds" "int timeout"
.Sh DESCRIPTION
.Fn poll
provides a mechanism for reporting I/O conditions across a set of file
descriptors.
.Pp
The arguments are as follows:
.Bl -tag -width timeout
.It Pa fds
Points to an array of
.Nm pollfd
structures, which are defined as:
.Bd -literal -offset indent
struct pollfd {
int fd;
short events;
short revents;
};
.Ed
.Pp
The
.Pa fd
member is an open file descriptor.
The
.Pa events
and
.Pa revents
members are bitmasks of conditions to monitor and conditions found,
respectively.
.It Pa nfds
The number of
.Nm pollfd
structures in the array.
.It Pa timeout
Maximum interval to wait for the poll to complete, in milliseconds.
If this value is 0, then
.Fn poll
will return immediately.
If this value is INFTIM (-1),
.Fn poll
will block indefinitely until a condition is found.
.El
.Pp
The calling process sets the
.Pa events
bitmask and
.Fn poll
sets the
.Pa revents
bitmask.
Each call to
.Fn poll
resets the
.Pa revents
bitmask for accuracy.
The condition flags in the bitmasks are defined as:
.Bl -tag -width POLLRDNORM
.It Nm POLLIN
Data is available on the file descriptor for reading.
.It Nm POLLNORM
Same as
.Nm POLLIN .
.It Nm POLLPRI
Same as
.Nm POLLIN .
.It Nm POLLOUT
Data can be written to the file descriptor without blocking.
.It Nm POLLERR
This flag is not used in this implementation and is provided only for source
code compatibility.
.It Nm POLLHUP
The file descriptor was valid before the polling process and invalid after.
Presumably, this means that the file descriptor was closed sometime during
the poll.
.It Nm POLLNVAL
The corresponding file descriptor is invalid.
.It Nm POLLRDNORM
Same as
.Nm POLLIN .
.It Nm POLLRDBAND
Same as
.Nm POLLIN .
.It Nm POLLWRNORM
Same as
.Nm POLLOUT .
.It Nm POLLWRBAND
Same as
.Nm POLLOUT .
.It Nm POLLMSG
This flag is not used in this implementation and is provided only for source
code compatibility.
.El
.Pp
All flags except
.Nm POLLIN ,
.Nm POLLOUT ,
and their synonyms are for use only in the
.Pa revents
member of the
.Nm pollfd
structure.
An attempt to set any of these flags in the
.Pa events
member will generate an error condition.
.Pp
In addition to I/O multiplexing,
.Fn poll
can be used to generate simple timeouts.
This functionality may be achieved by passing a null pointer for
.Pa fds .
.Sh WARNINGS
The
.Nm POLLHUP
flag is only a close approximation and may not always be accurate.
.Sh RETURN VALUES
Upon error,
.Fn poll
returns a \-1 and sets the global variable
.Va errno
to indicate the error.
If the timeout interval was reached before any events occurred,
a 0 is returned.
Otherwise,
.Fn poll
returns the number of file descriptors for which
.Pa revents
is non-zero.
.Sh ERRORS
.Fn poll
will fail if:
.Bl -tag -width "EINVAL "
.It Bq Er EINVAL
.Pa nfds
was either a negative number or greater than the number of available
file descriptors.
.It Bq Er EINVAL
An invalid flags was set in the
.Pa events
member of the
.Nm pollfd
structure.
.It Bq Er EINVAL
The timeout passed to
.Fn poll
was too large.
.It Bq Er EAGAIN
Resource allocation failed inside of
.Fn poll .
Subsequent calls to
.Fn poll
may succeed.
.It Bq Er EINTR
.Fn poll
caught a signal during the polling process.
.El
.Sh SEE ALSO
.Xr poll 2 ,
.Xr select 2 ,
.Xr sysconf 3
.Sh HISTORY
A
.Fn poll
system call appeared in
.At V .
/sys/socket.2
0,0 → 1,264
.\" $OpenBSD: socket.2,v 1.18 2000/10/18 05:12:12 aaron Exp $
.\" $NetBSD: socket.2,v 1.5 1995/02/27 12:37:53 cgd 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.
.\"
.\" @(#)socket.2 8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt SOCKET 2
.Os
.Sh NAME
.Nm socket
.Nd create an endpoint for communication
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn socket "int domain" "int type" "int protocol"
.Sh DESCRIPTION
.Fn socket
creates an endpoint for communication and returns a descriptor.
.Pp
The
.Fa domain
parameter specifies a communications domain within which
communication will take place; this selects the protocol family
which should be used.
These families are defined in the include file
.Ao Pa sys/socket.h Ac .
The currently understood formats are
.Pp
.Bd -literal -offset indent -compact
AF_UNIX (UNIX internal protocols),
AF_INET (ARPA Internet protocols),
AF_INET6 (ARPA IPv6 protocols),
AF_ISO (ISO protocols),
AF_NS (Xerox Network Systems protocols),
AF_IPX (Internetwork Packet Exchange), and
AF_IMPLINK (IMP \*(lqhost at IMP\*(rq link layer).
.Ed
.Pp
The socket has the indicated
.Fa type ,
which specifies the semantics of communication.
Currently defined types are:
.Pp
.Bd -literal -offset indent -compact
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_SEQPACKET
SOCK_RDM
.Ed
.Pp
A
.Dv SOCK_STREAM
type provides sequenced, reliable,
two-way connection based byte streams.
An out-of-band data transmission mechanism may be supported.
A
.Dv SOCK_DGRAM
socket supports
datagrams (connectionless, unreliable messages of
a fixed (typically small) maximum length).
A
.Dv SOCK_SEQPACKET
socket may provide a sequenced, reliable,
two-way connection-based data transmission path for datagrams
of fixed maximum length; a consumer may be required to read
an entire packet with each read system call.
This facility is protocol specific, and presently implemented
only for
.Dv PF_NS .
.Dv SOCK_RAW
sockets provide access to internal network protocols and interfaces.
The types
.Dv SOCK_RAW ,
which is available only to the superuser, and
.Dv SOCK_RDM ,
which is planned,
but not yet implemented, are not described here.
.Pp
The
.Fa protocol
specifies a particular protocol to be used with the socket.
Normally only a single protocol exists to support a particular
socket type within a given protocol family.
However, it is possible that many protocols may exist,
in which case a particular protocol must be specified in this manner.
The protocol number to use is particular to the \*(lqcommunication domain\*(rq
in which communication is to take place; see
.Xr protocols 5 .
A value of 0 for
.Fa protocol
will let the system select an appropriate protocol for the requested
socket type.
.Pp
Sockets of type
.Dv SOCK_STREAM
are full-duplex byte streams, similar to pipes.
A stream socket must be in a
.Em connected
state before any data may be sent or received on it.
A connection to another socket is created with a
.Xr connect 2
call.
Once connected, data may be transferred using
.Xr read 2
and
.Xr write 2
calls or some variant of the
.Xr send 2
and
.Xr recv 2
calls.
When a session has been completed a
.Xr close 2
may be performed.
Out-of-band data may also be transmitted as described in
.Xr send 2
and received as described in
.Xr recv 2 .
.Pp
The communications protocols used to implement a
.Dv SOCK_STREAM
ensure that data is not lost or duplicated.
If a piece of data for which the peer protocol has buffer space cannot
be successfully transmitted within a reasonable length of time, then the
connection is considered broken and calls will indicate an error with \-1
returns and with
.Er ETIMEDOUT
as the specific code in the global variable
.Va errno .
The protocols optionally keep sockets
.Dq warm
by forcing transmissions roughly every minute in the absence of other activity.
An error is then indicated if no response can be elicited on an otherwise
idle connection for a extended period (e.g., 5 minutes).
A
.Dv SIGPIPE
signal is raised if a process sends on a broken stream; this causes
naive processes, which do not handle the signal, to exit.
.Pp
.Dv SOCK_SEQPACKET
sockets employ the same system calls
as
.Dv SOCK_STREAM
sockets.
The only difference is that
.Xr read 2
calls will return only the amount of data requested,
and any remaining in the arriving packet will be discarded.
.Pp
.Dv SOCK_DGRAM
and
.Dv SOCK_RAW
sockets allow sending of datagrams to correspondents named in
.Xr send 2
calls.
Datagrams are generally received with
.Xr recvfrom 2 ,
which returns the next datagram with its return address.
.Pp
An
.Xr fcntl 2
call can be used to specify a process group to receive
a
.Dv SIGURG
signal when the out-of-band data arrives.
It may also enable non-blocking I/O and asynchronous notification
of I/O events via
.Dv SIGIO .
.Pp
The operation of sockets is controlled by socket level
.Em options .
These options are defined in the file
.Ao Pa sys/socket.h Ac .
.Xr setsockopt 2
and
.Xr getsockopt 2
are used to set and get options, respectively.
.Sh RETURN VALUES
A \-1 is returned if an error occurs, otherwise the return
value is a descriptor referencing the socket.
.Sh ERRORS
The
.Fn socket
call fails if:
.Bl -tag -width Er
.It Bq Er EPROTONOSUPPORT
The protocol type or the specified protocol is not supported
within this domain.
.It Bq Er EMFILE
The per-process descriptor table is full.
.It Bq Er ENFILE
The system file table is full.
.It Bq Er EACCES
Permission to create a socket of the specified type and/or protocol
is denied.
.It Bq Er ENOBUFS
Insufficient buffer space is available.
The socket cannot be created until sufficient resources are freed.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr getsockname 2 ,
.Xr getsockopt 2 ,
.Xr ioctl 2 ,
.Xr listen 2 ,
.Xr poll 2 ,
.Xr read 2 ,
.Xr recv 2 ,
.Xr select 2 ,
.Xr send 2 ,
.Xr setsockopt 2 ,
.Xr shutdown 2 ,
.Xr socketpair 2 ,
.Xr write 2 ,
.Xr getprotoent 3 ,
.Xr netintro 4
.Rs
.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
.Re
.Rs
.%T "BSD Interprocess Communication Tutorial"
.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1"
.Re
.Sh HISTORY
The
.Fn socket
function call appeared in
.Bx 4.2 .
/sys/send.2
0,0 → 1,227
.\" $OpenBSD: send.2,v 1.19 2000/10/18 05:12:11 aaron Exp $
.\" $NetBSD: send.2,v 1.6 1996/01/15 01:17:18 thorpej 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.
.\"
.\" @(#)send.2 8.2 (Berkeley) 2/21/94
.\"
.Dd July 28, 1998
.Dt SEND 2
.Os
.Sh NAME
.Nm send ,
.Nm sendto ,
.Nm sendmsg
.Nd send a message from a socket
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft ssize_t
.Fn send "int s" "const void *msg" "size_t len" "int flags"
.Ft ssize_t
.Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen"
.Ft ssize_t
.Fn sendmsg "int s" "const struct msghdr *msg" "int flags"
.Sh DESCRIPTION
.Fn send ,
.Fn sendto ,
and
.Fn sendmsg
are used to transmit a message to another socket.
.Fn send
may be used only when the socket is in a
.Em connected
state, while
.Fn sendto
and
.Fn sendmsg
may be used at any time.
.Pp
The address of the target is given by
.Fa to
with
.Fa tolen
specifying its size.
The length of the message is given by
.Fa len .
If the message is too long to pass atomically through the
underlying protocol, the error
.Er EMSGSIZE
is returned, and
the message is not transmitted.
.Pp
No indication of failure to deliver is implicit in a
.Fn send .
Locally detected errors are indicated by a return value of \-1.
.Pp
If no messages space is available at the socket to hold
the message to be transmitted, then
.Fn send
normally blocks, unless the socket has been placed in
non-blocking I/O mode.
The
.Xr select 2
or
.Xr poll 2
system calls may be used to determine when it is possible to
send more data.
.Pp
The
.Fa flags
parameter may include one or more of the following:
.Bd -literal
#define MSG_OOB 0x1 /* process out-of-band data */
#define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */
.Ed
.Pp
The flag
.Dv MSG_OOB
is used to send
.Dq out-of-band
data on sockets that support this notion (e.g.,
.Dv SOCK_STREAM ) ;
the underlying protocol must also support
.Dq out-of-band
data.
.Dv MSG_DONTROUTE
is usually used only by diagnostic or routing programs.
.Pp
See
.Xr recv 2
for a description of the
.Fa msghdr
structure.
.Sh RETURN VALUES
The call returns the number of characters sent, or \-1
if an error occurred.
.Sh ERRORS
.Fn send ,
.Fn sendto ,
and
.Fn sendmsg
fail if:
.Bl -tag -width Er
.It Bq Er EBADF
An invalid descriptor was specified.
.It Bq Er ENOTSOCK
The argument
.Fa s
is not a socket.
.It Bq Er EFAULT
An invalid user space address was specified for a parameter.
.It Bq Er EMSGSIZE
The socket requires that message be sent atomically,
and the size of the message to be sent made this impossible.
.It Bq Er EAGAIN
The socket is marked non-blocking and the requested operation
would block.
.It Bq Er ENOBUFS
The system was unable to allocate an internal buffer.
The operation may succeed when buffers become available.
.It Bq Er ENOBUFS
The output queue for a network interface was full.
This generally indicates that the interface has stopped sending,
but may be caused by transient congestion.
.It Bq Er EACCES
The
.Dv SO_BROADCAST
option is not set on the socket, and a broadcast address
was given as the destination.
.It Bq Er EHOSTUNREACH
The destination address specified an unreachable host.
.It Bq Er EINVAL
The
.Fa flags
parameter is invalid.
.It Bq Er EHOSTDOWN
The destination address specified a host that is down.
.It Bq Er ENETDOWN
The destination address specified a network that is down.
.It Bq Er ECONNREFUSED
The destination host rejected the message (or a previous one).
This error can only be returned by connected sockets.
.It Bq Er ENOPROTOOPT
There was a problem sending the message.
This error can only be returned by connected sockets.
.It Bq Er EDESTADDRREQ
The socket is not connected, and no destination address was specified.
.It Bq Er EISCONN
The socket is already connected, and a destination address was specified.
.El
.Pp
In addition,
.Fn send
and
.Fn sendto
may return the following error:
.Bl -tag -width Er
.It Bq Er EINVAL
.Fa len
was larger than
.Dv SSIZE_MAX .
.El
.Pp
Also,
.Fn sendmsg
may return the following errors:
.Bl -tag -width Er
.It Bq Er EINVAL
The sum of the
.Fa iov_len
values in the
.Fa msg_iov
array overflowed an
.Em ssize_t .
.It Bq Er EMSGSIZE
The
.Fa msg_iovlen
member of
.Fa msg
was less than 0 or larger than
.Dv IOV_MAX .
.It Bq Er EAFNOSUPPORT
Addresses in the specified address family cannot be used with this socket.
.El
.Sh SEE ALSO
.Xr fcntl 2 ,
.Xr getsockopt 2 ,
.Xr poll 2 ,
.Xr recv 2 ,
.Xr select 2 ,
.Xr poll 2 ,
.Xr socket 2 ,
.Xr write 2
.Sh HISTORY
The
.Fn send
function call appeared in
.Bx 4.2 .
/sys/connect.2
0,0 → 1,165
.\" $OpenBSD: connect.2,v 1.14 1999/08/15 13:14:11 deraadt Exp $
.\" $NetBSD: connect.2,v 1.8 1995/10/12 15:40:48 jtc Exp $
.\"
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)connect.2 8.1 (Berkeley) 6/4/93
.\"
.Dd February 15, 1999
.Dt CONNECT 2
.Os
.Sh NAME
.Nm connect
.Nd initiate a connection on a socket
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn connect "int s" "const struct sockaddr *name" "socklen_t namelen"
.Sh DESCRIPTION
The parameter
.Fa s
is a socket.
If it is of type
.Dv SOCK_DGRAM ,
this call specifies the peer with which the socket is to be associated;
this address is that to which datagrams are to be sent,
and the only address from which datagrams are to be received.
If the socket is of type
.Dv SOCK_STREAM ,
this call attempts to make a connection to
another socket.
The other socket is specified by
.Fa name ,
which is an address in the communications space of the socket.
Each communications space interprets the
.Fa name
parameter in its own way.
Generally, stream sockets may successfully
.Fn connect
only once; datagram sockets may use
.Fn connect
multiple times to change their association.
Datagram sockets may dissolve the association
by connecting to an invalid address, such as a null address.
.Sh RETURN VALUES
If the connection or binding succeeds, 0 is returned.
Otherwise a \-1 is returned, and a more specific error
code is stored in
.Va errno .
.Sh ERRORS
The
.Fn connect
call fails if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa S
is not a valid descriptor.
.It Bq Er ENOTSOCK
.Fa S
is a descriptor for a file, not a socket.
.It Bq Er EADDRNOTAVAIL
The specified address is not available on this machine.
.It Bq Er EAFNOSUPPORT
Addresses in the specified address family cannot be used with this socket.
.It Bq Er EISCONN
The socket is already connected.
.It Bq Er ETIMEDOUT
Connection establishment timed out without establishing a connection.
.It Bq Er EINVAL
A TCP connection with a local broadcast, the all-ones or a
multicast address as the peer was attempted.
.It Bq Er ECONNREFUSED
The attempt to connect was forcefully rejected.
.It Bq Er EINTR
A connect was interrupted before it succeeded
by the delivery of a signal.
.It Bq Er ENETUNREACH
The network isn't reachable from this host.
.It Bq Er EADDRINUSE
The address is already in use.
.It Bq Er EFAULT
The
.Fa name
parameter specifies an area outside
the process address space.
.It Bq Er EINPROGRESS
The socket is non-blocking
and the connection cannot
be completed immediately.
It is possible to
.Xr select 2
or
.Xr poll 2
for completion by selecting the socket for writing, and also use
.Xr getsockopt 2
with
.Dv SO_ERROR
to check for error conditions.
.It Bq Er EALREADY
The socket is non-blocking
and a previous connection attempt
has not yet been completed.
.El
.Pp
The following errors are specific to connecting names in the UNIX domain.
These errors may not apply in future versions of the UNIX IPC domain.
.Bl -tag -width Er
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded
.Dv {NAME_MAX}
characters, or an entire path name exceeded
.Dv {PATH_MAX}
characters.
.It Bq Er ENOENT
The named socket does not exist.
.It Bq Er EACCES
Search permission is denied for a component of the path prefix.
.It Bq Er EACCES
Write access to the named socket is denied.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr getsockname 2 ,
.Xr getsockopt 2 ,
.Xr poll 2 ,
.Xr select 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn connect
function call appeared in
.Bx 4.2 .
/sys/ioctl.2
0,0 → 1,126
.\" $OpenBSD: ioctl.2,v 1.11 2001/07/30 01:12:43 deraadt Exp $
.\" $NetBSD: ioctl.2,v 1.5 1995/02/27 12:33:47 cgd Exp $
.\"
.\" Copyright (c) 1980, 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.
.\"
.\" @(#)ioctl.2 8.2 (Berkeley) 12/11/93
.\"
.Dd December 11, 1993
.Dt IOCTL 2
.Os
.Sh NAME
.Nm ioctl
.Nd control device
.Sh SYNOPSIS
.Fd #include <sys/ioctl.h>
.Ft int
.Fn ioctl "int d" "unsigned long request" "..."
.Sh DESCRIPTION
The
.Fn ioctl
function manipulates the underlying device parameters of special files.
In particular, many operating
characteristics of character special files (e.g., terminals)
may be controlled with
.Fn ioctl
requests.
.Pp
The argument
.Fa d
must be an open file descriptor. The third argument is called
.Fa arg
and contains additional information needed by this device
to perform the requested function.
.Fa arg
is either an
.Li int
or a pointer to a device-specific data structure, depending upon
the given
.Fa request .
.Pp
An
.Nm
.Fa request
has encoded in it whether the argument is an
.Dq in
parameter
or
.Dq out
parameter, and the size of the third argument
.Pq Fa arg
in bytes.
Macros and defines used in specifying an ioctl
.Fa request
are located in the file
.Ao Pa sys/ioctl.h Ac .
.Sh RETURN VALUES
If an error has occurred, a value of \-1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn ioctl
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa d
is not a valid descriptor.
.It Bq Er ENOTTY
.Fa d
is not associated with a character
special device.
.It Bq Er ENOTTY
The specified request does not apply to the kind
of object that the descriptor
.Fa d
references.
.It Bq Er EINVAL
.Fa request
or
.Fa arg
is not valid.
.It Bq Er EFAULT
.Fa arg
points outside the process's allocated address space.
.El
.Sh SEE ALSO
.Xr cdio 1 ,
.Xr chio 1 ,
.Xr mt 1 ,
.Xr execve 2 ,
.Xr fcntl 2 ,
.Xr intro 4 ,
.Xr tty 4
.Sh HISTORY
An
.Fn ioctl
function call appeared in
.At v7 .
/sys/shutdown.2
0,0 → 1,103
.\" $OpenBSD: shutdown.2,v 1.9 2000/08/09 12:57:54 aaron Exp $
.\" $NetBSD: shutdown.2,v 1.5 1995/02/27 12:37:11 cgd 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.
.\"
.\" @(#)shutdown.2 8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt SHUTDOWN 2
.Os
.Sh NAME
.Nm shutdown
.Nd shut down part of a full-duplex connection
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn shutdown "int s" "int how"
.Sh DESCRIPTION
The
.Fn shutdown
call causes all or part of a full-duplex connection on
the socket associated with
.Fa s
to be shut down.
If
.Fa how
is
.Ar SHUT_RD ,
further receives will be disallowed.
If
.Fa how
is
.Ar SHUT_WR ,
further sends will be disallowed.
If
.Fa how
is
.Ar SHUT_RDWR ,
further sends and receives will be disallowed.
.Sh RETURN VALUES
A 0 is returned if the call succeeds, \-1 if it fails.
.Sh ERRORS
The call succeeds unless:
.Bl -tag -width Er
.It Bq Er EINVAL
.Fa how
is not
.Ar SHUT_RD ,
.Ar SHUT_WR ,
or
.Ar SHUT_RDWR .
.It Bq Er EBADF
.Fa s
is not a valid descriptor.
.It Bq Er ENOTSOCK
.Fa s
is a file, not a socket.
.It Bq Er ENOTCONN
The specified socket is not connected.
.El
.Sh SEE ALSO
.Xr connect 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn shutdown
function call appeared in
.Bx 4.2 .
The
.Fa how
arguments used to be simply 0, 1, and 2, but now have named values
as specified by
.St -xpg4 .
/sys/bind.2
0,0 → 1,131
.\" $OpenBSD: bind.2,v 1.10 2000/10/18 05:12:08 aaron Exp $
.\" $NetBSD: bind.2,v 1.8 1995/10/12 15:40:46 jtc Exp $
.\"
.\" Copyright (c) 1983, 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.
.\"
.\" @(#)bind.2 8.1 (Berkeley) 6/4/93
.\"
.Dd February 15, 1999
.Dt BIND 2
.Os
.Sh NAME
.Nm bind
.Nd bind a name to a socket
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn bind "int s" "const struct sockaddr *name" "socklen_t namelen"
.Sh DESCRIPTION
.Fn bind
assigns a name to an unnamed socket.
When a socket is created with
.Xr socket 2
it exists in a name space (address family) but has no name assigned.
.Fn bind
requests that
.Fa name
be assigned to the socket.
.Sh NOTES
Binding a name in the UNIX domain creates a socket in the file
system that must be deleted by the caller when it is no longer
needed (using
.Xr unlink 2 ) .
.Pp
The rules used in name binding vary between communication domains.
Consult the manual entries in section 4 for detailed information.
.Sh RETURN VALUES
If the bind is successful, a 0 value is returned.
A return value of \-1 indicates an error, which is
further specified in the global
.Va errno .
.Sh ERRORS
The
.Fn bind
call will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa S
is not a valid descriptor.
.It Bq Er ENOTSOCK
.Fa S
is not a socket.
.It Bq Er EADDRNOTAVAIL
The specified address is not available from the local machine.
.It Bq Er EADDRINUSE
The specified address is already in use.
.It Bq Er EINVAL
The socket is already bound to an address.
.It Bq Er EINVAL
The family of the socket and that requested in
.Va name->sa_family
are not equivalent.
.It Bq Er EACCES
The requested address is protected, and the current user
has inadequate permission to access it.
.It Bq Er EFAULT
The
.Fa name
parameter is not in a valid part of the user address space.
.El
.Pp
The following errors are specific to binding names in the UNIX domain.
.Bl -tag -width Er
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded
.Dv {NAME_MAX}
characters, or an entire path name exceeded
.Dv {PATH_MAX}
characters.
.It Bq Er ENOENT
A prefix component of the path name does not exist.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
.It Bq Er EIO
An I/O error occurred while making the directory entry or allocating the inode.
.It Bq Er EROFS
The name would reside on a read-only file system.
.It Bq Er EISDIR
An empty pathname was specified.
.El
.Sh SEE ALSO
.Xr connect 2 ,
.Xr getsockname 2 ,
.Xr listen 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn bind
function call appeared in
.Bx 4.2 .
/sys/getpeername.2
0,0 → 1,141
.\" $OpenBSD: getpeername.2,v 1.16 2001/06/26 19:56:52 dugsong Exp $
.\" $NetBSD: getpeername.2,v 1.6 1995/10/12 15:40:56 jtc 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.
.\"
.\" @(#)getpeername.2 8.1 (Berkeley) 6/4/93
.\"
.Dd July 17, 1999
.Dt GETPEERNAME 2
.Os
.Sh NAME
.Nm getpeername
.Nd get name of connected peer
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fn getpeername "int s" "struct sockaddr *name" "socklen_t *namelen"
.Sh DESCRIPTION
.Fn getpeername
returns the address information of the peer connected to socket
.Fa s .
One common use occurs when a process inherits an open socket, such as
TCP servers forked from
.Xr inetd 8 .
In this scenario,
.Fn getpeername
is used to determine the connecting client's IP address.
.Pp
.Fn getpeername
takes three parameters:
.Pp
.Fa s
Contains the file descriptor of the socket whose peer should be looked up.
.Pp
.Fa name
Points to a
.Li sockaddr
structure that will hold the address information for the connected peer.
Normal use requires one to use a structure
specific to the protocol family in use, such as
.Li sockaddr_in
(IPv4) or
.Li sockaddr_in6
(IPv6), cast to a (struct sockaddr *).
.Pp
For greater portability, especially with the newer protocol families, the new
.Li struct sockaddr_storage
should be used.
.Li sockaddr_storage
is large enough to hold any of the other sockaddr_* variants.
On return, it can be cast to the correct sockaddr type,
based the protocol family contained in its ss_family field.
.Pp
.Fa namelen
Indicates the amount of space pointed to by
.Fa name ,
in bytes.
.Pp
If address information for the local end of the socket is required, the
.Xr getsockname 2
function should be used instead.
.Pp
If
.Fa name
does not point to enough space to hold the entire socket address, the
result will be truncated to
.Fa namelen
bytes.
.Sh RETURN VALUES
If the call succeeds, a 0 is returned and
.Fa namelen
is set to the actual size of the socket address returned in
.Fa name .
Otherwise,
.Va errno
is set and a value of \-1 is returned.
.Sh ERRORS
On failure,
.Va errno
is set to one of the following:
.Bl -tag -width Er
.It Bq Er EBADF
The argument
.Fa s
is not a valid descriptor.
.It Bq Er ENOTSOCK
The argument
.Fa s
is a file, not a socket.
.It Bq Er ENOTCONN
The socket is not connected.
.It Bq Er ENOBUFS
Insufficient resources were available in the system
to perform the operation.
.It Bq Er EFAULT
The
.Fa name
parameter points to memory not in a valid part of the
process address space.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr bind 2 ,
.Xr getsockname 2 ,
.Xr getpeereid 2 ,
.Xr socket 2
.Sh HISTORY
The
.Fn getpeername
function call appeared in
.Bx 4.2 .

powered by: WebSVN 2.1.0

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