getnameinfo()--Get Name Information for Socket Address


  Syntax 
  #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);

  Service Program Name: QSOSRV2

  Default Public Authority: *USE

  Threadsafe: Yes

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

  • If the flag bit NI_NUMERICSCOPE is set, the numeric form of the scope identifier is returned on link-local addresses (for example, its interface index) instead of its interface (line description) name, under all circumstances. This flag is ignored when sa is not an IPv6 address.

Authorities

No authorization required.


Return Value

getnameinfo() returns an integer. Possible values are:

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. If the returned values are to be used as part of any further name resolution (for example, passed to getaddrinfo(), callers must provide buffers large enough to store any result possible on the system.


Error Conditions

When getnameinfo() 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.

[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_OVERFLOW]

There is not enough buffer space for the requested operation. The buffer pointed to by nodename or servname is not large enough.

[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. 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. 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 local host table, the default CCSID of the job is not used. To request conversion of the host information when it is retrieved from the local host table, you must use a job CCSID of something other than 65535.

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


API introduced: V5R2

[ Back to top | UNIX-Type APIs | APIs by category ]