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

FreeBSD Manual Pages


home | help
GETHOSTBYNAME(3)       FreeBSD Library Functions Manual	      GETHOSTBYNAME(3)

     gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror
     --	get network host entry

     #include <netdb.h>

     extern int	h_errno;

     struct hostent *
     gethostbyname(char	*name);

     struct hostent *
     gethostbyname2(char *name,	int af);

     struct hostent *
     gethostbyaddr(char	*addr, int len,	type);

     struct hostent *

     sethostent(int stayopen);


     herror(char *string);

     Gethostbyname(), gethostbyname2(),	and gethostbyaddr() each return	a
     pointer to	a hostent structure (see below)	describing an internet host
     referenced	by name	or by address, as the function names indicate.	This
     structure contains	either the information obtained	from the name server,
     or	broken-out fields from a line in /etc/hosts.  If the local name	server
     is	not running, these routines do a lookup	in /etc/hosts.

	   struct  hostent {
		   char	   *h_name;	   /* official 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	from name server */

	   #define h_addr  h_addr_list[0]  /* address, for backward compatibility */

     The members of this structure are:

     h_name	  Official name	of the host.

     h_aliases	  A zero-terminated array of alternate names for the host.

     h_addrtype	  The type of address being returned; usually AF_INET.

     h_length	  The length, in bytes,	of the address.

     h_addr_list  A zero-terminated array of network addresses for the host.
		  Host addresses are returned in network byte order.

     h_addr	  The first address in h_addr_list; this is for	backward com-

     When using	the nameserver,	gethostbyname()	will search for	the named host
     in	each parent domain given in the	"search" directive of resolv.conf(5)
     unless the	name contains a	dot (".").  If the name	contains no dot, and
     if	the environment	variable HOSTALIASES contains the name of an alias
     file, the alias file will first be	searched for an	alias matching the in-
     put name.	See hostname(7)	for the	domain search procedure	and the	alias
     file format.

     Gethostbyname2() is an evolution of gethostbyname() intended to allow
     lookups in	address	families other than AF_INET, for example, AF_INET6.
     Currently,	the af argument	must be	specified as AF_INET else the function
     will return NULL after having set h_errno to NETDB_INTERNAL.

     Sethostent() may be used to request the use of a connected	TCP socket for
     queries.  If the stayopen flag is non-zero, this sets the option to send
     all queries to the	name server using TCP and to retain the	connection af-
     ter each call to gethostbyname() or gethostbyaddr().  Otherwise, queries
     are performed using UDP datagrams.

     Endhostent() closes the TCP connection.

     HOSTALIASES    Name of file containing (host alias, full hostname)	pairs.

     /etc/hosts	    See	hosts(5).

     Error return status from gethostbyname() and gethostbyaddr() is indicated
     by	return of a null pointer.  The external	integer	h_errno	may then be
     checked to	see whether this is a temporary	failure	or an invalid or un-
     known host.  The routine herror() can be used to print an error message
     describing	the failure.  If its argument string is	non-NULL, it is
     printed, followed by a colon and a	space.	The error message is printed
     with a trailing newline.

     h_errno can have the following values:

	   NETDB_INTERNAL    This indicates an internal	error in the library,
			     unrelated to the network or name service.	errno
			     will be valid in this case; see perror.

	   HOST_NOT_FOUND    No	such host is known.

	   TRY_AGAIN	     This is usually a temporary error and means that
			     the local server did not receive a	response from
			     an	authoritative server.  A retry at some later
			     time may succeed.

	   NO_RECOVERY	     Some unexpected server failure was	encountered.
			     This is a non-recoverable error, as one might ex-

	   NO_DATA	     The requested name	is valid but does not have an
			     IP	address; this is not a temporary error.	 This
			     means that	the name is known to the name server
			     but there is no address associated	with this
			     name.  Another type of request to the name	server
			     using this	domain name will result	in an answer;
			     for example, a mail-forwarder may be registered
			     for this domain.

     hosts(5), hostname(7), resolver(3), resolver(5).

     Gethostent() is defined, and sethostent() and endhostent()	are redefined,
     when libc is built	to use only the	routines to lookup in /etc/hosts and
     not the name server:

	   Gethostent()	reads the next line of /etc/hosts, opening the file if

	   Sethostent()	is redefined to	open and rewind	the file.  If the
	   stayopen argument is	non-zero, the hosts data base will not be
	   closed after	each call to gethostbyname() or	gethostbyaddr().

	   Endhostent()	is redefined to	close the file.

     All information is	contained in a static area so it must be copied	if it
     is	to be saved.  Only the Internet	address	format is currently under-

4th Berkeley Distribution	 June 23, 1990	     4th Berkeley Distribution


Want to link to this manual page? Use this URL:

home | help