MAN page from Trustix bind-devel-8.2.6-3tr.i586.rpm

GETADDRINFO

Section: C Library Functions (3)
Index
BSD mandoc
KAME

NAME

getaddrinfofreeaddrinfo gai_strerror - nodename-to-address translation in protocol-independent manner

SYNOPSIS

Fd #include <sys/socket.h>Fd #include <netdb.h>Ft intFn getaddrinfo const char *nodename const char *servname const struct addrinfo *hints struct addrinfo **resFt voidFn freeaddrinfo struct addrinfo *aiFt char *Fn gai_strerror int ecode

DESCRIPTION

TheFn getaddrinfofunction is defined for protocol-independent nodename-to-address translation.It performs functionality of gethostbyname(3)andgetservbyname(3),in more sophisticated manner.

The addrinfo structure is defined as a result of including the<netdb.h>header:

struct addrinfo {                                                  *     int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */     int     ai_family;    /* PF_xxx */     int     ai_socktype;  /* SOCK_xxx */     int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */     size_t  ai_addrlen;   /* length of ai_addr */     char   *ai_canonname; /* canonical name for nodename */     struct sockaddr  *ai_addr; /* binary address */     struct addrinfo  *ai_next; /* next structure in linked list */};

TheFa nodenameandFa servnamearguments are pointers to null-terminated strings orNULL One or both of these two arguments must be anon -NULLpointer.In the normal client scenario, both theFa nodenameandFa servnameare specified.In the normal server scenario, only theFa servnameis specified.Anon -NULLFa nodenamestring can be either a node name or a numeric host address stringPo i.e., a dotted-decimal IPv4 address or an IPv6 hex addressPc .Anon -NULLFa servnamestring can be either a service name or a decimal port number.

The caller can optionally pass anaddrinfostructure, pointed to by the third argument,to provide hints concerning the type of socket that the caller supports.In thisFa hintsstructure all members other thanFa ai_flags ,Fa ai_family ,Fa ai_socktype ,andFa ai_protocolmust be zero or aNULLpointer.A value ofPF_UNSPECforFa ai_familymeans the caller will accept any protocol family.A value of 0 forFa ai_socktypemeans the caller will accept any socket type.A value of 0 forFa ai_protocolmeans the caller will accept any protocol.For example, if the caller handles only TCP and not UDP, then theFa ai_socktypemember of the hints structure should be set toSOCK_STREAMwhenFn getaddrinfois called.If the caller handles only IPv4 and not IPv6, then theFa ai_familymember of theFa hintsstructure should be set toPF_INETwhenFn getaddrinfois called.If the third argument toFn getaddrinfois aNULLpointer, this is the same as if the caller had filled in anaddrinfostructure initialized to zero withFa ai_familyset to PF_UNSPEC.

Upon successful return a pointer to a linked list of one or moreaddrinfostructures is returned through the final argument.The caller can process eachaddrinfostructure in this list by following theFa ai_nextpointer, until aNULLpointer is encountered.In each returnedaddrinfostructure the three membersFa ai_family ,Fa ai_socktype ,andFa ai_protocolare the corresponding arguments for a call to theFn socketfunction.In eachaddrinfostructure theFa ai_addrmember points to a filled-in socket address structure whose length isspecified by theFa ai_addrlenmember.

If theAI_PASSIVEbit is set in theFa ai_flagsmember of theFa hintsstructure, then the caller plans to use the returned socket addressstructure in a call toFn bind .In this case, if theFa nodenameargument is aNULLpointer, then the IP address portion of the socketaddress structure will be set toINADDR_ANYfor an IPv4 address orIN6ADDR_ANY_INITfor an IPv6 address.

If theAI_PASSIVEbit is not set in theFa ai_flagsmember of theFa hintsstructure, then the returned socket address structure will be ready for acall toFn connect(for a connection-oriented protocol)or eitherFn connect ,Fn sendto ,orFn sendmsg(for a connectionless protocol) In this case, if theFa nodenameargument is aNULLpointer, then the IP address portion of thesocket address structure will be set to the loopback address.

If theAI_CANONNAMEbit is set in theFa ai_flagsmember of theFa hintsstructure, then upon successful return theFa ai_canonnamemember of the firstaddrinfostructure in the linked list will point to a null-terminated stringcontaining the canonical name of the specifiedFa nodename .

If theAI_NUMERICHOSTbit is set in theFa ai_flagsmember of theFa hintsstructure, then anon -NULLFa nodenamestring must be a numeric host address string.Otherwise an error ofEAI_NONAMEis returned.This flag prevents any type of name resolution service (e.g., the DNS)from being called.

All of the information returned byFn getaddrinfois dynamically allocated:theaddrinfostructures, and the socket address structures and canonical node namestrings pointed to by the addrinfo structures.To return this information to the system the functionFn freeaddrinfois called.TheFa addrinfostructure pointed to by theFa ai argumentis freed, along with any dynamic storage pointed to by the structure.This operation is repeated until aNULLFa ai_nextpointer is encountered.

To aid applications in printing error messages based on theEAI_xxxcodes returned byFn getaddrinfo ,Fn gai_strerroris defined.The argument is one of theEAI_xxxvalues defined earlier and the return value points to a string describingthe error.If the argument is not one of theEAI_xxxvalues, the function still returns a pointer to a string whose contentsindicate an unknown error.

FILES

/etc/hosts
/etc/host.conf
/etc/resolv.conf

DIAGNOSTICS

Error return status from Fn getaddrinfois zero on success and non-zero on errors.Non-zero error codes are defined in<netdb.h> and as follows:

EAI_ADDRFAMILY: address family for nodename not supported
EAI_AGAIN: temporary failure in name resolution
EAI_BADFLAGS: invalid value for ai_flags
EAI_FAIL: non-recoverable failure in name resolution
EAI_FAMILY: ai_family not supported
EAI_MEMORY: memory allocation failure
EAI_NODATA: no address associated with nodename
EAI_NONAME: nodename nor servname provided, or not known
EAI_SERVICE: servname not supported for ai_socktype
EAI_SOCKTYPE: ai_socktype not supported
EAI_SYSTEM: system error returned in errno

If called with proper argument,Fn gai_strerrorreturns a pointer to a string describing the given error code.If the argument is not one of theEAI_xxxvalues, the function still returns a pointer to a string whose contentsindicate an unknown error.

HISTORY

The implementation first appeared in WIDE Hydrangea IPv6 protocol stack kit.

STANDARDS

TheFn getaddrinfofunction is defined IEEE POSIX 1003.1g draft specification,and documented in ``Basic Socket Interface Extensions for IPv6''(RFC2133)

BUGS

The text was shamelessly copied from RFC2133.

This document was created byman2html,using the manual pages.