![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gethostbyname.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDTahoe / man / man3|
Return to gethostbyname.3 CVS log | Up to [CSRG BSD Unix] / 43BSDTahoe / man / man3 |
1.1 root 1: .\" Copyright (c) 1983,1987 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)gethostbyname.3 6.9 (Berkeley) 4/5/88
6: .\"
7: .TH GETHOSTBYNAME 3N "April 5, 1988"
8: .UC 5
9: .SH NAME
10: gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry
11: .SH SYNOPSIS
12: .B "#include <netdb.h>
13: .PP
14: .B "extern int h_errno;
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
24: .B "struct hostent *gethostent()
25: .PP
26: .B "sethostent(stayopen)
27: .br
28: .B "int stayopen;
29: .PP
30: .B "endhostent()
31: .PP
32: .B "herror(string)
33: .br
34: .B "char *string;
35: .PP
36: .SH DESCRIPTION
37: .I Gethostbyname
38: and
39: .I gethostbyaddr
40: each return a pointer to an object with the
41: following structure describing an internet host
42: referenced by name or by address, respectively.
43: This structure contains either the information obtained from the name server,
44: .IR named (8),
45: or broken-out fields from a line in
46: .IR /etc/hosts .
47: If the local name server is not running these routines do a lookup in
48: .IR /etc/hosts .
49: .RS
50: .PP
51: .nf
52: struct hostent {
53: char *h_name; /* official name of host */
54: char **h_aliases; /* alias list */
55: int h_addrtype; /* host address type */
56: int h_length; /* length of address */
57: char **h_addr_list; /* list of addresses from name server */
58: };
59: #define h_addr h_addr_list[0] /* address, for backward compatibility */
60: .ft R
61: .ad
62: .fi
63: .RE
64: .PP
65: The members of this structure are:
66: .TP \w'h_addr_list'u+2n
67: h_name
68: Official name of the host.
69: .TP \w'h_addr_list'u+2n
70: h_aliases
71: A zero terminated array of alternate names for the host.
72: .TP \w'h_addr_list'u+2n
73: h_addrtype
74: The type of address being returned; currently always AF_INET.
75: .TP \w'h_addr_list'u+2n
76: h_length
77: The length, in bytes, of the address.
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
83: h_addr
84: The first address in h_addr_list; this is for backward compatiblity.
85: .PP
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
97: .I Sethostent
98: may be used to request the use of a connected TCP socket for queries.
99: If the
100: .I stayopen
101: flag is non-zero,
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
104: .I gethostbyname
105: or
106: .IR gethostbyaddr .
107: Otherwise, queries are performed using UDP datagrams.
108: .PP
109: .I Endhostent
110: closes the TCP connection.
111: .SH DIAGNOSTICS
112: .PP
113: Error return status from
114: .I gethostbyname
115: and
116: .I gethostbyaddr
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.
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.
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
141: Some unexpected server failure was encountered.
142: This is a non-recoverable error.
143: .IP NO_DATA \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.
146: This means that the name is known to the name server but there is no address
147: associated with this name.
148: Another type of request to the name server using this domain name
149: will result in an answer;
150: for example, a mail-forwarder may be registered for this domain.
151: .RE
152: .SH FILES
153: /etc/hosts
154: .SH "SEE ALSO"
155: resolver(3), hosts(5), hostname(7), named(8)
156: .SH CAVEAT
157: .PP
158: .I Gethostent
159: is defined, and
160: .I sethostent
161: and
162: .I endhostent
163: are redefined,
164: when
165: .IR libc
166: is built to use only the routines to lookup in
167: .IR /etc/hosts
168: and not the name server.
169: .PP
170: .I Gethostent
171: reads the next line of
172: .IR /etc/hosts ,
173: opening the file if necessary.
174: .PP
175: .I Sethostent
176: is redefined to open and rewind the file. If the
177: .I stayopen
178: argument is non-zero,
179: the hosts data base will not be closed after each call to
180: .I gethostbyname
181: or
182: .IR gethostbyaddr .
183: .I Endhostent
184: is redefined to close the file.
185: .SH BUGS
186: All information
187: is contained in a static area
188: so it must be copied if it is
189: to be saved. Only the Internet
190: address format is currently understood.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.