Commit | Line | Data |
---|---|---|
5cff1869 | 1 | .\" Copyright (c) 1983,1987 Regents of the University of California. |
b9a6fdfb KM |
2 | .\" All rights reserved. The Berkeley software License Agreement |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
d97ed772 | 5 | .\" @(#)gethostbyname.3 6.8 (Berkeley) %G% |
b9a6fdfb | 6 | .\" |
a7fb1b36 | 7 | .TH GETHOSTBYNAME 3N "" |
b9a6fdfb KM |
8 | .UC 5 |
9 | .SH NAME | |
a7fb1b36 | 10 | gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent \- get network host entry |
b9a6fdfb KM |
11 | .SH SYNOPSIS |
12 | .B "#include <netdb.h> | |
13 | .PP | |
a7fb1b36 | 14 | .B "extern int h_errno; |
b9a6fdfb KM |
15 | .PP |
16 | .B "struct hostent *gethostbyname(name) | |
17 | .br | |
18 | .B "char *name; | |
19 | .PP | |
20 | .B "struct hostent *gethostbyaddr(addr, len, type) | |
21 | .br | |
22 | .B "char *addr; int len, type; | |
23 | .PP | |
a7fb1b36 KD |
24 | .B "struct hostent *gethostent() |
25 | .PP | |
b9a6fdfb KM |
26 | .B "sethostent(stayopen) |
27 | .br | |
92953539 | 28 | .B "int stayopen; |
b9a6fdfb KM |
29 | .PP |
30 | .B "endhostent() | |
92953539 | 31 | .PP |
5cff1869 MK |
32 | .B "herror(string) |
33 | .br | |
34 | .B "char *string; | |
35 | .PP | |
b9a6fdfb | 36 | .SH DESCRIPTION |
a7fb1b36 | 37 | .I Gethostbyname |
b9a6fdfb KM |
38 | and |
39 | .I gethostbyaddr | |
40 | each return a pointer to an object with the | |
d97ed772 MK |
41 | following structure describing an internet host |
42 | referenced by name or by address, respectively. | |
a7fb1b36 | 43 | This structure contains either the information obtained from the name server, |
576c34d8 JL |
44 | .IR named (8), |
45 | or broken-out fields from a line in | |
a7fb1b36 KD |
46 | .IR /etc/hosts . |
47 | If the local name server is not running these routines do a lookup in | |
48 | .IR /etc/hosts . | |
b9a6fdfb KM |
49 | .RS |
50 | .PP | |
51 | .nf | |
52 | struct hostent { | |
53 | char *h_name; /* official name of host */ | |
54 | char **h_aliases; /* alias list */ | |
a7fb1b36 | 55 | int h_addrtype; /* host address type */ |
b9a6fdfb | 56 | int h_length; /* length of address */ |
a7fb1b36 | 57 | char **h_addr_list; /* list of addresses from name server */ |
b9a6fdfb | 58 | }; |
a7fb1b36 | 59 | #define h_addr h_addr_list[0] /* address, for backward compatibility */ |
b9a6fdfb KM |
60 | .ft R |
61 | .ad | |
62 | .fi | |
63 | .RE | |
64 | .PP | |
65 | The members of this structure are: | |
a7fb1b36 | 66 | .TP \w'h_addr_list'u+2n |
b9a6fdfb KM |
67 | h_name |
68 | Official name of the host. | |
a7fb1b36 | 69 | .TP \w'h_addr_list'u+2n |
b9a6fdfb KM |
70 | h_aliases |
71 | A zero terminated array of alternate names for the host. | |
a7fb1b36 | 72 | .TP \w'h_addr_list'u+2n |
b9a6fdfb KM |
73 | h_addrtype |
74 | The type of address being returned; currently always AF_INET. | |
a7fb1b36 | 75 | .TP \w'h_addr_list'u+2n |
b9a6fdfb KM |
76 | h_length |
77 | The length, in bytes, of the address. | |
a7fb1b36 KD |
78 | .TP \w'h_addr_list'u+2n |
79 | h_addr_list | |
80 | A zero terminated array of network addresses for the host. | |
81 | Host addresses are returned in network byte order. | |
82 | .TP \w'h_addr_list'u+2n | |
b9a6fdfb | 83 | h_addr |
a7fb1b36 | 84 | The first address in h_addr_list; this is for backward compatiblity. |
b9a6fdfb | 85 | .PP |
d97ed772 MK |
86 | When using the nameserver, |
87 | .I gethostbyname | |
88 | will search for the named host in the current domain and its parents | |
89 | unless the name ends in a dot. | |
90 | If the name contains no dot, and if the environment variable ``HOSTALAIASES'' | |
91 | contains the name of an alias file, the alias file will first be searched | |
92 | for an alias matching the input name. | |
93 | See | |
94 | .IR hostname (7) | |
95 | for the domain search procedure and the alias file format. | |
96 | .PP | |
b9a6fdfb | 97 | .I Sethostent |
d97ed772 | 98 | may be used to request the use of a connected TCP socket for queries. |
a7fb1b36 | 99 | If the |
b9a6fdfb KM |
100 | .I stayopen |
101 | flag is non-zero, | |
a7fb1b36 KD |
102 | this sets the option to send all queries to the name server using TCP |
103 | and to retain the connection after each call to | |
16b80cdf | 104 | .I gethostbyname |
0d1b3ffd JL |
105 | or |
106 | .IR gethostbyaddr . | |
d97ed772 | 107 | Otherwise, queries are performed using UDP datagrams. |
b9a6fdfb KM |
108 | .PP |
109 | .I Endhostent | |
a7fb1b36 KD |
110 | closes the TCP connection. |
111 | .SH DIAGNOSTICS | |
92953539 | 112 | .PP |
a7fb1b36 | 113 | Error return status from |
576c34d8 | 114 | .I gethostbyname |
b9a6fdfb KM |
115 | and |
116 | .I gethostbyaddr | |
a7fb1b36 KD |
117 | is indicated by return of a null pointer. |
118 | The external integer | |
119 | .IR h_errno | |
120 | may then be checked to see whether this is a temporary failure | |
121 | or an invalid or unknown host. | |
5cff1869 MK |
122 | The routine |
123 | .I herror | |
124 | can be used to print an error message describing the failure. | |
125 | If its argument | |
126 | .I string | |
127 | is non-NULL, it is printed, followed by a colon and a space. | |
128 | The error message is printed with a trailing newline. | |
a7fb1b36 KD |
129 | .PP |
130 | .IR h_errno | |
131 | can have the following values: | |
132 | .RS | |
133 | .IP HOST_NOT_FOUND \w'HOST_NOT_FOUND'u+2n | |
134 | No such host is known. | |
135 | .IP TRY_AGAIN \w'HOST_NOT_FOUND'u+2n | |
136 | This is usually a temporary error | |
137 | and means that the local server did not receive | |
138 | a response from an authoritative server. | |
139 | A retry at some later time may succeed. | |
140 | .IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n | |
5cff1869 | 141 | Some unexpected server failure was encountered. |
a7fb1b36 KD |
142 | This is a non-recoverable error. |
143 | .IP NO_ADDRESS \w'HOST_NOT_FOUND'u+2n | |
144 | The requested name is valid but does not have an IP address; | |
145 | this is not a temporary error. | |
5cff1869 MK |
146 | This means another type of request to the name server using this domain name |
147 | will result in an answer; | |
148 | for example, a mail-forwarder may be registered for this domain. | |
a7fb1b36 | 149 | .RE |
b9a6fdfb KM |
150 | .SH FILES |
151 | /etc/hosts | |
152 | .SH "SEE ALSO" | |
5cff1869 | 153 | resolver(3), hosts(5), hostname(7), named(8) |
a7fb1b36 KD |
154 | .SH CAVEAT |
155 | .PP | |
576c34d8 | 156 | .I Gethostent |
a7fb1b36 | 157 | is defined, and |
576c34d8 JL |
158 | .I sethostent |
159 | and | |
160 | .I endhostent | |
161 | are redefined, | |
a7fb1b36 KD |
162 | when |
163 | .IR libc | |
164 | is built to use only the routines to lookup in | |
165 | .IR /etc/hosts | |
166 | and not the name server. | |
167 | .PP | |
576c34d8 | 168 | .I Gethostent |
a7fb1b36 | 169 | reads the next line of |
576c34d8 | 170 | .IR /etc/hosts , |
a7fb1b36 KD |
171 | opening the file if necessary. |
172 | .PP | |
576c34d8 JL |
173 | .I Sethostent |
174 | is redefined to open and rewind the file. If the | |
a7fb1b36 | 175 | .I stayopen |
576c34d8 | 176 | argument is non-zero, |
a7fb1b36 | 177 | the hosts data base will not be closed after each call to |
576c34d8 | 178 | .I gethostbyname |
a7fb1b36 | 179 | or |
576c34d8 JL |
180 | .IR gethostbyaddr . |
181 | .I Endhostent | |
182 | is redefined to close the file. | |
b9a6fdfb KM |
183 | .SH BUGS |
184 | All information | |
185 | is contained in a static area | |
186 | so it must be copied if it is | |
187 | to be saved. Only the Internet | |
188 | address format is currently understood. |