👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for getaddrinfo (linux section 3posix)

FREEADDRINFO(P) 		    POSIX Programmer's Manual			  FREEADDRINFO(P)

NAME
       freeaddrinfo, getaddrinfo - get address information

SYNOPSIS
       #include <sys/socket.h>
       #include <netdb.h>

       void freeaddrinfo(struct addrinfo *ai);
       int getaddrinfo(const char *restrict nodename,
	      const char *restrict servname,
	      const struct addrinfo *restrict hints,
	      struct addrinfo **restrict res);

DESCRIPTION
       The  freeaddrinfo() function shall free one or more addrinfo structures returned by getad-
       drinfo(), along with any additional storage  associated	with  those  structures.  If  the
       ai_next	field of the structure is not null, the entire list of structures shall be freed.
       The freeaddrinfo() function shall support the freeing of arbitrary sublists of an addrinfo
       list originally returned by getaddrinfo().

       The  getaddrinfo() function shall translate the name of a service location (for example, a
       host name) and/or a service name and shall return a set of socket addresses and associated
       information to be used in creating a socket with which to address the specified service.

       Note:  In  many	cases  it  is  implemented  by	the  Domain Name System, as documented in
	      RFC 1034, RFC 1035, and RFC 1886.

       The freeaddrinfo() and getaddrinfo() functions shall be thread-safe.

       The nodename and servname arguments are either null pointers or	pointers  to  null-termi-
       nated  strings. One or both of these two arguments shall be supplied by the application as
       a non-null pointer.

       The format of a valid name depends on the address family or families.  If a specific  fam-
       ily is not given and the name could be interpreted as valid within multiple supported fam-
       ilies, the implementation shall attempt to resolve the name in all supported families and,
       in absence of errors, one or more results shall be returned.

       If  the	nodename  argument is not null, it can be a descriptive name or can be an address
       string. If the specified address family is  AF_INET,	AF_INET6,   or	AF_UNSPEC,  valid
       descriptive  names  include  host  names.  If  the  specified address family is AF_INET or
       AF_UNSPEC,  address  strings  using  Internet  standard	dot  notation  as  specified   in
       inet_addr() are valid.

       If  the	specified  address  family  is	AF_INET6  or  AF_UNSPEC, standard IPv6 text forms
       described in inet_ntop() are valid.

       If nodename is not null, the requested service location is named by  nodename;  otherwise,
       the requested service location is local to the caller.

       If servname is null, the call shall return network-level addresses for the specified node-
       name. If servname is not null, it is a null-terminated character  string  identifying  the
       requested service. This can be either a descriptive name or a numeric representation suit-
       able for use with the address family or families.  If  the  specified  address  family  is
       AF_INET,   AF_INET6,   or AF_UNSPEC, the service can be specified as a string specifying a
       decimal port number.

       If the hints argument is not null, it refers to a structure containing input  values  that
       may  direct the operation by providing options and by limiting the returned information to
       a specific socket type, address family, and/or protocol. In  this  hints  structure  every
       member  other  than ai_flags, ai_family, ai_socktype, and ai_protocol shall be set to zero
       or a null pointer. A value of AF_UNSPEC for ai_family means that the caller  shall  accept
       any  address  family.   A value of zero for ai_socktype means that the caller shall accept
       any socket type. A value of zero for ai_protocol means that the caller  shall  accept  any
       protocol.  If hints is a null pointer, the behavior shall be as if it referred to a struc-
       ture containing the value zero for the ai_flags, ai_socktype, and ai_protocol fields,  and
       AF_UNSPEC for the ai_family field.

       The ai_flags field to which the hints parameter points shall be set to zero or be the bit-
       wise-inclusive OR of one or more of the values AI_PASSIVE,  AI_CANONNAME,  AI_NUMERICHOST,
       AI_NUMERICSERV, AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG.

       If  the	AI_PASSIVE  flag is specified, the returned address information shall be suitable
       for use in binding a socket for accepting incoming connections for the specified  service.
       In  this case, if the nodename argument is null, then the IP address portion of the socket
       address structure shall be set to INADDR_ANY for an IPv4 address or  IN6ADDR_ANY_INIT  for
       an IPv6 address. If the AI_PASSIVE flag is not specified, the returned address information
       shall be suitable for a call to connect() (for a connection-mode protocol) or for  a  call
       to connect(), sendto(), or sendmsg() (for a connectionless protocol). In this case, if the
       nodename argument is null, then the IP address portion of  the  socket  address	structure
       shall be set to the loopback address. The AI_PASSIVE flag shall be ignored if the nodename
       argument is not null.

       If the AI_CANONNAME flag is specified and the nodename argument is not null, the  function
       shall  attempt  to determine the canonical name corresponding to nodename (for example, if
       nodename is an alias or shorthand notation for a complete name).

       Note:  Since different implementations use different conceptual models, the terms ``canon-
	      ical  name''  and  ``alias'' cannot be precisely defined for the general case. How-
	      ever, Domain Name System implementations are expected to interpret them as they are
	      used in RFC 1034.

       A  numeric  host  address  string  is not a ``name'', and thus does not have a ``canonical
       name'' form; no address to host name translation is performed. See below for  handling  of
       the case where a canonical name cannot be obtained.

       If the AI_NUMERICHOST flag is specified, then a non-null nodename string supplied shall be
       a numeric host address string.  Otherwise, an [EAI_NONAME] error is  returned.  This  flag
       shall  prevent  any  type  of  name  resolution	service (for example, the DNS) from being
       invoked.

       If the AI_NUMERICSERV flag is specified, then a non-null servname string supplied shall be
       a  numeric  port  string.   Otherwise,  an [EAI_NONAME] error shall be returned. This flag
       shall prevent any type of name resolution service (for example, NIS+) from being invoked.

       If the AI_V4MAPPED flag is specified along with an  ai_family  of  AF_INET6,  then  getad-
       drinfo()  shall	return IPv4-mapped IPv6 addresses on finding no matching IPv6 addresses (
       ai_addrlen shall be 16). The AI_V4MAPPED flag shall be  ignored	unless	ai_family  equals
       AF_INET6.  If  the AI_ALL flag is used with the AI_V4MAPPED flag, then getaddrinfo() shall
       return all matching IPv6 and IPv4 addresses. The AI_ALL flag without the AI_V4MAPPED  flag
       is ignored.

       If  the	AI_ADDRCONFIG flag is specified, IPv4 addresses shall be returned only if an IPv4
       address is configured on the local system,    and IPv6 addresses shall be returned only if
       an IPv6 address is configured on the local system.

       The  ai_socktype  field	to  which argument hints points specifies the socket type for the
       service, as defined in socket() . If a specific socket type is not given (for  example,	a
       value  of zero) and the service name could be interpreted as valid with multiple supported
       socket types, the implementation shall attempt to resolve the service name  for	all  sup-
       ported socket types and, in the absence of errors, all possible results shall be returned.
       A non-zero socket type value shall limit the returned information to values with the spec-
       ified socket type.

       If  the	ai_family field to which hints points has the value AF_UNSPEC, addresses shall be
       returned for use with any address family that can be  used  with  the  specified  nodename
       and/or  servname.  Otherwise,  addresses shall be returned for use only with the specified
       address family. If ai_family is not AF_UNSPEC and ai_protocol is not zero, then	addresses
       are  returned  for  use	only with the specified address family and protocol; the value of
       ai_protocol shall be interpreted as in a call to the socket()  function	with  the  corre-
       sponding values of ai_family and ai_protocol.

