freeaddrinfo man page on SunOS

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

freeaddrinfo(3XNEX/Open Networking Services Library Functiofreeaddrinfo(3XNET)

NAME
       freeaddrinfo, getaddrinfo - get address information

SYNOPSIS
       cc [ flag ... ] file ... -lxnet [ library ... ]
       #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  frees  one  or  more addrinfo structures
       returned by getaddrinfo(), along with any additional storage associated
       with  those  structures.	 If the ai_next member of the structure is not
       null, the entire list of structures is freed. The freeaddrinfo()	 func‐
       tion  supports  the  freeing  of arbitrary sublists of an addrinfo list
       originally returned by getaddrinfo().

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

       The  nodename and servname arguments are either null pointers or point‐
       ers to null-terminated strings. One or both of these two arguments  are
       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 attempts
       to resolve the name in  all  supported  families	 and,  in  absence  of
       errors, one or more results are 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(3XNET)
       are valid.

       If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6
       text forms described in inet_ntop(3XNET) 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 returns network-level addresses for the
       specified nodename. If servname is not null, it	is  a  null-terminated
       character  string identifying the requested service. This string 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 can 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 is set to 0 or a
       null pointer. A value of AF_UNSPEC for ai_family means that the	caller
       accepts	any  address  family.  A value of 0 for ai_socktype means that
       the caller accepts any socket type. A value of 0 for ai_protocol	 means
       that  the  caller accepts any protocol. If hints is a null pointer, the
       behavior is as if it referred to a structure containing the value 0 for
       the  ai_flags,  ai_socktype, and ai_protocol members, and AF_UNSPEC for
       the ai_family member.

       The ai_flags member to which the hints parameter points is set to 0  or
       be  the	bitwise-inclusive  OR of one or more of the values AI_PASSIVE,
       AI_CANONNAME, AI_NUMERICHOST, and AI_NUMERICSERV.

       If the AI_PASSIVE flag is specified, the returned  address  information
       is  suitable for use in binding a socket for accepting incoming connec‐
       tions for the specified service. In this case, if the nodename argument
       is null, then 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 the AI_PASSIVE flag is not specified, the returned address
       information is suitable for a call to connect(3XNET) (for a connection-
       mode   protocol)	  or  for  a  call  to	connect(),  sendto(3XNET),  or
       sendmsg(3XNET) (for a connectionless protocol). In this	case,  if  the
       nodename	 argument  is  null, then the IP address portion of the socket
       address structure is set to the loopback address.

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

       If  the	AI_NUMERICHOST	flag  is  specified,  then a non-null nodename
       string supplied is a numeric host address string. Otherwise, an EAI_NO‐
       NAME  error is returned. This flag prevents 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	 is  a	numeric	 port string. Otherwise, an EAI_NONAME
       error is returned. This flag prevents any type of name resolution  ser‐
       vice (for example, NIS+) from being invoked.

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

       The  ai_socktype	 member	 to  which argument hints points specifies the
       socket type for the service, as defined in socket(3XNET). If a specific
       socket  type  is	 not given (for example, a value of 0) and the service
       name could be interpreted  as  valid  with  multiple  supported	socket
       types,  the implementation attempts to resolve the service name for all
       supported socket types and, in the  absence  of	errors,	 all  possible
       results	are returned. A non-zero socket type value limits the returned
       information to values with the specified socket type.

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

RETURN VALUES
       A  0  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 refers to a linked list of addrinfo structures,  each  of	 which
       specifies a socket address and information for use in creating a socket
       with which to use that socket address. The list includes at  least  one
       addrinfo	 structure.  The  ai_next  member 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 includes
       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 speci‐
       fied, for use with the bind(3XNET) function. The ai_family  ,  ai_sock‐
       type,  and  ai_protocol	members	 are  usable  as  the arguments to the
       socket() function to create a socket suitable for use with the returned
       address. The ai_addr and ai_addrlen members 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 member of the first returned addrinfo structure points  to
       a null-terminated string containing the canonical name corresponding to
       the input nodename. If  the  canonical  name  is	 not  available,  then
       ai_canonname  refers to the nodename argument or a string with the same
       contents. The contents of the ai_flags member of	 the  returned	struc‐
       tures are undefined.

       All members in socket address structures returned by getaddrinfo() that
       are not filled in through an explicit argument (for example, sin6_flow‐
       info)  are  set to 0, making it easier to compare socket address struc‐
       tures.

ERRORS
       The getaddrinfo() function will fail if:

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

       EAI_BADFLAGS    The  ai_flags  member  of the addrinfo structure 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      he name does not resolve for the	 supplied  parameters.
		       Neither	nodename  nor servname were supplied. At least
		       one of these must 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.

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.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Standard			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       connect(3XNET),	gai_strerror(3XNET),  gethostbyname(3XNET),   getname‐
       info(3XNET),  getservbyname(3XNET), inet_addr(3XNET), inet_ntop(3XNET),
       socket(3XNET), attributes(5), standards(5)

SunOS 5.10			  1 Nov 2003		   freeaddrinfo(3XNET)
[top]

List of man pages available for SunOS

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