getaddrinfo()--Get Address Information

  #include  <sys/socket.h>
  #include  <netdb.h>

  int getaddrinfo(const char *nodename, const char *servname,
                  const struct addrinfo *hints,
                  struct addrinfo **res);

The getaddrinfo() function translates the name of a service location (for example, a host name) and/or a service name and returns a set of socket addresses and associated information to be used in creating a socket with which to address the specified service.

Parameters

The nodename and servname parameters are either null pointers or pointers to null-terminated strings. One or both of these two parameters must be a non-null pointer.

The format of a valid name depends on the address family or families. If a specific family is not given and the name could be interpreted as valid within multiple supported families, the implementation will attempt to resolve the name in all supported families and, in the absence of errors, one or more results shall be returned.

nodename

(Input) The pointer to the null-terminated character string that contains the descriptive name or address string for which the address information is to be retrieved. If the servname parameter is null, a nodename must be specified and the requested network-level address will be returned. If the nodename parameter is null, a servname must be specified and the requested service location will be assumed to be local to the caller. If the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, valid descriptive names include host names. If the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, the permissable address string formats for the nodename parameter are specified as defined in inet_pton().

servname

(Input) The pointer to the null-terminated character string that contains the descriptive name or numeric representation suitable for use with the address family or families for which the requested service information is to be retrieved. If nodename is not null, the requested service location is named by nodename; otherwise, the requested service location is local to the caller. If the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, the service can be specified as a string specifying a decimal port number.

hints

(Input) The pointer to a struct addrinfo. If the parameter hints is not null, it refers to a structure containing input values that may direct the operation by providing options and by limiting the returned information to a specific socket type, address family and/or protocol. In this hints structure every member other than ai_flags, ai_family, ai_socktype and ai_protocol must be zero or a null pointer. If hints is a null pointer, the behavior will be as if it referred to a structure containing the value zero for the ai_flags, ai_socktype and ai_protocol fields, and AF_UNSPEC for the ai_family field.

The structure struct addrinfo is defined in <netdb.h>.

      struct addrinfo {
        int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, .. */
        int     ai_family;    /* AF_xxx */
        int     ai_socktype;  /* SOCK_xxx */
        int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
        socklen_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 */

        int     ai_eflags;    /* Extended flags for special usage */

      };

A value of AF_UNSPEC for ai_family means that the caller will accept any address family. A value of zero for ai_socktype means that the caller will accept any socket type. A value of zero for ai_protocol means that the caller will accept any protocol.

If the caller handles only IPv4 and not IPv6, then the ai_family member of the hints structure should be set to AF_INET when getaddrinfo() is called.

If the caller handles only TCP and not UDP, for example, then the ai_protocol member of the hints structure should be set to IPPROTO_TCP when getaddrinfo() is called.

The ai_flags field to which hints parameter points must have the value zero or be the bitwise OR of one or more of the values AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED, AI_ALL, AI_ADDRCONFIG, and AI_EXTFLAGS.

The AI_PASSIVE flag in the ai_flags member of the hints structure specifies how to fill in the IP address portion of the socket address structure. If the AI_PASSIVE flag is specified, then the returned address information will be suitable for use in binding a socket for accepting incoming connections for the specified service (that is, a call to bind()). In this case, if the nodename parameter is null, 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, the returned address information will be suitable for a call to connect() (for a connection-oriented protocol) or for a call to connect(), sendto(), or sendmsg() (for a connectionless protocol). In this case, if the nodename parameter is null, then the IP address portion of the socket address structure will be set to the loopback address. This flag is ignored if the nodename parameter is not null.

If the flag AI_CANONNAME is specified and the nodename parameter is not null, the function attempts to determine the canonical name corresponding to nodename (for example, if nodename is an alias or shorthand notation for a complete name).

If the flag AI_NUMERICHOST is specified then a non-null nodename string must be a numeric host address string. Otherwise an error of [EAI_NONAME] is returned. This flag prevents any type of name resolution service (for example, the DNS) from being called.

If the flag AI_NUMERICSERV is specified then a non-null servname string must be a numeric port string. Otherwise an error [EAI_NONAME] is returned. This flag prevents any type of name resolution service (for example, NIS+) from being called.

If the AI_V4MAPPED flag is specified along with an ai_family of AF_INET6, then the caller will accept IPv4-mapped IPv6 addresses. That is, if no IPv6 addresses are found then a query is made for A records and an IPv4 local host table lookup is performed and any results are returned as IPv4-mapped IPv6 addresses (ai_addrlen will be 28). The AI_V4MAPPED flag is ignored unless ai_family equals AF_INET6.