RETURN VALUE
       A  zero	return value for getaddrinfo() indicates successful completion; a non-zero return
       value indicates failure. The possible values for the failures are  listed  in  the  ERRORS
       section.

       Upon successful return of getaddrinfo(), the location to which res points shall refer to a
       linked list of addrinfo structures, each of which  shall  specify  a  socket  address  and
       information  for  use in creating a socket with which to use that socket address. The list
       shall include at least one addrinfo structure. The ai_next field of  each  structure  con-
       tains  a  pointer  to  the next structure on the list, or a null pointer if it is the last
       structure on the list. Each structure on the list shall include values for use with a call
       to  the socket() function, and a socket address for use with the connect() function or, if
       the AI_PASSIVE flag was specified, for use with the bind() function. The fields ai_family,
       ai_socktype,  and ai_protocol shall be usable as the arguments to the socket() function to
       create a socket suitable for use  with  the  returned  address.	The  fields  ai_addr  and
       ai_addrlen  are	usable	as the arguments to the connect() or bind() functions with such a
       socket, according to the AI_PASSIVE flag.

       If nodename is not null, and if requested by the AI_CANONNAME flag, the ai_canonname field
       of  the first returned addrinfo structure shall point to a null-terminated string contain-
       ing the canonical name corresponding to the input nodename; if the canonical name  is  not
       available,  then  ai_canonname  shall  refer to the nodename argument or a string with the
       same contents. The contents of the ai_flags field of the  returned  structures  are  unde-
       fined.

       All  fields  in socket address structures returned by getaddrinfo() that are not filled in
       through an explicit argument (for example, sin6_flowinfo) shall be set to zero.

       Note:  This makes it easier to compare socket address structures.

ERRORS
       The getaddrinfo() function shall fail and return the corresponding value if:

       EAI_AGAIN
	      The name could not be resolved at this time. Future attempts may succeed.

       EAI_BADFLAGS

	      The flags parameter had an invalid value.

       EAI_FAIL
	      A non-recoverable error occurred when attempting to resolve the name.

       EAI_FAMILY
	      The address family was not recognized.

       EAI_MEMORY
	      There was a memory allocation failure when  trying  to  allocate	storage  for  the
	      return value.

       EAI_NONAME
	      The name does not resolve for the supplied parameters.

       Neither nodename nor servname were supplied. At least one of these shall be supplied.

       EAI_SERVICE
	      The service passed was not recognized for the specified socket type.

       EAI_SOCKTYPE

	      The intended socket type was not recognized.

       EAI_SYSTEM
	      A system error occurred; the error code can be found in errno.

       EAI_OVERFLOW

	      An argument buffer overflowed.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       If  the	caller	handles only TCP and not UDP, for example, then the ai_protocol member of
       the hints structure should be set to IPPROTO_TCP when getaddrinfo() is called.

       If the caller handles only IPv4 and not IPv6, then  the	ai_family  member  of  the  hints
       structure should be set to AF_INET when getaddrinfo() is called.

       The  term  ``canonical  name''  is  misleading;	it  is	taken from the Domain Name System
       (RFC 2181). It should be noted that the canonical name is a result  of  alias  processing,
       and  not  necessarily  a  unique  attribute  of	a host, address, or set of addresses. See
       RFC 2181 for more discussion of this in the Domain Name System context.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       connect() , gai_strerror() , gethostbyaddr() , getnameinfo() , getservbyname() ,  socket()
       , the Base Definitions volume of IEEE Std 1003.1-2001, <netdb.h>, <sys/socket.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				  FREEADDRINFO(P)


All times are GMT -4. The time now is 01:32 PM.

Unix & Linux Forums Content Copyright1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password