ARES\_GETHOSTBYADDR(3) Library Functions Manual ARES\_GETHOSTBYADDR(3)

# [NAME](#NAME)

ares\_gethostbyaddr - Initiate a host query by address

# [SYNOPSIS](#SYNOPSIS)

```
#include <ares.h>
typedef void (*ares_host_callback)(void *arg, int status,


                                   int timeouts,


                                   struct hostent *hostent)
void ares_gethostbyaddr(ares_channel_t *channel, const void *addr,


                        int addrlen, int family,


                        ares_host_callback callback, void *arg)
```

# [DESCRIPTION](#DESCRIPTION)

The **ares\_gethostbyaddr** function initiates a host query by address on the name service channel identified by *channel*. The parameters *addr* and *addrlen* give the address as a series of bytes, and *family* gives the type of address. When the query is complete or has failed, the ares library will invoke *callback*. Completion or failure of the query may happen immediately, or may happen during a later call to [*ares\_process(3)*](/man/os/c-ares/ares_process.3), [*ares\_destroy(3)*](/man/os/c-ares/ares_destroy.3) or [*ares\_cancel(3)*](/man/os/c-ares/ares_cancel.3).

The callback argument *arg* is copied from the **ares\_gethostbyaddr** argument *arg*. The callback argument *status* indicates whether the query succeeded and, if not, how it failed. It may have any of the following values:

[**ARES\_SUCCESS**](#ARES_SUCCESS)

The host lookup completed successfully.

[**ARES\_ENOTIMP**](#ARES_ENOTIMP)

The ares library does not know how to look up addresses of type *family*.

[**ARES\_ENOTFOUND**](#ARES_ENOTFOUND)

The address *addr* was not found.

[**ARES\_ENOMEM**](#ARES_ENOMEM)

Memory was exhausted.

[**ARES\_ECANCELLED**](#ARES_ECANCELLED)

The query was cancelled.

[**ARES\_EDESTRUCTION**](#ARES_EDESTRUCTION)

The name service channel *channel* is being destroyed; the query will not be completed.

The callback argument *timeouts* reports how many times a query timed out during the execution of the given request.

On successful completion of the query, the callback argument *hostent* points to a **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 *hostent*; the ares library will free it when the callback returns. The callback **must not** modify the **struct hostent** or retain a reference to it after returning; it is owned by c-ares and is only valid for the duration of the callback. The parameter is intentionally not declared **const** solely to preserve API/ABI compatibility with existing applications. If the query did not complete successfully, *hostent* will be **NULL**.

When the associated callback is called, it is called with a channel lock so care must be taken to ensure any processing is minimal to prevent DNS channel stalls.

The callback may be triggered from a different thread than the one which called [*ares\_gethostbyaddr(3)*](/man/os/c-ares/ares_gethostbyaddr.3).

For integrators running their own event loops and not using **ARES\_OPT\_EVENT\_THREAD**, care needs to be taken to ensure any file descriptor lists are updated immediately within the eventloop when notified.

# [SEE ALSO](#SEE_ALSO)

[**ares\_process**(3)](/man/os/c-ares/ares_process.3), [**ares\_gethostbyname**(3)](/man/os/c-ares/ares_gethostbyname.3)

24 July 1998

---

Document: ares_gethostbyaddr(3) from c-ares 1.34.9-r0 (Chainguard OS)
Source: https://github.com/c-ares/c-ares