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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5295 - (show annotations) (download)
Mon Aug 22 00:30:05 2005 UTC (14 years, 3 months ago) by jason
File size: 2796 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_GETHOSTBYADDR 3 "24 July 1998"
17 .SH NAME
18 ares_gethostbyaddr \- Initiate a host query by address
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_gethostbyaddr(ares_channel \fIchannel\fP, const void *\fIaddr\fP,
27 .B int \fIaddrlen\fP, int \fIfamily\fP, ares_host_callback \fIcallback\fP,
28 .B void *\fIarg\fP)
29 .fi
30 .SH DESCRIPTION
31 The
32 .B ares_gethostbyaddr
33 function initiates a host query by address on the name service channel
34 identified by
35 .IR channel .
36 The parameters
37 .I addr
38 and
39 .I addrlen
40 give the address as a series of bytes, and
41 .I family
42 gives the type of address. When the query is complete or has failed,
43 the ares library will invoke
44 .IR callback .
45 Completion or failure of the query may happen immediately, or may
46 happen during a later call to
47 .BR ares_process (3)
48 or
49 .BR ares_destroy (3).
50 .PP
51 The callback argument
52 .I arg
53 is copied from the
54 .B ares_gethostbyaddr
55 argument
56 .IR arg .
57 The callback argument
58 .I status
59 indicates whether the query succeeded and, if not, how it failed. It
60 may have any of the following values:
61 .TP 19
62 .B ARES_SUCCESS
63 The host lookup completed successfully.
64 .TP 19
65 .B ARES_ENOTIMP
66 The ares library does not know how to look up addresses of type
67 .IR family .
68 .TP 19
69 .B ARES_ENOTFOUND
70 The address
71 .I addr
72 was not found.
73 .TP 19
74 .B ARES_ENOMEM
75 Memory was exhausted.
76 .TP 19
77 .B ARES_EDESTRUCTION
78 The name service channel
79 .I channel
80 is being destroyed; the query will not be completed.
81 .PP
82 On successful completion of the query, the callback argument
83 .I hostent
84 points to a
85 .B struct hostent
86 containing the name of the host returned by the query. The callback
87 need not and should not attempt to free the memory pointed to by
88 .IR hostent ;
89 the ares library will free it when the callback returns. If the query
90 did not complete successfully,
91 .I hostent
92 will be
93 .BR NULL .
94 .SH SEE ALSO
95 .BR ares_process (3)
96 .SH AUTHOR
97 Greg Hudson, MIT Information Systems
98 .br
99 Copyright 1998 by the Massachusetts Institute of Technology.

webmaster AT resiprocate DOT org
ViewVC Help
Powered by ViewVC 1.1.27