asyncns.h File Reference

Go to the source code of this file.

## Typedefs

typedef struct asyncns | asyncns_t
| An opaque libasyncns session structure.
typedef struct asyncns_query | asyncns_query_t
| An opaque libasyncns query structure.

## Functions

asyncns_t * | asyncns_new (unsigned n_proc)
| Allocate a new libasyncns session with n_proc worker processes/threads.
void | asyncns_free (asyncns_t *asyncns)
| Free a libasyncns session.
int | asyncns_fd (asyncns_t *asyncns)
| Return the UNIX file descriptor to select() for readability on.
int | asyncns_wait (asyncns_t *asyncns, int block)
| Process pending responses.
asyncns_query_t * | asyncns_getaddrinfo (asyncns_t *asyncns, const char *node, const char *service, const struct addrinfo *hints)
| Issue a name to address query on the specified session.
int | asyncns_getaddrinfo_done (asyncns_t *asyncns, asyncns_query_t *q, struct addrinfo **ret_res)
| Retrieve the results of a preceding asyncns_getaddrinfo() call.
asyncns_query_t * | asyncns_getnameinfo (asyncns_t *asyncns, const struct sockaddr *sa, socklen_t salen, int flags, int gethost, int getserv)
| Issue an address to name query on the specified session.
int | asyncns_getnameinfo_done (asyncns_t *asyncns, asyncns_query_t *q, char *ret_host, size_t hostlen, char *ret_serv, size_t servlen)
| Retrieve the results of a preceding asyncns_getnameinfo() call.
asyncns_query_t * | asyncns_res_query (asyncns_t *asyncns, const char *dname, int class, int type)
| Issue a resolver query on the specified session.
asyncns_query_t * | asyncns_res_search (asyncns_t *asyncns, const char *dname, int class, int type)
| Issue an resolver query on the specified session.
int | asyncns_res_done (asyncns_t *asyncns, asyncns_query_t *q, unsigned char **answer)
| Retrieve the results of a preceding asyncns_res_query() or asyncns_res_search call.
asyncns_query_t * | asyncns_getnext (asyncns_t *asyncns)
| Return the next completed query object.
int | asyncns_getnqueries (asyncns_t *asyncns)
| Return the number of query objects (completed or not) attached to this session.
void | asyncns_cancel (asyncns_t *asyncns, asyncns_query_t *q)
| Cancel a currently running query.
void | asyncns_freeaddrinfo (struct addrinfo *ai)
| Free the addrinfo structure as returned by asyncns_getaddrinfo_done().
void | asyncns_freeanswer (unsigned char *answer)
| Free the answer data as returned by asyncns_res_done().
int | asyncns_isdone (asyncns_t *asyncns, asyncns_query_t *q)
| Returns non-zero when the query operation specified by q has been completed.
void | asyncns_setuserdata (asyncns_t *asyncns, asyncns_query_t *q, void *userdata)
| Assign some opaque userdata with a query object.
void * | asyncns_getuserdata (asyncns_t *asyncns, asyncns_query_t *q)
| Return userdata assigned to a query object.

## Typedef Documentation

## asyncns_query_t

typedef struct asyncns_query asyncns_query_t

An opaque libasyncns query structure.

## asyncns_t

typedef struct asyncns asyncns_t

An opaque libasyncns session structure.

## Function Documentation

## asyncns_cancel()

void asyncns_cancel | ( | asyncns_t * | asyncns,
|  | asyncns_query_t * | q
| ) |  |

Cancel a currently running query.

q is is destroyed by this call and may not be used any futher.

## asyncns_fd()

int asyncns_fd | ( | asyncns_t * | asyncns | ) |

Return the UNIX file descriptor to select() for readability on.

Use this function to integrate libasyncns with your custom main loop.

## asyncns_free()

void asyncns_free | ( | asyncns_t * | asyncns | ) |

Free a libasyncns session.

This destroys all attached asyncns_query_t objects automatically

Examples
  asyncns-test.c.

## asyncns_freeaddrinfo()

void asyncns_freeaddrinfo | ( | struct addrinfo * | ai | ) |

Free the addrinfo structure as returned by asyncns_getaddrinfo_done().

Make sure to use this functions instead of the libc's freeaddrinfo()!

Examples
  asyncns-test.c.

## asyncns_freeanswer()

void asyncns_freeanswer | ( | unsigned char * | answer | ) |

Free the answer data as returned by asyncns_res_done().

Examples
  asyncns-test.c.

## asyncns_getaddrinfo()

asyncns_query_t * asyncns_getaddrinfo | ( | asyncns_t * | asyncns,
|  | const char * | node,
|  | const char * | service,
|  | const struct addrinfo * | hints
| ) |  |

Issue a name to address query on the specified session.

The arguments are compatible with the ones of libc's getaddrinfo(3). The function returns a new query object. When the query is completed you may retrieve the results using asyncns_getaddrinfo_done().

Examples
  asyncns-test.c.

