freeaddrinfo man page on YellowDog

Man page or keyword search:  
man Server   18644 pages
apropos Keyword Search (all sections)
Output format
YellowDog logo
[printable version]

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 getaddrinfo(), 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	 loca‐
       tion  (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 cre‐
       ating 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	point‐
       ers  to	null-terminated	 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 family is not given and the name could be interpreted as
       valid within multiple  supported	 families,  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  nodename.  If servname is not null, it is a null-termi‐
       nated character string identifying the requested service. This  can  be
       either  a descriptive name or a numeric representation suitable 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	proto‐
       col.  If	 hints	is  a  null  pointer,  the  behavior shall be as if it
       referred to a structure 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  bitwise-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  por‐
       tion  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 corre‐
       sponding 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  ``canonical name'' and ``alias'' cannot be precisely
	      defined for the general case. However, Domain Name System imple‐
	      mentations  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 per‐
       formed. See below for handling of the case where a canonical name  can‐
       not 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_NO‐
       NAME] 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 getaddrinfo() 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 con‐
       figured 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  supported 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 specified 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	proto‐
       col;  the value of ai_protocol shall be interpreted as in a call to the
       socket() function  with	the  corresponding  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 creat‐
       ing 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 contains 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() func‐
       tion,  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 containing 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 undefined.

       All  fields in socket address structures returned by getaddrinfo() that
       are not filled in through an explicit argument (for example, sin6_flow‐
       info) 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() , get‐
       servbyname()  ,	 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 original Standard can be  obtained	online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group		     2003		       FREEADDRINFO(P)
[top]

List of man pages available for YellowDog

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net