The AI_ALL flag is used in conjunction with the AI_V4MAPPED flag, and is only used with an ai_family of AF_INET6. When AI_ALL is logically or'd with AI_V4MAPPED flag then the caller will accept all addresses: IPv6 and IPv4-mapped IPv6. A query is first made for AAAA records and if successful, the IPv6 addresses are returned. Another query is then made for A records and any found are returned as IPv4-mapped IPv6 addresses (ai_addrlen will be 28). This flag is ignored unless ai_family equals AF_INET6.

If the AI_ADDRCONFIG flag is specified then a family of addresses will only be returned if at least one source address is configured for that family. That is, a query for AAAA records and an IPv6 local host table lookup will occur only if the node has at least one IPv6 source address configured. Similarly, a query for A records and an IPv4 local host table lookup will occur only if the node has at least one IPv4 source address configured. If the AI_V4MAPPED flag is also specified, then IPv4-mapped IPv6 addresses are returned only if at least one IPv4 source address is configured.
The loopback address is not considered as a valid configured source address.

If the AI_EXTFLAGS flag is specified then the system should look for the "ai_eflags" extended flag-set field in the addrinfo structure. That is if AI_EXTFLAGS is set, getaddrinfo will look for the values stored in the extended flag-set field, "ai_eflags", of the addrinfo data structure to determine source address selection preferences.

The ai_socktype field to which argument hints points specifies the socket type for the service. If a specific socket type is not given (for example, a value of zero) and the service name could be interpreted as valid with multiple supported socket types, the implementation will attempt to resolve the service name for all supported socket types and, all successful results will be returned. A non-zero socket type value will limit the returned information to values with the specified socket type.

The ai_eflags member of the hints structure specifies the preferred address selection rules. This field must have a value of zero or a valid bitwise OR combination of the values defined in <netdb.h>: IPV6_PREFER_SRC_HOME, IPV6_PREFER_SRC_COA, IPV6_PREFER_SRC_TMP, IPV6_PREFER_SRC_PUBLIC, IPV6_PREFER_SRC_CGA, and IPV6_PREFER_SRC_NONCGA. If ai_eflags is zero, then the default address selection rules will be used.

If the IPV6_PREFER_SRC_HOME (0x00000001) flag is specified then home addresses will be preferred as the source address. If this flag is set then IPV6_PREFER_SRC_COA must not be set.

If the IPV6_PREFER_SRC_COA (0x00000002) flag is specified then care-of addresses will be preferred as the source address. If this flag is set then IPV6_PREFER_SRC_HOME must not be set.

If the IPV6_PREFER_SRC_TMP (0x00000004) flag is specified then temporary addresses will be preferred as the source address. If this flag is set then IPV6_PREFER_SRC_PUBLIC must not be set.

If the IPV6_PREFER_SRC_PUBLIC (0x00000008) flag is specified then public addresses will be preferred as the source address. If this flag is set then IPV6_PREFER_SRC_TMP must not be set.

If the IPV6_PREFER_SRC_CGA (0x00000010) flag is specified then CGA addresses will be preferred as the source address. If this flag is set then IPV6_PREFER_SRC_NONCGA must not be set.

If the IPV6_PREFER_SRC_NONCGA (0x00000020) flag is specified then non-CGA addresses will be preferred as the source address. If this flag is set then IPV6_PREFER_SRC_CGA must not be set.

res

(Output) The pointer to a linked list of addrinfo structures, each of which specifies a socket address and information for use in creating a socket with which to use that socket address. The list will include at least one addrinfo structure. The ai_next field of each structure contains a pointer to the next structure on the list, or a null pointer if it is the last structure on the list. Each structure on the list includes values for use with a call to the socket() function, and a socket address for use with the connect() function or, if the AI_PASSIVE flag was specified, for use with the bind() function. The fields ai_family, ai_socktype, and ai_protocol are usable as the arguments to the socket() function to create a socket suitable for use with the returned address. The fields ai_addr and ai_addrlen are usable as the arguments to the connect() or bind() functions with such a socket, according to the AI_PASSIVE flag.

If nodename is not null, and if requested by the AI_CANONNAME flag, the ai_canonname field of the first returned addrinfo structure points to a null-terminated string containing the canonical name corresponding to the input nodename; if the canonical name is not available, then ai_canonname refers to the argument nodename or a string with the same contents. The contents of the ai_flags field of the returned structures is undefined.

