freeaddrinfo man page on HP-UX

Printed from

getaddrinfo(3N)						       getaddrinfo(3N)

       getaddrinfo(),  getnameinfo(),  freeaddrinfo(),	gai_strerror()	-  get
       hostname and address entry

       Hostname-to-address translation is done in a protocol-independent fash‐
       ion using the function.

       The  function  returns  an  integer.   The input arguments hostname and
       servname are pointers to null-terminated strings or NULL.  One or  both
       of these two arguments must be a non-NULL pointer.

       In  the	normal	client scenario, both hostname and servname are speci‐
       fied.  The non-NULL hostname string can	be  either  a  hostname	 or  a
       numeric	host  address string (a dotted-decimal IPv4 address or a hexa‐
       decimal IPv6 address).  The non-NULL servname string can	 be  either  a
       service	name  or  a  decimal port number.  However, in the server sce‐
       nario, only servname is specified.

       The third input argument is a pointer to the structure of type  defined
       as follows in

       The members of this structure are:

	      The  flag	 used  to set the socket address structure for an IPv4
				or an IPv6 address.

				If the bit is then the returned socket address
				structure from the function will be used as an
				argument to the function call.	When this  bit
				is  set and the hostname argument to the func‐
				tion is a NULL pointer, then  the  IP  address
				portion	 of  the socket address structure will
				be set to for an IPv4 address or for  an  IPv6

				If  the	 is  not set, then the returned socket
				address structure will be used as an  argument
				to  the	 or  functions.	  In this case, if the
				hostname argument is a NULL pointer, then  the
				IP  address portion of the socket address will
				be set to address.

				If  the	 bit  is  set,	then  upon  successful
				return,	 will  return  the member of the first
				structure, which is a NULL  terminated	string
				containing the canonical name of the specified

				If an flag  is	specified  with	 an  value  of
				returns	 IPv4-mapped  IPv6  addresses  when it
				does not find  any  matching  IPv6  addresses.
				ignores an flag if the is not equal to

				If  an	flag is used with an flag, returns all
				the matching IPv6 and IPv4 addresses.  ignores
				an flag without an flag.

				If  an	flag is specified, then IPv4 addresses
				are returned only if an IPv4 address  is  con‐
				figured	  in   the   local  system,  and  IPv6
				addresses are returned only if an IPv6 address
				is  configured	in  the local system.  In this
				case, the loopback address is  not  considered
				as a valid configured address.

	      The  protocol  family the caller will accept.  If this member is
	      set to
				then the caller will accept any protocol  fam‐
				ily.   If  the	caller handles only IPv4 stack
				and not IPv6 stack, then the must be set to

	      The protocol the caller supports.	 If
				is set to then the caller will accept any pro‐

	      The socket type the caller supports.  If
				is  set	 to  then  the	caller will accept any
				socket type.  However, if the  caller  handles
				only TCP and not UDP, then the must be set to

	      The length, in bytes, of the IPv4 or IPv6 address.

	      The canonical name of the host.

	      The binary address of the host.

	      The next		structure in the linked list.

       The above argument, is optional.	 If the caller wants to provide infor‐
       mation such as the type of socket and protocol family that  the	caller
       supports,  the  caller can specify them using the structure.  When this
       information is passed to all the fields other than and must be  set  to
       or a NULL pointer.

       When  returns  successfully, holds a pointer to a linked list of one or
       more structures.	 The caller can process each structure in this list by
       following the pointer, until a NULL pointer is encountered.  In each of
       the returned structures, the three members and are used as arguments to
       the  function  call.   The  member points to a socket address structure
       whose length is specified by the member.

   Destination Address Selection
       supports the Destination Address Selection  algorithm  defined  in  RFC
       3484.   This  feature can be enabled by setting the ndd tunable, to See
       ndd(1M) for information on setting a network tunable  parameter.	  Upon
       enabling	 the feature, sorts the linked list of structures based on the
       Destination Address Selection rules defined in RFC 3484.	 This  sorting
       process	ensures	 that the best possible addresses are at the beginning
       of the list.

   Return Value for getaddrinfo()
       The return value from the function is upon success, or a nonzero	 error

       The following are the nonzero error codes given by These are defined in

	      Address family for     hostname not supported.

	      Temporary failure in name resolution.

	      Invalid value for

	      Non-recoverable failure in name resolution.

	      Argument buffer overflow

	      not supported.

	      Memory allocation failure.

	      No address associated with

	      No		     hostname  nor  servname  provided, or not

	      The		     servname is not supported for

	      not supported.

	      System error returned in errno.

       All the information returned by is dynamically  allocated:  the	struc‐
       tures,  the  socket address structures, and canonical host name strings
       pointed to by the structures.  To return this information to  the  sys‐
       tem, the function is called:

       The  structure  pointed	to  by	the  argument is freed, along with any
       dynamic storage	pointed	 to  by	 the  structure.   This	 operation  is
       repeated until a NULL pointer is encountered.

       To  aid	applications  in  printing  error  messages based on the codes
       returned by the function is defined.

       The argument is one of the values defined earlier, and the return value
       points to a string describing the error.	 If the argument is not one of
       the values, the function still returns a pointer to a string whose con‐
       tents indicate an unknown error.

       The  function is used to look up a hostname and service name, given the
       binary address and port.	 The function is defined as follows:

       This function looks up an IP address and port number  provided  by  the
       caller  in  the	DNS  and  system-specific  database,  and returns text
       strings for both in buffers provided by the caller.

       The function indicates successful completion by a zero return value;  a
       non-zero return value indicates failure.

       If  the	address is IPv6 unspecified address ( :: ), then the following
       actions occur:

	      returns if the flag is set.

	      returns success, if the flag is not set.

       The host argument contains the numeric form of  the  IPv6  address  and
       does not perform a lookup for the IPv6 address.

       The first argument, points to either a structure (for IPv4) or a struc‐
       ture (for IPv6) that holds the IP address and port number.   The	 argu‐
       ment gives the length of the or structure.

       The function returns the hostname associated with the IP address in the
       buffer pointed to by the argument.  The caller  provides	 the  size  of
       this  buffer  via  the  argument.  The service name associated with the
       port number is returned in the buffer pointed to by  and	 the  argument
       gives  the  length  of this buffer.  The caller specifies not to return
       either string by providing zero values for the  or  arguments.	Other‐
       wise, the caller must provide buffers large enough to hold the hostname
       and the service name, including the terminating null characters.

       Unfortunately, most systems do not provide constants that  specify  the
       maximum size of either a fully-qualified domain name or a service name.
       Therefore, to aid the application in allocating buffers for  these  two
       returned strings, the following constants are defined in

       In  recent versions of DNS/BIND, the first value is actually defined as
       the constant in the header file (Older versions	of  BIND  define  this
       constant to be 256.)

       The  final  argument to the function is a flag that changes the default
       actions of this function.  By default, the fully-qualified domain  name
       (FQDN)  for the host is looked up in the DNS and returned.  If the flag
       bit is only the hostname portion of the	FQDN  is  returned  for	 local

       If  the flag bit is or if the host's name cannot be located in the DNS,
       the numeric form of the host's address is returned instead of its  name
       (by calling instead of

       If  the	flag  bit is an error is returned if the host's name cannot be
       located in the DNS.

       If the flag  bit is the numeric form of the service address (port  num‐
       ber)  is	 returned  instead of its name.	 The two flags are required to
       support the flag that many commands provide.

       A fifth flag bit, specifies that the service is a datagram service, and
       causes  to  be  called  with  a second argument of "udp" instead of its
       default of "tcp".  This action is required for the few ports  (512-514)
       that have different services for UDP and TCP.

       These flags are defined in along with the flags already defined for

   Name Service Switch-Based Operation
       The  and	 library  routines  internally call the name service switch to
       access the database lookup policy configured  in	 the  file  (see  nss‐
       witch.conf(4))  for  the	 name/address  resolution, and database lookup
       policy for the service/port resolution.	The lookup policy defines  the
       order  and criteria of the supported name services that can be used for
       resolution.  If addresses are not gathered  after  contacting  all  the
       directives,  and	 if the caller has set the to or set to with an of use
       the directive in the file to resolve  the  hostname/address.   In  this
       case,  when  the directive hostname/address resolution fails, the error
       number returned will be that of the error  returned  by	the  directive
       lookup.	 The operations of these name services, Domain Name Server and
       Nonserver Modes, are described below: If the local system is configured
       to  use	the  BIND  name	 server,  (see	named(1M) and resolver(4)) for
       name/address resolution, the function retrieves	the  host  information
       from the name server.  The host names are matched irrespective of upper
       or lower case alphabets.	 For example, the domain names and  match  the
       same entry in the name server database.	When the directive is used for
       hostname/address resolution, a delay may be observed due	 to  an	 addi‐
       tional lookup using the sources specified for the directive.

   Nonserver Operation
       During  a  name/address	resolution,  if the database is configured for
       files resolution, and use the file for resolution.  Similarly,  if  the
       database is configured for files resolution, the file is used for reso‐
       lution.	If the file is used for name/address  resolution,  the	method
       used by the functions and to search an address is listed below:

	      Sequentially searches the
				  file	until  an  address  matching  the  src
				  parameter is found or until the end of  file
				  is encountered.

	      Sequentially searches the
				  file	until a host name (official name or an
				  alias name) matching the name	 parameter  is
				  found	 or  until  the end of file is encoun‐
				  tered. The host names are matched  irrespec‐
				  tive of upper or lower case alphabets.

   Obsolescent Interfaces
       The  following interfaces are included to support existing applications
       and may be removed in future releases.

       New applications must use the APIs and for name/address resolution.

   Obsolescent Directive
       The directive, which is used by the and APIs, may not be	 supported  in
       future  HP-UX  releases.	  In  order to minimize the impact to applica‐
       tions, HP recommends that you have the same configuration for  the  and
       the directives.

       was developed by HP.

       SEE ALSO
	      ndd(1M), gethostent(3N), resolver(3N), nsswitch.conf(4).


List of man pages available for HP-UX

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]
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