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

LIBRARY
  Standard C Library (libc.so, libc.a)

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

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 alias corresponding to the address 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 host 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 flag
  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_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 flag 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.

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

Index for Section 3

Alphabetical listing for G

Top of page