Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
getipnodebyname(3SOCKET)   Sockets Library Functions  getipnodebyname(3SOCKET)

NAME
       getipnodebyname,	getipnodebyaddr, freehostent - get IP node entry

SYNOPSIS
       cc [flag	...] file ... -lsocket -lnsl [library ...]

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

       struct  hostent	*getipnodebyname(const	char *name, int	af, int	flags,
       int *error_num);

       struct hostent *getipnodebyaddr(const void *src,	size_t	len,  int  af,
       int *error_num);

       void freehostent(struct hostent *ptr);

DESCRIPTION
       The  getipnodebyname()  function	searches the ipnodes database from the
       beginning and finds the first entry for which the hostname specified by
       name  matches  the h_name member.  It takes an af  argument that	speci-
       fies the	address	family,	which can be either AF_INET for	IPv4 addresses
       or AF_INET6 for IPv6 addresses.	The flags argument determines what re-
       sults will be returned based on the value of flags.  If the flags   ar-
       gument  is set to 0 (zero), then	the default operation of this function
       is specified as follows:

	  o  If	the af argument	is AF_INET, then a query is made for an	  IPv4
	     address.	If  successful,	 IPv4  addresses  are returned and the
	     h_length member of	the hostent structure will  be	4.  Otherwise,
	     the function returns a null pointer.

	  o  If	 the af	argument is AF_INET6, then a query is made for an IPv6
	     address.  If successful, IPv6  addresses  are  returned  and  the
	     h_length  member  of the hostent structure	will be	16. Otherwise,
	     the function returns a null pointer.

       The flags argument changes the default actions of  the  function.   You
       can set the flags argument by logically ORing any of the	following val-
       ues together:

	  o  AI_V4MAPPED

	  o  AI_ALL

	  o  AI_ADDRCONFIG

       Note that a special flags value of AI_DEFAULT, as defined below,	should
       handle  most applications.  In other words, porting simple applications
       to use IPv6 replaces the	call

       hptr = gethostbyname(name);

       with

       hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);

       A flags of 0 implies a strict interpretation of the af argument:

	  o  If	flags is 0 and af is AF_INET, then the caller wants only  IPv4
	     addresses.	  A  query  is made for	A records.  If successful, the
	     IPv4 addresses are	returned and the h_length member of  the  hos-
	     tent  structure will be 4;	otherwise, the function	returns	a null
	     pointer.

	  o  If	flags is 0, and	if af is AF_INET6, then	the caller wants  only
	     IPv6  addresses.	A query	is made	for AAAA records.  If success-
	     ful, the  IPv6 addresses are returned and the h_length member  of
	     the hostent structure will	be 16; otherwise, the function returns
	     a null pointer.

       Other constants can be logically-ORed into the flags argument, to  mod-
       ify the behavior	of the function.

	  o  If	 the  AI_V4MAPPED  flag	 is  specified	along  with  an	 af of
	     AF_INET6, then the	caller can accept IPv4-mapped IPv6  addresses.
	     That is, if no AAAA records are found, then a query is made for A
	     records, and any  found are  returned  as	IPv4-mapped  IPv6  ad-
	     dresses (h_length is 16). The  AI_V4MAPPED	flag is	ignored	unless
	     af	equals AF_INET6.

	  o  The AI_ALL	flag is	used in	conjunction with the AI_V4MAPPED flag,
	     and  is  only  used with the IPv6 address family.	When AI_ALL is
	     logically ORed with AI_V4MAPPED flag then the  caller  wants  all
	     addresses:	 IPv6 and IPv4-mapped IPv6.  A query is	first made for
	     AAAA records and if successful, the IPv6 addresses	are  returned.
	     Another  query  is	then made for A	records, and any found are re-
	     turned as	IPv4-mapped IPv6 addresses. h_length is	16.
	      Only if both queries  fail  does	the  function  return  a  null
	     pointer.  This flag is ignored unless af equals AF_INET6.

	  o  The  AI_ADDRCONFIG	 flag  specifies that a	query for AAAA records
	     should occur only if the node has at least	one  IPv6  source  ad-
	     dress  configured.	A query	for A records should occur only	if the
	     node has at least one IPv4	source address configured.  For	 exam-
	     ple, if the node has no IPv6 source addresses configured,	and af
	     equals AF_INET6, and the node name	being looked up	has both  AAAA
	     and A records, then:

	     1.	If  only  AI_ADDRCONFIG	 is  specified,	the function returns a
		null pointer.

	     2.	If AI_ADDRCONFIG or AI_V4MAPPED	is specified,  the  A  records
		are returned as	IPv4-mapped IPv6 addresses.

       The special flags value of AI_DEFAULT is	defined	as

       #define	AI_DEFAULT  (AI_V4MAPPED | AI_ADDRCONFIG)

       The  getipnodebyname() function must allow the name  argument to	be ei-
       ther a node name	or a literal address string, that is, a	dotted-decimal
       IPv4 address or an IPv6 hex address. This saves	applications from hav-
       ing to call inet_pton(3SOCKET) to handle	literal	address	strings.

       Four scenarios arise based on the type of literal  address  string  and
       the  value of the af argument.  The two simple cases are	when name is a
       dotted-decimal IPv4 address and af equals AF_INET, or when name	is  an
       IPv6  hex  address and af equals	AF_INET6.  The members of the returned
       hostent structure are:

       h_name
	     Points to a copy of the name argument

       h_aliases
	     Is	a null pointer.

       h_addrtype
	     Is	a copy of the af argument.

       h_length
	     Is	either 4 (for AF_INET) or 16 (for AF_INET6).

       h_addr_list[0]
	     Is	a pointer to the 4-byte	or 16-byte binary address.

       h_addr_list[1]
	     Is	a null pointer

