HP-UX Reference (11i v1 05/09) - 3 Library Functions A-M (vol 6)

g
getaddrinfo(3N) getaddrinfo(3N)
NAME
getaddrinfo(), getnameinfo(), freeaddrinfo(), gai_strerror() - get hostname and address entry
SYNOPSIS
#include <sys/socket.h>
#include <netdb.h>
int getaddrinfo(const char *hostname, const char *servname,
const struct addrinfo *hints, struct addrinfo **res);
int getnameinfo(const struct sockaddr *sa, size_t salen,
char *host, size_t hostlen,
char *serv, size_t servlen, int flags);
void freeaddrinfo(struct addrinfo *ai);
char *gai_strerror(int encode);
DESCRIPTION
getaddrinfo()
Hostname-to-address translation is done in a protocol-independent fashion using the
getaddrinfo()
function.
The getaddrinfo() function returns an integer. The input arguments hostname and servname 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 hostname and servname are specified. The non-NULL hostname string
can be either a hostname or a numeric host address string (i.e., a dotted-decimal IPv4 address or a hexade-
cimal IPv6 address). The non-NULL servname string can be either a service name or a decimal port
number. However, in the server scenario, only servname is specified.
The third input argument is a pointer to the structure of type
addrinfo defined as follows in
<netdb.h>:
struct addrinfo {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
size_t ai_addrlen;
char *ai_canonname;
struct sockaddr *ai_addr;
struct addrinfo *ai_next;
};
The members of this structure are:
ai_flags The flag used to set the socket address structure for an IPv4 address or an IPv6
address.
If the AI_PASSIVE bit is set, then the returned socket address structure from
the getaddrinfo() function will be used as an argument to the bind() func-
tion call. When this bit is set and the hostname argument to the getad-
drinfo()
function 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 is not set, then the returned socket address structure will be
used as an argument to the connect(), sendto(),orsendmsg() functions.
In this case, if the hostname argument is a NULL pointer, then the IP address por-
tion of the socket address will be set to loopback address.
If the AI_CANONNAME bit is set, then upon successful return, getaddrinfo()
will return the ai_canonname member of the first addrinfo structure, which
is a NULL terminated string containing the canonical name of the specified host.
If an AI_V4MAPPED flag is specified with an ai_family value of AF_INET6,
getaddrinfo() returns IPv4-mapped IPv6 addresses when it does not find any
Section 3−−300 Hewlett-Packard Company − 1 − HP-UX 11i Version 1: September 2005