path: root/upstream/archlinux/man3p/freeaddrinfo.3p

'\" et
.TH FREEADDRINFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
freeaddrinfo,
getaddrinfo
\(em get address information
.SH SYNOPSIS
.LP
.nf
#include <sys/socket.h>
#include <netdb.h>
.P
void freeaddrinfo(struct addrinfo *\fIai\fP);
int getaddrinfo(const char *restrict \fInodename\fP,
    const char *restrict \fIservname\fP,
    const struct addrinfo *restrict \fIhints\fP,
    struct addrinfo **restrict \fIres\fP);
.fi
.SH DESCRIPTION
The
\fIfreeaddrinfo\fR()
function shall free one or more
.BR addrinfo
structures returned by
\fIgetaddrinfo\fR(),
along with any additional storage associated with those structures. If
the
.IR ai_next
field of the structure is not null, the entire list of structures shall
be freed. The
\fIfreeaddrinfo\fR()
function shall support the freeing of arbitrary sublists of an
.BR addrinfo
list originally returned by
\fIgetaddrinfo\fR().
.P
The
\fIgetaddrinfo\fR()
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.
.TP 10
.BR Note:
In many cases it is implemented by the Domain Name System,
as documented in RFC\ 1034, RFC\ 1035, and RFC\ 1886.
.P
.P
The
\fIfreeaddrinfo\fR()
and
\fIgetaddrinfo\fR()
functions shall be thread-safe.
.P
The
.IR nodename
and
.IR 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.
.P
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.
.P
If the
.IR 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
.IR "\fIinet_addr\fR\^(\|)"
are valid.
.P
If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
text forms described in
.IR "\fIinet_ntop\fR\^(\|)"
are valid.
.P
If
.IR nodename
is not null, the requested service location is named by
.IR nodename ;
otherwise, the requested service location is local to the caller.
.P
If
.IR servname
is null, the call shall return network-level addresses for the
specified
.IR nodename.
If
.IR 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.
.P
If the
.IR hints
argument is not null, it refers to a structure containing input values
that directs the operation by providing options and by limiting the
returned information to a specific socket type, address family, and/or
protocol, as described below. The application shall ensure that each of the
.IR ai_addrlen ,
.IR ai_addr ,
.IR ai_canonname ,
and
.IR ai_next
members, as well as each of the non-standard additional members,
if any, of this
.IR hints
structure is initialized. If any of these members has a value
other than the value that would result from default initialization,
the behavior is implementation-defined. A value of AF_UNSPEC for
.IR ai_family
means that the caller shall accept any address family. A value of zero
for
.IR ai_socktype
means that the caller shall accept any socket type. A value of zero for
.IR ai_protocol
means that the caller shall accept any protocol. If
.IR hints
is a null pointer, the behavior shall be as if it referred to a
structure containing the value zero for the
.IR ai_flags ,
.IR ai_socktype ,
and
.IR ai_protocol
fields, and AF_UNSPEC for the
.IR ai_family
field.
.P
The
.IR ai_flags
field to which the
.IR 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.
.P
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
.IR 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
\fIconnect\fR()
(for a connection-mode protocol) or for a call to
\fIconnect\fR(),
\fIsendto\fR(),
or
\fIsendmsg\fR()
(for a connectionless protocol). In this case, if the
.IR 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
.IR nodename
argument is not null.
.P
If the AI_CANONNAME flag is specified and the
.IR nodename
argument is not null, the function shall attempt to determine the
canonical name corresponding to
.IR nodename
(for example, if
.IR nodename
is an alias or shorthand notation for a complete name).
.TP 10
.BR 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.
.RS 10 
.P
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.
.RE
.P
.P
If the AI_NUMERICHOST flag is specified, then a non-null
.IR nodename
string supplied shall be a numeric host address string. Otherwise, an
.BR [EAI_NONAME] 
error is returned. This flag shall prevent any type of name resolution
service (for example, the DNS) from being invoked.
.P
If the AI_NUMERICSERV flag is specified, then a non-null
.IR servname
string supplied shall be a numeric port string. Otherwise, an
.BR [EAI_NONAME] 
error shall be returned. This flag shall prevent any type of name
resolution service (for example, NIS+) from being invoked.
.P
By default, with an
.IR ai_family
of AF_INET6,
\fIgetaddrinfo\fR()
shall return only IPv6 addresses. If the AI_V4MAPPED flag is
specified along with an
.IR ai_family
of AF_INET6, then
\fIgetaddrinfo\fR()
shall return IPv4-mapped IPv6 addresses on finding no matching IPv6
addresses. The AI_V4MAPPED flag shall be ignored unless
.IR ai_family
equals AF_INET6. If the AI_ALL flag is used with the AI_V4MAPPED flag,
then
\fIgetaddrinfo\fR()
shall return all matching IPv6 and IPv4 addresses. The AI_ALL flag
without the AI_V4MAPPED flag shall be ignored.
.P
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.
.P
The
.IR ai_socktype
field to which argument
.IR hints
points specifies the socket type for the service, as defined in
.IR "\fIsocket\fR\^(\|)".
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.
.P
If the
.IR ai_family
field to which
.IR hints
points has the value AF_UNSPEC, addresses shall be returned for use
with any address family that can be used with the specified
.IR nodename
and/or
.IR servname .
Otherwise, addresses shall be returned for use only with the specified
address family. If
.IR ai_family
is not AF_UNSPEC and
.IR ai_protocol
is not zero, then addresses shall be returned for use only with the
specified address family and protocol; the value of
.IR ai_protocol
shall be interpreted as in a call to the
\fIsocket\fR()
function with the corresponding values of
.IR ai_family
and
.IR ai_protocol .
.SH "RETURN VALUE"
A zero return value for
\fIgetaddrinfo\fR()
indicates successful completion; a non-zero return value indicates
failure. The possible values for the failures are listed in the
ERRORS section.
.P
Upon successful return of
\fIgetaddrinfo\fR(),
the location to which
.IR res
points shall refer to a linked list of
.BR 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
.BR addrinfo
structure. The
.IR 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
\fIsocket\fR()
function, and a socket address for use with the
\fIconnect\fR()
function or, if the AI_PASSIVE flag was specified, for use with the
\fIbind\fR()
function. The fields
.IR ai_family ,
.IR ai_socktype ,
and
.IR ai_protocol
shall be usable as the arguments to the
\fIsocket\fR()
function to create a socket suitable for use with the returned
address. The fields
.IR ai_addr
and
.IR ai_addrlen
are usable as the arguments to the
\fIconnect\fR()
or
\fIbind\fR()
functions with such a socket, according to the AI_PASSIVE flag.
.P
If
.IR nodename
is not null, and if requested by the AI_CANONNAME flag, the
.IR ai_canonname
field of the first returned
.BR addrinfo
structure shall point to a null-terminated string containing the
canonical name corresponding to the input
.IR nodename ;
if the canonical name is not available, then
.IR ai_canonname
shall refer to the
.IR nodename
argument or a string with the same contents. The contents of the
.IR ai_flags
field of the returned structures are undefined.
.P
All fields in socket address structures returned by
\fIgetaddrinfo\fR()
that are not filled in through an explicit argument (for example,
.IR sin6_flowinfo )
shall be set to zero.
.TP 10
.BR Note:
This makes it easier to compare socket address structures.
.P
.SH ERRORS
The
\fIgetaddrinfo\fR()
function shall fail and return the corresponding error value if:
.IP [EAI_AGAIN] 12
The name could not be resolved at this time. Future attempts may
succeed.
.IP [EAI_BADFLAGS] 12
.br
The
.IR flags
parameter had an invalid value.
.IP [EAI_FAIL] 12
A non-recoverable error occurred when attempting to resolve the name.
.IP [EAI_FAMILY] 12
The address family was not recognized.
.IP [EAI_MEMORY] 12
There was a memory allocation failure when trying to allocate storage
for the return value.
.IP [EAI_NONAME] 12
The name does not resolve for the supplied parameters.
.RS 12 
.P
Neither
.IR nodename
nor
.IR servname
were supplied. At least one of these shall be supplied.
.RE
.IP [EAI_SERVICE] 12
The service passed was not recognized for the specified socket type.
.IP [EAI_SOCKTYPE] 12
.br
The intended socket type was not recognized.
.IP [EAI_SYSTEM] 12
A system error occurred; the error code can be found in
.IR errno .
.LP
.IR "The following sections are informative."
.SH "EXAMPLES"
The following (incomplete) program demonstrates the use of
\fIgetaddrinfo\fR()
to obtain the socket address structure(s) for the service named in the
program's command-line argument. The program then loops through each
of the address structures attempting to create and bind a socket to the
address, until it performs a successful
\fIbind\fR().
.sp
.RS 4
.nf

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <sys/socket.h>
#include <netdb.h>
.P
int
main(int argc, char *argv[])
{
    struct addrinfo *result, *rp;
    int sfd, s;
.P
    if (argc != 2) {
        fprintf(stderr, "Usage: %s port\en", argv[0]);
        exit(EXIT_FAILURE);
    }
.P
    struct addrinfo hints = {0};
    hints.ai_family = AF_UNSPEC;
    hints.ai_socktype = SOCK_DGRAM;
    hints.ai_flags = AI_PASSIVE;
    hints.ai_protocol = 0;
.P
    s = getaddrinfo(NULL, argv[1], &hints, &result);
    if (s != 0) {
        fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s));
        exit(EXIT_FAILURE);
    }
