.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "libval_async 3" .TH libval_async 3 "2013-03-11" "perl v5.12.4" "Programmer's Manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" val_async_submit() \- submits a request for asynchronous processing of DNS queries. .PP val_async_select_info() \- set the appropriate file descriptors for outstanding asynchronous requests. .PP val_async_check_wait() \- handle timeouts or processes DNS responses to outstanding queries. .PP val_async_cancel() \- cancel an asynchronous query request. .PP val_async_cancel_all() \- cancel all asynchronous queries for a given context. .SH "SYNOPSIS" .IX Header "SYNOPSIS" #include .PP typedef int (*val_async_event_cb)(val_async_status *async_status, int event, val_context_t *context, void *cb_data, val_cb_params_t *cbp); .PP int val_async_submit(val_context_t *context, const char * name, int class, int type, unsigned int flags, val_async_event_cb callback, void *cb_data, val_async_status **async_status); .PP int val_async_select_info(val_context_t *context, fd_set *fds, int *num_fds, struct timeval *timeout); .PP int val_async_check_wait(val_context_t *context, fd_set *pending_desc, int *nfds, struct timeval *tv, unsigned int flags); .PP int val_async_cancel(val_context_t *context, val_async_status *as, unsigned int flags); .PP int val_async_cancel_all(val_context_t *context, unsigned int flags); .SH "DESCRIPTION" .IX Header "DESCRIPTION" The asynchronous \s-1DNSSEC\s0 validator \s-1API\s0 allows an application to submit multiple requests, which can be processed in parallel. In most cases, this will result in validation completing much sooner than a series of synchronous requests. .PP The \fIctx\fR parameter in the various functions below specifies the validation context, which can be set to \s-1NULL\s0 for default values (see \&\fI\fIlibval\fI\|(3)\fR and \fIdnsval.conf\fR for more details on validation contexts and alidation policy). .PP The \fI\fIval_async_submit()\fI\fR function submits a request for asynchronous processing of \s-1DNS\s0 queries for the data associated with the given domain \fIname\fR, \fIclass\fR and \fItype\fR. The \fIasync_status\fR object uniquely identifies a particular request and provides a handle for future operations on that asynchronous request, including cancelling it prior to lookup completion. .PP The \fIflags\fR parameter affects when and how often the callback is called. The following flags are defined. .IP "\fB\s-1VAL_AS_IGNORE_CACHE\s0\fR" 4 .IX Item "VAL_AS_IGNORE_CACHE" Don't use any internal cache for answers to this query. .IP "\fB\s-1VAL_AS_NO_NEW_QUERIES\s0\fR" 4 .IX Item "VAL_AS_NO_NEW_QUERIES" Don't send any new queries. Answers will be returned from the internal cache. .IP "\fB\s-1VAL_AS_NO_ANSWERS\s0\fR" 4 .IX Item "VAL_AS_NO_ANSWERS" Caller doesn't care about the answer results. This can be used for priming the cache. .IP "\fB\s-1VAL_AS_NO_CALLBACKS\s0\fR" 4 .IX Item "VAL_AS_NO_CALLBACKS" Don't call any callbacks. .IP "\fB\s-1VAL_AS_NO_CANCEL_CALLBACKS\s0\fR" 4 .IX Item "VAL_AS_NO_CANCEL_CALLBACKS" Call callbacks with results, but don't call any callbacks when the request is canceled. .IP "\fB\s-1VAL_AS_INTERIM_CALLBACKS\s0\fR" 4 .IX Item "VAL_AS_INTERIM_CALLBACKS" Call the callback function with interim results. If this flag is not specified, the callback function will only be called when all validation results are ready. .PP When results from the asynchronous call become available, the \&\fIcallback\fR function (if non-NULL) will be called with the \fIcb_data\fR value, originally supplied to the \fI\fIval_async_submit()\fI\fR call, as one of its arguments. The results from the lookup are returned in \fIcb_data\fR, which is a pointer to the \fIval_cb_params_t\fR structure shown below. .PP .Vb 9 \& typedef struct val_cb_params_s { \& val_status_t val_status; \& char *name; \& int class_h; \& int type_h; \& int retval; \& struct val_result_chain *results; \& struct val_answer_chain *answers; \& } val_cb_params_t; .Ve .PP The \fIval_cb_params_t\fR structure contains the orginal query parameters in \fIname\fR, \fIclass_h\fR and \fItype_h\fR respectively, the return value for the lookup operation in \fIretval\fR, pointers to the \fIresults\fR and \fIanswers\fR chains (see \fIlibval\fR\|(3) for more details), and the final validation status of the lookup operation in \fIval_status\fR. The application must release the memory associated with \fIresults\fR and \&\fIanswers\fR using the \fI\fIval_free_result_chain()\fI\fR and \&\fI\fIval_free_answer_chain()\fI\fR respectively (see \fIlibval\fR\|(3) for more details). .PP On completion of the asynchronous lookup operation, an event code is returned in \fIevent\fR. The following event types are defined: .IP "\fB\s-1VAL_AS_EVENT_COMPLETED\s0\fR" 4 .IX Item "VAL_AS_EVENT_COMPLETED" The request was completed. .IP "\fB\s-1VAL_AS_EVENT_INTERIM\s0\fR" 4 .IX Item "VAL_AS_EVENT_INTERIM" The request is still being processed, but some interim results are available. .IP "\fB\s-1VAL_AS_EVENT_CANCELED\s0\fR" 4 .IX Item "VAL_AS_EVENT_CANCELED" The request was canceled. The val_status, results and answers members of the callback parameter structure are undefined. .PP The \fI\fIval_async_select_info()\fI\fR function examines all outstanding asynchronous requests for the given context and sets the appropriate file descriptors, timeout value and maximum file descriptor value in preparation for a call to \fI\fIselect\fI\|(3)\fR. .PP The file descriptor for each socket awating a response is set in the \fIfds\fR parameter and \fImax_fd\fR is set to the highest file descriptor number of any pending asynchronous request unless that value is less than the current vaule of \fImax_fd\fR, in which case it is left unchanged. The \fItimeout\fR field is set to the lowest timeout value of any pending asynchronous query timeout which is less than the current value in this field by the application. .PP After the application calls \fI\fIselect\fI\|(3)\fR, it must also call \&\fI\fIval_async_check_wait()\fI\fR with the \fIfd_set\fR and the number of ready file descriptors, \fIndfs\fR, returned by \fI\fIselect()\fI\fR. The \&\fI\fIval_async_check_wait()\fI\fR function handles timeouts or processes \s-1DNS\s0 responses to outstanding queries. It also call callbacks for completed requests. .PP \&\fI\fIval_async_check_wait()\fI\fR provides two modes of operation. The first is for use with an application that has its own \fI\fIselect()\fI\fR loop. The applications sets its own file descriptors, calls \&\fI\fIval_async_select_info()\fI\fR to set file descriptors for pending queries and calls \fIselect(\fR). The \fIfds\fR and \fInfds\fR parameters from select are passed in to val_async_check_wait and the timeout value is ignored. If responses for a file descriptor are processed, the the appropriate file descriptor in \fIfds\fR is cleared and \fInfds\fR is decremented. .PP In the second mode of operation, the application can set \fIfds\fR and \&\fInfds\fR to \s-1NULL\s0 specify a value for \fItimeout\fR. Here, \&\fI\fIval_async_select_info()\fI\fR and \fI\fIselect()\fI\fR are called internally and any responses received before the timeout value expires are processed. .PP The \fI\fIval_async_cancel()\fI\fR function can be used to cancel the asynchronous request identified by its handle \fIas\fR, while \&\fI\fIval_async_cancel_all()\fI\fR can be used to cancel all asynchronous requests associated with a given context. The following flag may be set for the cancellation request. .IP "\fB\s-1VAL_AS_CANCEL_NO_CALLBACKS\s0\fR" 4 .IX Item "VAL_AS_CANCEL_NO_CALLBACKS" Do not call completed or cancelled callbacks. .SH "RETURN VALUES" .IX Header "RETURN VALUES" The \fI\fIval_async_submit()\fI\fR function returns \fB\s-1VAL_NO_ERROR\s0\fR on success and one of \fB\s-1VAL_RESOURCE_UNAVAILABLE\s0\fR, \fB\s-1VAL_BAD_ARGUMENT\s0\fR or \&\fB\s-1VAL_INTERNAL_ERROR\s0\fR on failure. .PP \&\fI\fIval_async_select_info()\fI\fR returns \fB\s-1VAL_NO_ERROR\s0\fR on success and \fB\s-1VAL_BAD_ARGUMENT\s0\fR if an illegal argument was passed to the function. .PP \&\fI\fIval_async_check_wait()\fI\fR returns 0 when no pending requests are found and a positive integer when requests are still pending. A value less than zero on error. .PP \&\fI\fIval_async_cancel()\fI\fR and \fI\fIval_async_cancel_all()\fI\fR return \&\fB\s-1VAL_NO_ERROR\s0\fR on success. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2004\-2013 \s-1SPARTA\s0, Inc. All rights reserved. See the \s-1COPYING\s0 file included with the DNSSEC-Tools package for details. .SH "AUTHORS" .IX Header "AUTHORS" Robert Story .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fI\fIlibval\fI\|(3)\fR .PP draft-hayatnagarkar-dnsext-validator-api .PP http://www.dnssec\-tools.org