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

# [NAME](#NAME)

ares\_gethostbyname - Initiate a host query by name

# [SYNOPSIS](#SYNOPSIS)

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


                                   int timeouts,


                                   struct hostent *hostent)
void ares_gethostbyname(ares_channel_t *channel, const char *name,


                        int family, ares_host_callback callback,


                        void *arg)
```

# [DESCRIPTION](#DESCRIPTION)

The **ares\_gethostbyname** function initiates a host query by name on the name service channel identified by *channel*. The parameter *name* gives the hostname as a NUL-terminated C string, and *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 *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\_gethostbyname** 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 find addresses of type *family*.

[**ARES\_EBADNAME**](#ARES_EBADNAME)

The hostname **name** is composed entirely of numbers and periods, but is not a valid representation of an Internet address.

[**ARES\_ENODATA**](#ARES_ENODATA)

There was no data returned to extract a result from.

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

The name *name* 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\_gethostbyname(3)*](/man/os/c-ares/ares_gethostbyname.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\_gethostbyaddr**(3)](/man/os/c-ares/ares_gethostbyaddr.3)

25 July 1998

---

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