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