getaddrinfo man page on RedHat

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

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

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

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 config‐
       ured 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(),  getservby‐
       name(),	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(3P)
[top]

List of man pages available for RedHat

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