X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=src%2Fadns.h;h=ba44b06c972add406a5c565d6aae008f1c1bb244;hb=HEAD;hp=e248c10e9bf1a58bfe96b300bf80830cc0bc55c9;hpb=58a876e5ac9539ff14acb7dc3ea3633f5bdb41d8;p=adns.git diff --git a/src/adns.h b/src/adns.h index e248c10..ba44b06 100644 --- a/src/adns.h +++ b/src/adns.h @@ -4,11 +4,8 @@ */ /* * - * This file is - * Copyright (C) 1997-2000,2003,2006,2014 Ian Jackson - * - * It is part of adns, which is - * Copyright (C) 1997-2000,2003,2006,2014 Ian Jackson + * This file is part of adns, which is + * Copyright (C) 1997-2000,2003,2006,2014-2016 Ian Jackson * Copyright (C) 1999-2000,2003,2006 Tony Finch * Copyright (C) 1991 Massachusetts Institute of Technology * @@ -50,8 +47,6 @@ * or the GNU Library General Public License, as appropriate, along * with this program; if not, write to the Free Software Foundation. * - * - * $Id$ */ #ifndef ADNS_H_INCLUDED @@ -105,6 +100,7 @@ typedef enum { /* In general, or together the desired flags: */ adns_if_noautosys= 0x0010,/* do not make syscalls at every opportunity */ adns_if_eintr= 0x0020,/* allow _wait and _synchronous to return EINTR */ adns_if_nosigpipe= 0x0040,/* applic has SIGPIPE ignored, do not protect */ + adns_if_monotonic= 0x0080,/* enable if you can; see adns_processtimeouts */ adns_if_checkc_entex=0x0100,/* consistency checks on entry/exit to adns fns */ adns_if_checkc_freq= 0x0300,/* consistency checks very frequently (slow!) */ @@ -130,6 +126,7 @@ typedef enum { /* In general, or together the desired flags: */ adns_qf_quoteok_anshost=0x00000040,/* ... in things supposedly hostnames */ adns_qf_quotefail_cname=0x00000080,/* refuse if quote-req chars in CNAME we go via */ adns_qf_cname_loose= 0x00000100,/* allow refs to CNAMEs - without, get _s_cname */ + adns_qf_cname_strict= 0x00010000,/* forbid CNAME refs (default, currently) */ adns_qf_cname_forbid= 0x00000200,/* don't follow CNAMEs, instead give _s_cname */ adns_qf_want_ipv4= 0x00000400,/* try to return IPv4 addresses */ @@ -489,6 +486,21 @@ typedef struct { * these approaches has optimal performance. */ +/* + * Use of time: + * + * adns needs to manipulate timeouts. For API compatibility reasons + * (adns predates clock_gettime) the default is to use wall clock time + * from gettimeofday. This will malfunction if the system clock is + * not suitably stable. To avoid this, you should set + * adns_if_monotonic + * + * If you specify adns_if_monotonic then all `now' values passed to + * adns must be from clock_gettime(CLOCK_MONOTONIC). clock_gettime + * returns a struct timespec; you must convert it to a struct timeval + * by dividing the nsec by 1000 to make usec, rounding down. + */ + int adns_init(adns_state *newstate_r, adns_initflags flags, FILE *diagfile /*0=>stderr*/); @@ -590,6 +602,12 @@ int adns_init_logfn(adns_state *newstate_r, adns_initflags flags, * Lookups occur (logically) concurrently; use the `sortlist' directive to * control the relative order of addresses in answers. This option * overrides the corresponding init flags (covered by adns_if_afmask). + * + * adns_ignoreunkcfg + * Ignore unknown options and configuration directives, rather than + * logging them. To be effective, appear in the configuration + * before the unknown options. ADNS_RES_OPTIONS is generally early + * enough. * * There are a number of environment variables which can modify the * behaviour of adns. They take effect only if adns_init is used, and @@ -710,8 +728,7 @@ int adns_addr2text(const struct sockaddr *sa, adns_queryflags flags, * port is always in host byte order and is simply copied to and * from the appropriate sockaddr field (byteswapped as necessary). * - * The only flags supported are adns_qf_addrlit_...; others are - * ignored. + * The only flags supported are adns_qf_addrlit_... * * Error return values are: * @@ -734,6 +751,8 @@ int adns_addr2text(const struct sockaddr *sa, adns_queryflags flags, * * EAFNOSUPPORT sa->sa_family is not supported (addr2text only). * + * ENOSYS Unsupported flags set. + * * Only if neither adns_qf_addrlit_scope_forbid nor * adns_qf_addrlit_scope_numeric are set: * @@ -816,6 +835,8 @@ int adns_processexceptional(adns_state ads, int fd, const struct timeval *now); * use that fd and only in the manner specified, regardless of whether * adns_if_noautosys was specified. * + * now is as for adns_processtimeouts. + * * adns_processexceptional should be called when select(2) reports an * exceptional condition, or poll(2) reports POLLPRI. * @@ -831,15 +852,19 @@ void adns_processtimeouts(adns_state ads, const struct timeval *now); /* Gives adns flow-of-control so that it can process any timeouts * which might have happened. Very like _processreadable/writeable. * - * now may be 0; if it isn't, *now must be the current time, recently - * obtained from gettimeofday. + * now may be 0; if it isn't, *now must be the current time from + * gettimeofday, or iff adns_if_monotonic it must be converted + * from the results of clock_gettime(CLOCK_MONOTONIC) (with the + * timespec.tv_nsec rounded down to make timeval.tv_usec). */ void adns_firsttimeout(adns_state ads, struct timeval **tv_mod, struct timeval *tv_buf, struct timeval now); /* Asks adns when it would first like the opportunity to time - * something out. now must be the current time, from gettimeofday. + * something out. + * + * now must be the current time, as for adns_processtimeouts. * * If tv_mod points to 0 then tv_buf must be non-null, and * _firsttimeout will fill in *tv_buf with the time until the first @@ -863,8 +888,9 @@ void adns_globalsystemfailure(adns_state ads); * adns_s_systemfail, and adns will close any stream sockets it has * open. * - * This is used by adns, for example, if gettimeofday() fails. - * Without this the program's event loop might start to spin ! + * This is used by adns, for example, if gettimeofday() or + * clock_gettime fails. Without this the program's event loop might + * start to spin ! * * This call will never block. */ @@ -880,9 +906,11 @@ void adns_beforeselect(adns_state ads, int *maxfd, fd_set *readfds, /* Find out file descriptors adns is interested in, and when it would * like the opportunity to time something out. If you do not plan to * block then tv_mod may be 0. Otherwise, tv_mod and tv_buf are as - * for adns_firsttimeout. readfds, writefds, exceptfds and maxfd_io may + * for adns_processtimeouts. readfds, writefds, exceptfds and maxfd_io may * not be 0. * + * now is as for adns_processtimeouts. + * * If tv_mod is 0 on entry then this will never actually do any I/O, * or change the fds that adns is using or the timeouts it wants. In * any case it won't block, and it will set the timeout to zero if a @@ -896,6 +924,8 @@ void adns_afterselect(adns_state ads, int maxfd, const fd_set *readfds, * select. This is just a fancy way of calling adns_processreadable/ * writeable/timeouts as appropriate, as if select had returned the * data being passed. Always succeeds. + * + * now is as for adns_processtimeouts. */ /* @@ -959,6 +989,8 @@ int adns_beforepoll(adns_state ads, struct pollfd *fds, * descriptors, and use _firsttimeout is used to find out when adns * might want to time something out.) * + * now is as for adns_processtimeouts. + * * adns_beforepoll will return 0 on success, and will not fail for any * reason other than the fds buffer being too small (ERANGE). * @@ -981,6 +1013,8 @@ void adns_afterpoll(adns_state ads, const struct pollfd *fds, int nfds, /* Gives adns flow-of-control for a bit; intended for use after * poll(2). fds and nfds should be the results from poll(). pollfd * structs mentioning fds not belonging to adns will be ignored. + * + * now is as for adns_processtimeouts. */ @@ -1051,8 +1085,13 @@ const char *adns_errtypeabbrev(adns_status st); * the abbreviation of the error - eg, for adns_s_timeout it returns * "timeout". adns_errtypeabbrev returns the abbreviation of the * error class: ie, for values up to adns_s_max_XXX it will return the - * string XXX. You MUST NOT call these functions with status values - * not returned by the same adns library. + * string XXX. + * + * If you call these functions with status values not actually + * returned from other functions in the same adns library, the + * returned information may be NULL. (You are also guaranteed + * that the return value will not be NULL for values in the + * adns_status enum, *except* for adns_s_max_XXXX.) */ #ifdef __cplusplus