getaddrinfo Subroutine

Purpose

Note: Hostname-to-address translation is done in a protocol-independent fashion using this function.

Attention: This specification is taken from IEEE POSIX 1003.1g (Protocol Independent Interfaces) DRAFT 6.3. This function may be modified to match that specification as it develops. Should there be any discrepancies between this description and the POSIX description, the POSIX description takes precedence.

Library

Syntax

#include=<sys/socket.h>
#include=<netdb.h>
int getaddrinfo (hostname, servname, hints, res)
const char *hostname;
const char *servname;
const struct addrinfo *hints
struct addrinfo **res;

Description

The first two arguments describe the hostname and/or service name to be referenced. 0 (zero) or 1 (one) of these arguments may be NULL. A non-NULLhostname may be either a hostname or a numeric host address string (a dotted-decimal for IPv4 or hex for IPv6). A non-NULL servname may be either a service name or a decimal port number.

The third argument specifies hints concerning the desired return information. To be valid, the hints structure must contain zero (or NULL) values for all members, with the exceptions of: ai_flags, ai_family, ai_socktype, and ai_protocol. These members may be set to a specific value to indicate desired results (ai_family may be set to PF_INET6 to indicate only IPv6 sockets), or to zero (or the appropriate unspecified value (PF_UNSPEC for ai_family)) to indicate that any type will be accepted.

The addrinfo structure is defined as:

struct addrinfo {
  int               ai_flags;          /* AI_PASSIVE, AI_CANONNAME */
  int               ai_family;         /* PF_xxx */
  int               ai_socktype;       /* SOCK_xxx */
  int               ai_protocol;       /* 0 or IP=PROTO_xxx for IPv4 and IPv6 */
  size_t            ai_addrlen;        /* length of ai_addr */
  char              *ai_canonname;     /* canoncial name for hostname */
  struct sockaddr   *ai_addr;          /* binary address */
  struct addrinfo   *ai_next;          /* next structure in linked list */

Return Values

If the query is successful, a pointer to a linked list of one or more addrinfo structures is returned via the fourth argument. If the query fails, a non-zero error code will be returned.

Error Codes

The following names are the non-zero error codes. See netdb.h for further definition.

Implementation Specifics

The hostname and servname arguments are pointers to null-terminated strings or NULL. One or both of these two arguments must be a non-NULL pointer. In the normal client scenario, both the hostname and servname are specified. In the normal server scenario, only the servname is specified. A non-NULL hostname string can be either a host name or a numeric host address string (i.e., a dotted-decimal IPv4 address or an IPv6 hex address) 2E A non-NULL servname string can be either a service name or a decimal port number.

The caller can optionally pass an addrinfo structure, pointed to by the third argument, to provide hints concerning the type of socket that the caller supports. In this hints structure all members other than ai_flags, ai_family, ai_socktype, and ai_protocol must be zero or a NULL pointer. A value of PF_UNSPEC for ai_family means the caller will accept any protocol family. A value of 0 for ai_socktype means the caller will accept any socket type. A value of 0 for ai_protocol means the caller will accept any protocol. For example, if the caller handles only TCP and not UDP, then the ai_socktype member of the hints structure should be set to SOCK_STREAM 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 PF_INET when getaddrinfo() is called. If the third argument to getad drinfo() is a NULL pointer, this is the same as if the caller had filled in an addrinfo structure initialized to zero with ai_family set to PF_UNSPEC.

Upon successful return a pointer to a linked list of one or more addrinfo structures is returned through the final argument. The caller can process each addrinfo structure in this list by following the ai_next pointer, until a NULL pointer is encountered. In each returned addrinfo structure the three members ai_family, ai_socktype, and ai_protocol are the corresponding arguments for a call to the socket() function. In each addrinfo structure the ai_addr member points to a filled-in socket address structure whose length is specified by the ai_addrlen member.

If the AI_PASSIVE bit is set in the ai_flags member of the hints structure, then the caller plans to use the returned socket address structure in a call to bind(). In this case, if the hostname argument is a NULL pointer, then the IP address portion of the socket address structure will be set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address.

If the AI_PASSIVE bit is not set in the ai_flags member of the hints structure, then the returned socket address structure will be ready for a call to connect() (for a connection-oriented protocol) or either connect(), sendto(), or sendmsg() (for a connectionless protocol). In this case, if the hostname argument is a NULL pointer, then the IP address portion of the socket address structure will be set to the loopback address.

If the AI_CANONNAME bit is set in the ai_flags member of the hints structure, then upon successful return the ai_canonname member of the first addrinfo structure in the linked list will point to a null-terminated string containing the canonical name of the specified hostname.

All of the information returned by getaddrinfo() is dynamically allocated: the addrinfo structures, the socket address structures, and canonical host name strings pointed to by the addrinfo structures. To return this information to the system the function freeaddrinfo is called.

Related Information

The freeaddrinfo subroutine.