## asyncns_getaddrinfo_done()

int asyncns_getaddrinfo_done | ( | asyncns_t * | asyncns,
|  | asyncns_query_t * | q,
|  | struct addrinfo ** | ret_res
| ) |  |

Retrieve the results of a preceding asyncns_getaddrinfo() call.

Returns a addrinfo structure and a return value compatible with libc's getaddrinfo(3). The query object q is destroyed by this call and may not be used any further. Make sure to free the returned addrinfo structure with asyncns_freeaddrinfo() and not libc's freeaddrinfo(3)! If the query is not completed yet EAI_AGAIN is returned.

Examples
  asyncns-test.c.

## asyncns_getnameinfo()

asyncns_query_t * asyncns_getnameinfo | ( | asyncns_t * | asyncns,
|  | const struct sockaddr * | sa,
|  | socklen_t | salen,
|  | int | flags,
|  | int | gethost,
|  | int | getserv
| ) |  |

Issue an address to name query on the specified session.

The arguments are compatible with the ones of libc's getnameinfo(3). The function returns a new query object. When the query is completed you may retrieve the results using asyncns_getnameinfo_done(). Set gethost (resp. getserv) to non-zero if you want to query the hostname (resp. the service name).

Examples
  asyncns-test.c.

## asyncns_getnameinfo_done()

int asyncns_getnameinfo_done | ( | asyncns_t * | asyncns,
|  | asyncns_query_t * | q,
|  | char * | ret_host,
|  | size_t | hostlen,
|  | char * | ret_serv,
|  | size_t | servlen
| ) |  |

Retrieve the results of a preceding asyncns_getnameinfo() call.

Returns the hostname and the service name in ret_host and ret_serv. The query object q is destroyed by this call and may not be used any further. If the query is not completed yet EAI_AGAIN is returned.

Examples
  asyncns-test.c.

## asyncns_getnext()

asyncns_query_t * asyncns_getnext | ( | asyncns_t * | asyncns | ) |

Return the next completed query object.

If no query has been completed yet, return NULL. Please note that you need to run asyncns_wait() before this function will return sensible data.

## asyncns_getnqueries()

int asyncns_getnqueries | ( | asyncns_t * | asyncns | ) |

Return the number of query objects (completed or not) attached to this session.

## asyncns_getuserdata()

void * asyncns_getuserdata | ( | asyncns_t * | asyncns,
|  | asyncns_query_t * | q
| ) |  |

Return userdata assigned to a query object.

Use asyncns_setuserdata() to set this data. If no data has been set prior to this call it returns NULL.

## asyncns_isdone()

int asyncns_isdone | ( | asyncns_t * | asyncns,
|  | asyncns_query_t * | q
| ) |  |

Returns non-zero when the query operation specified by q has been completed.

Examples
  asyncns-test.c.

## asyncns_new()

asyncns_t * asyncns_new | ( | unsigned | n_proc | ) |

Allocate a new libasyncns session with n_proc worker processes/threads.

Examples
  asyncns-test.c.

## asyncns_res_done()

int asyncns_res_done | ( | asyncns_t * | asyncns,
|  | asyncns_query_t * | q,
|  | unsigned char ** | answer
| ) |  |

Retrieve the results of a preceding asyncns_res_query() or asyncns_res_search call.

The query object q is destroyed by this call and may not be used any further. Returns a pointer to the answer of the res_query call. If the query is not completed yet -EAGAIN is returned, on failure -errno is returned, otherwise the length of answer is returned. Make sure to free the answer is a call to asyncns_freeanswer().

Examples
  asyncns-test.c.

## asyncns_res_query()

asyncns_query_t * asyncns_res_query | ( | asyncns_t * | asyncns,
|  | const char * | dname,
|  | int | class,
|  | int | type
| ) |  |

Issue a resolver query on the specified session.

The arguments are compatible with the ones of libc's res_query(3). The function returns a new query object. When the query is completed you may retrieve the results using asyncns_res_done().

Examples
  asyncns-test.c.

## asyncns_res_search()

asyncns_query_t * asyncns_res_search | ( | asyncns_t * | asyncns,
|  | const char * | dname,
|  | int | class,
|  | int | type
| ) |  |

Issue an resolver query on the specified session.

The arguments are compatible with the ones of libc's res_search(3). The function returns a new query object. When the query is completed you may retrieve the results using asyncns_res_done().

## asyncns_setuserdata()

void asyncns_setuserdata | ( | asyncns_t * | asyncns,
|  | asyncns_query_t * | q,
|  | void * | userdata
| ) |  |

Assign some opaque userdata with a query object.

## asyncns_wait()

int asyncns_wait | ( | asyncns_t * | asyncns,
|  | int | block
| ) |  |

Process pending responses.

After this function is called you can get the next completed query object(s) using asyncns_getnext(). If block is non-zero wait until at least one response has been processed. If block is zero, process all pending responses and return.

Examples
  asyncns-test.c.