.P
    /* getaddrinfo() returns a list of address structures.
       Try each address until a successful bind().
       If socket(2) (or bind(2)) fails, close the socket
       and try the next address. */
.P
    for (rp = result; rp != NULL; rp = rp->ai_next) {
        sfd = socket(rp->ai_family, rp->ai_socktype,
            rp->ai_protocol);
        if (sfd == -1)
            continue;
.P
        if (bind(sfd, rp->ai_addr, rp->ai_addrlen) == 0)
            break;            /* Success */
.P
        close(sfd);
    }
.P
    if (rp == NULL) {         /* No address succeeded */
        fprintf(stderr, "Could not bind\en");
        exit(EXIT_FAILURE);
    }
.P
    freeaddrinfo(result);     /* No longer needed */
.P
             /* ... use socket bound to sfd ... */
}
.fi
.P
.RE
.SH "APPLICATION USAGE"
If the caller handles only TCP and not UDP, for example, then the
.IR ai_protocol
member of the
.IR hints
structure should be set to IPPROTO_TCP when
\fIgetaddrinfo\fR()
is called.
.P
If the caller handles only IPv4 and not IPv6, then the
.IR ai_family
member of the
.IR hints
structure should be set to AF_INET when
\fIgetaddrinfo\fR()
is called.
.P
Although it is common practice to initialize the
.IR hints
structure using:
.sp
.RS 4
.nf

struct addrinfo hints;
memset(&hints, 0, sizeof hints);
.fi
.P
.RE
.P
this method is not portable according to this standard, because
the structure can contain pointer or floating-point members that
are not required to have an all-bits-zero representation after
default initialization. Portable methods make use of default
initialization; for example:
.sp
.RS 4
.nf

struct addrinfo hints = { 0 };
.fi
.P
.RE
.P
or:
.sp
.RS 4
.nf

static struct addrinfo hints_init;
struct addrinfo hints = hints_init;
.fi
.P
.RE
.P
A future version of this standard may require that a pointer object
with an all-bits-zero representation is a null pointer, and that
.BR addrinfo
does not have any floating-point members if a floating-point
object with an all-bits-zero representation does not have the value 0.0.
.P
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.
.SH "RATIONALE"
None.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIconnect\fR\^(\|)",
.IR "\fIendservent\fR\^(\|)",
.IR "\fIgai_strerror\fR\^(\|)",
.IR "\fIgetnameinfo\fR\^(\|)",
.IR "\fIsocket\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<netdb.h>\fP",
.IR "\fB<sys_socket.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .