jpayne@68: .\"
jpayne@68: .\" Copyright 1998 by the Massachusetts Institute of Technology.
jpayne@68: .\" SPDX-License-Identifier: MIT
jpayne@68: .\"
jpayne@68: .TH ARES_GETHOSTBYADDR 3 "24 July 1998"
jpayne@68: .SH NAME
jpayne@68: ares_gethostbyaddr \- Initiate a host query by address
jpayne@68: .SH SYNOPSIS
jpayne@68: .nf
jpayne@68: #include <ares.h>
jpayne@68: 
jpayne@68: typedef void (*ares_host_callback)(void *\fIarg\fP, int \fIstatus\fP,
jpayne@68:                                    int \fItimeouts\fP,
jpayne@68:                                    struct hostent *\fIhostent\fP)
jpayne@68: 
jpayne@68: void ares_gethostbyaddr(ares_channel_t *\fIchannel\fP, const void *\fIaddr\fP,
jpayne@68:                         int \fIaddrlen\fP, int \fIfamily\fP,
jpayne@68:                         ares_host_callback \fIcallback\fP, void *\fIarg\fP)
jpayne@68: .fi
jpayne@68: .SH DESCRIPTION
jpayne@68: The
jpayne@68: .B ares_gethostbyaddr
jpayne@68: function initiates a host query by address on the name service channel
jpayne@68: identified by
jpayne@68: .IR channel .
jpayne@68: The parameters
jpayne@68: .I addr
jpayne@68: and
jpayne@68: .I addrlen
jpayne@68: give the address as a series of bytes, and
jpayne@68: .I family
jpayne@68: gives the type of address.  When the query is complete or has failed, the ares
jpayne@68: library will invoke \fIcallback\fP.  Completion or failure of the query may
jpayne@68: happen immediately, or may happen during a later call to
jpayne@68: \fIares_process(3)\fP, \fIares_destroy(3)\fP or \fIares_cancel(3)\fP.
jpayne@68: .PP
jpayne@68: The callback argument
jpayne@68: .I arg
jpayne@68: is copied from the
jpayne@68: .B ares_gethostbyaddr
jpayne@68: argument
jpayne@68: .IR arg .
jpayne@68: The callback argument
jpayne@68: .I status
jpayne@68: indicates whether the query succeeded and, if not, how it failed.  It
jpayne@68: may have any of the following values:
jpayne@68: .TP 19
jpayne@68: .B ARES_SUCCESS
jpayne@68: The host lookup completed successfully.
jpayne@68: .TP 19
jpayne@68: .B ARES_ENOTIMP
jpayne@68: The ares library does not know how to look up addresses of type
jpayne@68: .IR family .
jpayne@68: .TP 19
jpayne@68: .B ARES_ENOTFOUND
jpayne@68: The address
jpayne@68: .I addr
jpayne@68: was not found.
jpayne@68: .TP 19
jpayne@68: .B ARES_ENOMEM
jpayne@68: Memory was exhausted.
jpayne@68: .TP 19
jpayne@68: .B ARES_ECANCELLED
jpayne@68: The query was cancelled.
jpayne@68: .TP 19
jpayne@68: .B ARES_EDESTRUCTION
jpayne@68: The name service channel
jpayne@68: .I channel
jpayne@68: is being destroyed; the query will not be completed.
jpayne@68: .PP
jpayne@68: The callback argument
jpayne@68: .I timeouts
jpayne@68: reports how many times a query timed out during the execution of the
jpayne@68: given request.
jpayne@68: .PP
jpayne@68: On successful completion of the query, the callback argument
jpayne@68: .I hostent
jpayne@68: points to a
jpayne@68: .B struct hostent
jpayne@68: containing the name of the host returned by the query.  The callback
jpayne@68: need not and should not attempt to free the memory pointed to by
jpayne@68: .IR hostent ;
jpayne@68: the ares library will free it when the callback returns.  If the query
jpayne@68: did not complete successfully,
jpayne@68: .I hostent
jpayne@68: will be
jpayne@68: .BR NULL .
jpayne@68: .PP
jpayne@68: When the associated callback is called, it is called with a channel lock so care
jpayne@68: must be taken to ensure any processing is minimal to prevent DNS channel stalls.
jpayne@68: 
jpayne@68: The callback may be triggered from a different thread than the one which
jpayne@68: called \fIares_gethostbyaddr(3)\fP.
jpayne@68: 
jpayne@68: For integrators running their own event loops and not using \fBARES_OPT_EVENT_THREAD\fP,
jpayne@68: care needs to be taken to ensure any file descriptor lists are updated immediately
jpayne@68: within the eventloop when notified.
jpayne@68: .SH SEE ALSO
jpayne@68: .BR ares_process (3),
jpayne@68: .BR ares_gethostbyname (3)