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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
LWRES_GETHOSTENT(3)		     BIND9		   LWRES_GETHOSTENT(3)

NAME
       lwres_gethostbyname, lwres_gethostbyname2, lwres_gethostbyaddr,
       lwres_gethostent, lwres_sethostent, lwres_endhostent,
       lwres_gethostbyname_r, lwres_gethostbyaddr_r, lwres_gethostent_r,
       lwres_sethostent_r, lwres_endhostent_r -	lightweight resolver get
       network host entry

SYNOPSIS
       #include	<lwres/netdb.h>

       struct hostent *	lwres_gethostbyname(const char *name);

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

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

       struct hostent *	lwres_gethostent(void);

       void lwres_sethostent(int stayopen);

       void lwres_endhostent(void);

       struct hostent *	lwres_gethostbyname_r(const char *name,
					      struct hostent *resbuf,
					      char *buf, int buflen,
					      int *error);

       struct hostent *	lwres_gethostbyaddr_r(const char *addr,	int len,
					      int type,
					      struct hostent *resbuf,
					      char *buf, int buflen,
					      int *error);

       struct hostent *	lwres_gethostent_r(struct hostent *resbuf, char	*buf,
					   int buflen, int *error);

       void lwres_sethostent_r(int stayopen);

       void lwres_endhostent_r(void);

DESCRIPTION
       These functions provide hostname-to-address and address-to-hostname
       lookups by means	of the lightweight resolver. They are similar to the
       standard	gethostent(3) functions	provided by most operating systems.
       They use	a struct hostent which is usually defined in _namedb.h_.

	   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
	   The official	(canonical) name of the	host.

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

       h_addrtype
	   The type of address being returned -- PF_INET or PF_INET6.

       h_length
	   The length of the address in	bytes.

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

       For backward compatibility with very old	software, h_addr is the	first
       address in h_addr_list.

       lwres_gethostent(), lwres_sethostent(), lwres_endhostent(),
       lwres_gethostent_r(), lwres_sethostent_r() and lwres_endhostent_r()
       provide iteration over the known	host entries on	systems	that provide
       such functionality through facilities like /etc/hosts or	NIS. The
       lightweight resolver does not currently implement these functions; it
       only provides them as stub functions that always	return failure.

       lwres_gethostbyname() and lwres_gethostbyname2()	look up	the hostname
       name.  lwres_gethostbyname() always looks for an	IPv4 address while
       lwres_gethostbyname2() looks for	an address of protocol family af:
       either PF_INET or PF_INET6 -- IPv4 or IPV6 addresses respectively.
       Successful calls	of the functions return	a struct hostentfor the	name
       that was	looked up.  NULL is returned if	the lookups by
       lwres_gethostbyname() or	lwres_gethostbyname2() fail.

       Reverse lookups of addresses are	performed by lwres_gethostbyaddr().
       addr is an address of length len	bytes and protocol family type --
       PF_INET or PF_INET6.  lwres_gethostbyname_r() is	a thread-safe function
       for forward lookups. If an error	occurs,	an error code is returned in
       *error.	resbuf is a pointer to a struct	hostent	which is initialised
       by a successful call to lwres_gethostbyname_r().	 buf is	a buffer of
       length len bytes	which is used to store the h_name, h_aliases, and
       h_addr_list elements of the struct hostent returned in resbuf.
       Successful calls	to lwres_gethostbyname_r() return resbuf, which	is a
       pointer to the struct hostent it	created.

       lwres_gethostbyaddr_r() is a thread-safe	function that performs a
       reverse lookup of address addr which is len bytes long and is of
       protocol	family type -- PF_INET or PF_INET6. If an error	occurs,	the
       error code is returned in *error. The other function parameters are
       identical to those in lwres_gethostbyname_r().  resbuf is a pointer to
       a struct	hostent	which is initialised by	a successful call to
       lwres_gethostbyaddr_r().	 buf is	a buffer of length len bytes which is
       used to store the h_name, h_aliases, and	h_addr_list elements of	the
       struct hostent returned in resbuf. Successful calls to
       lwres_gethostbyaddr_r() return resbuf, which is a pointer to the	struct
       hostent() it created.

RETURN VALUES
       The functions lwres_gethostbyname(), lwres_gethostbyname2(),
       lwres_gethostbyaddr(), and lwres_gethostent() return NULL to indicate
       an error. In this case the global variable lwres_h_errno	will contain
       one of the following error codes	defined	in _lwres/netdb.h_:

       HOST_NOT_FOUND
	   The host or address was not found.

       TRY_AGAIN
	   A recoverable error occurred, e.g., a timeout. Retrying the lookup
	   may succeed.

       NO_RECOVERY
	   A non-recoverable error occurred.

       NO_DATA
	   The name exists, but	has no address information associated with it
	   (or vice versa in the case of a reverse lookup). The	code
	   NO_ADDRESS is accepted as a synonym for NO_DATA for backwards
	   compatibility.

       lwres_hstrerror(3) translates these error codes to suitable error
       messages.

       lwres_gethostent() and lwres_gethostent_r() always return NULL.

       Successful calls	to lwres_gethostbyname_r() and lwres_gethostbyaddr_r()
       return resbuf, a	pointer	to the struct hostent that was initialised by
       these functions.	They return NULL if the	lookups	fail or	if buf was too
       small to	hold the list of addresses and names referenced	by the h_name,
       h_aliases, and h_addr_list elements of the struct hostent. If buf was
       too small, both lwres_gethostbyname_r() and lwres_gethostbyaddr_r() set
       the global variable errno to ERANGE.

SEE ALSO
       gethostent(3), lwres_getipnode(3), lwres_hstrerror(3)

BUGS
       lwres_gethostbyname(), lwres_gethostbyname2(), lwres_gethostbyaddr()
       and lwres_endhostent() are not thread safe; they	return pointers	to
       static data and provide error codes through a global variable.
       Thread-safe versions for	name and address lookup	are provided by
       lwres_gethostbyname_r(),	and lwres_gethostbyaddr_r() respectively.

       The resolver daemon does	not currently support any non-DNS name
       services	such as	/etc/hosts or NIS, consequently	the above functions
       don't, either.

COPYRIGHT
       Copyright (C) 2004, 2005, 2007, 2012 Internet Systems Consortium, Inc.
       ("ISC")
       Copyright (C) 2001 Internet Software Consortium.

BIND9				 Jun 30, 2000		   LWRES_GETHOSTENT(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | BUGS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=lwres_gethostent&sektion=3&manpath=FreeBSD+9.1-RELEASE>

home | help