-.\" $FreeBSD: src/lib/libc/net/getaddrinfo.3,v 1.2.2.8 2001/08/17 15:42:38 ru Exp $
-.\" $KAME: getaddrinfo.3,v 1.22 2000/08/09 21:16:17 itojun Exp $
+.\" $NetBSD: getaddrinfo.3,v 1.39 2005/01/11 06:01:41 itojun Exp $
+.\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $
+.\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $
.\"
-.\" Copyright (c) 1983, 1987, 1991, 1993
-.\" The Regents of the University of California. All rights reserved.
+.\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (C) 2000, 2001 Internet Software Consortium.
.\"
-.\" 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.
+.\" 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.
.\"
-.\" 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.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
+.\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+.\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
+.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+.\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+.\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+.\" PERFORMANCE OF THIS SOFTWARE.
.\"
-.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
-.\"
-.Dd May 25, 1995
+.Dd December 20, 2004
.Dt GETADDRINFO 3
.Os
-.\"
.Sh NAME
.Nm getaddrinfo ,
-.Nm freeaddrinfo ,
-.Nm gai_strerror
-.Nd nodename-to-address translation in protocol-independent manner
-.\"
-.Sh LIBRARY
-.Lb libc
+.Nm freeaddrinfo
+.Nd socket address structure to host and service name
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Fd #include <netdb.h>
.Ft int
-.Fn getaddrinfo "const char *nodename" "const char *servname" \
-"const struct addrinfo *hints" "struct addrinfo **res"
+.Fn getaddrinfo "const char *hostname" "const char *servname" \
+ "const struct addrinfo *hints" "struct addrinfo **res"
.Ft void
.Fn freeaddrinfo "struct addrinfo *ai"
-.Ft "const 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
+function is used to get a list of
+.Tn IP
+addresses and port numbers for host
+.Fa hostname
+and service
+.Fa servname .
+It is a replacement for and provides more flexibility than the
.Xr gethostbyname 3
and
-.Xr getservbyname 3 ,
-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
+.Xr getservbyname 3
+functions.
.Pp
The
-.Fa nodename
-and
-.Fa servname
-arguments are pointers to null-terminated strings or
-.Dv NULL .
-One or both of these two arguments must be a
-.Pf non Dv -NULL
-pointer.
-In the normal client scenario, both the
-.Fa nodename
+.Fa hostname
and
.Fa servname
-are specified.
-In the normal server scenario, only the
+arguments are either pointers to NUL-terminated strings or the null pointer.
+An acceptable value for
+.Fa hostname
+is either a valid host name or a numeric host address string consisting
+of a dotted decimal IPv4 address or an IPv6 address.
+The
.Fa servname
-is specified.
-A
-.Pf non Dv -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
-.Pf non Dv -NULL
+is either a decimal port number or a service name listed in
+.Xr services 5 .
+At least one of
+.Fa hostname
+and
.Fa servname
-string can be either a service name or a decimal port number.
+must be non-null.
.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
-.Dv NULL
-pointer.
-A value of
-.Dv PF_UNSPEC
-for
+is an optional pointer to a
+.Li struct addrinfo ,
+as defined by
+.Aq Pa netdb.h :
+.Bd -literal
+struct addrinfo {
+ int ai_flags; /* input flags */
+ int ai_family; /* protocol family for socket */
+ int ai_socktype; /* socket type */
+ int ai_protocol; /* protocol for socket */
+ socklen_t ai_addrlen; /* length of socket-address */
+ struct sockaddr *ai_addr; /* socket-address for socket */
+ char *ai_canonname; /* canonical name for service location */
+ struct addrinfo *ai_next; /* pointer to next in list */
+};
+.Ed
+.Pp
+This structure can be used to provide hints concerning the type of socket
+that the caller supports or wishes to use.
+The caller can supply the following structure elements in
+.Fa hints :
+.Bl -tag -width "ai_socktypeXX"
+.It Fa ai_family
+The protocol family that should be used.
+When
.Fa ai_family
-means the caller will accept any protocol family.
-A value of 0 for
+is set to
+.Dv PF_UNSPEC ,
+it means the caller will accept any protocol family supported by the
+operating system.
+.It Fa ai_socktype
+Denotes the type of socket that is wanted:
+.Dv SOCK_STREAM ,
+.Dv SOCK_DGRAM ,
+or
+.Dv SOCK_RAW .
+When
.Fa ai_socktype
-means the caller will accept any socket type.
-A value of 0 for
+is zero the caller will accept any socket type.
+.It Fa ai_protocol
+Indicates which transport protocol is desired,
+.Dv IPPROTO_UDP
+or
+.Dv IPPROTO_TCP .
+If
.Fa ai_protocol
-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
+is zero the caller will accept any protocol.
+.It Fa ai_flags
+.Fa ai_flags
+is formed by
+.Tn OR Ns 'ing
+the following values:
+.Bl -tag -width "AI_CANONNAMEXX"
+.It Dv AI_CANONNAME
+If the
+.Dv AI_CANONNAME
+bit is set, a successful call to
.Fn getaddrinfo
-is a
-.Dv 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
-.Dv 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
+will return a NUL-terminated string containing the canonical name
+of the specified hostname in the
+.Fa ai_canonname
+element of the first
.Li addrinfo
-structure the
-.Fa ai_addr
-member points to a filled-in socket address structure whose length is
-specified by the
-.Fa ai_addrlen
-member.
-.Pp
+structure returned.
+.It Dv AI_NUMERICHOST
+If the
+.Dv AI_NUMERICHOST
+bit is set, it indicates that
+.Fa hostname
+should be treated as a numeric string defining an IPv4 or IPv6 address
+and no name resolution should be attempted.
+.It Dv AI_PASSIVE
If the
.Dv AI_PASSIVE
-bit is set 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 .
+bit is set it indicates that the returned socket address structure
+is intended for use in a call to
+.Xr bind 2 .
In this case, if the
-.Fa nodename
-argument is a
-.Dv NULL
-pointer, then the IP address portion of the socket
-address structure will be set to
+.Fa hostname
+argument is the null pointer, then the IP address portion of the
+socket address structure will be set to
.Dv INADDR_ANY
for an IPv4 address or
.Dv IN6ADDR_ANY_INIT
.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
-(for a connection-oriented protocol)
-or either
-.Fn connect ,
-.Fn sendto ,
+bit is not set, the returned socket address structure will be ready
+for use in a call to
+.Xr connect 2
+for a connection-oriented protocol or
+.Xr connect 2 ,
+.Xr sendto 2 ,
or
-.Fn sendmsg
-(for a connectionless protocol).
-In this case, if the
-.Fa nodename
-argument is a
-.Dv NULL
-pointer, then the IP address portion of the
-socket address structure will be set to the loopback address.
+.Xr sendmsg 2
+if a connectionless protocol was chosen.
+The
+.Tn IP
+address portion of the socket address structure will be set to the
+loopback address if
+.Fa hostname
+is the null pointer and
+.Dv AI_PASSIVE
+is not set.
+.El
+.El
.Pp
-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
+All other elements of the
.Li addrinfo
-structure in the linked list will point to a null-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
+structure passed via
.Fa hints
-structure, then a
-.Pf non Dv -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.
+must be zero or the null pointer.
.Pp
-The arguments to
-.Fn getaddrinfo
-must be sufficiently consistent and unambiguous.
-Here are some problem cases you may encounter:
-.Bl -bullet
-.It
-.Fn getaddrinfo
-will fail if the members in the
+If
.Fa hints
-structure are not consistent.
-For example, for internet address families,
-.Fn getaddrinfo
-will fail 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 fail because the arguments are not consistent.
-For example,
-.Fn getaddrinfo
-will return 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 ,
+is the null pointer,
.Fn getaddrinfo
-will fail, because service names are not defined for the internet
-.Dv SOCK_RAW
-space.
-.It
-If you specify numeric
-.Fa servname ,
-while leaving
-.Fa ai_socktype
-and
-.Fa ai_protocol
-unspecified,
-.Fn getaddrinfo
-will fail.
-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
+behaves as if the caller provided a
+.Li struct addrinfo
+with
+.Fa ai_family
+set to
+.Dv PF_UNSPEC
+and all other elements set to zero or
+.Dv NULL .
.Pp
-All of the information returned by
-.Fn getaddrinfo
-is dynamically allocated:
-the
+After a successful call to
+.Fn getaddrinfo ,
+.Fa *res
+is a pointer to a linked list of one or more
.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
+structures.
+The list can be traversed by following the
.Fa ai_next
-pointer is encountered.
+pointer in each
+.Li addrinfo
+structure until a null pointer is encountered.
+The three members
+.Fa ai_family,
+.Fa ai_socktype,
+and
+.Fa ai_protocol
+in each returned
+.Li addrinfo
+structure are suitable for a call to
+.Xr socket 2 .
+For each
+.Li addrinfo
+structure in the list, the
+.Fa ai_addr
+member points to a filled-in socket address structure of length
+.Fa ai_addrlen .
.Pp
-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.
-.\"
-.Sh EXTENSIONS
-This implementation supports numeric IPv6 address notation with the
-experimental scope identifier.
-By appending a percent sign and scope identifier to the address, you
-can specify the value of the
+This implementation of
+.Fn getaddrinfo
+allows numeric IPv6 address notation with scope identifier,
+as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt.
+By appending the percent character and scope identifier to addresses,
+one can fill the
.Li sin6_scope_id
-field of the socket address.
-This makes management of scoped address easier,
+field for addresses.
+This would make management of scoped addresses easier
and allows cut-and-paste input of scoped addresses.
.Pp
-At the moment the code supports only link-local addresses in this format.
-The scope identifier is hardcoded to name of hardware interface associated
-with the link,
-(such as
-.Li ne0 ) .
-For example,
+At this moment the code supports only link-local addresses with the format.
+The scope identifier is hardcoded to the name of the hardware interface
+associated
+with the link
+.Po
+such as
+.Li ne0
+.Pc .
+An example is
.Dq Li fe80::1%ne0 ,
which means
.Do
interface
.Dc .
.Pp
-This implementation is still very experimental and non-standard.
The current implementation assumes a one-to-one relationship between
-interfaces and links, which is not necessarily true according to the
-specification.
-.\"
+the interface and link, which is not necessarily true from the specification.
+.Pp
+All of the information returned by
+.Fn getaddrinfo
+is dynamically allocated: the
+.Li addrinfo
+structures themselves as well as the socket address structures and
+the canonical host name strings included in the
+.Li addrinfo
+structures.
+.Pp
+Memory allocated for the dynamically allocated structures created by
+a successful call to
+.Fn getaddrinfo
+is released by the
+.Fn freeaddrinfo
+function.
+The
+.Fa ai
+pointer should be a
+.Li addrinfo
+structure created by a call to
+.Fn getaddrinfo .
+.Sh RETURN VALUES
+.Fn getaddrinfo
+returns zero on success or one of the error codes listed in
+.Xr gai_strerror 3
+if an error occurs.
.Sh EXAMPLES
The following code tries to connect to
.Dq Li www.kame.net
service
-.Dq Li http .
-via stream socket.
-It loops through all the addresses available, regardless of the address family.
+.Dq Li http
+via a stream socket.
+It loops through all the addresses available, regardless of address family.
If the destination resolves to an IPv4 address, it will use an
.Dv AF_INET
socket.
Similarly, if it resolves to IPv6, an
.Dv AF_INET6
socket is used.
-Observe that there is no hardcoded reference to particular address family.
+Observe that there is no hardcoded reference to a particular address family.
The code works even if
.Fn getaddrinfo
returns addresses that are not IPv4/v6.
/*NOTREACHED*/
}
s = -1;
-cause = "no addresses";
-errno = EADDRNOTAVAIL;
for (res = res0; res; res = res->ai_next) {
s = socket(res->ai_family, res->ai_socktype,
res->ai_protocol);
break; /* okay we got one */
}
if (s < 0) {
- err(1, cause);
+ err(1, "%s", cause);
/*NOTREACHED*/
}
freeaddrinfo(res0);
close(s[nsock]);
continue;
}
-
- if (listen(s[nsock], SOMAXCONN) < 0) {
- cause = "listen";
- close(s[nsock]);
- continue;
- }
+ (void) listen(s[nsock], 5);
nsock++;
}
if (nsock == 0) {
- err(1, cause);
+ err(1, "%s", cause);
/*NOTREACHED*/
}
freeaddrinfo(res0);
.Ed
-.\"
-.Sh FILES
-.Bl -tag -width /etc/resolv.conf -compact
-.It Pa /etc/hosts
-.It Pa /etc/host.conf
-.It Pa /etc/resolv.conf
-.El
-.\"
-.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 an appropriate 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 bind 2 ,
+.Xr connect 2 ,
+.Xr send 2 ,
+.Xr socket 2 ,
+.Xr gai_strerror 3 ,
.Xr gethostbyname 3 ,
.Xr getnameinfo 3 ,
.Xr getservbyname 3 ,
+.Xr resolver 3 ,
.Xr hosts 5 ,
+.Xr resolv.conf 5 ,
.Xr services 5 ,
.Xr hostname 7 ,
.Xr named 8
-.Pp
.Rs
.%A R. Gilligan
.%A S. Thomson
.%A J. Bound
+.%A J. McCann
.%A W. Stevens
.%T Basic Socket Interface Extensions for IPv6
-.%R RFC2553
-.%D March 1999
+.%R RFC 3493
+.%D February 2003
.Re
.Rs
-.%A Tatsuya Jinmei
-.%A Atsushi Onoe
-.%T "An Extension of Format for IPv6 Scoped Addresses"
+.%A S. Deering
+.%A B. Haberman
+.%A T. Jinmei
+.%A E. Nordmark
+.%A B. Zill
+.%T "IPv6 Scoped Address Architecture"
.%R internet draft
-.%N draft-ietf-ipngwg-scopedaddr-format-02.txt
+.%N draft-ietf-ipv6-scoping-arch-02.txt
.%O work in progress material
.Re
.Rs
.%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
-.St -p1003.1g-2000 ,
-and documented in
-.Dq Basic Socket Interface Extensions for IPv6
-(RFC2553).
-.\"
+function is defined by the
+.St -p1003.1g-2000
+draft specification and documented in
+.Dv "RFC 3493" ,
+.Dq Basic Socket Interface Extensions for IPv6 .
.Sh BUGS
-The current implementation is not thread-safe.
-.Pp
-The text was shamelessly copied from RFC2553.
+The implementation of
+.Fn getaddrinfo
+is not thread-safe.
projects / apple / libinfo.git / blobdiff