1 .\" Copyright (c) 1983, 1987 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms are permitted provided
5 .\" that: (1) source distributions retain this entire copyright notice and
6 .\" comment, and (2) distributions including binaries display the following
7 .\" acknowledgement: ``This product includes software developed by the
8 .\" University of California, Berkeley and its contributors'' in the
9 .\" documentation or other materials provided with the distribution and in
10 .\" all advertising materials mentioning features or use of this software.
11 .\" Neither the name of the University nor the names of its contributors may
12 .\" be used to endorse or promote products derived from this software without
13 .\" specific prior written permission.
14 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
15 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
16 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
18 .\" @(#)gethostbyname.3 6.12 (Berkeley) 6/23/90
21 .Dt GETHOSTBYNAME @LIB_NETWORK_EXT_U@
30 .Nd get network host entry
32 .Fd #include <netdb.h>
37 .Fn gethostbyname "char *name";
39 .Fn gethostbyname2 "char *name" "int af";
41 .Fn gethostbyaddr "char *addr" "int len, type";
44 .Fn sethostent "int stayopen";
46 .Fn herror "char *string";
52 each return a pointer to a
54 structure (see below) describing an internet host
55 referenced by name or by address, as the function names indicate.
56 This structure contains either the information obtained from the name server,
57 .Xr @INDOT@named @SYS_OPS_EXT@ ,
58 or broken-out fields from a line in
60 If the local name server is not running, these routines do a lookup in
62 .Bd -literal -offset indent
64 char *h_name; /* official name of host */
65 char **h_aliases; /* alias list */
66 int h_addrtype; /* host address type */
67 int h_length; /* length of address */
68 char **h_addr_list; /* list of addresses from name server */
71 #define h_addr h_addr_list[0] /* address, for backward compatibility */
74 The members of this structure are:
75 .Bl -tag -width "h_addr_list"
77 Official name of the host.
79 A zero-terminated array of alternate names for the host.
81 The type of address being returned; usually
84 The length, in bytes, of the address.
86 A zero-terminated array of network addresses for the host.
87 Host addresses are returned in network byte order.
91 this is for backward compatibility.
94 When using the nameserver,
96 will search for the named host in each parent domain given in the
99 .Xr resolv.conf @FORMAT_EXT@
100 unless the name contains a dot
102 If the name contains no dot, and if the environment variable
104 contains the name of an alias file, the alias file will first be searched
105 for an alias matching the input name.
107 .Xr hostname @DESC_EXT@
108 for the domain search procedure and the alias file format.
113 intended to allow lookups in address families other than
119 argument must be specified as
121 else the function will return
129 may be used to request the use of a connected TCP socket for queries.
133 this sets the option to send all queries to the name server using TCP
134 and to retain the connection after each call to
138 Otherwise, queries are performed using UDP datagrams.
141 closes the TCP connection.
143 .Bl -tag -width "HOSTALIASES " -compress
145 Name of file containing
146 .Pq Ar host alias , full hostname
150 .Bl -tag -width "HOSTALIASES " -compress
153 .Xr hosts @FORMAT_EXT@ .
155 Name of file containing
156 .Pq Ar host alias , full hostname
161 Error return status from
165 is indicated by return of a null pointer.
168 may then be checked to see whether this is a temporary failure
169 or an invalid or unknown host.
172 can be used to print an error message describing the failure.
175 is non-NULL, it is printed, followed by a colon and a space.
176 The error message is printed with a trailing newline.
179 can have the following values:
180 .Bl -tag -width "HOST_NOT_FOUND " -offset indent
181 .It Dv NETDB_INTERNAL
182 This indicates an internal error in the library, unrelated to the network
185 will be valid in this case; see
186 .Xr perror @SYSCALL_EXT@ .
187 .It Dv HOST_NOT_FOUND
188 No such host is known.
190 This is usually a temporary error
191 and means that the local server did not receive
192 a response from an authoritative server.
193 A retry at some later time may succeed.
195 Some unexpected server failure was encountered.
196 This is a non-recoverable error, as one might expect.
198 The requested name is valid but does not have an IP address;
199 this is not a temporary error.
200 This means that the name is known to the name server but there is no address
201 associated with this name.
202 Another type of request to the name server using this domain name
203 will result in an answer;
204 for example, a mail-forwarder may be registered for this domain.
207 .Xr hosts @FORMAT_EXT@ ,
208 .Xr hostname @DESC_EXT@ ,
209 .Xr @INDOT@named @SYS_OPS_EXT@ ,
210 .Xr resolver @LIB_NETWORK_EXT@ ,
211 .Xr resolver @FORMAT_EXT@ .
222 is built to use only the routines to lookup in
224 and not the name server:
225 .Bd -filled -offset indent
228 reads the next line of
230 opening the file if necessary.
233 is redefined to open and rewind the file. If the
235 argument is non-zero,
236 the hosts data base will not be closed after each call to
242 is redefined to close the file.
245 All information is contained in a static area so it must be copied if it is
246 to be saved. Only the Internet address format is currently understood.