PARAMETERS
       af    Address family

       flags Various flags

       name  Name of host

       error_num
	     Error storage

       src   Address for lookup

       len   Length of address

       ptr   Pointer to	hostent	structure

RETURN VALUES
       Upon successful completion, getipnodebyname() and getipnodebyaddr() re-
       turn a hostent structure. Otherwise they	return NULL.

       The hostent structure does not change from its existing definition when
       used with gethostbyname(3NSL). For example,  host  entries  are	repre-
       sented  by the struct hostent structure defined in <netdb.h>:

       struct hostent {
		      char   *h_name;	      /* canonical name	of host	*/
		      char   **h_aliases;     /* alias list */
		      int    h_addrtype;      /* host address type */
		      int    h_length;	      /* length	of address */
		      char   **h_addr_list;   /* list of addresses */
		 };

       An error	occurs when name is an IPv6 hex	address	and af equals AF_INET.
       The function's return value is a	 null  pointer	and  error_num	equals
       HOST_NOT_FOUND.

       The  getipnodebyaddr()  function	has the	same arguments as the existing
       gethostbyaddr(3NSL) function, but adds an error number. As with getipn-
       odebyname(),  getipnodebyaddr() is thread safe.	The error_num value is
       returned	to the caller with the	appropriate   error  code  to  support
       thread safe error code returns.	The following  error conditions	can be
       returned	for error_num:

       HOST_NOT_FOUND
	     Host is unknown.

       NO_DATA
	     No	address	is available for the name specified in the server  re-
	     quest.   This  error  is  not a soft error.  Another type of name
	     server request might be successful.

       NO_RECOVERY
	     An	unexpected server failure occurred, which is a	nonrecoverable
	     error.

       TRY_AGAIN
	     This  error  is a soft error that indicates that the local	server
	     did not	      receive a	response from an authoritative server.
	     A retry at	some later time	might be successful.

       One  possible  source  of confusion is the handling of IPv4-mapped IPv6
       addresses and IPv4-compatible IPv6 addresses, but the  following	 logic
       should apply:

       1. If af	is AF_INET6, and if len	equals 16, and if the IPv6 address  is
	  an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, then
	  skip over the	first 12 bytes of the IPv6 address, set	af to AF_INET,
	  and set len to 4.

       2. If af	is AF_INET, lookup the name for	the given IPv4 address.

       3. If af	is AF_INET6, lookup the	name for the given IPv6	address.

       4. If the function is returning success,	then the single	 address  that
	  is returned in the hostent structure is a copy of the	first argument
	  to the function with the same	address	family that was	passed	as  an
	  argument to this function.

       All four	steps listed are performed in order.

       This  structure,	 and the information pointed to	by this	structure, are
       dynamically allocated by	getipnodebyname() and getipnodebyaddr().   The
       freehostent() function frees this memory.

