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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
     #include <netdb.h>

     extern int	h_errno;

     struct hostent *
     gethostbyname(const char *name);

     struct hostent *
     gethostent(void);

     void
     sethostent(int stayopen);

     void
     endhostent(void);

     void
     herror(const char *string);

     const char	*
     hstrerror(int err);

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

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

     struct hostent *
     gethostbyaddr(const void *addr, socklen_t len, int	af);

DESCRIPTION
     The gethostbyname(), gethostbyname2(), and	gethostbyaddr()	functions each
     return a pointer to an object with	the following structure	describing an
     Internet host referenced by name or addr, respectively.  This structure
     contains either information obtained from a name server, broken-out
     fields from a line	in /etc/hosts, or database entries supplied by the
     yp(8) system.  resolv.conf(5) describes how the particular	database is
     chosen.

	   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 returned addresses */
	   };
	   #define h_addr  h_addr_list[0]  /* address, for backward compat */

     The members of this structure are:

     h_name	  Official name	of the host.

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

     h_addrtype	  The type of address being returned.

     h_length	  The length, in bytes,	of the address.

     h_addr_list  A NULL-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-
		  patibility.

     The function gethostbyname() will search for the named host in the	cur-
     rent domain and its parents using the search lookup semantics detailed in
     resolv.conf(5) and	hostname(7).

     gethostbyname2() is similar to gethostbyname() except that	it supports an
     af	of AF_INET6 in addition	to AF_INET.

     The gethostbyaddr() function will search for the specified	address	of
     length len	in the address family af.  The only address family supported
     is	AF_INET.

     The sethostent(), gethostent(), and endhostent() functions	are deprecated
     and no longer have	any effect.  They could	be used	in the past for
     queries over a persistent TCP connection or to iterate entries in the
     hosts(5) file.

     The herror() function prints an error message describing the failure.  If
     its argument string is not	NULL, it is prepended to the message string
     and separated from	it by a	colon (`:') and	a space.  The error message is
     printed with a trailing newline.  The contents of the error message is
     the same as that returned by hstrerror() with argument h_errno.

ENVIRONMENT
     RES_OPTIONS  A list of options to override	the resolver's internal	de-
		  faults.  See resolv.conf(5) for more information.

FILES
     /etc/hosts
     /etc/resolv.conf

DIAGNOSTICS
     Error return status from gethostbyname(), gethostbyname2(), 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 unknown host.

     The variable 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 lo-
		     cal 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 ad-
		     dress; this is not	a temporary error.  This means that
		     the name is known to the name server but there is no ad-
		     dress 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 regis-
		     tered for this domain.

     NETDB_INTERNAL  An	internal error occurred.  This may occur when an ad-
		     dress family other	than AF_INET or	AF_INET6 is specified
		     or	when a resource	is unable to be	allocated.  It is al-
		     ways set by gethostent().

     NETDB_SUCCESS   The function completed successfully.

SEE ALSO
     getaddrinfo(3), getnameinfo(3), res_init(3), hosts(5), resolv.conf(5),
     hostname(7)

HISTORY
     The endhostent(), gethostbyaddr(),	gethostbyname(), gethostent(), and
     sethostent() functions appeared in	4.1cBSD.  The function herror()	was
     added in 4.3BSD-Tahoe, hstrerror()	in 4.4BSD, and gethostbyname2()	in
     OpenBSD 2.1.

BUGS
     These functions use static	data storage; if the data is needed for	future
     use, it should be copied before any subsequent calls overwrite it.

     Only the Internet address formats are currently understood.

     YP	does not support any address families other than AF_INET and uses the
     traditional database format.

FreeBSD	13.0			August 30, 2019			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | FILES | DIAGNOSTICS | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gethostbyname&sektion=3&manpath=OpenBSD+6.9>

home | help