getnameinfo()--Get Name Information for Socket Address

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

  int getnameinfo(const struct sockaddr *sa, socklen_t salen,
                  char *nodename, socklen_t nodenamelen, 
                  char *servname, socklen_t servnamelen, 
                  int flags);

The getnameinfo() function translates a socket address to a node name and service location, all of which are defined as with getaddrinfo().

Parameters

sa

(Input) The pointer to a socket address structure to be translated.

salen

(Input) The length of the socket address structure pointed to by sa.

nodename

(Output) If the nodename parameter is non-NULL and the nodenamelen parameter is nonzero, then the nodename parameter must point to a buffer able to contain up to nodenamelen characters that will receive the node name as a null-terminated string. If the nodename parameter is NULL or the nodenamelen parameter is zero, the node name will not be returned. If the node's name cannot be located, the numeric form of the nodes address is returned instead of its name.

nodenamelen

(Input) The length of the buffer pointed to by nodename

servname

(Output) If the servname parameter is non-NULL and the servnamelen parameter is nonzero, then the servname parameter must point to a buffer able to contain up to servnamelen characters that will receive the service name as a null-terminated string. If the servname parameter is NULL or the servnamelen parameter is zero, the service name will not be returned. If the service name cannot be located, the numeric form of the service address (for example, its port number) is returned instead of its name.

servnamelen

(Input) The length of the buffer pointed to by servname

flags

(Input) A flag that changes the default actions of the function. By default the fully-qualified domain name (FQDN) for the host is returned, unless one of the following is true:

• If the flag bit NI_NOFQDN is set, only the nodename portion of the FQDN is returned for local hosts.
  
  
• If the flag bit NI_NUMERICHOST is set, the numeric form of the host's address is returned instead of its name, under all circumstances.
  
  
• If the flag bit NI_NAMEREQD is set, an error is returned if the host's name cannot be located.
  
  
• If the flag bit NI_NUMERICSERV is set, the numeric form of the service address is returned (for example, its port number) instead of its name, under all circumstances.
  
  
• If the flag bit NI_DGRAM is set, this indicates that the service is a datagram service (SOCK_DGRAM). The default behavior is to assume that the service is a stream service (SOCK_STREAM).

Authorities

No authorization required.

Return Value

getnameinfo() returns an integer. Possible values are:

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

On successful completion, function getnameinfo() returns the node and service names, if requested, in the buffers provided. The returned names are always null-terminated strings, and may be truncated if the actual values are longer than can be stored in the buffers provided. If the returned values are to be used as part of any further name resolution (for example, passed to getaddrinfo(), callers must either provide buffers large enough to store any result possible on the system or must check for truncation and handle that case appropriately.

Error Conditions

[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.

[EAI_FAMILY]

The address family was not recognized or the address length was invalid for the specified family.

[EAI_MEMORY]

There was a memory allocation failure.

[EAI_NONAME]

The name does not resolve for the supplied parameters. NI_NAMEREQD is set and the host's name cannot be located, or both nodename and servname were null.

[EAI_SYSTEM]

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

Usage Notes

1. The nodename and servname parameters cannot both be NULL.
   
   
2. The gai_strerror() API may be used to retrieve an error message associated with one of the error return values described above.
   
   
3. If the node and service information is obtained from the domain name server, the information is returned in the default coded character set identifier (CCSID) currently in effect for the job. (The default CCSID is the same as the job CCSID unless 65535 is requested, in which case the default CCSID is set based on the language ID of the job. See Globalization for more information.) If the node and service information is retrieved from the host database file, the default CCSID of the job is not used. To request conversion of the host information when it is retrieved from the host database file, you must use a job CCSID of something other than 65535.
   
   
4. 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 getnameinfo() API is mapped to qetnameinfo98().

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
  
  
• getaddrinfo()--Get Address Information
  
  
• gai_strerror()--Retrieve Address Information Runtime Error Message
  
  
• gethostbyaddr()--Get Host Information for IP Address
  
  
• getservbyport()--Get Service Name for Port Number
  
  
• inet_ntop()--Convert IPv4 and IPv6 Addresses Between Binary and Text Form