2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com>
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" References: RFC 2553
|
2005-08-09 11:40:12 +00:00
|
|
|
.\"
|
|
|
|
.\" 2005-08-09, mtk, added AI_ALL, AI_ADDRCONFIG, AI_V4MAPPED,
|
|
|
|
.\" and AI_NUMERICSERV.
|
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.TH getaddrinfo 3 2000-12-18 "Linux Man Page" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
getaddrinfo, freeaddrinfo, gai_strerror \- network address and service translation
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <sys/types.h>
|
|
|
|
.B #include <sys/socket.h>
|
|
|
|
.B #include <netdb.h>
|
|
|
|
.sp
|
|
|
|
.BI "int getaddrinfo(const char *" "node" ", const char *" "service" ,
|
|
|
|
.BI " const struct addrinfo *" "hints" ,
|
|
|
|
.BI " struct addrinfo **" "res" );
|
|
|
|
.sp
|
|
|
|
.BI "void freeaddrinfo(struct addrinfo *" "res" );
|
|
|
|
.sp
|
|
|
|
.BI "const char *gai_strerror(int " "errcode" );
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
|
|
|
.BR getaddrinfo (3)
|
|
|
|
function combines the functionality provided by the
|
|
|
|
.BR getipnodebyname (3),
|
|
|
|
.BR getipnodebyaddr (3),
|
|
|
|
.BR getservbyname (3),
|
|
|
|
and
|
|
|
|
.BR getservbyport (3)
|
|
|
|
functions into a single interface.
|
|
|
|
The thread-safe
|
|
|
|
.BR getaddrinfo (3)
|
|
|
|
function creates one or more socket address structures that can be used by the
|
|
|
|
.BR bind (2)
|
|
|
|
and
|
|
|
|
.BR connect (2)
|
|
|
|
system calls to create a client or a server socket.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.BR getaddrinfo (3)
|
|
|
|
function is not limited to creating IPv4 socket address structures;
|
|
|
|
IPv6 socket address structures can be created if IPv6 support is available.
|
|
|
|
These socket address structures can be used directly by
|
|
|
|
.BR bind (2)
|
|
|
|
or
|
|
|
|
.BR connect (2),
|
|
|
|
to prepare a client or a server socket.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.B addrinfo
|
|
|
|
structure used by this function contains the following members:
|
|
|
|
.sp
|
|
|
|
.nf
|
|
|
|
.B struct addrinfo {
|
|
|
|
.BI " int " "ai_flags" ";"
|
|
|
|
.BI " int " "ai_family" ";"
|
|
|
|
.BI " int " "ai_socktype" ";"
|
|
|
|
.BI " int " "ai_protocol" ";"
|
|
|
|
.BI " size_t " "ai_addrlen" ";"
|
|
|
|
.BI " struct sockaddr *" "ai_addr" ";"
|
|
|
|
.BI " char *" "ai_canonname" ";"
|
|
|
|
.BI " struct addrinfo *" "ai_next" ";"
|
|
|
|
.B };
|
|
|
|
.fi
|
|
|
|
.PP
|
|
|
|
.BR getaddrinfo (3)
|
|
|
|
sets
|
|
|
|
.I res
|
2005-08-09 10:10:29 +00:00
|
|
|
to point to a dynamically-allocated linked list of
|
2004-11-03 13:51:07 +00:00
|
|
|
.B addrinfo
|
|
|
|
structures, linked by the
|
|
|
|
.I ai_next
|
|
|
|
member.
|
|
|
|
There are several reasons why
|
2005-08-09 10:10:29 +00:00
|
|
|
the linked list may have more than one
|
2004-11-03 13:51:07 +00:00
|
|
|
.B addrinfo
|
|
|
|
structure, including: if the network host is
|
|
|
|
multi-homed; or if the same service
|
|
|
|
is available from multiple socket protocols (one
|
|
|
|
.B SOCK_STREAM
|
|
|
|
address and another
|
|
|
|
.B SOCK_DGRAM
|
|
|
|
address, for example).
|
|
|
|
.PP
|
|
|
|
The members
|
|
|
|
.IR ai_family ,
|
|
|
|
.IR ai_socktype ,
|
|
|
|
and
|
|
|
|
.I ai_protocol
|
|
|
|
have the same meaning as the corresponding parameters in the
|
|
|
|
.BR socket (2)
|
|
|
|
system call.
|
|
|
|
The
|
|
|
|
.BR getaddrinfo (3)
|
|
|
|
function returns socket addresses in either IPv4 or IPv6
|
|
|
|
address family,
|
|
|
|
.RI "(" "ai_family"
|
|
|
|
will be set to either
|
2005-08-09 11:40:12 +00:00
|
|
|
.B AF_INET
|
2004-11-03 13:51:07 +00:00
|
|
|
or
|
2005-08-09 11:40:12 +00:00
|
|
|
.BR AF_INET6 ).
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I hints
|
|
|
|
parameter specifies
|
|
|
|
the preferred socket type, or protocol.
|
|
|
|
A NULL
|
|
|
|
.I hints
|
|
|
|
specifies that any network address or protocol is acceptable.
|
2005-08-09 11:40:12 +00:00
|
|
|
If this parameter is not NULL it points to an
|
2004-11-03 13:51:07 +00:00
|
|
|
.B addrinfo
|
|
|
|
structure
|
|
|
|
whose
|
|
|
|
.IR ai_family ,
|
|
|
|
.IR ai_socktype ,
|
|
|
|
and
|
|
|
|
.I ai_protocol
|
|
|
|
members specify the preferred socket type.
|
2005-08-09 11:40:12 +00:00
|
|
|
.B AF_UNSPEC
|
2004-11-03 13:51:07 +00:00
|
|
|
in
|
|
|
|
.I ai_family
|
|
|
|
specifies any protocol family (either IPv4 or IPv6, for example).
|
|
|
|
0 in
|
|
|
|
.I ai_socktype
|
|
|
|
or
|
|
|
|
.I ai_protocol
|
|
|
|
specifies that any socket type or protocol is acceptable as well.
|
|
|
|
The
|
|
|
|
.I ai_flags
|
|
|
|
member
|
|
|
|
specifies additional options, defined below.
|
|
|
|
Multiple flags are specified by logically OR-ing them together.
|
|
|
|
All the other members in the
|
|
|
|
.I hints
|
|
|
|
parameter must contain either 0, or a null pointer.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I node
|
|
|
|
or
|
|
|
|
.I service
|
|
|
|
parameter, but not both, may be NULL.
|
|
|
|
.I node
|
|
|
|
specifies either a numerical network address
|
|
|
|
(dotted-decimal format for IPv4, hexadecimal format for IPv6)
|
|
|
|
or a network hostname, whose network addresses are looked up and resolved.
|
2005-08-09 11:40:12 +00:00
|
|
|
If
|
|
|
|
.I hints.ai_flags
|
|
|
|
contains the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B AI_NUMERICHOST
|
|
|
|
flag then the
|
|
|
|
.I node
|
|
|
|
parameter must be a numerical network address.
|
|
|
|
The
|
|
|
|
.B AI_NUMERICHOST
|
|
|
|
flag suppresses any potentially lengthy network host address lookups.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.BR getaddrinfo (3)
|
2005-08-09 10:10:29 +00:00
|
|
|
function creates a linked list of
|
2004-11-03 13:51:07 +00:00
|
|
|
.B addrinfo
|
|
|
|
structures, one for each network address subject to any restrictions
|
|
|
|
imposed by the
|
|
|
|
.I hints
|
|
|
|
parameter.
|
2005-08-09 10:10:29 +00:00
|
|
|
The
|
2004-11-03 13:51:07 +00:00
|
|
|
.I ai_canonname
|
2005-08-09 10:10:29 +00:00
|
|
|
field of the first of these
|
|
|
|
.B addrinfo
|
|
|
|
structures is set to point to the official name of the host, if
|
2005-08-09 11:40:12 +00:00
|
|
|
.I hints.ai_flags
|
2004-11-03 13:51:07 +00:00
|
|
|
includes the
|
|
|
|
.B AI_CANONNAME
|
|
|
|
flag.
|
2005-08-09 10:10:29 +00:00
|
|
|
.\" In glibc prior to 2.3.4, the ai_canonname of each addrinfo
|
|
|
|
.\" structure was set pointing to the canonical name; that was
|
|
|
|
.\" more than SUSv3 specified, or other implementations provided.
|
|
|
|
.\" MTK, Aug 05
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR ai_family ,
|
|
|
|
.IR ai_socktype ,
|
|
|
|
and
|
|
|
|
.I ai_protocol
|
|
|
|
specify the socket creation parameters.
|
|
|
|
A pointer to the socket address is placed in the
|
|
|
|
.I ai_addr
|
|
|
|
member, and the length of the socket address, in bytes,
|
|
|
|
is placed in the
|
|
|
|
.I ai_addrlen
|
|
|
|
member.
|
|
|
|
.PP
|
|
|
|
If
|
|
|
|
.I node
|
|
|
|
is NULL,
|
|
|
|
the
|
|
|
|
network address in each socket structure is initialized according to the
|
|
|
|
.B AI_PASSIVE
|
2005-08-09 11:40:12 +00:00
|
|
|
flag, which is set in
|
|
|
|
.IR hints.ai_flags .
|
2004-11-03 13:51:07 +00:00
|
|
|
The network address in each socket structure will be left unspecified
|
|
|
|
if
|
|
|
|
.B AI_PASSIVE
|
|
|
|
flag is set.
|
|
|
|
This is used by server applications, which intend to accept
|
|
|
|
client connections on any network address.
|
|
|
|
The network address will be set to the loopback interface address
|
|
|
|
if the
|
|
|
|
.B AI_PASSIVE
|
|
|
|
flag is not set.
|
|
|
|
This is used by client applications, which intend to connect
|
|
|
|
to a server running on the same network host.
|
|
|
|
.PP
|
2005-08-09 11:40:12 +00:00
|
|
|
If
|
|
|
|
.I hints.ai_flags
|
|
|
|
includes the
|
|
|
|
.B AI_ADDRCONFIG
|
|
|
|
flag, then IPv4 addresses are returned in the list pointed to by
|
|
|
|
.I result
|
|
|
|
only if the local system has at least has at least one
|
|
|
|
IPv4 address configured, and IPv6 addresses are only returned
|
|
|
|
if the local system has at least one IPv6 address configured.
|
|
|
|
.PP
|
|
|
|
If
|
|
|
|
.I hint.ai_flags
|
|
|
|
specifies the
|
|
|
|
.B AI_V4MAPPED
|
|
|
|
flag, and
|
|
|
|
.I hints.ai_family
|
|
|
|
was specified as
|
|
|
|
.BR AF_INET6 ,
|
|
|
|
and no matching IPv6 addresses could be found,
|
|
|
|
then return IPv4-mapped IPv6 addresses in the list pointed to by
|
|
|
|
.IR result .
|
|
|
|
If both
|
|
|
|
.B AI_V4MAPPED
|
|
|
|
and
|
|
|
|
.B AI_ALL
|
|
|
|
are specified in
|
|
|
|
.IR hints.ai_family ,
|
|
|
|
then return both IPv6 and IPv4-mapped IPv6 addresses
|
|
|
|
in the list pointed to by
|
|
|
|
.IR result .
|
|
|
|
.B AI_ALL
|
|
|
|
is ignored if
|
|
|
|
.B AI_V4MAPPED
|
|
|
|
is not also specified.
|
|
|
|
.PP
|
2004-11-03 13:51:07 +00:00
|
|
|
.I service
|
|
|
|
sets the port number in the network address of each socket structure.
|
|
|
|
If
|
|
|
|
.I service
|
|
|
|
is NULL the port number will be left uninitialized.
|
2005-08-09 11:40:12 +00:00
|
|
|
If
|
|
|
|
.B AI_NUMERICSERV
|
|
|
|
is specified in
|
|
|
|
.IR hints.ai_flags
|
|
|
|
and
|
|
|
|
.I service
|
|
|
|
is not NULL, then
|
|
|
|
.I service
|
|
|
|
must point to a string containing a numeric port number.
|
|
|
|
This flag is used to inhibit the invocation of a name resolution service
|
|
|
|
in cases where it is known not to be required.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.BR freeaddrinfo (3)
|
|
|
|
function frees the memory that was allocated
|
2005-08-09 10:10:29 +00:00
|
|
|
for the dynamically allocated linked list
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR res .
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
.BR getaddrinfo (3)
|
|
|
|
returns 0 if it succeeds, or one of the following non-zero error codes:
|
|
|
|
.TP
|
|
|
|
.B EAI_FAMILY
|
|
|
|
The requested address family is not supported at all.
|
|
|
|
.TP
|
|
|
|
.B EAI_SOCKTYPE
|
|
|
|
The requested socket type is not supported at all.
|
|
|
|
.TP
|
|
|
|
.B EAI_BADFLAGS
|
|
|
|
.I ai_flags
|
|
|
|
contains invalid flags.
|
|
|
|
.TP
|
|
|
|
.B EAI_NONAME
|
|
|
|
The
|
|
|
|
.I node
|
|
|
|
or
|
|
|
|
.I service
|
2005-08-09 11:40:12 +00:00
|
|
|
is not known; or both
|
2004-11-03 13:51:07 +00:00
|
|
|
.I node
|
|
|
|
and
|
|
|
|
.I service
|
2005-08-09 11:40:12 +00:00
|
|
|
are NULL; or
|
|
|
|
.B AI_NUMERICSERV
|
|
|
|
was specified in
|
|
|
|
.I hints.ai_flags
|
|
|
|
and
|
|
|
|
.I service
|
|
|
|
was not a numeric port-number string.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EAI_SERVICE
|
|
|
|
The requested service is not available for the requested socket type.
|
|
|
|
It may be available through another socket type.
|
|
|
|
.TP
|
|
|
|
.B EAI_ADDRFAMILY
|
|
|
|
The specified network host does not have any network addresses in the
|
|
|
|
requested address family.
|
|
|
|
.TP
|
|
|
|
.B EAI_NODATA
|
|
|
|
The specified network host exists, but does not have any
|
|
|
|
network addresses defined.
|
|
|
|
.TP
|
|
|
|
.B EAI_MEMORY
|
|
|
|
Out of memory.
|
|
|
|
.TP
|
|
|
|
.B EAI_FAIL
|
|
|
|
The name server returned a permanent failure indication.
|
|
|
|
.TP
|
|
|
|
.B EAI_AGAIN
|
|
|
|
The name server returned a temporary failure indication.
|
|
|
|
Try again later.
|
|
|
|
.TP
|
|
|
|
.B EAI_SYSTEM
|
|
|
|
Other system error, check
|
|
|
|
.I errno
|
|
|
|
for details.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.BR gai_strerror (3)
|
|
|
|
function translates these error codes to a human readable string,
|
|
|
|
suitable for error reporting.
|
|
|
|
.SH "CONFORMING TO"
|
|
|
|
POSIX 1003.1-2003.
|
|
|
|
The
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR getaddrinfo ()
|
2005-07-20 07:50:45 +00:00
|
|
|
function is documented in RFC\ 2553.
|
2005-08-09 11:40:12 +00:00
|
|
|
.SH "NOTES"
|
|
|
|
.BR AI_ADDRCONFIG ,
|
|
|
|
.BR AI_ALL,
|
|
|
|
and
|
|
|
|
.BR AI_V4MAPPED
|
|
|
|
are available since glibc 2.3.3.
|
|
|
|
.BR AI_NUMERICSERV
|
|
|
|
is available since glibc 2.3.4.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR getipnodebyaddr (3),
|
|
|
|
.BR getipnodebyname (3)
|