Index for Section 3

Alphabetical listing for G

Bottom of page

getnameinfo(3)
NAME
  getnameinfo - 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
  sa  Points either to a sockaddr_in structure (for IPv4) or to a
      sockaddr_in6 structure (for IPv6) that holds the IP address and port
      number.

  salen
      Specifies the length of either the sockaddr_in structure or the
      sockaddr_in6 structure.

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

  nodelen
      Specifies the length of the node buffer.	A value of zero instructs the
      routine not to return a node name.

  serv
      Points to a buffer in which to receive the null-terminated network
      service name associated 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.

  servlen
      Specifies the length of the serv buffer.	A value of zero instructs the
      routine not to return a service name.

  flags
      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 parameters,
  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:

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

  NI_NAMEREQD
      Returns an error if the host's name cannot be located in the hosts
      database.

  NI_NOFQDN
      Searches the hosts database and returns the node name portion of the
      fully-qualified domain name for local hosts.

  NI_NUMERICHOST
      Returns the numeric form of the host's address instead of its name.  No
      host name resolution is performed.

  NI_NUMERICSCOPE
      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 formats is
      used:

	   link-local-address%interface-id
	   link-local-address%interface-name

  NI_NUMERICSERV
      Returns the numeric form (port number) of the service address instead
      of its name.  No service name resolution is performed.

  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:

  [EAI_AGAIN]
      The nodename parameter could not be resolved this time.  Try the
      request again.

  [EAI_BADFLAGS]
      The value of the flags parameter is invalid.

  [EAI_FAIL]
      A non-recoverable error occurred.

  [EAI_FAMILY]
      The address family (ai_family in the hints structure) was not
      recognized, or the address length was invalid.

  [EAI_MEMORY]
      A memory allocation failure occurred.

  [EAI_NONAME]
      Name does not resolve to supplied 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.

  [EAI_SYSTEM]
      A system error occurred; errno is set to the error value.

FILES
  /etc/hosts
      The Internet network hostname database.  Each record in the file
      occupies a single line and has three fields consisting of the host
      address, official hostname, and aliases.

  /etc/resolv.conf
      The resolver configuration file.

  /etc/svc.conf
      The database service selection configuration file.

SEE ALSO
  Functions: gai_strerror(3), getaddrinfo(3), getservbyname(3),
  gethostbyport(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

Index for Section 3

Alphabetical listing for G

Top of page