Index for Section 3

Alphabetical listing for L

Bottom of page

LWRES_GETADDRINFO(3)
NAME
  lwres_getaddrinfo, lwres_freeaddrinfo - socket address structure to host
  and service name

SYNOPSIS
  #include <lwres/netdb.h>

  int lwres_getaddrinfo(const char *hostname, const char *servname, const
  struct addrinfo *hints, struct addrinfo **res);

  void lwres_freeaddrinfo(struct addrinfo *ai);

  If the operating system does not provide a struct addrinfo,  the  following
  structure is used:

  struct  addrinfo {
	  int		  ai_flags;	  /* AI_PASSIVE, AI_CANONNAME */
	  int		  ai_family;	  /* PF_xxx */
	  int		  ai_socktype;	  /* SOCK_xxx */
	  int		  ai_protocol;	  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
	  size_t	  ai_addrlen;	  /* length of ai_addr */
	  char		  *ai_canonname;  /* canonical name for hostname */
	  struct sockaddr *ai_addr;	  /* binary address */
	  struct addrinfo *ai_next;	  /* next structure in linked list */
  };

DESCRIPTION
  lwres_getaddrinfo() is used to get a list of IP addresses and port  numbers
  for  host  hostname  and service servname.  The function is the lightweight
  resolver's implementation of getaddrinfo() as defined in RFC2133.  hostname
  and  servname are pointers to null-terminated strings or NULL.  hostname is
  either a host name or a numeric host address string: a dotted decimal	 IPv4
  address  or an IPv6 address.	servname is either a decimal port number or a
  service name as listed in /etc/services.

  hints is an optional pointer to a struct addrinfo.  This structure  can  be
  used	to  provide  hints  concerning	the  type  of  socket that the caller
  supports or wishes to use.  The caller can supply the	 following  structure
  elements in *hints:

  ai_family
       The protocol family that should be used.	 When  ai_family  is  set  to
       PF_UNSPEC,  it  means  the  caller  will	 accept	 any  protocol family
       supported by the operating system.

  ai_socktype
       denotes the type of socket - SOCK_STREAM,  SOCK_DGRAM  or  SOCK_RAW  -
       that  is	 wanted.  When ai_socktype is zero the caller will accept any
       socket type.

  ai_protocol
       indicates  which	 transport  protocol  is   wanted:   IPPROTO_UDP   or
       IPPROTO_TCP.   If  ai_protocol  is  zero	 the  caller  will accept any
       protocol.

  ai_flags
       Flag bits.  If the AI_CANONNAME bit  is	set,  a	 successful  call  to
       lwres_getaddrinfo()  will return a a null-terminated string containing
       the canonical name of the specified hostname in	ai_canonname  of  the
       first   addrinfo	 structure  returned.	Setting	 the  AI_PASSIVE  bit
       indicates that the returned socket address structure is	intended  for
       used  in a call to bind(2).  In this case, if the hostname argument is
       a NULL pointer, then the IP address  portion  of	 the  socket  address
       structure   will	  be  set  to  INADDR_ANY  for	an  IPv4  address  or
       IN6ADDR_ANY_INIT for an IPv6 address.

       When ai_flags does not set the AI_PASSIVE  bit,	the  returned  socket
       address	structure will be ready for use in a call to connect(2) for a
       connection-oriented protocol or connect(2), sendto(2),  or  sendmsg(2)
       if  a  connectionless  protocol was chosen.  The IP address portion of
       the socket address structure will be set to the	loopback  address  if
       hostname is a NULL pointer and AI_PASSIVE is not set in ai_flags.

       If ai_flags is set to AI_NUMERICHOST it indicates that hostname should
       be treated as a numeric string defining an IPv4 or IPv6 address and no
       name resolution should be attempted.

  All other elements of the struct addrinfo passed via hints must be zero.

  A hints of NULL is treated as if the	caller	provided  a  struct  addrinfo
  initialized to zero with ai_familyset to PF_UNSPEC.

  After a successful call to lwres_getaddrinfo(), *res	is  a  pointer	to  a
  linked  list	of  one or more addrinfo structures.  Each struct addrinfo in
  this list cn be processed by following the ai_next pointer,  until  a	 NULL
  pointer  is  encountered.   The  three  members ai_family, ai_socktype, and
  ai_protocol in each returned addrinfo structure contain  the	corresponding
  arguments  for  a  call  to  socket(2).  For each addrinfo structure in the
  list, the ai_addr member points to a filled-in socket address structure  of
  length ai_addrlen.

  All of the  information  returned  by	 lwres_getaddrinfo()  is  dynamically
  allocated:  the  addrinfo structures, and the socket address structures and
  canonical host name strings pointed to by the	 addrinfostructures.   Memory
  allocated  for the dynamically allocated structures created by a successful
  call to lwres_getaddrinfo() is released by lwres_freeaddrinfo().  ai	is  a
  pointer to a struct addrinfo created by a call to lwres_getaddrinfo().

RETURN VALUES
  lwres_getaddrinfo() returns zero on success  or  one	of  the	 error	codes
  listed  in  gai_strerror(3)  if  an  error  occurs.	If  both hostname and
  servname are NULL lwres_getaddrinfo() returns EAI_NONAME.

SEE ALSO
  lwres(3),	      lwres_getaddrinfo(3),	       lwres_freeaddrinfo(3),
  lwres_gai_strerror(3),   RFC2133,  getservbyname(3),	bind(2),  connect(2),
  sendto(2), sendmsg(2), socket(2).

Index for Section 3

Alphabetical listing for L

Top of page