#include <sys.socket.h>
#include <sys.socket.h>
Kernighan-Ritchie-C:
int getaddrinfo(nodename, servname, hints, res);
const char *nodename;
const char *servname;
const struct addrinfo *hints;
const struct addrinfo **res;
ANSI-C:
int getaddrinfo(const char* nodename, const char* servname, const struct addrinfo* hints, const struct addrinfo** res);
Description
The getaddrinfo() function allows host information for the AF_INET and AF_INET6 address families to be queried regardless of the protocol involved.
nodename and servname parameters
When getaddrinfo() is called, at least one of the parameters nodename or servname must be not be the null pointer. nodename and servname are either a null pointer or a string terminated with the null byte. The nodename parameter can be a name or an IPv4 address in decimal dotted notation or an IPv6 address in hexadecimal colon notation. The servname parameter can be either a service name or a decimal port number.
hints parameter
The hints parameter can be used to pass an addrinfo structure if desired. If not, the hints parameter must be the null pointer.
The addrinfo structure is declared as follows:
struct addrinfo {
int ai_flags; /* AI_PASSIVE,AI_CANONNAME,AI_NUMERICHOST*/
/* AI_NUMERICSERV,AI_V4MAPPED,AI_ALL */
/* AI_NUMERICHOST*/
int ai_family; /* PF_INET,PF_INET6 */
int ai_socktype; /* SOCK_STREAM,SOCK_DGRAM*/
int ai_protocol; /* 0 (not supported in SOCKETS) */
size_t ai_addrlen; /* length of the address */
char ai_canonname; /* canon name of the node */
struct sockaddr *ai_addr; /* socket address structure of the address*/
/* family AF_INET or AF_INET6 */
struct addrinfo ai_next; /* next structure in concatenated list */
};
All the elements in the object of the type struct addrinfo passed with hints except ai_flags, ai_family, ai_socktype must have the value 0 or must be the null pointer.
A selection is made with the values for the addrinfo components ai_flags, ai_family and ai_socktype:
ai_family = PF_UNSPEC means that any protocol family is desired.
ai_socktype = 0 means that an addrinfo structure is to be created for each socket type with the required service.
ai_flags = AI_PASSIVE means that the returned socket address structure is to be used for a bind() call. If nodename = NULL (see above), the IP address element is set to INADDR_ANY for an IPv4 address and to IN6ADDR_ANY for an IPv6 address.
If the AI_PASSIVE bit is not set, the returned socket address structure is used
for a connect() call if ai_socktype = SOCK_STREAM
for a connect()-, sendto()-, sendmsg() call if ai_socktype = SOCK_DGRAM
If, in these cases, nodename is the null pointer, the IP address of sockaddr is supplied with the value of the loopback address.
If the AI_CANONNAME bit is set in the ai_flags of the hints structure and getaddrinfo() is executed successfully, at least the first returned addrinfo structure in the element ai_canonname contains the pointer to the canon name terminated with the null byte of the selected host.
The ai_canonname is determined by a reverse lookup. If this reverse lookup is not successful, i.e. no name is found for the specified address, no error is reported, but the content of the nodename parameter is copied into the ai_canonname element if it is not equal to the null pointer. If nodename is a null pointer, a null pointer is entered in the ai_canonname element.
Please note that the content of nodename can also be an address! This is then also copied.If the AI_NUMERICHOST bit is set in the ai_flags of the hints structure, a nodename which is not the null pointer must be an IPv4 address string in decimal dotted notation or an IPv6 address string in hexadecimal colon notation. Otherwise, the return value is EAI_NONAME. The flag prevents a call that would resolve the name via a DNS service or internal host table.
If the AI_V4MAPPED bit is set in the ai_flags of the hints structure together with ai_family = PF_INET6 and no IPv6 addresses are supplied for the name, IPv4 addresses contained in the output list are entered in the form of IPv4-mapped IPv6 addresses. If the AI_ALL bit is also set, both IPv6 and the IPv4-mapped IPv6 addresses are entered.
If the AI_ADDRCONFIG bit is set in the ai_flags of the hints structure, IPv4 or IPv6 addresses which belong to the name are output only if a corresponding interface address is defined on the local computer. The loopback address does not count as a configured interface address here.
If the AI_NUMERICSERV bit is set in the ai_flags of the hints structure, the pointer of servname which is not a null pointer must point to a numerical port number string. If this is not the case, an error message (EAI_NONAME) is returned.
hints = NULL has the same effect as an addrinfo structure initialized with 0 and ai_family = PF_UNSPEC.
res parameter
If getaddrinfo() is executed successfully, a pointer to one or more concatenated addrinfo structures is passed in res, where the element ai_next = NULL indicates the last element in the chain. Each of the returned addrinfo structures contains a value corresponding to the socket() call in the elements ai_family and ai_socktype. ai_addr always points to a socket address structure whose length is specified in ai_addrlen.
Return value
0:
If successful.
>0:
If errors occur. Return value is an error code EAI_xxx defined in <netdb.h>.
-1:
If errors occur. errno is set to indicate the error.
Error code defined in <netdb.h>:
EAI_ADDRFAMILY
The Internet address families are not supported for the specified host.
EAI_AGAIN
Temporary error while accessing the host name information (e.g. DNS error).
The function should be called again.
EAI_BADFLAGS
Invalid value for the ai_flags parameter.
EAI_FAIL
Error while accessing the host name information
EAI_FAMILY
The protocol family is not supported.
EAI_MEMORY
Error when requesting memory.
EAI_NODATA
No address corresponding to the host name was found.
EAI_NONAME
Host or service name is not supported or is unknown.
EAI_SERVICE
Service is not supported for this socket type.
EAI_SOCKTYPE
The socket type is not supported.
EAI_SYSTEM
System error; is specified in more detail in errno.
Note
Memory for the addrinfo structures returned by the getaddrinfo() function is requested dynamically and must be released again with the freeaddrinfo() function.
In SOCKETS(BS2000), PF_UNSPEC = AF_UNSPEC.
If you are not using DNS, do not specify a fully-qualified-domain-name but rather a host name if you want to be able to use the BCAM processor table (e.g. host instead of host.mydomain.net).
The LWRESD resolver which is common to the SOCKETS(BS2000), BCAM and POSIX sockets is used to access the DNS. For more details, see the manual "BCAM Volume 1/2".