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

FreeBSD Manual Pages

  
 
  

home | help
gethostbyname(3NSL)  Networking	Services Library Functions gethostbyname(3NSL)

NAME
       gethostbyname, gethostbyname_r, gethostbyaddr, gethostbyaddr_r, gethos-
       tent, gethostent_r, sethostent, endhostent - get	network	host entry

SYNOPSIS
       cc [ flag ... ] file ...	-lnsl [	library	... ]
       #include	<netdb.h>

       struct hostent *gethostbyname(const char	*name);

       struct hostent *gethostbyname_r(const char *name, struct	 hostent  *re-
       sult, char *buffer, intbuflen, int *h_errnop);

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

       struct hostent *gethostbyaddr_r(const char *addr, int length, int type,
       struct hostent *result, char *buffer, int buflen, int *h_errnop);

       struct hostent *gethostent(void);

       struct hostent *gethostent_r(struct hostent *result, char *buffer,  int
       buflen, int *h_errnop);

       int sethostent(int stayopen);

       int endhostent(void);

DESCRIPTION
       These  functions	are used to obtain entries describing hosts.  An entry
       may come	from any of the	sources	for hosts specified in	the  /etc/nss-
       witch.conf  file.  See  nsswitch.conf(4).  Please  take note that these
       functions have been superseded by  the  newer  functions,  getipnodeby-
       name(3SOCKET),  getipnodebyaddr(3SOCKET), and getaddrinfo(3SOCKET). The
       newer functions provide greater portability to applications when	multi-
       threading  is  done or technologies such	as IPv6	are used. For example,
       the functions described below cannot be used with applications targeted
       to work with IPv6.

       gethostbyname()	searches  for information for a	host with the hostname
       specified by the	character-string parameter name.

       gethostbyaddr() searches	for information	for a host with	a  given  host
       address.	 The parameter type specifies the family of the	address.  This
       should be one of	the address families defined  in  <sys/socket.h>.  See
       the  NOTES  section  below  for more information. Also see the EXAMPLES
       section below on	how to convert a ``.'' separated Internet  IP  address
       notation	 into  the  addr  parameter.  The  parameter len specifies the
       length of the buffer indicated by  addr.

       All addresses are returned in network order.  In	order to interpret the
       addresses, byteorder(3SOCKET) must be used for byte order conversion.

       The  functions sethostent(), gethostent(), and endhostent() are used to
       enumerate host entries from the database.

       sethostent() sets (or resets) the enumeration to	the beginning  of  the
       set  of	host entries.  This function should be called before the first
       call to gethostent().  Calls  to	 gethostbyname()  and  gethostbyaddr()
       leave  the  enumeration	position  in  an indeterminate state.	If the
       stayopen	flag is	non-zero, the system may keep allocated	resources such
       as open file descriptors	until a	subsequent call	to endhostent().

       Successive  calls  to  gethostent() return either successive entries or
       NULL, indicating	the end	of the enumeration.

       endhostent() may	be called to indicate that the caller expects to do no
       further	host  entry retrieval operations; the system may then  deallo-
       cate resources it was using.  It	is still allowed,  but	possibly  less
       efficient,  for the process to call more	host retrieval functions after
       calling endhostent().

   Reentrant Interfaces
       The functions gethostbyname(), gethostbyaddr(),	and  gethostent()  use
       static  storage that is reused in each call, making these functions un-
       safe for	use in multi-threaded applications.

       The functions gethostbyname_r(),	gethostbyaddr_r(), and	gethostent_r()
       provide reentrant interfaces for	these operations.

       Each  reentrant	interface performs the same operation as its non-reen-
       trant counterpart, named	by removing the	 ``_r''	suffix.	 The reentrant
       interfaces,  however,  use  buffers supplied by the caller to store re-
       turned results, and  are	safe  for  use	in  both  single-threaded  and
       multi-threaded applications.

       Each reentrant interface	takes the same parameters as its non-reentrant
       counterpart, as well as the following additional	parameters.   The  pa-
       rameter	result	must  be a pointer to a	struct hostent structure allo-
       cated by	the caller.  On	successful completion,	the  function  returns
       the  host  entry	 in  this  structure.  The  parameter buffer must be a
       pointer to a buffer supplied by the caller.  This  buffer  is  used  as
       storage	space  for  the	host data.  All	of the pointers	within the re-
       turned struct hostent result point to data stored within	 this  buffer.
       See  RETURN  VALUES. The	buffer must be large enough to hold all	of the
       data associated with the	host entry. The	parameter  buflen should  give
       the  size  in  bytes  of	 the buffer indicated by buffer. The parameter
       h_errnop	should be a pointer to an integer.  An	integer	 error	status
       value is	stored there on	certain	error conditions. See ERRORS.

       For enumeration in multi-threaded applications, the position within the
       enumeration is a	process-wide property shared by	all  threads.  sethos-
       tent()  may be used in a	multi-threaded application but resets the enu-
       meration	position for all  threads.   If	 multiple  threads  interleave
       calls to	gethostent_r(),	the threads will enumerate disjoint subsets of
       the host	database.

       Like their non-reentrant	counterparts, gethostbyname_r()	 and  gethost-
       byaddr_r() leave	the enumeration	position in an indeterminate state.

