Commit 940008bb authored by Pekka Pessi's avatar Pekka Pessi
Browse files

sresolv: updated documentation.

darcs-hash:20061109142909-65a35-195080ac3ae8c61ace0bef750a3871de9facc1e6.gz
parent 3f88b988
......@@ -580,7 +580,8 @@ sres_resolver_new(char const *conf_file_path)
/** Copy a resolver.
*
* Make a copy of resolver with old
* Make a copy of resolver sharing the configuration and cache with old
* resolver.
*/
sres_resolver_t *sres_resolver_copy(sres_resolver_t *res)
{
......@@ -612,7 +613,7 @@ sres_resolver_t *sres_resolver_copy(sres_resolver_t *res)
* RES_OPTIONS by giving the directives in the NULL-terminated list.
*
* @param conf_file_path name of the resolv.conf configuration file
* @param cache optional pointer to a resolver cache
* @param cache optional pointer to a resolver cache (may be NULL)
* @param option, ... list of resolv.conf options directives
* (overriding options in conf_file)
*
......@@ -873,13 +874,14 @@ sres_resolver_get_async(sres_resolver_t const *res,
* #sres_type_srv, and
* #sres_type_naptr.
*
* Deprecated query type sres_type_a6 is also decoded.
* Deprecated query type #sres_type_a6 is also decoded.
*
* @note The domain name is not concatenated with the domains from seach
* path or with the local domain Use sres_search() in order to try domains
* @note The domain name is @b not concatenated with the domains from seach
* path or with the local domain. Use sres_search() in order to try domains
* in search path.
*
* @sa sres_search(), sres_blocking_query(), sres_cached_answers()
* @sa sres_search(), sres_blocking_query(), sres_cached_answers(),
* sres_query_sockaddr()
*
* @ERRORS
* @ERROR EFAULT @a res or @a domain point outside the address space
......@@ -1060,7 +1062,20 @@ sres_search(sres_resolver_t *res,
* The @a type should be #sres_type_ptr. The @a addr should contain either
* IPv4 (AF_INET) or IPv6 (AF_INET6) address.
*
* If the "options"
* If the #SRES_OPTIONS environment variable, #RES_OPTIONS environment
* variable or an "options" entry in resolv.conf file contains an option
* "ip6-dotint", the IPv6 addresses are resolved using suffix ".ip6.int"
* instead of the standard ".ip6.arpa" suffix.
*
* @ERRORS
* @ERROR EAFNOSUPPORT address family specified in @a addr is not supported
* @ERROR ENETDOWN no DNS servers configured
* @ERROR EFAULT @a res or @a addr point outside the address space
* @ERROR ENOMEM memory exhausted
*
* @sa sres_query(), sres_blocking_query_sockaddr(),
* sres_cached_answers_sockaddr()
*
*/
sres_query_t *
sres_query_sockaddr(sres_resolver_t *res,
......@@ -1249,7 +1264,17 @@ sres_search_cached_answers(sres_resolver_t *res,
/**Get a list of matching (type/domain) reverse records from cache.
*
* @param res pointer to resolver
* @param type record type to query (or sres_qtype_any for any record)
* @param addr socket address structure
*
* The @a type should be #sres_type_ptr. The @a addr should contain either
* IPv4 (AF_INET) or IPv6 (AF_INET6) address.
*
* If the #SRES_OPTIONS environment variable, #RES_OPTIONS environment
* variable or an "options" entry in resolv.conf file contains an option
* "ip6-dotint", the IPv6 addresses are resolved using suffix ".ip6.int"
* instead of default ".ip6.arpa".
*
* @retval
* pointer to an array of pointers to cached records, or
......
......@@ -67,6 +67,7 @@ typedef struct sres_blocking_context_s sres_blocking_context_t;
#include "sofia-resolv/sres.h"
#include "sofia-resolv/sres_async.h"
#include <sofia-sip/su_errno.h>
#if HAVE_POLL
#include <poll.h>
......@@ -261,6 +262,13 @@ int sres_is_blocking(sres_resolver_t *res)
* @retval 0 if result was found from cache
* @retval -1 upon error
*
* @ERRORS
* @ERROR EFAULT @a res or @a domain point outside the address space
* @ERROR ENAMETOOLONG @a domain is longer than SRES_MAXDNAME
* @ERROR ENETDOWN no DNS servers configured
* @ERROR ENOMEM memory exhausted
* @ERROR EOPNOTSUPP resolver @ares is in asynchronous mode
*
* @sa sres_query(), sres_blocking_search()
*
* @note A blocking query converts a resolver object permanently into
......@@ -278,13 +286,13 @@ int sres_blocking_query(sres_resolver_t *res,
sres_record_t **cached;
if (return_records == NULL)
return errno = EFAULT, -1;
return su_seterrno(EFAULT);
*return_records = NULL;
c->block = sres_set_blocking(res);
if (c->block == NULL)
return -1; /* Resolver in asynchronous mode */
return su_seterrno(EOPNOTSUPP); /* Resolver in asynchronous mode */
if (!ignore_cache) {
cached = sres_cached_answers(res, type, domain);
......@@ -318,6 +326,13 @@ int sres_blocking_query(sres_resolver_t *res,
* @retval 0 if result was found from cache
* @retval -1 upon error
*
* @ERRORS
* @ERROR EFAULT @a res or @a domain point outside the address space
* @ERROR ENAMETOOLONG @a domain is longer than SRES_MAXDNAME
* @ERROR ENETDOWN no DNS servers configured
* @ERROR ENOMEM memory exhausted
* @ERROR EOPNOTSUPP resolver @ares is in asynchronous mode
*
* @sa sres_blocking_query(), sres_search()
*
* @note A blocking query converts a resolver object permanently into
......@@ -335,13 +350,13 @@ int sres_blocking_search(sres_resolver_t *res,
sres_record_t **cached;
if (return_records == NULL)
return errno = EFAULT, -1;
return su_seterrno(EFAULT);
*return_records = NULL;
c->block = sres_set_blocking(res);
if (c->block == NULL)
return -1; /* Resolver in asynchronous mode */
return su_seterrno(EOPNOTSUPP); /* Resolver in asynchronous mode */
if (!ignore_cache) {
cached = sres_search_cached_answers(res, type, name);
......@@ -370,7 +385,13 @@ int sres_blocking_search(sres_resolver_t *res,
* @retval 0 if result was found from cache
* @retval -1 upon error
*
* @sa sres_blocking_query(), sres_query_sockaddr()
* @ERRORS
* @ERROR EFAULT @a res or @a addr point outside the address space
* @ERROR ENOMEM memory exhausted
* @ERROR ENETDOWN no DNS servers configured
* @ERROR EOPNOTSUPP resolver @ares is in asynchronous mode
*
* @sa sres_blocking_query(), sres_query_sockaddr(), sres_cached_answers_sockaddr()
*
* @note A blocking query converts a resolver object permanently into
* blocking mode. If you need to make blocking and non-blocking queries, use
......@@ -393,7 +414,7 @@ int sres_blocking_query_sockaddr(sres_resolver_t *res,
c->block = sres_set_blocking(res);
if (c->block == NULL)
return -1; /* Resolver in asynchronous mode */
return su_seterrno(EOPNOTSUPP); /* Resolver in asynchronous mode */
if (!ignore_cache) {
cached = sres_cached_answers_sockaddr(res, type, addr);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment