OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [rtos/] [rtems/] [c/] [src/] [libnetworking/] [libc/] [gethostbyname.3] - Blame information for rev 30

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 30 unneback
.\" Copyright (c) 1983, 1987, 1991, 1993
2
.\"     The Regents of the University of California.  All rights reserved.
3
.\"
4
.\" Redistribution and use in source and binary forms, with or without
5
.\" modification, are permitted provided that the following conditions
6
.\" are met:
7
.\" 1. Redistributions of source code must retain the above copyright
8
.\"    notice, this list of conditions and the following disclaimer.
9
.\" 2. Redistributions in binary form must reproduce the above copyright
10
.\"    notice, this list of conditions and the following disclaimer in the
11
.\"    documentation and/or other materials provided with the distribution.
12
.\" 3. All advertising materials mentioning features or use of this software
13
.\"    must display the following acknowledgement:
14
.\"     This product includes software developed by the University of
15
.\"     California, Berkeley and its contributors.
16
.\" 4. Neither the name of the University nor the names of its contributors
17
.\"    may be used to endorse or promote products derived from this software
18
.\"    without specific prior written permission.
19
.\"
20
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30
.\" SUCH DAMAGE.
31
.\"
32
.\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
33
.\"     $Id: gethostbyname.3,v 1.2 2001-09-27 12:01:53 chris Exp $
34
.\"
35
.Dd May 25, 1995
36
.Dt GETHOSTBYNAME 3
37
.Os BSD 4.2
38
.Sh NAME
39
.Nm gethostbyname ,
40
.Nm gethostbyname2 ,
41
.Nm gethostbyaddr ,
42
.Nm gethostent ,
43
.Nm sethostent ,
44
.Nm endhostent ,
45
.Nm herror ,
46
.Nm hstrerror
47
.Nd get network host entry
48
.Sh SYNOPSIS
49
.Fd #include 
50
.Vt extern int h_errno;
51
.Ft struct hostent *
52
.Fn gethostbyname "const char *name"
53
.Ft struct hostent *
54
.Fn gethostbyname2 "const char *name" "int af"
55
.Ft struct hostent *
56
.Fn gethostbyaddr "const char *addr" "int len" "int type"
57
.Ft struct hostent *
58
.Fn gethostent void
59
.Ft void
60
.Fn sethostent "int stayopen"
61
.Ft void
62
.Fn endhostent void
63
.Ft void
64
.Fn herror "const char *string"
65
.Ft const char *
66
.Fn hstrerror "int err"
67
.Sh DESCRIPTION
68
The
69
.Fn gethostbyname ,
70
.Fn gethostbyname2
71
and
72
.Fn gethostbyaddr
73
functions
74
each return a pointer to an object with the
75
following structure describing an internet host
76
referenced by name or by address, respectively.
77
This structure contains either the information obtained from the name server,
78
.Xr named 8 ,
79
or broken-out fields from a line in
80
.Pa /etc/hosts .
81
If the local name server is not running these routines do a lookup in
82
.Pa /etc/hosts .
83
.Bd -literal
84
struct  hostent {
85
        char    *h_name;        /* official name of host */
86
        char    **h_aliases;    /* alias list */
87
        int     h_addrtype;     /* host address type */
88
        int     h_length;       /* length of address */
89
        char    **h_addr_list;  /* list of addresses from name server */
90
};
91
#define h_addr  h_addr_list[0]  /* address, for backward compatibility */
92
.Ed
93
.Pp
94
The members of this structure are:
95
.Bl -tag -width h_addr_list
96
.It Fa h_name
97
Official name of the host.
98
.It Fa h_aliases
99
A NULL-terminated array of alternate names for the host.
100
.It Fa h_addrtype
101
The type of address being returned; usually
102
.Dv AF_INET .
103
.It Fa h_length
104
The length, in bytes, of the address.
105
.It Fa h_addr_list
106
A NULL-terminated array of network addresses for the host.
107
Host addresses are returned in network byte order.
108
.It Fa h_addr
109
The first address in
110
.Fa h_addr_list ;
111
this is for backward compatibility.
112
.El
113
.Pp
114
When using the nameserver,
115
.Fn gethostbyname
116
and
117
.Fn gethostbyname
118
will search for the named host in the current domain and its parents
119
unless the name ends in a dot.
120
If the name contains no dot, and if the environment variable
121
.Dq Ev HOSTALIASES
122
contains the name of an alias file, the alias file will first be searched
123
for an alias matching the input name.
124
See
125
.Xr hostname 7
126
for the domain search procedure and the alias file format.
127
.Pp
128
The
129
.Fn gethostbyname2
130
function is an evolution of
131
.Fn gethostbyname
132
which is intended to allow lookups in address families other than
133
.Dv AF_INET ,
134
for example
135
.Dv AF_INET6 .
136
Currently the
137
.Fa af
138
argument must be specified as
139
.Dv AF_INET
140
else the function will return
141
.Dv NULL
142
after having set
143
.Va h_errno
144
to
145
.Dv NETDB_INTERNAL
146
.Pp
147
The
148
.Fn sethostent
149
function
150
may be used to request the use of a connected
151
.Tn TCP
152
socket for queries.
153
If the
154
.Fa stayopen
155
flag is non-zero,
156
this sets the option to send all queries to the name server using
157
.Tn TCP
158
and to retain the connection after each call to
159
.Fn gethostbyname ,
160
.Fn gethostbyname2
161
or
162
.Fn gethostbyaddr .
163
Otherwise, queries are performed using
164
.Tn UDP
165
datagrams.
166
.Pp
167
The
168
.Fn endhostent
169
function
170
closes the
171
.Tn TCP
172
connection.
173
.Pp
174
The
175
.Fn herror
176
function writes a message to the diagnostic output consisting of the
177
string parameter
178
.Fa s ,
179
the constant string ": ", and a message corresponding to the value of
180
.Va h_errno .
181
.Pp
182
The
183
.Fn hstrerror
184
function returns a string which is the message text corresponding to the
185
value of the
186
.Fa err
187
parameter.
188
.Sh FILES
189
.Bl -tag -width /etc/resolv.conf -compact
190
.It Pa /etc/hosts
191
.It Pa /etc/host.conf
192
.It Pa /etc/resolv.conf
193
.El
194
.Sh DIAGNOSTICS
195
Error return status from
196
.Fn gethostbyname ,
197
.Fn gethostbyname2
198
and
199
.Fn gethostbyaddr
200
is indicated by return of a null pointer.
201
The external integer
202
.Va h_errno
203
may then be checked to see whether this is a temporary failure
204
or an invalid or unknown host.
205
The routine
206
.Fn herror
207
can be used to print an error message describing the failure.
208
If its argument
209
.Fa string
210
is
211
.Pf non Dv -NULL ,
212
it is printed, followed by a colon and a space.
213
The error message is printed with a trailing newline.
214
.Pp
215
The variable
216
.Va h_errno
217
can have the following values:
218
.Bl -tag -width HOST_NOT_FOUND
219
.It Dv HOST_NOT_FOUND
220
No such host is known.
221
.It Dv TRY_AGAIN
222
This is usually a temporary error
223
and means that the local server did not receive
224
a response from an authoritative server.
225
A retry at some later time may succeed.
226
.It Dv NO_RECOVERY
227
Some unexpected server failure was encountered.
228
This is a non-recoverable error.
229
.It Dv NO_DATA
230
The requested name is valid but does not have an IP address;
231
this is not a temporary error.
232
This means that the name is known to the name server but there is no address
233
associated with this name.
234
Another type of request to the name server using this domain name
235
will result in an answer;
236
for example, a mail-forwarder may be registered for this domain.
237
.El
238
.Sh SEE ALSO
239
.Xr resolver 3 ,
240
.Xr hosts 5 ,
241
.Xr hostname 7 ,
242
.Xr named 8
243
.Sh CAVEAT
244
The
245
.Fn gethostent
246
function
247
is defined, and
248
.Fn sethostent
249
and
250
.Fn endhostent
251
are redefined,
252
when
253
.Xr libc 3
254
is built to use only the routines to lookup in
255
.Pa /etc/hosts
256
and not the name server.
257
.Pp
258
The
259
.Fn gethostent
260
function
261
reads the next line of
262
.Pa /etc/hosts ,
263
opening the file if necessary.
264
.Pp
265
The
266
.Fn sethostent
267
function
268
opens and/or rewinds the file
269
.Pa /etc/hosts .
270
If the
271
.Fa stayopen
272
argument is non-zero,
273
the file will not be closed after each call to
274
.Fn gethostbyname ,
275
.Fn gethostbyname2
276
or
277
.Fn gethostbyaddr .
278
.Pp
279
The
280
.Fn endhostent
281
function
282
closes the file.
283
.Sh HISTORY
284
The
285
.Fn herror
286
function appeared in
287
.Bx 4.3 .
288
The
289
.Fn endhostent ,
290
.Fn gethostbyaddr ,
291
.Fn gethostbyname ,
292
.Fn gethostent ,
293
and
294
.Fn sethostent
295
functions appeared in
296
.Bx 4.2 .
297
The
298
.Fn gethostbyname2
299
function first appeared in bind-4.9.4.
300
.Sh BUGS
301
These functions use static data storage;
302
if the data is needed for future use, it should be
303
copied before any subsequent calls overwrite it.
304
Only the Internet
305
address format is currently understood.

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.