diff options
author | Daniel Stenberg <daniel@haxx.se> | 2003-10-07 21:54:04 +0000 |
---|---|---|
committer | Daniel Stenberg <daniel@haxx.se> | 2003-10-07 21:54:04 +0000 |
commit | 5e847a14bd65383ce65f143c578e120899981fd9 (patch) | |
tree | 0072e647fe22e05aee94cf4e4bf101209e30626c /ares_gethostbyname.3 | |
download | c-ares-5e847a14bd65383ce65f143c578e120899981fd9.tar.gz c-ares-5e847a14bd65383ce65f143c578e120899981fd9.tar.bz2 c-ares-5e847a14bd65383ce65f143c578e120899981fd9.zip |
ares 1.1.1 with collected applied patches
Diffstat (limited to 'ares_gethostbyname.3')
-rw-r--r-- | ares_gethostbyname.3 | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/ares_gethostbyname.3 b/ares_gethostbyname.3 new file mode 100644 index 0000000..9f5b07e --- /dev/null +++ b/ares_gethostbyname.3 @@ -0,0 +1,103 @@ +.\" $Id$ +.\" +.\" Copyright 1998 by the Massachusetts Institute of Technology. +.\" +.\" Permission to use, copy, modify, and distribute this +.\" software and its documentation for any purpose and without +.\" fee is hereby granted, provided that the above copyright +.\" notice appear in all copies and that both that copyright +.\" notice and this permission notice appear in supporting +.\" documentation, and that the name of M.I.T. not be used in +.\" advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. +.\" M.I.T. makes no representations about the suitability of +.\" this software for any purpose. It is provided "as is" +.\" without express or implied warranty. +.\" +.TH ARES_GETHOSTBYNAME 3 "25 July 1998" +.SH NAME +ares_gethostbyname \- Initiate a host query by name +.SH SYNOPSIS +.nf +.B #include <ares.h> +.PP +.B typedef void (*ares_host_callback)(void *\fIarg\fP, int \fIstatus\fP, +.B struct hostent *\fIhostent\fP) +.PP +.B void ares_gethostbyname(ares_channel \fIchannel\fP, const char *\fIname\fP, +.B int \fIfamily\fP, ares_host_callback \fIcallback\fP, void *\fIarg\fP) +.fi +.SH DESCRIPTION +The +.B ares_gethostbyname +function initiates a host query by name on the name service channel +identified by +.IR channel . +The parameter +.I name +gives the hostname as a NUL-terminated C string, and +.I family +gives the desired type of address for the resulting host entry. When +the query is complete or has failed, the ares library will invoke +.IR callback . +Completion or failure of the query may happen immediately, or may +happen during a later call to +.BR ares_process (3) +or +.BR ares_destroy (3). +.PP +The callback argument +.I arg +is copied from the +.B ares_gethostbyname +argument +.IR arg . +The callback argument +.I status +indicates whether the query succeeded and, if not, how it failed. It +may have any of the following values: +.TP 19 +.B ARES_SUCCESS +The host lookup completed successfully. +.TP 19 +.B ARES_ENOTIMP +The ares library does not know how to find addresses of type +.IR family . +.TP 19 +.B ARES_EBADNAME +The hostname +.B name +is composed entirely of numbers and periods, but is not a valid +representation of an Internet address. +.TP 19 +.B ARES_ENOTFOUND +The address +.I addr +was not found. +.TP 19 +.B ARES_ENOMEM +Memory was exhausted. +.TP 19 +.B ARES_EDESTRUCTION +The name service channel +.I channel +is being destroyed; the query will not be completed. +.PP +On successful completion of the query, the callback argument +.I hostent +points to a +.B struct hostent +containing the name of the host returned by the query. The callback +need not and should not attempt to free the memory pointed to by +.IR hostent ; +the ares library will free it when the callback returns. If the query +did not complete successfully, +.I hostent +will be +.BR NULL . +.SH SEE ALSO +.BR ares_process (3) +.SH AUTHOR +Greg Hudson, MIT Information Systems +.br +Copyright 1998 by the Massachusetts Institute of Technology. |