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

g
getaddrinfo(3N) getaddrinfo(3N)
freeaddrinfo()
All 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:
#include <sys/socket.h>
#include <netdb.h>
void freeaddrinfo(struct addrinfo *ai);
The addrinfo structure pointed to by the ai
argument is freed, along with any dynamic storage
pointed to by the structure. This operation is repeated until a NULL ai_next pointer is encountered.
gai_strerror()
To aid applications in printing error messages based on the
EAI_xxx codes returned by getad-
drinfo(), the gai_strerror function is defined.
#include <sys/socket.h>
#include <netdb.h>
char *gai_strerror(int ecode);
The argument is one of the EAI_xxx values defined earlier, and the return value points to a string
describing the error. If the argument is not one of the EAI_xxx values, the function still returns a
pointer to a string whose contents indicate an unknown error.
getnameinfo()
The
getnameinfo() function is used to look up a hostname and service name, given the binary
address and port. The function is defined as follows:
#include <sys/socket.h>
#include <netdb.h>
int getnameinfo(const struct sockaddr *sa, size_t salen,
char *host, size_t hostlen, char *serv,
size_t servlen, int flags);
This function looks up an IP address and port number provided by the caller in the DNS and system-
specific database, and returns text strings for both in buffers provided by the caller.
The function indicates successful completion by a zero return value; a non-zero return value indicates
failure.
The first argument,
sa, points to either a sockaddr_in structure (for IPv4) or a
sockaddr_in6
structure (for IPv6) that holds the IP address and port number. The
salen argument gives the length of
the
sockaddr_in or sockaddr_in6 structure.
The function returns the hostname associated with the IP address in the buffer pointed to by the
host
argument. The caller provides the size of this buffer via the hostlen argument. The service name asso-
ciated with the port number is returned in the buffer pointed to by serv, and the servlen argument
gives the length of this buffer. The caller specifies not to return either string by providing zero values for
the hostlen or servlen arguments. Otherwise, the caller must provide buffers large enough to hold
the hostname and the service name, including the terminating null characters.
Unfortunately, most systems do not provide constants that specify the maximum size of either a fully-
qualified domain name or a service name. Therefore, to aid the application in allocating buffers for these
two returned strings, the following constants are defined in
<netdb.h>:
#define NI_MAXHOST 1025
#define NI_MAXSERV 32
In recent versions of DNS/BIND, the first value NI_MAXHOST is actually defined as the constant
MAXDNAME in the header file <arpa/nameser.h>. (Older versions of BIND define this constant to be
256.)
The final argument to the
getnameinfo() function is a flag that changes the default actions of this
function. By default, the fully-qualified domain name (FQDN) for the host is looked up in the DNS and
returned. If the flag bit NI_NOFQDN is set, only the hostname portion of the FQDN is returned for local
hosts.
Section 3−−360 Hewlett-Packard Company − 3 − HP-UX 11i Version 2: September 2004