1GETHOSTBYNAME(3)           Library Functions Manual           GETHOSTBYNAME(3)
2
3
4

NAME

6       gethostbyname,  gethostbyaddr, gethostent, sethostent, endhostent, her‐
7       ror - get network host entry
8

SYNOPSIS

10       #include <netdb.h>
11
12       extern int h_errno;
13
14       struct hostent *gethostbyname(name)
15       char *name;
16
17       struct hostent *gethostbyaddr(addr, len, type)
18       char *addr; int len, type;
19
20       struct hostent *gethostent()
21
22       sethostent(stayopen)
23       int stayopen;
24
25       endhostent()
26
27       herror(string)
28       char *string;
29

DESCRIPTION

31       Gethostbyname and gethostbyaddr each return a pointer to an object with
32       the  following structure describing an internet host referenced by name
33       or by address, respectively.  This structure contains either the infor‐
34       mation  obtained  from  the name server, named(8), or broken-out fields
35       from a line in /etc/hosts.  If the local name  server  is  not  running
36       these routines do a lookup in /etc/hosts.
37
38              struct    hostent {
39                   char *h_name;  /* official name of host */
40                   char **h_aliases;   /* alias list */
41                   int  h_addrtype;    /* host address type */
42                   int  h_length; /* length of address */
43                   char **h_addr_list; /* list of addresses from name server */
44              };
45              #define   h_addr  h_addr_list[0]   /* address, for backward compatibility */
46
47       The members of this structure are:
48
49       h_name       Official name of the host.
50
51       h_aliases    A zero terminated array of alternate names for the host.
52
53       h_addrtype   The  type  of  address  being  returned;  currently always
54                    AF_INET.
55
56       h_length     The length, in bytes, of the address.
57
58       h_addr_list  A zero terminated array of network addresses for the host.
59                    Host addresses are returned in network byte order.
60
61       h_addr       The  first  address  in  h_addr_list; this is for backward
62                    compatiblity.
63
64       When using the nameserver, gethostbyname will search for the named host
65       in  the  current  domain and its parents unless the name ends in a dot.
66       If the name contains no dot, and if the environment variable  ``HOSTAL‐
67       IASES''  contains  the name of an alias file, the alias file will first
68       be searched for an alias matching the input name.  See hostname(7)  for
69       the domain search procedure and the alias file format.
70
71       Sethostent may be used to request the use of a connected TCP socket for
72       queries.  If the stayopen flag is non-zero, this  sets  the  option  to
73       send all queries to the name server using TCP and to retain the connec‐
74       tion after each call to  gethostbyname  or  gethostbyaddr.   Otherwise,
75       queries are performed using UDP datagrams.
76
77       Endhostent closes the TCP connection.
78

DIAGNOSTICS

80       Error  return  status from gethostbyname and gethostbyaddr is indicated
81       by return of a null pointer.  The external integer h_errno may then  be
82       checked  to  see  whether  this is a temporary failure or an invalid or
83       unknown host.  The routine herror can be used to print an error message
84       describing  the  failure.   If  its  argument string is non-NULL, it is
85       printed, followed by a colon and a space.  The error message is printed
86       with a trailing newline.
87
88       h_errno can have the following values:
89
90              HOST_NOT_FOUND  No such host is known.
91
92              TRY_AGAIN       This is usually a temporary error and means that
93                              the local server did not receive a response from
94                              an  authoritative server.  A retry at some later
95                              time may succeed.
96
97              NO_RECOVERY     Some unexpected server failure was  encountered.
98                              This is a non-recoverable error.
99
100              NO_DATA         The requested name is valid but does not have an
101                              IP address; this is not a temporary error.  This
102                              means  that the name is known to the name server
103                              but there is no  address  associated  with  this
104                              name.   Another  type  of  request  to  the name
105                              server using this domain name will result in  an
106                              answer;  for  example,  a  mail-forwarder may be
107                              registered for this domain.
108

FILES

110       /etc/hosts
111

SEE ALSO

113       resolver(3), hosts(5), hostname(7), named(8)
114

CAVEAT

116       Gethostent is defined, and sethostent  and  endhostent  are  redefined,
117       when libc is built to use only the routines to lookup in /etc/hosts and
118       not the name server.
119
120       Gethostent reads the next line of /etc/hosts, opening the file if  nec‐
121       essary.
122
123       Sethostent  is  redefined to open and rewind the file.  If the stayopen
124       argument is non-zero, the hosts data base will not be closed after each
125       call  to  gethostbyname  or  gethostbyaddr.  Endhostent is redefined to
126       close the file.
127

BUGS

129       All information is contained in a static area so it must be  copied  if
130       it  is  to  be  saved.   Only  the Internet address format is currently
131       understood.
132
133
134
1354.2 Berkeley Distribution      October 30, 1996               GETHOSTBYNAME(3)
Impressum