RETURN VALUES
       Host entries are	represented 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 */
       };

       See the EXAMPLES	section	below for information about how	to retrieve  a
       ``.''  separated	 Internet IP address string from the h_addr_list field
       of struct hostent.

       The functions gethostbyname(), gethostbyname_r(), gethostbyaddr(),  and
       gethostbyaddr_r()  each	return	a  pointer to a	struct hostent if they
       successfully locate the requested entry;	otherwise they return NULL.

       The functions gethostent() and gethostent_r() each return a pointer  to
       a  struct  hostent  if  they successfully enumerate an entry; otherwise
       they return NULL, indicating the	end of the enumeration.

       The functions gethostbyname(), gethostbyaddr(),	and  gethostent()  use
       static  storage,	 so  returned  data must be copied before a subsequent
       call to any of these functions if the data is to	be saved.

       When the	pointer	returned by the	reentrant functions gethostbyname_r(),
       gethostbyaddr_r(),  and	gethostent_r() is not NULL, it is always equal
       to the result pointer that was supplied by the caller.

       The functions sethostent() and endhostent() return 0 on success.

ERRORS
       The  reentrant  functions   gethostbyname_r(),  gethostbyaddr_r(),  and
       gethostent_r()  will  return NULL and set errno to ERANGE if the	length
       of the buffer supplied by caller	is not large enough to store  the  re-
       sult.  See Intro(2) for the proper usage	and interpretation of errno in
       multithreaded applications.

       The reentrant functions gethostbyname_r() and gethostbyaddr_r() set the
       integer pointed to by h_errnop to one of	these values in	case of	error.

       On  failures,  the non-reentrant	functions gethostbyname() and gethost-
       byaddr()	set a global integer h_errno to	indicate one  of  these	 error
       codes  (defined	in <netdb.h>): HOST_NOT_FOUND, TRY_AGAIN, NO_RECOVERY,
       NO_DATA,	and NO_ADDRESS.

       Note however that if a resolver is provided with	a  malformed  address,
       or  if any other	error occurs before  gethostbyname() is	resolved, then
       gethostbyname() returns an internal error with a	value of  -1.

       gethostbyname() will set	h_errno	to NETDB_INTERNAL when	it  returns  a
       NULL value.

