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