diff options
Diffstat (limited to 'man-pages-posix-2017/man3p/freeaddrinfo.3p')
| -rw-r--r-- | man-pages-posix-2017/man3p/freeaddrinfo.3p | 556 |
1 files changed, 556 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/freeaddrinfo.3p b/man-pages-posix-2017/man3p/freeaddrinfo.3p new file mode 100644 index 0000000..e64225e --- /dev/null +++ b/man-pages-posix-2017/man3p/freeaddrinfo.3p @@ -0,0 +1,556 @@ +'\" 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 . |