EXAMPLES
       Example	1:  Getting  the  Canonical Name, Aliases, and Internet	IP Ad-
       dresses for a Given Hostname

       The following is	a  sample  program   that  retrieves   the   canonical
       name,   aliases,	and all	Internet IP addresses, both version 6 and ver-
       sion 4, for a given hostname.

	    #include <stdio.h>
	    #include <string.h>
	    #include <sys/types.h>
	    #include <sys/socket.h>
	    #include <netinet/in.h>
	    #include <arpa/inet.h>
	    #include <netdb.h>

	    main(int argc, const char **argv)
	    {
	    char abuf[INET6_ADDRSTRLEN];
	    int	error_num;
	    struct hostent *hp;
	    char **p;

		if (argc != 2) {
		    (void) printf("usage: %s hostname0,	argv[0]);
		    exit (1);
		}

	    /* argv[1] can be a	pointer	to a hostname or literal IP address */
	    hp = getipnodebyname(argv[1], AF_INET6, AI_ALL | AI_ADDRCONFIG |
	       AI_V4MAPPED, &error_num);
	    if (hp == NULL) {
	       if (error_num ==	TRY_AGAIN) {
		   printf("%s: unknown host or invalid literal address "
		       "(try again later)\n", argv[1]);
	       } else {
		   printf("%s: unknown host or invalid literal address\n",
		       argv[1]);
	       }
	       exit (1);
	    }
	    for	(p = hp->h_addr_list; *p != 0; p++) {
	       struct in6_addr in6;
	       char **q;

	       bcopy(*p, (caddr_t)&in6,	hp->h_length);
	       (void) printf("%s\t%s", inet_ntop(AF_INET6, (void *)&in6,
		   abuf, sizeof(abuf)),	hp->h_name);
	       for (q =	hp->h_aliases; *q != 0;	q++)
	       (void) printf(" %s", *q);
	       (void) putchar('\n');
	    }
	    freehostent(hp);
	    exit (0);
	    }

FILES
       /etc/inet/hosts

       /etc/inet/ipnodes

       /etc/netconfig

       /etc/nsswitch.conf

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsl, SUNWarc (32-bit)	   |
       +-----------------------------+-----------------------------+
       |			     |SUNWcslx (64-bit)		   |
       +-----------------------------+-----------------------------+
       |MT Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       getaddrinfo(3SOCKET),	   gethostbyname(3NSL),	       htonl(3SOCKET),
       inet(3SOCKET),  netdb(3HEAD),  hosts(4),	 ipnodes(4), nsswitch.conf(4),
       attributes(5)

NOTES
       Programs	that use the interfaces	described  in  this  manual page  can-
       not   be	linked statically since	the implementations of these functions
       employ dynamic  loading	and  linking of	shared objects at run time.

       No enumeration functions	are provided for IPv6.	Existing   enumeration
       functions,  for	example, sethostent(3NSL) does not work	in combination
       with getipnodebyname() and getipnodebyaddr().

       All the functions that return a struct hostent must always return   the
       canonical in the	h_name field.  This name,  by definition, is the well-
       known and official hostname shared  between all	aliases	 and  all  ad-
       dresses.	  The  underlying source that satisfies	the request determines
       the mapping of the input	 name or address into the set of names and ad-
       dresses in hostent.  Different sources might do that in different ways.
       If more than one	alias and more than one	address	in hostent  exist,  no
       pairing is implied between  them.

       The  current implementations of these functions	only  return or	accept
       addresses  for the Internet address family (type	     AF_INET)  or  the
       Internet	address	family Version 6 (type AF_INET6).

       The  form  for  an address of type AF_INET is a struct  in_addr defined
       in  <netinet/in.h>. The form for	an address  of	type   AF_INET6	 is  a
       struct  in6_addr,  defined  also	in <netinet/in.h>. The	functions  de-
       scribed	in inet_ntop(3SOCKET) and inet_pton(3SOCKET)  that are	illus-
       trated in the EXAMPLES section are helpful in  constructing and manipu-
       lating addresses	in either of these forms.

SunOS 5.9			  22 Jan 2002	      getipnodebyname(3SOCKET)

NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | RETURN VALUES | EXAMPLES | FILES | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getipnodebyname&sektion=3socket&manpath=SunOS+5.9>

home | help