From: Wouter Wijngaards Date: Wed, 1 Apr 2009 12:57:13 +0000 (+0000) Subject: new libunbound calls documented. X-Git-Tag: release-1.3.0~52 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7ad28caa4136031d18f8dcde40a8307a9151557a;p=thirdparty%2Funbound.git new libunbound calls documented. git-svn-id: file:///svn/unbound/trunk@1571 be551aaa-1e26-0410-a405-d3ace91eadb9 --- diff --git a/doc/Changelog b/doc/Changelog index 68c114e50..dc0b8fae8 100644 --- a/doc/Changelog +++ b/doc/Changelog @@ -3,6 +3,7 @@ ipv6 AAAA records for their nameservers with ipv4 mapped contents. Still tries to do so, could work when deployed in intranet. Higher verbosity shows the error. + - new libunbound calls documented. 30 March 2009: Wouter - Fixup LDFLAGS from libevent sourcedir compile configure restore. diff --git a/doc/libunbound.3.in b/doc/libunbound.3.in index 2fcdfb162..91bee7054 100644 --- a/doc/libunbound.3.in +++ b/doc/libunbound.3.in @@ -35,7 +35,12 @@ .B ub_resolve_async, .B ub_cancel, .B ub_resolve_free, -.B ub_strerror +.B ub_strerror, +.B ub_ctx_print_local_zones, +.B ub_ctx_zone_add, +.B ub_ctx_zone_remove, +.B ub_ctx_data_add, +.B ub_ctx_data_remove \- Unbound DNS validating resolver @version@ functions. .SH "SYNOPSIS" .LP @@ -114,6 +119,21 @@ .LP \fIconst char *\fR \fBub_strerror\fR(\fIint\fR err); +.LP +\fIint\fR +\fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx); +.LP +\fIint\fR +\fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type); +.LP +\fIint\fR +\fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name); +.LP +\fIint\fR +\fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); +.LP +\fIint\fR +\fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); .SH "DESCRIPTION" .LP .B Unbound @@ -278,7 +298,8 @@ void my_callback_function(void* my_arg, int err, struct ub_result* result); .IP The async_id is returned so you can (at your option) decide to track it -and cancel the request if needed. +and cancel the request if needed. If you pass a NULL pointer the async_id +is not returned. .TP .B ub_cancel Cancel an async query in progress. This may return an error if the query @@ -291,6 +312,23 @@ Free struct ub_result contents after use. .B ub_strerror Convert error value from one of the unbound library functions to a human readable string. +.TP +.B ub_ctx_print_local_zones +Debug printout the local authority information to stdout. +.TP +.B ub_ctx_zone_add +Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5) +statement. +.TP +.B ub_ctx_zone_remove +Delete zone from local authority info. +.TP +.B ub_ctx_data_add +Add resource record data to local authority info, like local\-data +\fIunbound.conf\fR(5) statement. +.TP +.B ub_ctx_data_remove +Delete local authority data from the name given. .SH "RESULT DATA STRUCTURE" .LP The result of the DNS resolution and validation is returned as diff --git a/doc/unbound.doxygen b/doc/unbound.doxygen index fca4aad5f..a436e5e6f 100644 --- a/doc/unbound.doxygen +++ b/doc/unbound.doxygen @@ -496,6 +496,9 @@ EXCLUDE = ./build \ util/configlexer.c \ util/locks.h \ pythonmod/Unbound.py \ + pythonmod/interface.h \ + pythonmod/examples/resgen.py \ + pythonmod/examples/resmod.py \ ./ldns-src # The EXCLUDE_SYMLINKS tag can be used select whether or not files or diff --git a/libunbound/libunbound.c b/libunbound/libunbound.c index 4daa31301..d4500e364 100644 --- a/libunbound/libunbound.c +++ b/libunbound/libunbound.c @@ -907,29 +907,30 @@ ub_ctx_hosts(struct ub_ctx* ctx, char* fname) return UB_NOERROR; } -static int ub_ctx_check_finalize(struct ub_ctx* ctx) +/** finalize the context, if not already finalized */ +static int ub_ctx_finalize(struct ub_ctx* ctx) { - int res = 0; - lock_basic_lock(&ctx->cfglock); - if (!ctx->finalized) { - res = context_finalize(ctx); - } - lock_basic_unlock(&ctx->cfglock); - return res; + int res = 0; + lock_basic_lock(&ctx->cfglock); + if (!ctx->finalized) { + res = context_finalize(ctx); + } + lock_basic_unlock(&ctx->cfglock); + return res; } -/** Print local zones and RR data */ +/* Print local zones and RR data */ int ub_ctx_print_local_zones(struct ub_ctx* ctx) { - int res = ub_ctx_check_finalize(ctx); - if (res) return res; + int res = ub_ctx_finalize(ctx); + if (res) return res; - local_zones_print(ctx->local_zones); + local_zones_print(ctx->local_zones); - return UB_NOERROR; + return UB_NOERROR; } -/** Add a new zone */ +/* Add a new zone */ int ub_ctx_zone_add(struct ub_ctx* ctx, char *zone_name, char *zone_type) { enum localzone_type t; @@ -938,91 +939,96 @@ int ub_ctx_zone_add(struct ub_ctx* ctx, char *zone_name, char *zone_type) int nmlabs; size_t nmlen; - int res = ub_ctx_check_finalize(ctx); - if (res) return res; + int res = ub_ctx_finalize(ctx); + if (res) return res; if(!local_zone_str2type(zone_type, &t)) { - return UB_SYNTAX; - } + return UB_SYNTAX; + } if(!parse_dname(zone_name, &nm, &nmlen, &nmlabs)) { return UB_SYNTAX; - } + } lock_quick_lock(&ctx->local_zones->lock); - if((z=local_zones_find(ctx->local_zones, nm, nmlen, nmlabs, LDNS_RR_CLASS_IN))) { + if((z=local_zones_find(ctx->local_zones, nm, nmlen, nmlabs, + LDNS_RR_CLASS_IN))) { /* already present in tree */ lock_rw_wrlock(&z->lock); z->type = t; /* update type anyway */ lock_rw_unlock(&z->lock); - free(nm); lock_quick_unlock(&ctx->local_zones->lock); + free(nm); return UB_NOERROR; } - if(!local_zones_add_zone(ctx->local_zones, nm, nmlen, nmlabs, LDNS_RR_CLASS_IN, t)) { + if(!local_zones_add_zone(ctx->local_zones, nm, nmlen, nmlabs, + LDNS_RR_CLASS_IN, t)) { lock_quick_unlock(&ctx->local_zones->lock); return UB_NOMEM; } lock_quick_unlock(&ctx->local_zones->lock); - return UB_NOERROR; + return UB_NOERROR; } -/** Remove zone */ +/* Remove zone */ int ub_ctx_zone_remove(struct ub_ctx* ctx, char *zone_name) { struct local_zone* z; - uint8_t* nm; + uint8_t* nm; int nmlabs; size_t nmlen; - int res = ub_ctx_check_finalize(ctx); - if (res) return res; + int res = ub_ctx_finalize(ctx); + if (res) return res; if(!parse_dname(zone_name, &nm, &nmlen, &nmlabs)) { return UB_SYNTAX; - } + } lock_quick_lock(&ctx->local_zones->lock); - if((z=local_zones_find(ctx->local_zones, nm, nmlen, nmlabs, LDNS_RR_CLASS_IN))) { + if((z=local_zones_find(ctx->local_zones, nm, nmlen, nmlabs, + LDNS_RR_CLASS_IN))) { /* present in tree */ local_zones_del_zone(ctx->local_zones, z); } - free(nm); lock_quick_unlock(&ctx->local_zones->lock); - return UB_NOERROR; + free(nm); + return UB_NOERROR; } -/** Add new RR data */ +/* Add new RR data */ int ub_ctx_data_add(struct ub_ctx* ctx, char *data) { - ldns_buffer* buf; - int res = ub_ctx_check_finalize(ctx); - if (res) return res; + ldns_buffer* buf; + int res = ub_ctx_finalize(ctx); + if (res) return res; lock_basic_lock(&ctx->cfglock); - buf = ldns_buffer_new(ctx->env->cfg->msg_buffer_size); + buf = ldns_buffer_new(ctx->env->cfg->msg_buffer_size); lock_basic_unlock(&ctx->cfglock); + if(!buf) return UB_NOMEM; - res = local_zones_add_RR(ctx->local_zones, data, buf); + res = local_zones_add_RR(ctx->local_zones, data, buf); - ldns_buffer_free(buf); - return (!res) ? UB_NOMEM : UB_NOERROR; + ldns_buffer_free(buf); + return (!res) ? UB_NOMEM : UB_NOERROR; } /* Remove RR data */ int ub_ctx_data_remove(struct ub_ctx* ctx, char *data) { - uint8_t* nm; + uint8_t* nm; int nmlabs; size_t nmlen; - int res = ub_ctx_check_finalize(ctx); - if (res) return res; + int res = ub_ctx_finalize(ctx); + if (res) return res; if(!parse_dname(data, &nm, &nmlen, &nmlabs)) return UB_SYNTAX; - local_zones_del_data(ctx->local_zones, nm, nmlen, nmlabs, LDNS_RR_CLASS_IN); + local_zones_del_data(ctx->local_zones, nm, nmlen, nmlabs, + LDNS_RR_CLASS_IN); - free(nm); - return UB_NOERROR; + free(nm); + return UB_NOERROR; } diff --git a/libunbound/unbound.h b/libunbound/unbound.h index 7a7a31fa9..4393e2640 100644 --- a/libunbound/unbound.h +++ b/libunbound/unbound.h @@ -470,10 +470,49 @@ void ub_resolve_free(struct ub_result* result); */ const char* ub_strerror(int err); +/** + * Debug routine. Print the local zone information to stdout. + * @param ctx: context. Is finalized by the routine. + * @return 0 if OK, else error. + */ int ub_ctx_print_local_zones(struct ub_ctx* ctx); + +/** + * Add a new zone with the zonetype to the local authority info of the + * library. + * @param ctx: context. Is finalized by the routine. + * @param zone_name: name of the zone in text, "example.com" + * If it already exists, the type is updated. + * @param zone_type: type of the zone (like for unbound.conf) in text. + * @return 0 if OK, else error. + */ int ub_ctx_zone_add(struct ub_ctx* ctx, char *zone_name, char *zone_type); + +/** + * Remove zone from local authority info of the library. + * @param ctx: context. Is finalized by the routine. + * @param zone_name: name of the zone in text, "example.com" + * If it does not exist, nothing happens. + * @return 0 if OK, else error. + */ int ub_ctx_zone_remove(struct ub_ctx* ctx, char *zone_name); + +/** + * Add localdata to the library local authority info. + * Similar to local-data config statement. + * @param ctx: context. Is finalized by the routine. + * @param data: the resource record in text format, for example + * "www.example.com IN A 127.0.0.1" + * @return 0 if OK, else error. + */ int ub_ctx_data_add(struct ub_ctx* ctx, char *data); + +/** + * Remove localdata from the library local authority info. + * @param ctx: context. Is finalized by the routine. + * @param data: the name to delete all data from, like "www.example.com". + * @return 0 if OK, else error. + */ int ub_ctx_data_remove(struct ub_ctx* ctx, char *data); #endif /* _UB_UNBOUND_H */ diff --git a/pythonmod/pythonmod.c b/pythonmod/pythonmod.c index 1b8fc3942..15f47e866 100644 --- a/pythonmod/pythonmod.c +++ b/pythonmod/pythonmod.c @@ -33,6 +33,10 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file + * Python module for unbound. Calls python script. + */ /* ignore the varargs unused warning from SWIGs internal vararg support */ #ifdef __GNUC__ diff --git a/pythonmod/pythonmod.h b/pythonmod/pythonmod.h index 7d0aed7fc..2d1f9740f 100644 --- a/pythonmod/pythonmod.h +++ b/pythonmod/pythonmod.h @@ -33,6 +33,10 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file + * Python module for unbound. Calls python script. + */ #ifndef PYTHONMOD_H #define PYTHONMOD_H #include "util/module.h" @@ -55,10 +59,13 @@ struct pythonmod_env { /** Python module. */ PyObject* module; - /** Module functions */ + /** Module init function */ PyObject* func_init; + /** Module deinit function */ PyObject* func_deinit; + /** Module operate function */ PyObject* func_operate; + /** Module super_inform function */ PyObject* func_inform; /** Python dictionary. */ diff --git a/services/localzone.c b/services/localzone.c index 1be05d153..60545dd61 100644 --- a/services/localzone.c +++ b/services/localzone.c @@ -119,7 +119,7 @@ local_data_cmp(const void* d1, const void* d2) b->namelabs, &m); } -/** form wireformat from text format domain name */ +/* form wireformat from text format domain name */ int parse_dname(const char* str, uint8_t** res, size_t* len, int* labs) { diff --git a/services/localzone.h b/services/localzone.h index 687b89546..8835c06df 100644 --- a/services/localzone.h +++ b/services/localzone.h @@ -297,6 +297,11 @@ void local_zones_del_data(struct local_zones* zones, /** * Form wireformat from text format domain name. + * @param str: the domain name in text "www.example.com" + * @param res: resulting wireformat is stored here with malloc. + * @param len: length of resulting wireformat. + * @param labs: number of labels in resulting wireformat. + * @return false on error, syntax or memory. Also logged. */ int parse_dname(const char* str, uint8_t** res, size_t* len, int* labs);