Provided by: librbl-dev_2.11.0~alpha-11build1_amd64 bug

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)