getnameinfo(3)getnameinfo(3)NAMEgetnameinfo - Get a node name and service name for an address and port
number
SYNOPSIS
#include <netdb.h>
int getnameinfo(
const struct sockaddr *sa,
socklen_t salen,
char *node,
size_t nodelen,
char *serv,
size_t servlen,
int flags );
LIBRARY
Standard C Library (libc)
PARAMETERS
Points either to a sockaddr_in structure (for IPv4) or to a sock‐
addr_in6 structure (for IPv6) that holds the IP address and port num‐
ber. Specifies the length of either the sockaddr_in structure or the
sockaddr_in6 structure. Points to a buffer in which to receive the
null-terminated network node name or address (either global address or
scoped address withh scope identifier) contained in sa. A NULL pointer
instructs the routine not to return a node name. Both node and serv
cannot be zero. Specifies the length of the node buffer. A value of
zero instructs the routine not to return a node name. Points to a buf‐
fer in which to receive the null-terminated network service name asso‐
ciated with the port number contained in sa. A NULL pointer instructs
the routine not to return a service name. Both node and serv cannot be
zero. Specifies the length of the serv buffer. A value of zero
instructs the routine not to return a service name. Specifies changes
to the routine's default actions. By default, the routine searches for
the fully-qualified domain name of the node in the hosts database and
returns it. See the "Flag Bits" section for additional flags.
DESCRIPTION
The getnameinfo() routine looks up an IP address and port number in a
sockaddr structure specified by sa and returns node name and service
name text strings in the buffers pointed to by the node and serv param‐
eters, respectively.
If the node's name is not found, the routine returns the numeric form
of the node's address, regardless of the value of the flags parameter.
If the service's name is not found, the routine returns the numeric
form of the service's address (port number) regardless of the value of
the flags parameter.
The application must provide buffers large enough to hold the fully-
qualified domain name and the service name, including the terminating
null characters. To assist in initializing the buffers, the following
constants are defined in <netdb.h>:
#define NI_MAXHOST 1025 #define NI_MAXSERV 32
Flag Bits
The flag bits and their meanings, if set, are as follows: Specifies
that the service is a datagram service (SOCK_DGRAM). The default is to
assume a stream service (SOCK_STREAM). This is required for the few
ports (512-514) that have different services for UDP and TCP. Returns
an error if the host's name cannot be located in the hosts database.
Searches the hosts database and returns the node name portion of the
fully-qualified domain name for local hosts. Returns the numeric form
of the host's address instead of its name. No host name resolution is
performed. Returns the interface index instead of the interface name
for scoped addresses. The address is returned in scoped address format.
No host name resolution is performed.
[Tru64 UNIX] For scoped addresses, either of the following for‐
mats is used:
link-local-address%interface-id link-local-address%interface-
name Returns the numeric form (port number) of the service
address instead of its name. No service name resolution is per‐
formed.
The two NI_NUMERIC* flags are required to support the -n option that
many commands provide. All flags are defined in <netdb.h> header file.
RETURN VALUES
Upon successful completion, the getnameinfo() function returns 0
(zero). Upon failure, it returns a non-zero value.
ERRORS
If the getnameinfo() function fails, it returns one of the following
values: The nodename parameter could not be resolved this time. Try
the request again. The value of the flags parameter is invalid. A
non-recoverable error occurred. The address family (ai_family in the
hints structure) was not recognized, or the address length was invalid.
A memory allocation failure occurred. Name does not resolve to sup‐
plied parameters.
The NI_NAMEREQD flag was set and the node's name was not found.
You did not pass either the nodename or servname parameter. You
must pass at least one. A system error occurred; errno is set
to the error value.
FILES
The Internet network hostname database. Each record in the file occu‐
pies a single line and has three fields consisting of the host address,
official hostname, and aliases. The resolver configuration file. The
database service selection configuration file.
SEE ALSO
Functions: gai_strerror(3), getaddrinfo(3), getservbyname(3), gethost‐
byport(3), inet_ntop(3), socket(3).
Files: hostname(5), resolv.conf(4), svc.conf(4).
Networks: bind_intro(7), nis_intro(7).
Network Programmer's Guide
getnameinfo(3)