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

FreeBSD Manual Pages


home | help
gethostbyname(3NSL)					   gethostbyname(3NSL)

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

       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, int buflen, 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);

       These  functions	 are used to obtain entries describing hosts. An entry
       can come	from any of the	sources	for hosts specified in	the  /etc/nss-
       witch.conf file.	See nsswitch.conf(4). These functions have been	super-
       seded by	getipnodebyname(3SOCKET), getipnodebyaddr(3SOCKET), and	getad-
       drinfo(3SOCKET),	which provide greater portability to applications when
       multithreading is performed or technologies such	as IPv6	are used.  For
       example,	 the  functions	described in the following cannot be used with
       applications targeted to	work with IPv6.

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

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

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

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

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

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

       The endhostent()	function can be	called to indicate that	the caller ex-
       pects  to do no further host entry retrieval operations;	the system can
       then deallocate resources it was	using. It is still allowed, but	possi-
       bly  less  efficient, for the process to	call more host retrieval func-
       tions after calling endhostent().

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

       The gethostbyname_r(), gethostbyaddr_r(), and gethostent_r()  functions
       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  in-
       terfaces, however, use buffers supplied by the caller to	store returned
       results and the interfaces are safe for use in both single-threaded and
       multithreaded applications.

       Each reentrant interface	takes the same parameters as its non-reentrant
       counterpart, as well as the following additional	parameters. The	param-
       eter  result  must be a pointer to a struct hostent structure allocated
       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 returned	struct hostent
       result point to data stored within this buffer. See the	RETURN	VALUES
       section	for  more information. 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 the ER-
       RORS section for	more information.

       For enumeration in multithreaded	applications, the position within  the
       enumeration  is	a  process-wide	 property  shared  by all threads. The
       sethostent() function can be used in a  multithreaded  application  but
       resets  the  enumeration	 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.

       Host entries are	represented by the struct hostent structure defined in

       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 for information about how to retrieve a ``.''
       separated Internet IP address string  from  the	h_addr_list  field  of
       struct hostent.

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

       The  gethostent() and gethostent_r() functions 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  gethostbyname(),  gethostbyaddr(),	and gethostent() functions 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 sethostent()	and endhostent() functions return 0 on success.

       The reentrant functions gethostbyname_r(), gethostbyaddr_r(), and geth-
       ostent_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 result.
       See Intro(2) for	the proper usage and interpretation of errno in	multi-
       threaded	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.

       If a resolver is	provided with a	malformed address, or if any other er-
       ror occurs before gethostbyname() is resolved, then gethostbyname() re-
       turns an	internal error with a value of -1.

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

       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

       #include	<stdio.h>
       #include	<stdlib.h
       #include	<string.h>
       #include	<sys/types.h>
       #include	<sys/socket.h>
       #include	<netinet/in.h>
       #include	<arpa/inet.h>
       #include	<netdb.h>
       int main(int argc, const	char **argv)
	    in_addr_t addr;
	    struct hostent *hp;
	    char **p;
	    if (argc !=	2) {
		(void) printf("usage: %s IP-address0, argv[0]);
		exit (1);
	    if ((int)(addr = inet_addr(argv[1])) == -1)	{
		(void) printf("IP-address must be of the form a.b.c.d0);
		exit (2);
	    hp = gethostbyaddr((char *)&addr, 4, AF_INET);
	    if (hp == NULL) {
		(void) printf("host information	for %s not found0, 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%s", inet_ntoa(in), hp->h_name);
		for (q = hp->h_aliases;	*q != 0; q++)
		    (void) printf(" %s", *q);
		(void) putchar('');
	    exit (0);

       Note that the preceding sample program is  unsafe  for  use  in	multi-
       threadeded applications.




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

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |See Reentrant Interfaces in  |
       |			     |the DESCRIPTION section.	   |

       Intro(2), Intro(3), byteorder(3SOCKET), inet(3SOCKET),  netdb.h(3HEAD),
       netdir(3NSL),  hosts(4),	 netconfig(4),	nss(4),	 nsswitch.conf(4), at-

       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.

       To ensure that they all	return	consistent  results,  gethostbyname(),
       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 netcon-
       fig(4) and the hosts: entry in  nsswitch.conf(4).  Similarly,  gethost-
       byaddr(),  gethostbyaddr_r(), and netdir_getbyaddr() are	implemented in
       terms of	the same internal library function. If the inet	family entries
       in  netconfig(4)	 have  a  ``-''	 in the	last column for	nametoaddr li-
       braries,	then the entry for hosts in nsswitch.conf will be used;	 name-
       toaddr  libraries  in  that column will be used,	and nsswitch.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 can 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 attempts to put those addresses that	are on the same	subnet
       as the caller before addresses that are on different subnets.  However,
       if  address  sorting  is	disabled by setting SORT_ADDRS to FALSE	in the
       /etc/default/nss	file, the system does not put  the  local  subnet  ad-
       dresses first. See nss(4) for more information.

       When  compiling multithreaded applications, see Intro(3), MULTITHREADED
       APPLICATIONS, for information about the use of the _REENTRANT flag.

       Use of the enumeration interfaces gethostent()  and  gethostent_r()  is
       discouraged;  enumeration  might	 not  be  supported  for  all database
       sources.	The semantics of enumeration are  discussed  further  in  nss-

       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, are helpful in constructing and manipu-
       lating addresses	in this	form.

				  30 Jun 2005		   gethostbyname(3NSL)


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

home | help