Index for Section 3

Alphabetical listing for G

Bottom of page

getaddrinfo(3)
NAME
  getaddrinfo - Get a network host entry by address

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

SYNOPSIS
  #include <netdb.h>

  int getaddrinfo(
	  const char *nodename,
	  const char *servname,
	  const struct addrinfo *hints,
	  struct addrinfo **res);

STANDARDS
  The getaddrinfo function supports POSIX.1g Draft 6.6.

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  nodename  Points to a network node name, alias, or numeric host address
	    (for example, a IPv4 dotted-decimal address or an IPv6
	    hexadecimal address).  This is a null-terminated string or NULL.
	    Either the nodename or servname parameter, or both, must be non-
	    NULL.

  servname  Points to a network service name or port number.  This is a
	    null-terminated string or NULL.  Either the nodename or servname
	    parameter, or both, must be non-NULL.

  hints	    Points to an addrinfo structure that contains information about
	    the type of socket the caller supports.  The netdb.h header file
	    defines the addrinfo structure.  This is an optional parameter.

  res	    Points to a linked list of one or more addrinfo structures.

DESCRIPTION
  The getaddrinfo() routine returns a pointer to a linked list of one or more
  structures of type addrinfo.	Its members specify data obtained from either
  the local /etc/hosts file or one of the files distributed by DNS/BIND or
  NIS.	To determine which file or files to search, and in which order, the
  system uses the switches in the /etc/svc.conf file. The netdb.h header file
  defines the addrinfo structure.


  If using DNS/BIND, the information is obtained from a name server specified
  in the /etc/resolv.conf file.

  Clients typically specify both the nodename and servname parameters.
  Servers typically specify only the servname parameter.

  If you specify the hints parameter, all addrinfo structure members other
  than ai_flags, ai_family, ai_socktype, and ai_protocol must be zero or a
  NULL pointer.

  If you specify a value of PF_UNSPEC for ai_family, you will accept any
  protocol family.  If you specify a value of 0 for ai_socktype, you will
  accept any socket type.  If you specify a value of 0 for ai_protocol, you
  will accept any protocol.  For example, if the application handles only
  TCP, set the ai_socktype member of the hints structure to SOCK_STREAM.  If
  the application handles only IPv4, set the ai_family member of the hints
  structure to PF_INET.

  If the hints parameter is a NULL pointer, this is identical to passing an
  addrinfo structure that has been initialized to zero and the ai_family
  member set to PF_UNSPEC.

  Upon successful return, getaddrinfo returns a pointer to a linked list of
  one or more addrinfo structures.  The application can process each addrinfo
  structure in the list by following the ai_next pointer, until a NULL
  pointer is encountered.  In each returned addrinfo structure, the
  ai_family, ai_socktype, and ai_protocol members are the corresponding
  arguments for a call to the socket() function.  The ai_addr member points
  to a filled-in socket address structure whose length is specified by the
  ai_addrlen member.

  addrinfo Structure Flags


  The following flags are defined for the ai_flags member of the addrinfo
  structure:

  AI_PASSIVE
      If set, your application is to use the returned socket address
      structure in a call to bind().  If the nodename parameter is a NULL
      pointer, the IP address portion of the socket address structure is set
      to INADDR_ANY (for an IPv4 address) or IN6ADDR_ANY_INIT (for an IPv6
      address).

      If not set, the returned socket address structure is ready for your
      application to call connect() (for a connection-oriented protocol) or
      either connect(), sendto(), or sendmsg() (for a connectionless
      protocol).  If the nodename parameter is a NULL pointer, the IP address
      portion of the socket address structure will be set to the loopback
      address.

  AI_CANONNAME
      If set, when the getaddrinfo() returns successfully, the ai_canonname
      member of the first addrinfo structure in the linked list points to a
      null-terminated string containing the canonical name of the specified
      hostname.

  AI_NUMERICHOST
      If set, a non-NULL node name string must be a numeric host address
      string.  This prevents any type of name resolution service (for
      example, DNS/BIND) from being called.

  These flags are defined in <netdb.h>.



RETURN VALUES
  Upon successful completion, the getaddrinfo() function returns 0 (zero).
  Upon failure, it returns one of the EAI_* error codes defined in netdb.h.
  Use the gai_strerror(3) command to print error messages based on these
  return codes.

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: endhostent(3), freeaddrinfo(3), gai_strerror(3),
  gethostbyaddr(3), sethostent(3).

  Files: hostname(5), resolv.conf(4), svc.conf(4).

  Networks: bind_intro(7), nis_intro(7).

  Standards: standards(5).

Index for Section 3

Alphabetical listing for G

Top of page