/[resiprocate]/main/contrib/ares/ares_gethostbyname.3
ViewVC logotype

Contents of /main/contrib/ares/ares_gethostbyname.3

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5295 - (show annotations) (download)
Mon Aug 22 00:30:05 2005 UTC (14 years, 2 months ago) by jason
File size: 2943 byte(s)
merged 5270:HEAD from b-directory-reorg
1 .\"
2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
3 .\"
4 .\" Permission to use, copy, modify, and distribute this
5 .\" software and its documentation for any purpose and without
6 .\" fee is hereby granted, provided that the above copyright
7 .\" notice appear in all copies and that both that copyright
8 .\" notice and this permission notice appear in supporting
9 .\" documentation, and that the name of M.I.T. not be used in
10 .\" advertising or publicity pertaining to distribution of the
11 .\" software without specific, written prior permission.
12 .\" M.I.T. makes no representations about the suitability of
13 .\" this software for any purpose. It is provided "as is"
14 .\" without express or implied warranty.
15 .\"
16 .TH ARES_GETHOSTBYNAME 3 "25 July 1998"
17 .SH NAME
18 ares_gethostbyname \- Initiate a host query by name
19 .SH SYNOPSIS
20 .nf
21 .B #include <ares.h>
22 .PP
23 .B typedef void (*ares_host_callback)(void *\fIarg\fP, int \fIstatus\fP,
24 .B struct hostent *\fIhostent\fP)
25 .PP
26 .B void ares_gethostbyname(ares_channel \fIchannel\fP, const char *\fIname\fP,
27 .B int \fIfamily\fP, ares_host_callback \fIcallback\fP, void *\fIarg\fP)
28 .fi
29 .SH DESCRIPTION
30 The
31 .B ares_gethostbyname
32 function initiates a host query by name on the name service channel
33 identified by
34 .IR channel .
35 The parameter
36 .I name
37 gives the hostname as a NUL-terminated C string, and
38 .I family
39 gives the desired type of address for the resulting host entry. When
40 the query is complete or has failed, the ares library will invoke
41 .IR callback .
42 Completion or failure of the query may happen immediately, or may
43 happen during a later call to
44 .BR ares_process (3)
45 or
46 .BR ares_destroy (3).
47 .PP
48 The callback argument
49 .I arg
50 is copied from the
51 .B ares_gethostbyname
52 argument
53 .IR arg .
54 The callback argument
55 .I status
56 indicates whether the query succeeded and, if not, how it failed. It
57 may have any of the following values:
58 .TP 19
59 .B ARES_SUCCESS
60 The host lookup completed successfully.
61 .TP 19
62 .B ARES_ENOTIMP
63 The ares library does not know how to find addresses of type
64 .IR family .
65 .TP 19
66 .B ARES_EBADNAME
67 The hostname
68 .B name
69 is composed entirely of numbers and periods, but is not a valid
70 representation of an Internet address.
71 .TP 19
72 .B ARES_ENOTFOUND
73 The address
74 .I addr
75 was not found.
76 .TP 19
77 .B ARES_ENOMEM
78 Memory was exhausted.
79 .TP 19
80 .B ARES_EDESTRUCTION
81 The name service channel
82 .I channel
83 is being destroyed; the query will not be completed.
84 .PP
85 On successful completion of the query, the callback argument
86 .I hostent
87 points to a
88 .B struct hostent
89 containing the name of the host returned by the query. The callback
90 need not and should not attempt to free the memory pointed to by
91 .IR hostent ;
92 the ares library will free it when the callback returns. If the query
93 did not complete successfully,
94 .I hostent
95 will be
96 .BR NULL .
97 .SH SEE ALSO
98 .BR ares_process (3)
99 .SH AUTHOR
100 Greg Hudson, MIT Information Systems
101 .br
102 Copyright 1998 by the Massachusetts Institute of Technology.

webmaster AT resiprocate DOT org
ViewVC Help
Powered by ViewVC 1.1.27