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

# [NAME](#NAME)

ares\_getnameinfo - Address-to-nodename translation in protocol-independent manner

# [SYNOPSIS](#SYNOPSIS)

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


                                       int timeouts, char *node,


                                       char *service)
void ares_getnameinfo(ares_channel_t *channel, const struct sockaddr *sa,


                      ares_socklen_t salen, int flags,


                      ares_nameinfo_callback callback, void *arg)
```

# [DESCRIPTION](#DESCRIPTION)

The **ares\_getnameinfo** function is defined for protocol-independent address translation. The function is a combination of [*ares\_gethostbyaddr(3)*](/man/os/c-ares/ares_gethostbyaddr.3) and [*getservbyport(3)*](/man/os/c-ares/getservbyport.3). The function will translate the address either by executing a host query on the name service channel identified by *channel* or it will attempt to resolve it locally if possible. The parameters *sa* and *len* give the address as a sockaddr structure, and *flags* gives the options that the function will use. Valid flags are listed below:

[**ARES\_NI\_NOFQDN**](#ARES_NI_NOFQDN)

Only the nodename portion of the FQDN is returned for local hosts.

[**ARES\_NI\_NUMERICHOST**](#ARES_NI_NUMERICHOST)

The numeric form of the hostname is returned rather than the name.

[**ARES\_NI\_NAMEREQD**](#ARES_NI_NAMEREQD)

An error is returned if the hostname cannot be found in the DNS.

[**ARES\_NI\_NUMERICSERV**](#ARES_NI_NUMERICSERV)

The numeric form of the service is returned rather than the name.

[**ARES\_NI\_TCP**](#ARES_NI_TCP)

The service name is to be looked up for the TCP protocol.

[**ARES\_NI\_UDP**](#ARES_NI_UDP)

The service name is to be looked up for the UDP protocol.

[**ARES\_NI\_SCTP**](#ARES_NI_SCTP)

The service name is to be looked up for the SCTP protocol.

[**ARES\_NI\_DCCP**](#ARES_NI_DCCP)

The service name is to be looked up for the DCCP protocol.

[**ARES\_NI\_NUMERICSCOPE**](#ARES_NI_NUMERICSCOPE)

The numeric form of the scope ID is returned rather than the name.

[**ARES\_NI\_LOOKUPHOST**](#ARES_NI_LOOKUPHOST)

A hostname lookup is being requested.

[**ARES\_NI\_LOOKUPSERVICE**](#ARES_NI_LOOKUPSERVICE)

A service name lookup is being requested.

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).

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\_getnameinfo(3)*](/man/os/c-ares/ares_getnameinfo.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.

The callback argument *arg* is copied from the **ares\_getnameinfo** 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.

[**ARES\_EBADFLAGS**](#ARES_EBADFLAGS)

The *flags* parameter contains an illegal value.

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 *node* contains a string representing the hostname (assuming **ARES\_NI\_LOOKUPHOST** was specified). Additionally, *service* contains a string representing the service name (assuming **ARES\_NI\_LOOKUPSERVICE** was specified). If the query did not complete successfully, or one of the values was not requested, *node* or *service* will be **NULL**.

The *node* and *service* strings are owned by the c-ares library and are only valid for the duration of the callback. The callback **must not** modify or free them, and must not retain references to them after returning; treat them as read-only. The parameters are intentionally not declared **const** solely to preserve API/ABI compatibility with existing applications.

# [SEE ALSO](#SEE_ALSO)

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

1 May 2009

---

Document: ares_getnameinfo(3) from c-ares 1.34.8-r4 (Chainguard OS)
Source: https://github.com/c-ares/c-ares