2.11BSD#431 - /usr/man/cat3/gethostbyname.0

GETHOSTBYNAME(3)    UNIX Programmer's Manual	 GETHOSTBYNAME(3)


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

SYNOPSIS
     #include <netdb.h>

     extern int h_errno;

     struct hostent *gethostbyname(name)
     char *name;

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

     struct hostent *gethostent()

     sethostent(stayopen)
     int stayopen;

     endhostent()

     herror(string)
     char *string;

DESCRIPTION
     Gethostbyname and gethostbyaddr each return a pointer to an
     object with the following structure describing an internet
     host referenced by name or by address, respectively.  This
     structure contains either the information obtained from the
     name server, named(8), 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;	currently
		  always AF_INET.


Printed 11/26/99	October 30, 1996			1


GETHOSTBYNAME(3)    UNIX Programmer's Manual	 GETHOSTBYNAME(3)


     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 compatiblity.

     When using the nameserver, gethostbyname will search for the
     named  host in the current domain and its parents unless the
     name ends in 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  input  name.   See hostname(7) for the
     domain search procedure and the alias file format.

     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 after each call to gethost-
     byname or gethostbyaddr.  Otherwise, queries  are	performed
     using UDP datagrams.

     Endhostent closes the TCP connection.

DIAGNOSTICS
     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  tem-
     porary  failure  or an invalid or unknown 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:

	  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  authorita-
			  tive	server.   A  retry  at some later
			  time may succeed.

	  NO_RECOVERY	  Some	unexpected  server  failure   was
			  encountered.	This is a non-recoverable
			  error.

	  NO_DATA	  The requested name is  valid	but  does
			  not  have  an IP address; this is not a


Printed 11/26/99	October 30, 1996			2


GETHOSTBYNAME(3)    UNIX Programmer's Manual	 GETHOSTBYNAME(3)


			  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.

FILES
     /etc/hosts

SEE ALSO
     resolver(3), hosts(5), hostname(7), named(8)

CAVEAT
     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 necessary.

     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.

BUGS
     All information is contained in a static area so it must  be
     copied if it is to be saved.  Only the Internet address for-
     mat is currently understood.


Printed 11/26/99	October 30, 1996			3