All fields in socket address structures returned by getaddrinfo() that are not filled in through an explicit argument (for example, sin6_flowinfo and sin_zero) will be set to zero.

Note: This makes it easier to compare socket address structures.

Authorities

Authorization of *R (allow access to the object) to the host aliases file specified by the HOSTALIASES environment variable.

You also need *X authority to each directory in the path of the host aliases file.

Return Value

getaddrinfo() returns an integer. Possible values are:

• 0 (successful)
  
  
• non-zero (unsuccessful)
  
  

Error Conditions

When getaddrinfo() fails, the error return value can be set to one of the following:

[EAI_AGAIN]

The name could not be resolved at this time. Future attempts may succeed.

[EAI_BADFLAGS]

The flags parameter had an invalid value.

[EAI_FAIL]

A non-recoverable error occurred when attempting to resolve the name.

[EAI_FAMILY]

The address family was not recognized.

[EAI_MEMORY]

There was a memory allocation failure when trying to allocate storage for the return value.

[EAI_NONAME]

The name does not resolve for the supplied parameters. Neither nodename nor servname were passed. At least one of these must be passed.

[EAI_SERVICE]

The service passed was not recognized for the specified socket type.

[EAI_SOCKTYPE]

The intended socket type was not recognized.

[EAI_SYSTEM]

A system error occurred; the error code can be found in errno

[EAI_BADEXTFLAGS]

The extended flags parameter had an invalid value.

Usage Notes

1. The freeaddrinfo() API must be used to free the addrinfo structures returned by getaddrinfo().
   
   
2. The gai_strerror() API may be used to retrieve an error message associated with one of the error return values described above.
   
   
3. The System i^® Navigator or the following CL commands can be used to access the local host table:
   • ADDTCPHTE (Add TCP/IP Host Table Entry)
   • RMVTCPHTE (Remove TCP/IP Host Table Entry)
   • CHGTCPHTE (Change TCP/IP Host Table Entry)
   • RNMTCPHTE (Rename TCP/IP Host Table Entry)
   • MRGTCPHT (Merge TCP/IP Host Tables)
   • CFGTCP (Configure TCP/IP), option "10. Work with TCP/IP host table entries"
   
   
   
4. A job has a coded character set identifier (CCSID) and a default CCSID. The default CCSID is the same as the job CCSID unless the job CCSID specifies 65535, which requests that no translation be performed. In this case, the default CCSID is set by the system based on the language ID in effect for the job.

   If the address information is retrieved from the domain name server, sockets converts the address information specified by the nodename and servname parameters from the default (CCSID) to ASCII before communicating with the domain name server. If the address information is retrieved from the local host table, no conversion is done on the node and service names specified by the nodename and servname parameters unless the CCSID of the job is something other than 65535.

   In addition, the canonical names for nodename returned in the addrinfo structures will be returned in the default CCSID of the job if they are obtained from the domain name server. For conversion to occur for the canonical names returned in the addrinfo structures when they are obtained from the local host table, you must use a job CCSID of something other than 65535.

5. getaddrinfo() has been extended to allow scope zone name or scope zone index to be appended to nodename. For example:

   www.ibm.com%8 or www.ibm.com%ethline
   FE80::1%8 or FE80::1%ethline
   

   If appended, the sin6_scope_id field in the sockaddr_in6 structure pointed to by ai_addr will be set to the integer value associated with the appended value.
   
   
6. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the getaddrinfo() API is mapped to qso_getaddrinfo98().
   
   
7. When a numeric port is specified for the servname, a valid non-zero value must be specified for either ai_socktype or ai_protocol in the hints parameter. This is true regardless of the AI_NUMERICSERV flag setting.

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX^® 98 compatible interface
  
  
• bind()--Set a Local Address for the Socket
  
  
• connect()--Establish Connection or Destination Address
  
  
• freeaddrinfo()--Free Address Information
  
  
• gai_strerror()--Retrieve Address Information Runtime Error Message
  
  
• gethostbyname()--Get Host Information for Host Name
  
  
• getnameinfo()--Get Name Information for Socket Address
  
  
• getservbyname()--Get Port Number for Service Name
  
  
• getservbyport()--Get Service Name for Port Number
  
  
• inet_pton()--Convert IPv4 and IPv6 Addresses Between Text and Binary Form
  
  
• sendto()--Send Data
  
  
• sendmsg()--Send Data or Descriptors or Both
  
  
• socket()--Create a Socket