EXAMPLES
       Example 1: Using	gethostbyname()

       Here  is	 a  sample  program that gets the canonical name, aliases, and
       ``.'' separated Internet	IP addresses for a given  ``.''	 separated  IP
       address:

       #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)
       {
	    ulong_t addr;
	    struct hostent *hp;
	    char **p;
	    if (argc !=	2) {
		(void) printf("usage: %s IP-address\n",	argv[0]);
		exit (1);
	    }
	    if ((int)(addr = inet_addr(argv[1])) == -1)	{
		(void) printf("IP-address must be of the form a.b.c.d\n");
		exit (2);
	    }
	    hp = gethostbyaddr((char *)&addr, sizeof (addr), AF_INET);
	    if (hp == NULL) {
		(void) printf("host information	for %s not found\n", argv[1]);
		exit (3);
	    }
	    for	(p = hp->h_addr_list; *p != 0; p++) {
		struct in_addr in;
		char **q;
		(void) memcpy(&in.s_addr, *p, sizeof (in.s_addr));
		   (void) printf("%s\t%s", inet_ntoa(in), hp->h_name);
		for (q = hp->h_aliases;	*q != 0; q++)
		    (void) printf(" %s", *q);
		(void) putchar('\n');
	    }
	    exit (0);
       }

       Note  that  the above sample program is unsafe for use in  multithread-
       eded applications.

FILES
       /etc/hosts

       /etc/netconfig

       /etc/nsswitch.conf

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |See "Reentrant  Interfaces"  |
       |			     |in DESCRIPTION.		   |
       +-----------------------------+-----------------------------+

SEE ALSO
       Intro(2),  Intro(3),  byteorder(3SOCKET),  inet(3SOCKET), netdir(3NSL),
       hosts(4), netconfig(4), nsswitch.conf(4), attributes(5),	netdb(3HEAD)

WARNINGS
       The  reentrant  interfaces  gethostbyname_r(),  gethostbyaddr_r(),  and
       gethostent_r()  are  included  in  this release on an uncommitted basis
       only, and are subject to	change or removal in future minor releases.

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

       In order	to ensure that they all	return consistent results,  gethostby-
       name(),	gethostbyname_r(),  and	 netdir_getbyname() are	implemented in
       terms of	the same internal library function. This function obtains  the
       system-wide  source  lookup  policy based on the	inet family entries in
       netconfig(4) and	the hosts: entry in nsswitch.conf(4). Similarly, geth-
       ostbyaddr(),  gethostbyaddr_r(),	and netdir_getbyaddr() are implemented
       in terms	of the same internal library function. If the inet family  en-
       tries  in  netconfig(4)	have a ``-'' in	the last column	for nametoaddr
       libraries, then the entry for hosts in nsswitch.conf will be used; oth-
       erwise  the  nametoaddr libraries in that column	will be	used, and nss-
       witch.conf will not be consulted.

       There is	no analogue of gethostent() and	gethostent_r() in  the	netdir
       functions,  so these enumeration	functions go straight to the hosts en-
       try in nsswitch.conf. Thus enumeration may return results from  a  dif-
       ferent  source  than  that  used	by gethostbyname(), gethostbyname_r(),
       gethostbyaddr(),	and gethostbyaddr_r().

       All the functions that return a	struct hostent must always return  the
       canonical  name	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 there	is more	than one alias and more	than one address  in  hostent,
       no pairing is implied between them.

       The  system will	strive to put the addresses on the same	subnet as that
       of the caller first.

       When compiling multi-threaded applications,  see	  Intro(3),  Notes  On
       Multithread  Applications,  for information about the use of the	_REEN-
       TRANT flag.

       Use of the enumeration interfaces gethostent()  and  gethostent_r()  is
       discouraged; enumeration	may not	be supported for all database sources.
       The semantics of	enumeration are	discussed further in nsswitch.conf(4).

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

       The  form for an	address	of type	AF_INET	is a struct in_addr defined in
       <netinet/in.h>. The functions described in  inet(3SOCKET),  and	illus-
       trated  in  the EXAMPLES	section	above, are helpful in constructing and
       manipulating addresses in this form.

SunOS 5.9			  22 Jan 2002		   gethostbyname(3NSL)

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

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

home | help