Originální popis anglicky:
freeaddrinfo, getaddrinfo - get address information
Návod, kniha: POSIX Programmer's Manual
#include <sys/socket.h>
#include <netdb.h>
void freeaddrinfo(struct addrinfo *
ai);
int getaddrinfo(const char *restrict
nodename,
const char *restrict
servname,
const struct addrinfo *restrict
hints,
struct addrinfo **restrict
res);
The
freeaddrinfo() function shall free one or more
addrinfo
structures returned by
getaddrinfo(), along with any additional storage
associated with those structures. If the
ai_next field of the structure
is not null, the entire list of structures shall be freed. The
freeaddrinfo() function shall support the freeing of arbitrary sublists
of an
addrinfo list originally returned by
getaddrinfo().
The
getaddrinfo() function shall translate the name of a service location
(for example, a host name) and/or a service name and shall return a set of
socket addresses and associated information to be used in creating a socket
with which to address the specified service.
- Note:
- In many cases it is implemented by the Domain Name System,
as documented in RFC 1034, RFC 1035, and RFC 1886.
The
freeaddrinfo() and
getaddrinfo() functions shall be
thread-safe.
The
nodename and
servname arguments are either null pointers or
pointers to null-terminated strings. One or both of these two arguments shall
be supplied by the application as a non-null pointer.
The format of a valid name depends on the address family or families. If a
specific family is not given and the name could be interpreted as valid within
multiple supported families, the implementation shall attempt to resolve the
name in all supported families and, in absence of errors, one or more results
shall be returned.
If the
nodename argument is not null, it can be a descriptive name or can
be an address string. If the specified address family is AF_INET,
AF_INET6, or AF_UNSPEC, valid descriptive names include host names. If
the specified address family is AF_INET or AF_UNSPEC, address strings using
Internet standard dot notation as specified in
inet_addr() are valid.
If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 text
forms described in
inet_ntop() are valid.
If
nodename is not null, the requested service location is named by
nodename; otherwise, the requested service location is local to the
caller.
If
servname is null, the call shall return network-level addresses for
the specified
nodename. If
servname is not null, it is a
null-terminated character string identifying the requested service. This can
be either a descriptive name or a numeric representation suitable for use with
the address family or families. If the specified address family is AF_INET,
AF_INET6, or AF_UNSPEC, the service can be specified as a string
specifying a decimal port number.
If the
hints argument is not null, it refers to a structure containing
input values that may direct the operation by providing options and by
limiting the returned information to a specific socket type, address family,
and/or protocol. In this
hints structure every member other than
ai_flags,
ai_family,
ai_socktype, and
ai_protocol
shall be set to zero or a null pointer. A value of AF_UNSPEC for
ai_family means that the caller shall accept any address family. A
value of zero for
ai_socktype means that the caller shall accept any
socket type. A value of zero for
ai_protocol means that the caller
shall accept any protocol. If
hints is a null pointer, the behavior
shall be as if it referred to a structure containing the value zero for the
ai_flags,
ai_socktype, and
ai_protocol fields, and
AF_UNSPEC for the
ai_family field.
The
ai_flags field to which the
hints parameter points shall be
set to zero or be the bitwise-inclusive OR of one or more of the values
AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED, AI_ALL,
and AI_ADDRCONFIG.
If the AI_PASSIVE flag is specified, the returned address information shall be
suitable for use in binding a socket for accepting incoming connections for
the specified service. In this case, if the
nodename argument is null,
then the IP address portion of the socket address structure shall be set to
INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address. If the
AI_PASSIVE flag is not specified, the returned address information shall be
suitable for a call to
connect() (for a connection-mode protocol) or
for a call to
connect(),
sendto(), or
sendmsg() (for a
connectionless protocol). In this case, if the
nodename argument is
null, then the IP address portion of the socket address structure shall be set
to the loopback address. The AI_PASSIVE flag shall be ignored if the
nodename argument is not null.
If the AI_CANONNAME flag is specified and the
nodename argument is not
null, the function shall attempt to determine the canonical name corresponding
to
nodename (for example, if
nodename is an alias or shorthand
notation for a complete name).
- Note:
- Since different implementations use different conceptual
models, the terms ``canonical name'' and ``alias'' cannot be precisely
defined for the general case. However, Domain Name System implementations
are expected to interpret them as they are used in RFC 1034.
A numeric host address string is not a ``name'', and thus does not have a
``canonical name'' form; no address to host name translation is performed. See
below for handling of the case where a canonical name cannot be obtained.
If the AI_NUMERICHOST flag is specified, then a non-null
nodename string
supplied shall be a numeric host address string. Otherwise, an [EAI_NONAME]
error is returned. This flag shall prevent any type of name resolution service
(for example, the DNS) from being invoked.
If the AI_NUMERICSERV flag is specified, then a non-null
servname string
supplied shall be a numeric port string. Otherwise, an [EAI_NONAME] error
shall be returned. This flag shall prevent any type of name resolution service
(for example, NIS+) from being invoked.
If the AI_V4MAPPED flag is specified along with an
ai_family of AF_INET6,
then
getaddrinfo() shall return IPv4-mapped IPv6 addresses on finding
no matching IPv6 addresses (
ai_addrlen shall be 16). The AI_V4MAPPED
flag shall be ignored unless
ai_family equals AF_INET6. If the AI_ALL
flag is used with the AI_V4MAPPED flag, then
getaddrinfo() shall return
all matching IPv6 and IPv4 addresses. The AI_ALL flag without the AI_V4MAPPED
flag is ignored.
If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be returned only if
an IPv4 address is configured on the local system, and IPv6 addresses
shall be returned only if an IPv6 address is configured on the local system.
The
ai_socktype field to which argument
hints points specifies the
socket type for the service, as defined in
socket() . If a specific
socket type is not given (for example, a value of zero) and the service name
could be interpreted as valid with multiple supported socket types, the
implementation shall attempt to resolve the service name for all supported
socket types and, in the absence of errors, all possible results shall be
returned. A non-zero socket type value shall limit the returned information to
values with the specified socket type.
If the
ai_family field to which
hints points has the value
AF_UNSPEC, addresses shall be returned for use with any address family that
can be used with the specified
nodename and/or
servname.
Otherwise, addresses shall be returned for use only with the specified address
family. If
ai_family is not AF_UNSPEC and
ai_protocol is not
zero, then addresses are returned for use only with the specified address
family and protocol; the value of
ai_protocol shall be interpreted as
in a call to the
socket() function with the corresponding values of
ai_family and
ai_protocol.
A zero return value for
getaddrinfo() indicates successful completion; a
non-zero return value indicates failure. The possible values for the failures
are listed in the ERRORS section.
Upon successful return of
getaddrinfo(), the location to which
res
points shall refer to a linked list of
addrinfo structures, each of
which shall specify a socket address and information for use in creating a
socket with which to use that socket address. The list shall include at least
one
addrinfo structure. The
ai_next field of each structure
contains a pointer to the next structure on the list, or a null pointer if it
is the last structure on the list. Each structure on the list shall include
values for use with a call to the
socket() function, and a socket
address for use with the
connect() function or, if the AI_PASSIVE flag
was specified, for use with the
bind() function. The fields
ai_family,
ai_socktype, and
ai_protocol shall be usable
as the arguments to the
socket() function to create a socket suitable
for use with the returned address. The fields
ai_addr and
ai_addrlen are usable as the arguments to the
connect() or
bind() functions with such a socket, according to the AI_PASSIVE flag.
If
nodename is not null, and if requested by the AI_CANONNAME flag, the
ai_canonname field of the first returned
addrinfo structure
shall point to a null-terminated string containing the canonical name
corresponding to the input
nodename; if the canonical name is not
available, then
ai_canonname shall refer to the
nodename
argument or a string with the same contents. The contents of the
ai_flags field of the returned structures are undefined.
All fields in socket address structures returned by
getaddrinfo() that
are not filled in through an explicit argument (for example,
sin6_flowinfo) shall be set to zero.
- Note:
- This makes it easier to compare socket address structures.
The
getaddrinfo() function shall fail and return the corresponding value
if:
- EAI_AGAIN
- The name could not be resolved at this time. Future
attempts may succeed.
- EAI_BADFLAGS
-
The flags parameter had an invalid value.
- EAI_FAIL
- A non-recoverable error occurred when attempting to resolve
the name.
- EAI_FAMILY
- The address family was not recognized.
- EAI_MEMORY
- There was a memory allocation failure when trying to
allocate storage for the return value.
- EAI_NONAME
- The name does not resolve for the supplied parameters.
Neither
nodename nor
servname were supplied. At least one of these
shall be supplied.
- EAI_SERVICE
- The service passed was not recognized for the specified
socket type.
- EAI_SOCKTYPE
-
The intended socket type was not recognized.
- EAI_SYSTEM
- A system error occurred; the error code can be found in
errno.
- EAI_OVERFLOW
-
An argument buffer overflowed.
The following sections are informative.
None.
If the caller handles only TCP and not UDP, for example, then the
ai_protocol member of the
hints structure should be set to
IPPROTO_TCP when
getaddrinfo() is called.
If the caller handles only IPv4 and not IPv6, then the
ai_family member
of the
hints structure should be set to AF_INET when
getaddrinfo() is called.
The term ``canonical name'' is misleading; it is taken from the Domain Name
System (RFC 2181). It should be noted that the canonical name is a
result of alias processing, and not necessarily a unique attribute of a host,
address, or set of addresses. See RFC 2181 for more discussion of this
in the Domain Name System context.
None.
None.
connect() ,
gai_strerror() ,
gethostbyaddr() ,
getnameinfo() ,
getservbyname() ,
socket() , the Base
Definitions volume of IEEE Std 1003.1-2001,
<netdb.h>,
<sys/socket.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard, the original
IEEE and The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.opengroup.org/unix/online.html
.
