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:
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. 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
The nodename and servname parameters cannot both be
NULL.
The gai_strerror() API may be used to
retrieve an error message associated with one of the error return values
described above.
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"
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.
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