gethostbyname man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

GETHOSTBYNAME(3NSL)					   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 *result, 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);

DESCRIPTION
       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
       address. 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
       addr.

       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
       expects to do no further host entry retrieval  operations;  the	system
       can  then  deallocate  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  gethostbyname(),  gethostbyaddr(),	and gethostent() functions use
       static storage that is reused in	 each  call,  making  these  functions
       unsafe 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
       interfaces, 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
       ERRORS 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.

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

ERRORS
       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
       error  occurs  before gethostbyname() is resolved, then gethostbyname()
       returns an internal error with a value of −1.

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

EXAMPLES
       Example 1 Using gethostbyaddr()

       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 <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-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, 4, 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%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	preceding  sample  program is unsafe for use in multi‐
       threaded applications.

FILES
       /etc/hosts
			     hosts file that associates	 the  names  of	 hosts
			     with their Internet Protocol (IP) addresses

       /etc/netconfig
			     network configuration database

       /etc/nsswitch.conf
			     configuration file for the name service switch

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

       ┌───────────────┬────────────────────────────┐
       │ATTRIBUTE TYPE │      ATTRIBUTE VALUE	    │
       ├───────────────┼────────────────────────────┤
       │MT-Level       │ See  Reentrant	 Interfaces │
       │	       │ in  the  DESCRIPTION  sec‐ │
       │	       │ tion.			    │
       └───────────────┴────────────────────────────┘

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

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
       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
       libraries,  then	 the  entry  for  hosts in nsswitch.conf will be used;
       nametoaddr 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
       entry 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
       addresses. The underlying source that satisfies the request  determines
       the  mapping  of	 the  input  name or address into the set of names and
       addresses in hostent. Different sources	might  do  that	 in  different
       ways. If there is more than one alias and more than one address in hos‐
       tent, 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
       addresses 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‐
       witch.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, are helpful in constructing and manipu‐
       lating addresses in this form.

				 Sep 10, 2013		   GETHOSTBYNAME(3NSL)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net