Provided by: librbl-dev_2.11.0~alpha-11build1_amd64 
NAME
rbl_init(), rbl_close(), rbl_geterror(), rbl_setdomain(), rbl_query_start(),
rbl_query_check(), rbl_query_cancel(), rbl_settimeout(), rbl_setcallbackint(),
rbl_setcallbackctx(), rbl_setdnscallback(), rbl_dns_set_query_service(),
rbl_dns_set_query_start(), rbl_dns_set_query_cancel(), rbl_dns_set_query_waitreply(),
rbl_dns_set_init(), rbl_dns_set_close(), rbl_dns_set_nslist(), rbl_dns_set_config(),
rbl_dns_set_trustanchor(), rbl_dns_init() - Realtime Blacklist (RBL) service facility
SYNOPSIS
#include <rbl.h>
RBL * rbl_init (void *(* mallocf )(void *, size_t), void (* freef )(void *, void *p), void
* closure );
unsigned char * rbl_geterror (RBL * rbl );
void rbl_setdomain (RBL * rbl, unsigned char * qroot );
RBL_STAT rbl_query_start (RBL * rbl, unsigned char * query, void ** qh );
RBL_STAT rbl_settimeout (RBL * rbl, unsigned int timeout );
RBL_STAT rbl_setcallbackint (RBL * rbl, unsigned int cbint );
RBL_STAT rbl_setcallbackctx (RBL *, rbl, void * ctx );
RBL_STAT rbl_setdnscallback (RBL *, rbl, void (* func )(const void *));
void * rbl_dns_set_query_service (RBL * rbl, void * svc );
void rbl_dns_set_query_cancel (RBL * rbl, int (* func )(void *, void *));
void rbl_dns_set_query_start (RBL * rbl, int (* func )(void *, int, unsigned char *,
unsigned char *, size_t, void **));
void rbl_dns_set_query_waitreply (RBL * rbl, int (* func )(void *, void *, struct timeval
*, size_t *, int *, int *));
void rbl_dns_set_init (RBL * rbl, int (* func )(void **);
void rbl_dns_set_close (RBL * rbl, int (* func )(void *);
void rbl_dns_set_config (RBL * rbl, int (* func )(void *, const char *);
void rbl_dns_set_nslist (RBL * rbl, int (* func )(void *, const char *);
void rbl_dns_set_trustanchor (RBL * rbl, int (* func )(void *, const char *);
RBL_STAT rbl_dns_init (RBL * rbl );
void rbl_close (RBL * rbl );
DESCRIPTION
These functions are an interface to a facility to conduct Realtime Blacklist (RBL) queries
and return their results. RBLs are described in RFC5782.
An application first initializes the package by calling rbl_init(). The optional mallocf
parameter is a caller-provided memory allocation function taking a pointer to a caller-
provided opaque data structure (the closure parameter) and a number of bytes to allocate.
If mallocf is not provided, the default system memory allocator function malloc(3) is
used. The optional freef parameter specifies a matching caller-provided memory
deallocator function, taking a pointer to a caller-provided opaque data structure (the
closure parameter) and a pointer to the memory to be released. If freef is not provided,
the default system memory release function free(3) is used. A handle for future use of
the initialized library instance is returned, or NULL on error and errno will be set to
indicate the cause of the failure.
The rbl_geterror() function can be used to poll the library for an error string that
provides further description for the most recent failed operation.
A call to rbl_setdomain() sets the RBL's base domain. This specifies the "root" of all
future queries for the provided rbl handle to qroot. Future queries passed to this handle
will be prepended to the string provided here.
A query is initialized with a call to rbl_query_start() which takes an RBL library handle
as rbl, the string to be queried as query, and a pointer to a void pointer that will be
updated to contain a reference to the initiated query as qh.
A query previously started by rbl_query_start() can be canceled by calling
rbl_query_cancel(), passing it an RBL library handle as rbl and a query handle as qh as
previously returned when the query was started.
A query previously started by rbl_query_start() can be polled for its status or a result
using rbl_query_check(), passing it an RBL library handle as rbl, a query handle as qh, a
pointer to a "struct timeval" ast timeout (which can be NULL if an infinite wait is
acceptable), and a pointer to a 32-bit integer as res into which any result will be
returned (or it can be NULL if the caller doesn't actually want the result). Results are
in network byte order. If this function returns RBL_STAT_FOUND or RBL_STAT_NOTFOUND, the
query is automatically canceled and need not be passed to rbl_query_cancel().
The rbl_settimeout() function can be used to change the query timeout. The default is ten
seconds.
If it is useful to have the library periodically call a user-provided function as an
indication that queries are still in progress, such a function can be registered with the
rbl_setdnscallback() function. The function provided should take a void context pointer
as its sole argument. rbl_setcallbackctx() is used to tell the library what context
pointer should be used, and rbl_setcallbackint() is used to tell the library what
frequency, in seconds, should be used to call that callback function. Each of these takes
the corresponding RBL library handle as its first argument, and the obvious parameter for
its second.
By default, the library will use the stock system resolver to conduct DNS queries. If
alternates should be used, these can be specified using the following functions:
rbl_dns_set_query_service() sets a context pointer to the query service to be used, if
any. This will be passed as-is to the other DNS functions. It returns its previous
value.
rbl_dns_set_query_cancel() sets a pointer to the function that should be called to cancel
an open query, and should take the following parameters: a void pointer to the DNS query
service to be used, and a void pointer to a query handle as previously returned by a call
to rbl_dns_set_query_start(). The function should return one of the DNS result codes
described below.
rbl_dns_set_query_start() sets a pointer to the function that should be called to initiate
a new query, and should take the following parameters: a void pointer to the DNS query
service to be used, a DNS record type (e.g. T_TXT), a pointer to a string containing the
query to be started, a pointer to a buffer into which the reply should be written, the
number of bytes available in that buffer, and a pointer to a void pointer that will be
updated to contain a unique handle for that query once started. The function should
return one of the DNS result codes described below.
rbl_dns_set_query_waitreply() sets a pointer to the function that should be called to wait
for a reply to an open query, and should take the following parameters: a void pointer to
the DNS query service to be used, a void pointer referencing the query of interest as
previously returned by a call to rbl_dns_set_query_start(), a pointer to a "struct
timeval" structure indicating how long the function should wait for a reply (or NULL if
infinite waiting is acceptable), a pointer to a "size_t" that will be updated to contain
the size of the received reply, a pointer to an integer that will contain an error code if
the query fails (can be NULL if that information is not interesting to the caller), and a
pointer to an integer that will contain a DNSSEC status indication (can be NULL if that
information is not interesting to the caller). The function should return one of the DNS
result codes described below.
rbl_dns_set_init() sets a pointer to the function that should be called when it is
necessary to initialize a resolver. The function should store a handle to the initialized
resolver and return zero, or return non-zero if initialization could not be completed.
The function specified here is called before the first call to the query start function
(see above).
rbl_dns_set_close() sets a pointer to the function that should be called when it is
necessary to terminate a resolver. The function will receive a handle referencing the
resolver to be terminated, and should return zero on success or non-zero on failure.
rbl_dns_set_nslist() sets a pointer to the function that should be called when it is
necessary to change the set of nameservers that are to be used to resolve RBL queries.
The function will receive a handle referencing the active resolver and a string containing
a comma-separated list of nameservers to use. It should return zero on success and non-
zero on failure.
rbl_dns_set_config() sets a pointer to the function that should be called when it is
necessary to provide arbitrary configuration information to the resolver. The function
will receive a handle referencing the active resolver and a string containing the
configuration. It should return zero on success and non-zero on failure.
rbl_dns_set_trustanchor() sets a pointer to the function that should be called when it is
necessary to provide trust anchor information (supporting DNSSEC) to the resolver. The
function will receive a handle referencing the active resolver and a string containing the
trust anchor data. It should return zero on success and non-zero on failure.
Calling rbl_dns_init() forces (re-)initialization of the resolver. This essentially
causes the library to call any initialization function defined by rbl_dns_set_init().
When the library handle is no longer needed, it should be passed to rbl_close().
RETURN VALUES
The following return codes, of type RBL_STAT, can be returned:
RBL_STAT_OK
successful completion
RBL_STAT_INVALID
operation failed because an invalid parameter was provided
RBL_STAT_DNSERROR
operation could not be completed because of errors requesting or receiving a DNS
reply; note that this does not include a successful reply that contains a "no
record found" result, which is a successful answer
RBL_STAT_NORESOURCE
a caller-provided buffer was too small to complete the requested operation, or a
memory or file descriptor allocation failed
RBL_STAT_NOTIMPLEMENT
an optional library feature was not selected at compilation time
RBL_STAT_FOUND
the requested record was found in the RBL
RBL_STAT_NOTFOUND
the requested record was not found in the RBL (but the query did complete)
RBL_STAT_NOREPLY
a call to rbl_query_check() timed out before a result could be returned
RBL_STAT_EXPIRED
the underlying resolver reported that the query expired; this is included to
support resolvers that have an overall query timeout as well as a single wait
timeout
DNS RETURN CODES
Any registered DNS functions should return one of the following result codes:
RBL_DNS_ERROR
An error occurred. The cause of the error can be retrieved using rbl_geterror().
RBL_DNS_SUCCESS
The operation was successful.
RBL_DNS_REPLY
A reply is available (returned by the "waitreply" function).
RBL_DNS_NOREPLY
No reply was received by the time the query timeout was reached (returned by the
"waitreply" function).
RBL_DNS_EXPIRED
The query expired completely (returned by the "waitreply" function). Some
resolvers set an overall timeout for the query at start time in addition to one for
each single wait request; this code indicates the former timeout expired.
COPYRIGHT
Copyright (c) 2010-2013, The Trusted Domain Project. All rights reserved.
SEE ALSO
intro(2)
librbl(3)