diff --git a/CHANGES b/CHANGES index cb5f733d52..d781e56309 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,5 @@ +1851. [doc] Doxygen comment markup. [RT #11398] + 1850. [bug] Memory leak in lwres_getipnodebyaddr(). [RT #14591] 1849. [doc] All forms of the man pages (docbook, man, html) should diff --git a/acconfig.h b/acconfig.h index 20df3a618e..5d86b063c3 100644 --- a/acconfig.h +++ b/acconfig.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: acconfig.h,v 1.47 2004/12/04 06:47:02 marka Exp $ */ +/* $Id: acconfig.h,v 1.48 2005/04/27 04:55:41 sra Exp $ */ + +/*! \file */ /*** *** This file is not to be included by any public header files, because @@ -23,95 +25,97 @@ ***/ @TOP@ -/* define to `int' if doesn't define. */ +/** define to `int' if doesn't define. */ #undef ssize_t -/* define on DEC OSF to enable 4.4BSD style sa_len support */ +/** define on DEC OSF to enable 4.4BSD style sa_len support */ #undef _SOCKADDR_LEN -/* define if your system needs pthread_init() before using pthreads */ +/** define if your system needs pthread_init() before using pthreads */ #undef NEED_PTHREAD_INIT -/* define if your system has sigwait() */ +/** define if your system has sigwait() */ #undef HAVE_SIGWAIT -/* define if sigwait() is the UnixWare flavor */ +/** define if sigwait() is the UnixWare flavor */ #undef HAVE_UNIXWARE_SIGWAIT -/* define on Solaris to get sigwait() to work using pthreads semantics */ +/** define on Solaris to get sigwait() to work using pthreads semantics */ #undef _POSIX_PTHREAD_SEMANTICS -/* define if LinuxThreads is in use */ +/** define if LinuxThreads is in use */ #undef HAVE_LINUXTHREADS -/* define if sysconf() is available */ +/** define if sysconf() is available */ #undef HAVE_SYSCONF -/* define if sysctlbyname() is available */ +/** define if sysctlbyname() is available */ #undef HAVE_SYSCTLBYNAME -/* define if catgets() is available */ +/** define if catgets() is available */ #undef HAVE_CATGETS -/* define if getifaddrs() exists */ +/** define if getifaddrs() exists */ #undef HAVE_GETIFADDRS -/* define if you have the NET_RT_IFLIST sysctl variable and sys/sysctl.h */ +/** define if you have the NET_RT_IFLIST sysctl variable and sys/sysctl.h */ #undef HAVE_IFLIST_SYSCTL -/* define if chroot() is available */ +/** define if chroot() is available */ #undef HAVE_CHROOT -/* define if tzset() is available */ +/** define if tzset() is available */ #undef HAVE_TZSET -/* define if struct addrinfo exists */ +/** define if struct addrinfo exists */ #undef HAVE_ADDRINFO -/* define if getaddrinfo() exists */ +/** define if getaddrinfo() exists */ #undef HAVE_GETADDRINFO -/* define if gai_strerror() exists */ +/** define if gai_strerror() exists */ #undef HAVE_GAISTRERROR -/* define if arc4random() exists */ +/** define if arc4random() exists */ #undef HAVE_ARC4RANDOM -/* define if pthread_setconcurrency() should be called to tell the +/** + * define if pthread_setconcurrency() should be called to tell the * OS how many threads we might want to run. */ #undef CALL_PTHREAD_SETCONCURRENCY -/* define if IPv6 is not disabled */ +/** define if IPv6 is not disabled */ #undef WANT_IPV6 -/* define if flockfile() is available */ +/** define if flockfile() is available */ #undef HAVE_FLOCKFILE -/* define if getc_unlocked() is available */ +/** define if getc_unlocked() is available */ #undef HAVE_GETCUNLOCKED -/* Shut up warnings about sputaux in stdio.h on BSD/OS pre-4.1 */ +/** Shut up warnings about sputaux in stdio.h on BSD/OS pre-4.1 */ #undef SHUTUP_SPUTAUX #ifdef SHUTUP_SPUTAUX struct __sFILE; extern __inline int __sputaux(int _c, struct __sFILE *_p); #endif -/* Shut up warnings about missing sigwait prototype on BSD/OS 4.0* */ +/** Shut up warnings about missing sigwait prototype on BSD/OS 4.0* */ #undef SHUTUP_SIGWAIT #ifdef SHUTUP_SIGWAIT int sigwait(const unsigned int *set, int *sig); #endif -/* Shut up warnings from gcc -Wcast-qual on BSD/OS 4.1. */ +/** Shut up warnings from gcc -Wcast-qual on BSD/OS 4.1. */ #undef SHUTUP_STDARG_CAST #if defined(SHUTUP_STDARG_CAST) && defined(__GNUC__) -#include /* Grr. Must be included *every time*. */ -/* +#include /** Grr. Must be included *every time*. */ +/** * The silly continuation line is to keep configure from * commenting out the #undef. */ + #undef \ va_start #define va_start(ap, last) \ @@ -120,21 +124,21 @@ int sigwait(const unsigned int *set, int *sig); _u.konst = &(last); \ ap = (va_list)(_u.var + __va_words(__typeof(last))); \ } while (0) -#endif /* SHUTUP_STDARG_CAST && __GNUC__ */ +#endif /** SHUTUP_STDARG_CAST && __GNUC__ */ -/* define if the system has a random number generating device */ +/** define if the system has a random number generating device */ #undef PATH_RANDOMDEV -/* define if pthread_attr_getstacksize() is available */ +/** define if pthread_attr_getstacksize() is available */ #undef HAVE_PTHREAD_ATTR_GETSTACKSIZE -/* define if pthread_attr_setstacksize() is available */ +/** define if pthread_attr_setstacksize() is available */ #undef HAVE_PTHREAD_ATTR_SETSTACKSIZE -/* define if you have strerror in the C library. */ +/** define if you have strerror in the C library. */ #undef HAVE_STRERROR -/* Define if you are running under Compaq TruCluster. */ +/** Define if you are running under Compaq TruCluster. */ #undef HAVE_TRUCLUSTER /* Define if OpenSSL includes DSA support */ diff --git a/bin/check/check-tool.c b/bin/check/check-tool.c index d38cd8aea5..dacd56ac55 100644 --- a/bin/check/check-tool.c +++ b/bin/check/check-tool.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: check-tool.c,v 1.15 2005/01/10 23:43:12 marka Exp $ */ +/* $Id: check-tool.c,v 1.16 2005/04/27 04:55:42 sra Exp $ */ + +/*! \file */ #include @@ -94,6 +96,7 @@ setup_logging(isc_mem_t *mctx, isc_log_t **logp) { return (ISC_R_SUCCESS); } +/*% load the zone */ isc_result_t load_zone(isc_mem_t *mctx, const char *zonename, const char *filename, const char *classname, dns_zone_t **zonep) @@ -146,6 +149,7 @@ load_zone(isc_mem_t *mctx, const char *zonename, const char *filename, return (result); } +/*% dump the zone */ isc_result_t dump_zone(const char *zonename, dns_zone_t *zone, const char *filename) { diff --git a/bin/check/check-tool.h b/bin/check/check-tool.h index 6f64cf54ce..06ba0309e5 100644 --- a/bin/check/check-tool.h +++ b/bin/check/check-tool.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: check-tool.h,v 1.7 2004/03/05 04:57:20 marka Exp $ */ +/* $Id: check-tool.h,v 1.8 2005/04/27 04:55:43 sra Exp $ */ #ifndef CHECK_TOOL_H #define CHECK_TOOL_H +/*! \file */ + #include #include diff --git a/bin/check/named-checkconf.c b/bin/check/named-checkconf.c index 109d17e1ce..e6d165e0a3 100644 --- a/bin/check/named-checkconf.c +++ b/bin/check/named-checkconf.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: named-checkconf.c,v 1.30 2005/03/03 06:33:05 marka Exp $ */ +/* $Id: named-checkconf.c,v 1.31 2005/04/27 04:55:43 sra Exp $ */ + +/*! \file */ #include @@ -52,6 +54,7 @@ isc_log_t *logc = NULL; goto cleanup; \ } while (0) +/*% usage */ static void usage(void) { fprintf(stderr, "usage: named-checkconf [-j] [-v] [-z] [-t directory] " @@ -59,6 +62,7 @@ usage(void) { exit(1); } +/*% directory callback */ static isc_result_t directory_callback(const char *clausename, cfg_obj_t *obj, void *arg) { isc_result_t result; @@ -84,6 +88,7 @@ directory_callback(const char *clausename, cfg_obj_t *obj, void *arg) { return (ISC_R_SUCCESS); } +/*% configure the zone */ static isc_result_t configure_zone(const char *vclass, const char *view, cfg_obj_t *zconfig, isc_mem_t *mctx) @@ -124,6 +129,7 @@ configure_zone(const char *vclass, const char *view, cfg_obj_t *zconfig, return(result); } +/*% configure a view */ static isc_result_t configure_view(const char *vclass, const char *view, cfg_obj_t *config, cfg_obj_t *vconfig, isc_mem_t *mctx) @@ -157,6 +163,7 @@ configure_view(const char *vclass, const char *view, cfg_obj_t *config, } +/*% load zones from the configuration */ static isc_result_t load_zones_fromconfig(cfg_obj_t *config, isc_mem_t *mctx) { cfg_listelt_t *element; @@ -197,6 +204,7 @@ load_zones_fromconfig(cfg_obj_t *config, isc_mem_t *mctx) { return (result); } +/*% The main processing routine */ int main(int argc, char **argv) { int c; diff --git a/bin/check/named-checkzone.c b/bin/check/named-checkzone.c index f23e7291d1..f8bdfae90c 100644 --- a/bin/check/named-checkzone.c +++ b/bin/check/named-checkzone.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: named-checkzone.c,v 1.33 2005/01/10 23:43:12 marka Exp $ */ +/* $Id: named-checkzone.c,v 1.34 2005/04/27 04:55:43 sra Exp $ */ + +/*! \file */ #include @@ -77,6 +79,7 @@ destroy(void) { dns_zone_detach(&zone); } +/*% main processing routine */ int main(int argc, char **argv) { int c; diff --git a/bin/dig/dig.c b/bin/dig/dig.c index 1f5e971f34..96baacbad9 100644 --- a/bin/dig/dig.c +++ b/bin/dig/dig.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dig.c,v 1.202 2005/03/31 23:54:45 marka Exp $ */ +/* $Id: dig.c,v 1.203 2005/04/27 04:55:44 sra Exp $ */ + +/*! \file */ #include #include @@ -94,6 +96,7 @@ static isc_boolean_t short_form = ISC_FALSE, printcmd = ISC_TRUE, ip6_int = ISC_FALSE, plusquest = ISC_FALSE, pluscomm = ISC_FALSE, multiline = ISC_FALSE, nottl = ISC_FALSE, noclass = ISC_FALSE; +/*% opcode text */ static const char *opcodetext[] = { "QUERY", "IQUERY", @@ -113,6 +116,7 @@ static const char *opcodetext[] = { "RESERVED15" }; +/*% return code text */ static const char *rcodetext[] = { "NOERROR", "FORMERR", @@ -135,6 +139,7 @@ static const char *rcodetext[] = { extern char *progname; +/*% print usage */ static void print_usage(FILE *fp) { fputs( @@ -151,11 +156,13 @@ usage(void) { exit(1); } +/*% version */ static void version(void) { fputs("DiG " VERSION "\n", stderr); } +/*% help */ static void help(void) { print_usage(stdout); @@ -227,7 +234,7 @@ help(void) { stdout); } -/* +/*% * Callback from dighost.c to print the received message. */ void @@ -287,7 +294,7 @@ trying(char *frm, dig_lookup_t *lookup) { UNUSED(lookup); } -/* +/*% * Internal print routine used to print short form replies. */ static isc_result_t @@ -317,7 +324,7 @@ say_message(dns_rdata_t *rdata, dig_query_t *query, isc_buffer_t *buf) { return (ISC_R_SUCCESS); } -/* +/*% * short_form message print handler. Calls above say_message() */ static isc_result_t @@ -611,7 +618,7 @@ cleanup: return (result); } -/* +/*% * print the greeting message when the program first starts up. */ static void @@ -658,7 +665,7 @@ printgreeting(int argc, char **argv, dig_lookup_t *lookup) { } } -/* +/*% * Reorder an argument list so that server names all come at the end. * This is a bit of a hack, to allow batch-mode processing to properly * handle the server options. @@ -707,7 +714,7 @@ parse_uint(char *arg, const char *desc, isc_uint32_t max) { return (tmp); } -/* +/*% * We're not using isc_commandline_parse() here since the command line * syntax of dig is quite a bit different from that which can be described * by that routine. @@ -1080,8 +1087,8 @@ plus_option(char *option, isc_boolean_t is_batchfile, return; } -/* - * ISC_TRUE returned if value was used +/*% + * #ISC_TRUE returned if value was used */ static const char *single_dash_opts = "46dhimnv"; static const char *dash_opts = "46bcdfhikmnptvyx"; @@ -1306,10 +1313,11 @@ dash_option(char *option, char *next, dig_lookup_t **lookup, return (ISC_FALSE); } -/* +/*% * Because we may be trying to do memory allocation recording, we're going * to need to parse the arguments for the -m *before* we start the main * argument parsing routine. + * * I'd prefer not to have to do this, but I am not quite sure how else to * fix the problem. Argument parsing in dig involves memory allocation * by its nature, so it can't be done in the main argument parser. @@ -1654,6 +1662,7 @@ dighost_shutdown(void) { } } +/*% Main processing routine for dig */ int main(int argc, char **argv) { isc_result_t result; diff --git a/bin/dig/dighost.c b/bin/dig/dighost.c index 14bded45e5..9631ddd976 100644 --- a/bin/dig/dighost.c +++ b/bin/dig/dighost.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dighost.c,v 1.274 2005/03/31 23:54:45 marka Exp $ */ +/* $Id: dighost.c,v 1.275 2005/04/27 04:55:44 sra Exp $ */ -/* +/*! \file + * \note * Notice to programmers: Do not use this code as an example of how to * use the ISC library to perform DNS lookups. Dig and Host both operate * on the request level, since they allow fine-tuning of output and are @@ -119,14 +120,15 @@ int ndots = -1; int tries = 3; int lookup_counter = 0; -/* +/*% * Exit Codes: - * 0 Everything went well, including things like NXDOMAIN - * 1 Usage error - * 7 Got too many RR's or Names - * 8 Couldn't open batch file - * 9 No reply from server - * 10 Internal error + * + *\li 0 Everything went well, including things like NXDOMAIN + *\li 1 Usage error + *\li 7 Got too many RR's or Names + *\li 8 Couldn't open batch file + *\li 9 No reply from server + *\li 10 Internal error */ int exitcode = 0; int fatalexit = 0; @@ -292,7 +294,7 @@ struct_tk_list tk_list = { {NULL, NULL, NULL, NULL, NULL}, 0}; #define DIG_MAX_ADDRESSES 20 -/* +/*% * Apply and clear locks at the event level in global task. * Can I get rid of these using shutdown events? XXX */ @@ -373,7 +375,7 @@ hex_dump(isc_buffer_t *b) { printf("\n"); } -/* +/*% * Append 'len' bytes of 'text' at '*p', failing with * ISC_R_NOSPACE if that would advance p past 'end'. */ @@ -489,7 +491,7 @@ check_result(isc_result_t result, const char *msg) { } } -/* +/*% * Create a server structure, which is part of the lookup structure. * This is little more than a linked list of servers to query in hopes * of finding the answer the user is looking for @@ -531,7 +533,7 @@ addr2af(int lwresaddrtype) return (af); } -/* +/*% * Create a copy of the server list from the lwres configuration structure. * The dest list must have already had ISC_LIST_INIT applied. */ @@ -626,7 +628,7 @@ add_nameserver(lwres_conf_t *confdata, const char *addr, int af) { return (ISC_R_FAILURE); } -/* +/*% * Produce a cloned server list. The dest list must have already had * ISC_LIST_INIT applied. */ @@ -644,7 +646,7 @@ clone_server_list(dig_serverlist_t src, dig_serverlist_t *dest) { } } -/* +/*% * Create an empty lookup structure, which holds all the information needed * to get an answer to a user's question. This structure contains two * linked lists: the server list (servers to query) and the query list @@ -725,7 +727,7 @@ make_empty_lookup(void) { return (looknew); } -/* +/*% * Clone a lookup, perhaps copying the server list. This does not clone * the query list, since it will be regenerated by the setup_lookup() * function, nor does it queue up the new lookup for processing. @@ -797,7 +799,7 @@ clone_lookup(dig_lookup_t *lookold, isc_boolean_t servers) { return (looknew); } -/* +/*% * Requeue a lookup for further processing, perhaps copying the server * list. The new lookup structure is returned to the caller, and is * queued for processing. If servers are not cloned in the requeue, they @@ -929,7 +931,7 @@ create_search_list(lwres_conf_t *confdata) { } } -/* +/*% * Setup the system as a whole, reading key information and resolv.conf * settings. */ @@ -1009,7 +1011,7 @@ clear_searchlist(void) { } } -/* +/*% * Override the search list derived from resolv.conf by 'domain'. */ void @@ -1021,7 +1023,7 @@ set_search_domain(char *domain) { ISC_LIST_APPEND(search_list, search, link); } -/* +/*% * Setup the ISC and DNS libraries for use by the system. */ void @@ -1078,7 +1080,7 @@ setup_libs(void) { dns_result_register(); } -/* +/*% * Add EDNS0 option record to a message. Currently, the only supported * options are UDP buffer size and the DO bit. */ @@ -1114,7 +1116,7 @@ add_opt(dns_message_t *msg, isc_uint16_t udpsize, isc_boolean_t dnssec) { check_result(result, "dns_message_setopt"); } -/* +/*% * Add a question section to a message, asking for the specified name, * type, and class. */ @@ -1134,7 +1136,7 @@ add_question(dns_message_t *message, dns_name_t *name, ISC_LIST_APPEND(name->list, rdataset, link); } -/* +/*% * Check if we're done with all the queued lookups, which is true iff * all sockets, sends, and recvs are accounted for (counters == 0), * and the lookup list is empty. @@ -1155,7 +1157,7 @@ check_if_done(void) { } } -/* +/*% * Clear out a query when we're done with it. WARNING: This routine * WILL invalidate the query pointer. */ @@ -1191,7 +1193,7 @@ clear_query(dig_query_t *query) { isc_mem_free(mctx, query); } -/* +/*% * Try and clear out a lookup if we're done with it. Return ISC_TRUE if * the lookup was successfully cleared. If ISC_TRUE is returned, the * lookup pointer has been invalidated. @@ -1251,7 +1253,7 @@ try_clear_lookup(dig_lookup_t *lookup) { } -/* +/*% * If we can, start the next lookup in the queue running. * This assumes that the lookup on the head of the queue hasn't been * started yet. It also removes the lookup from the head of the queue, @@ -1367,7 +1369,7 @@ start_lookup(void) { } } -/* +/*% * If we can, clear the current lookup and start the next one running. * This calls try_clear_lookup, so may invalidate the lookup pointer. */ @@ -1388,7 +1390,7 @@ check_next_lookup(dig_lookup_t *lookup) { } } -/* +/*% * Create and queue a new lookup as a followup to the current lookup, * based on the supplied message and section. This is used in trace and * name server search modes to start a new lookup using servers from @@ -1524,7 +1526,7 @@ followup_lookup(dns_message_t *msg, dig_query_t *query, dns_section_t section) return (numLookups); } -/* +/*% * Create and queue a new lookup using the next origin from the search * list, read in setup_system(). * @@ -1558,7 +1560,7 @@ next_origin(dns_message_t *msg, dig_query_t *query) { return (ISC_TRUE); } -/* +/*% * Insert an SOA record into the sendmessage in a lookup. Used for * creating IXFR queries. */ @@ -1624,7 +1626,7 @@ insert_soa(dig_lookup_t *lookup) { dns_message_addname(lookup->sendmsg, soaname, DNS_SECTION_AUTHORITY); } -/* +/*% * Setup the supplied lookup structure, making it ready to start sending * queries to servers. Create and initialize the message to be sent as * well as the query structures and buffer space for the replies. If the @@ -1899,7 +1901,7 @@ setup_lookup(dig_lookup_t *lookup) { } } -/* +/*% * Event handler for send completion. Track send counter, and clear out * the query if the send was canceled. */ @@ -1921,7 +1923,7 @@ send_done(isc_task_t *_task, isc_event_t *event) { UNLOCK_LOOKUP; } -/* +/*% * Cancel a lookup, sending isc_socket_cancel() requests to all outstanding * IO sockets. The cancel handlers should take care of cleaning up the * query and lookup structures @@ -1987,7 +1989,7 @@ bringup_timer(dig_query_t *query, unsigned int default_timeout) { static void connect_done(isc_task_t *task, isc_event_t *event); -/* +/*% * Unlike send_udp, this can't be called multiple times with the same * query. When we retry TCP, we requeue the whole lookup, which should * start anew. @@ -2056,7 +2058,7 @@ send_tcp_connect(dig_query_t *query) { } } -/* +/*% * Send a UDP packet to the remote nameserver, possible starting the * recv action as well. Also make sure that the timer is running and * is properly reset. @@ -2133,7 +2135,7 @@ send_udp(dig_query_t *query) { } } -/* +/*% * IO timeout handler, used for both connect and recv timeouts. If * retries are still allowed, either resend the UDP packet or queue a * new TCP lookup. Otherwise, cancel the lookup. @@ -2192,7 +2194,7 @@ connect_timeout(isc_task_t *task, isc_event_t *event) { UNLOCK_LOOKUP; } -/* +/*% * Event handler for the TCP recv which gets the length header of TCP * packets. Start the next recv of length bytes. */ @@ -2275,7 +2277,7 @@ tcp_length_done(isc_task_t *task, isc_event_t *event) { UNLOCK_LOOKUP; } -/* +/*% * For transfers that involve multiple recvs (XFR's in particular), * launch the next recv. */ @@ -2337,7 +2339,7 @@ launch_next_query(dig_query_t *query, isc_boolean_t include_question) { return; } -/* +/*% * Event handler for TCP connect complete. Make sure the connection was * successful, then pass into launch_next_query to actually send the * question. @@ -2418,7 +2420,7 @@ connect_done(isc_task_t *task, isc_event_t *event) { UNLOCK_LOOKUP; } -/* +/*% * Check if the ongoing XFR needs more data before it's complete, using * the semantics of IXFR and AXFR protocols. Much of the complexity of * this routine comes from determining when an IXFR is complete. @@ -2563,7 +2565,7 @@ check_for_more_data(dig_query_t *query, dns_message_t *msg, return (ISC_TRUE); } -/* +/*% * Event handler for recv complete. Perform whatever actions are necessary, * based on the specifics of the user's request. */ @@ -3036,7 +3038,7 @@ recv_done(isc_task_t *task, isc_event_t *event) { UNLOCK_LOOKUP; } -/* +/*% * Turn a name into an address, using system-supplied routines. This is * used in looking up server names, etc... and needs to use system-supplied * routines, since they may be using a non-DNS system for these lookups. @@ -3055,7 +3057,7 @@ get_address(char *host, in_port_t port, isc_sockaddr_t *sockaddr) { INSIST(count == 1); } -/* +/*% * Initiate either a TCP or UDP lookup */ void @@ -3071,7 +3073,7 @@ do_lookup(dig_lookup_t *lookup) { send_udp(ISC_LIST_HEAD(lookup->q)); } -/* +/*% * Start everything in action upon task startup. */ void @@ -3084,7 +3086,7 @@ onrun_callback(isc_task_t *task, isc_event_t *event) { UNLOCK_LOOKUP; } -/* +/*% * Make everything on the lookup queue go away. Mainly used by the * SIGINT handler. */ @@ -3128,7 +3130,7 @@ cancel_all(void) { UNLOCK_LOOKUP; } -/* +/*% * Destroy all of the libs we are using, and get everything ready for a * clean shutdown. */ diff --git a/bin/dig/host.c b/bin/dig/host.c index 22f6c35bcf..05ff233294 100644 --- a/bin/dig/host.c +++ b/bin/dig/host.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: host.c,v 1.102 2005/03/16 00:55:14 marka Exp $ */ +/* $Id: host.c,v 1.103 2005/04/27 04:55:45 sra Exp $ */ + +/*! \file */ #include #include diff --git a/bin/dig/include/dig/dig.h b/bin/dig/include/dig/dig.h index 216061f383..c59636a0ab 100644 --- a/bin/dig/include/dig/dig.h +++ b/bin/dig/include/dig/dig.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dig.h,v 1.90 2005/03/31 23:54:45 marka Exp $ */ +/* $Id: dig.h,v 1.91 2005/04/27 04:55:45 sra Exp $ */ #ifndef DIG_H #define DIG_H +/*! \file */ + #include #include @@ -38,36 +40,43 @@ #define MXSERV 20 #define MXNAME (DNS_NAME_MAXTEXT+1) #define MXRD 32 +/*% Buffer Size */ #define BUFSIZE 512 #define COMMSIZE 0xffff #ifndef RESOLV_CONF +/*% location of resolve.conf */ #define RESOLV_CONF "/etc/resolv.conf" #endif +/*% output buffer */ #define OUTPUTBUF 32767 +/*% Max RR Limit */ #define MAXRRLIMIT 0xffffffff #define MAXTIMEOUT 0xffff +/*% Max number of tries */ #define MAXTRIES 0xffffffff +/*% Max number of dots */ #define MAXNDOTS 0xffff +/*% Max number of ports */ #define MAXPORT 0xffff +/*% Max serial number */ #define MAXSERIAL 0xffffffff -/* - * Default timeout values - */ +/*% Default TCP Timeout */ #define TCP_TIMEOUT 10 +/*% Default UDP Timeout */ #define UDP_TIMEOUT 5 #define SERVER_TIMEOUT 1 #define LOOKUP_LIMIT 64 -/* +/*% * Lookup_limit is just a limiter, keeping too many lookups from being * created. It's job is mainly to prevent the program from running away * in a tight loop of constant lookups. It's value is arbitrary. */ #define ROOTNS 1 -/* +/*% * Set the number of root servers to ask for information when running in * trace mode. * XXXMWS -- trace mode is currently semi-broken, and this number *MUST* @@ -98,22 +107,23 @@ typedef struct dig_message dig_message_t; typedef ISC_LIST(dig_server_t) dig_serverlist_t; typedef struct dig_searchlist dig_searchlist_t; +/*% The dig_lookup structure */ struct dig_lookup { isc_boolean_t - pending, /* Pending a successful answer */ + pending, /*%< Pending a successful answer */ waiting_connect, doing_xfr, - ns_search_only, /* dig +nssearch, host -C */ - identify, /* Append an "on server " message */ - identify_previous_line, /* Prepend a "Nameserver :" + ns_search_only, /*%< dig +nssearch, host -C */ + identify, /*%< Append an "on server " message */ + identify_previous_line, /*% Prepend a "Nameserver :" message, with newline and tab */ ignore, recurse, aaonly, adflag, cdflag, - trace, /* dig +trace */ - trace_root, /* initial query for either +trace or +nssearch */ + trace, /*% dig +trace */ + trace_root, /*% initial query for either +trace or +nssearch */ tcp_mode, ip6_int, comments, @@ -138,7 +148,7 @@ isc_boolean_t sigchase; #endif #endif - char textname[MXNAME]; /* Name we're going to be looking up */ + char textname[MXNAME]; /*% Name we're going to be looking up */ char cmdline[MXNAME]; dns_rdatatype_t rdtype; dns_rdatatype_t qrdtype; @@ -179,6 +189,7 @@ isc_boolean_t sigchase; dns_fixedname_t fdomain; }; +/*% The dig_query structure */ struct dig_query { dig_lookup_t *lookup; isc_boolean_t waiting_connect, @@ -313,13 +324,13 @@ printrdataset(dns_name_t *owner_name, dns_rdataset_t *rdataset, isc_result_t printmessage(dig_query_t *query, dns_message_t *msg, isc_boolean_t headers); -/* +/*%< * Print the final result of the lookup. */ void received(int bytes, isc_sockaddr_t *from, dig_query_t *query); -/* +/*%< * Print a message about where and when the response * was received from, like the final comment in the * output of "dig". diff --git a/bin/dnssec/dnssec-keygen.c b/bin/dnssec/dnssec-keygen.c index 15cb2a99c5..063594b8ea 100644 --- a/bin/dnssec/dnssec-keygen.c +++ b/bin/dnssec/dnssec-keygen.c @@ -16,7 +16,9 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dnssec-keygen.c,v 1.67 2004/06/11 01:12:39 marka Exp $ */ +/* $Id: dnssec-keygen.c,v 1.68 2005/04/27 04:55:46 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/dnssec/dnssec-makekeyset.c b/bin/dnssec/dnssec-makekeyset.c index c330cb9232..901c0724a7 100644 --- a/bin/dnssec/dnssec-makekeyset.c +++ b/bin/dnssec/dnssec-makekeyset.c @@ -16,7 +16,31 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dnssec-makekeyset.c,v 1.63 2004/08/28 06:16:50 marka Exp $ */ +/* $Id: dnssec-makekeyset.c,v 1.64 2005/04/27 04:55:47 sra Exp $ */ + +/*! \file */ + +/** + * \brief dnssec-makekeyset - DNSSEC zone signing tool + * + * \section dnssec-makekeyset-synopsis SYNOPSIS + * \par + * dnssec-makekeyset [ -a ] [ -s start-time ] [ -e end-time ] [ -h ] [ + * -p ] [ -r randomdev ] [ -tttl ] [ -v level ] key... + * + * \section dnssec-makekeyset-description DESCRIPTION + * \par + * dnssec-makekeyset generates a key set from one or more keys created by + * dnssec-keygen. It creates a file containing a KEY record for each key, + * and self-signs the key set with each zone key. The output file is of + * the form keyset-nnnn., where nnnn is the zone name. + * + * \link org.isc.doc.0037 More ... \endlink + */ + +/** \page org.isc.doc.0037 dnssec-makekeyset + * \htmlinclude org.isc.doc.0037.html + */ #include diff --git a/bin/dnssec/dnssec-signkey.c b/bin/dnssec/dnssec-signkey.c index 23f8c3aa78..37261079b9 100644 --- a/bin/dnssec/dnssec-signkey.c +++ b/bin/dnssec/dnssec-signkey.c @@ -16,7 +16,31 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dnssec-signkey.c,v 1.63 2004/08/28 06:16:50 marka Exp $ */ +/* $Id: dnssec-signkey.c,v 1.64 2005/04/27 04:55:47 sra Exp $ */ + +/*! \file */ + +/*% dnssec-signkey - DNSSEC key set signing tool + * + * \section dnssec-signkey-synopsis SYNOPSIS + * \par + * dnssec-signkey [ -a ] [ -c class ] [ -s start-time ] [ -e end-time ] + * [ -h ] [ -p ] [ -r randomdev ] [ -v level ] keyset key... + * + * \section dnssec-signkey-description DESCRIPTION + * \par + * dnssec-signkey signs a keyset. Typically the keyset will be for a child + * zone, and will have been generated by dnssec-makekeyset. The child + * zone's keyset is signed with the zone keys for its parent zone. The + * output file is of the form signedkey-nnnn., where nnnn is the zone + * name. + * + * \link org.isc.doc.0038 More ... \endlink + */ + +/** \page org.isc.doc.0038 dnssec-signkey + * \htmlinclude org.isc.doc.0038.html + */ #include diff --git a/bin/dnssec/dnssec-signzone.c b/bin/dnssec/dnssec-signzone.c index ba0813bfbc..e78b28b700 100644 --- a/bin/dnssec/dnssec-signzone.c +++ b/bin/dnssec/dnssec-signzone.c @@ -16,7 +16,9 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dnssec-signzone.c,v 1.187 2005/03/22 02:20:03 marka Exp $ */ +/* $Id: dnssec-signzone.c,v 1.188 2005/04/27 04:55:47 sra Exp $ */ + +/*! \file */ #include @@ -257,7 +259,7 @@ iszonekey(signer_key_t *key) { dst_key_iszonekey(key->key))); } -/* +/*% * Finds the key that generated a RRSIG, if possible. First look at the keys * that we've loaded already, and then see if there's a key on disk. */ @@ -295,7 +297,7 @@ keythatsigned(dns_rdata_rrsig_t *rrsig) { return (key); } -/* +/*% * Check to see if we expect to find a key at this name. If we see a RRSIG * and can't find the signing key that we expect to find, we drop the rrsig. * I'm not sure if this is completely correct, but it seems to work. @@ -341,7 +343,7 @@ setverifies(dns_name_t *name, dns_rdataset_t *set, signer_key_t *key, } } -/* +/*% * Signs a set. Goes through contortions to decide if each RRSIG should * be dropped or retained, and then determines if any new SIGs need to * be generated. @@ -602,7 +604,7 @@ opendb(const char *prefix, dns_name_t *name, dns_rdataclass_t rdclass, dns_db_detach(dbp); } -/* +/*% * Loads the key set for a child zone, if there is one, and builds DS records. */ static isc_result_t @@ -779,7 +781,7 @@ delegation(dns_name_t *name, dns_dbnode_t *node, isc_uint32_t *ttlp) { return (ISC_TF(result == ISC_R_SUCCESS)); } -/* +/*% * Signs all records at a name. This mostly just signs each set individually, * but also adds the RRSIG bit to any NSECs generated earlier, deals with * parent/child KEY signatures, and handles other exceptional cases. @@ -1028,7 +1030,7 @@ active_node(dns_dbnode_t *node) { return (active); } -/* +/*% * Extracts the TTL from the SOA. */ static dns_ttl_t @@ -1060,7 +1062,7 @@ soattl(void) { return (ttl); } -/* +/*% * Delete any RRSIG records at a node. */ static void @@ -1096,7 +1098,7 @@ cleannode(dns_db_t *db, dns_dbversion_t *version, dns_dbnode_t *node) { dns_rdatasetiter_destroy(&rdsiter); } -/* +/*% * Set up the iterator and global state before starting the tasks. */ static void @@ -1111,7 +1113,7 @@ presign(void) { check_result(result, "dns_dbiterator_first()"); } -/* +/*% * Clean up the iterator and global state after the tasks complete. */ static void @@ -1119,7 +1121,7 @@ postsign(void) { dns_dbiterator_destroy(&gdbiter); } -/* +/*% * Assigns a node to a worker thread. This is protected by the master task's * lock. */ @@ -1199,7 +1201,7 @@ assignwork(isc_task_t *task, isc_task_t *worker) { assigned++; } -/* +/*% * Start a worker task */ static void @@ -1211,7 +1213,7 @@ startworker(isc_task_t *task, isc_event_t *event) { isc_event_free(&event); } -/* +/*% * Write a node to the output file, and restart the worker task. */ static void @@ -1229,7 +1231,7 @@ writenode(isc_task_t *task, isc_event_t *event) { isc_event_free(&event); } -/* +/*% * Sign a database node. */ static void @@ -1254,7 +1256,7 @@ sign(isc_task_t *task, isc_event_t *event) { isc_task_send(master, ISC_EVENT_PTR(&wevent)); } -/* +/*% * Generate NSEC records for the zone. */ static void @@ -1329,7 +1331,7 @@ nsecify(void) { dns_dbiterator_destroy(&dbiter); } -/* +/*% * Load the zone file from disk */ static void @@ -1361,7 +1363,7 @@ loadzone(char *file, char *origin, dns_rdataclass_t rdclass, dns_db_t **db) { file, isc_result_totext(result)); } -/* +/*% * Finds all public zone keys in the zone, and attempts to load the * private keys from disk. */ @@ -1400,7 +1402,7 @@ loadzonekeys(dns_db_t *db) { dns_db_closeversion(db, ¤tversion, ISC_FALSE); } -/* +/*% * Finds all public zone keys in the zone. */ static void diff --git a/bin/dnssec/dnssectool.c b/bin/dnssec/dnssectool.c index 7012045dff..4ff240a7b6 100644 --- a/bin/dnssec/dnssectool.c +++ b/bin/dnssec/dnssectool.c @@ -15,7 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dnssectool.c,v 1.40 2004/03/05 04:57:41 marka Exp $ */ +/* $Id: dnssectool.c,v 1.41 2005/04/27 04:55:48 sra Exp $ */ + +/*! \file */ + +/*% + * DNSSEC Support Routines. + */ #include diff --git a/bin/named/builtin.c b/bin/named/builtin.c index 8fdf91b71f..31d3f269f6 100644 --- a/bin/named/builtin.c +++ b/bin/named/builtin.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: builtin.c,v 1.5 2004/03/05 04:57:46 marka Exp $ */ +/* $Id: builtin.c,v 1.6 2005/04/27 04:55:48 sra Exp $ */ -/* +/*! \file + * \brief * The built-in "version", "hostname", "id" and "authors" databases. */ diff --git a/bin/named/client.c b/bin/named/client.c index d33620a819..95ab3f9ac4 100644 --- a/bin/named/client.c +++ b/bin/named/client.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: client.c,v 1.225 2005/03/15 00:46:29 marka Exp $ */ +/* $Id: client.c,v 1.226 2005/04/27 04:55:48 sra Exp $ */ #include @@ -53,7 +53,9 @@ *** Client ***/ -/* +/*! \file + * Client Routines + * * Important note! * * All client state changes, other than that from idle to listening, occur @@ -87,6 +89,7 @@ #define SEND_BUFFER_SIZE 4096 #define RECV_BUFFER_SIZE 4096 +/*% nameserver client manager structure */ struct ns_clientmgr { /* Unlocked. */ unsigned int magic; @@ -96,15 +99,15 @@ struct ns_clientmgr { isc_mutex_t lock; /* Locked by lock. */ isc_boolean_t exiting; - client_list_t active; /* Active clients */ - client_list_t recursing; /* Recursing clients */ - client_list_t inactive; /* To be recycled */ + client_list_t active; /*%< Active clients */ + client_list_t recursing; /*%< Recursing clients */ + client_list_t inactive; /*%< To be recycled */ }; #define MANAGER_MAGIC ISC_MAGIC('N', 'S', 'C', 'm') #define VALID_MANAGER(m) ISC_MAGIC_VALID(m, MANAGER_MAGIC) -/* +/*! * Client object states. Ordering is significant: higher-numbered * states are generally "more active", meaning that the client can * have more dynamically allocated data, outstanding events, etc. @@ -117,12 +120,12 @@ struct ns_clientmgr { */ #define NS_CLIENTSTATE_FREED 0 -/* +/*%< * The client object no longer exists. */ #define NS_CLIENTSTATE_INACTIVE 1 -/* +/*%< * The client object exists and has a task and timer. * Its "query" struct and sendbuf are initialized. * It is on the client manager's list of inactive clients. @@ -130,7 +133,7 @@ struct ns_clientmgr { */ #define NS_CLIENTSTATE_READY 2 -/* +/*%< * The client object is either a TCP or a UDP one, and * it is associated with a network interface. It is on the * client manager's list of active clients. @@ -143,7 +146,7 @@ struct ns_clientmgr { */ #define NS_CLIENTSTATE_READING 3 -/* +/*%< * The client object is a TCP client object that has received * a connection. It has a tcpsocket, tcpmsg, TCP quota, and an * outstanding TCP read request. This state is not used for @@ -151,14 +154,14 @@ struct ns_clientmgr { */ #define NS_CLIENTSTATE_WORKING 4 -/* +/*%< * The client object has received a request and is working * on it. It has a view, and it may have any of a non-reset OPT, * recursion quota, and an outstanding write request. */ #define NS_CLIENTSTATE_MAX 9 -/* +/*%< * Sentinel value used to indicate "no state". When client->newstate * has this value, we are not attempting to exit the current state. * Must be greater than any valid state. @@ -215,7 +218,7 @@ ns_client_settimeout(ns_client_t *client, unsigned int seconds) { } } -/* +/*% * Check for a deactivation or shutdown request and take appropriate * action. Returns ISC_TRUE if either is in progress; in this case * the caller must no longer use the client object as it may have been @@ -489,7 +492,7 @@ exit_check(ns_client_t *client) { return (ISC_TRUE); } -/* +/*% * The client's task has received the client's control event * as part of the startup process. */ @@ -515,7 +518,7 @@ client_start(isc_task_t *task, isc_event_t *event) { } -/* +/*% * The client's task has received a shutdown event. */ static void @@ -684,7 +687,7 @@ client_senddone(isc_task_t *task, isc_event_t *event) { ns_client_next(client, ISC_R_SUCCESS); } -/* +/*% * We only want to fail with ISC_R_NOSPACE when called from * ns_client_sendraw() and not when called from ns_client_send(), * tcpbuffer is NULL when called from ns_client_sendraw() and diff --git a/bin/named/config.c b/bin/named/config.c index 98a4c4fef1..f4e5966d8c 100644 --- a/bin/named/config.c +++ b/bin/named/config.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: config.c,v 1.55 2005/01/11 23:10:04 marka Exp $ */ +/* $Id: config.c,v 1.56 2005/04/27 04:55:49 sra Exp $ */ + +/*! \file */ #include @@ -42,6 +44,7 @@ #include #include +/*% default configuration */ static char defaultconf[] = "\ options {\n\ # blackhole {none;};\n" diff --git a/bin/named/control.c b/bin/named/control.c index f8983fc827..e0577f6963 100644 --- a/bin/named/control.c +++ b/bin/named/control.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: control.c,v 1.24 2005/04/07 03:49:57 marka Exp $ */ +/* $Id: control.c,v 1.25 2005/04/27 04:55:49 sra Exp $ */ + +/*! \file */ #include @@ -52,7 +54,7 @@ command_compare(const char *text, const char *command) { return (ISC_FALSE); } -/* +/*% * This function is called to process the incoming command * when a control channel message is received. */ diff --git a/bin/named/controlconf.c b/bin/named/controlconf.c index 63d830439d..2c4b2689f4 100644 --- a/bin/named/controlconf.c +++ b/bin/named/controlconf.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: controlconf.c,v 1.43 2005/02/23 01:06:36 marka Exp $ */ +/* $Id: controlconf.c,v 1.44 2005/04/27 04:55:50 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/include/named/builtin.h b/bin/named/include/named/builtin.h index fb01182e33..129a3a825b 100644 --- a/bin/named/include/named/builtin.h +++ b/bin/named/include/named/builtin.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: builtin.h,v 1.2 2004/03/05 04:57:55 marka Exp $ */ +/* $Id: builtin.h,v 1.3 2005/04/27 04:55:56 sra Exp $ */ #ifndef NAMED_BUILTIN_H #define NAMED_BUILTIN_H 1 +/*! \file */ + #include isc_result_t ns_builtin_init(void); diff --git a/bin/named/include/named/client.h b/bin/named/include/named/client.h index dc2572f142..7993fc99de 100644 --- a/bin/named/include/named/client.h +++ b/bin/named/include/named/client.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: client.h,v 1.72 2005/02/11 00:01:57 marka Exp $ */ +/* $Id: client.h,v 1.73 2005/04/27 04:55:56 sra Exp $ */ #ifndef NAMED_CLIENT_H #define NAMED_CLIENT_H 1 @@ -24,9 +24,8 @@ ***** Module Info *****/ -/* - * Client - * +/*! \file + * \brief * This module defines two objects, ns_client_t and ns_clientmgr_t. * * An ns_client_t object handles incoming DNS requests from clients @@ -44,12 +43,12 @@ * fully handled (which can be much later), the ns_client_t must be * notified of this by calling one of the following functions * exactly once in the context of its task: - * + * \code * ns_client_send() (sending a non-error response) * ns_client_sendraw() (sending a raw response) * ns_client_error() (sending an error response) * ns_client_next() (sending no response) - * + *\endcode * This will release any resources used by the request and * and allow the ns_client_t to listen for the next request. * @@ -84,6 +83,7 @@ typedef ISC_LIST(ns_client_t) client_list_t; +/*% nameserver client structure */ struct ns_client { unsigned int magic; isc_mem_t * mctx; @@ -122,9 +122,9 @@ struct ns_client { ns_query_t query; isc_stdtime_t requesttime; isc_stdtime_t now; - dns_name_t signername; /* [T]SIG key name */ - dns_name_t * signer; /* NULL if not valid sig */ - isc_boolean_t mortal; /* Die after handling request */ + dns_name_t signername; /*%< [T]SIG key name */ + dns_name_t * signer; /*%< NULL if not valid sig */ + isc_boolean_t mortal; /*%< Die after handling request */ isc_quota_t *tcpquota; isc_quota_t *recursionquota; ns_interface_t *interface; @@ -132,7 +132,7 @@ struct ns_client { isc_boolean_t peeraddr_valid; struct in6_pktinfo pktinfo; isc_event_t ctlevent; - /* + /*% * Information about recent FORMERR response(s), for * FORMERR loop avoidance. This is separate for each * client object rather than global only to avoid @@ -144,7 +144,7 @@ struct ns_client { dns_messageid_t id; } formerrcache; ISC_LINK(ns_client_t) link; - /* + /*% * The list 'link' is part of, or NULL if not on any list. */ client_list_t *list; @@ -154,38 +154,41 @@ struct ns_client { #define NS_CLIENT_VALID(c) ISC_MAGIC_VALID(c, NS_CLIENT_MAGIC) #define NS_CLIENTATTR_TCP 0x01 -#define NS_CLIENTATTR_RA 0x02 /* Client gets recusive service */ -#define NS_CLIENTATTR_PKTINFO 0x04 /* pktinfo is valid */ -#define NS_CLIENTATTR_MULTICAST 0x08 /* recv'd from multicast */ -#define NS_CLIENTATTR_WANTDNSSEC 0x10 /* include dnssec records */ +#define NS_CLIENTATTR_RA 0x02 /*%< Client gets recusive service */ +#define NS_CLIENTATTR_PKTINFO 0x04 /*%< pktinfo is valid */ +#define NS_CLIENTATTR_MULTICAST 0x08 /*%< recv'd from multicast */ +#define NS_CLIENTATTR_WANTDNSSEC 0x10 /*%< include dnssec records */ /*** *** Functions ***/ -/* +/*% * Note! These ns_client_ routines MUST be called ONLY from the client's * task in order to ensure synchronization. */ void ns_client_send(ns_client_t *client); -/* +/*% * Finish processing the current client request and * send client->message as a response. + * \brief + * Note! These ns_client_ routines MUST be called ONLY from the client's + * task in order to ensure synchronization. */ void ns_client_sendraw(ns_client_t *client, dns_message_t *msg); -/* +/*% * Finish processing the current client request and * send msg as a response using client->message->id for the id. */ void ns_client_error(ns_client_t *client, isc_result_t result); -/* +/*% * Finish processing the current client request and return * an error response to the client. The error response * will have an RCODE determined by 'result'. @@ -193,32 +196,32 @@ ns_client_error(ns_client_t *client, isc_result_t result); void ns_client_next(ns_client_t *client, isc_result_t result); -/* +/*% * Finish processing the current client request, * return no response to the client. */ isc_boolean_t ns_client_shuttingdown(ns_client_t *client); -/* +/*% * Return ISC_TRUE iff the client is currently shutting down. */ void ns_client_attach(ns_client_t *source, ns_client_t **target); -/* +/*% * Attach '*targetp' to 'source'. */ void ns_client_detach(ns_client_t **clientp); -/* +/*% * Detach '*clientp' from its client. */ isc_result_t ns_client_replace(ns_client_t *client); -/* +/*% * Try to replace the current client with a new one, so that the * current one can go off and do some lengthy work without * leaving the dispatch/socket without service. @@ -226,20 +229,20 @@ ns_client_replace(ns_client_t *client); void ns_client_settimeout(ns_client_t *client, unsigned int seconds); -/* +/*% * Set a timer in the client to go off in the specified amount of time. */ isc_result_t ns_clientmgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr, ns_clientmgr_t **managerp); -/* +/*% * Create a client manager. */ void ns_clientmgr_destroy(ns_clientmgr_t **managerp); -/* +/*% * Destroy a client manager and all ns_client_t objects * managed by it. */ @@ -247,7 +250,7 @@ ns_clientmgr_destroy(ns_clientmgr_t **managerp); isc_result_t ns_clientmgr_createclients(ns_clientmgr_t *manager, unsigned int n, ns_interface_t *ifp, isc_boolean_t tcp); -/* +/*% * Create up to 'n' clients listening on interface 'ifp'. * If 'tcp' is ISC_TRUE, the clients will listen for TCP connections, * otherwise for UDP requests. @@ -255,7 +258,7 @@ ns_clientmgr_createclients(ns_clientmgr_t *manager, unsigned int n, isc_sockaddr_t * ns_client_getsockaddr(ns_client_t *client); -/* +/*% * Get the socket address of the client whose request is * currently being processed. */ @@ -264,27 +267,27 @@ isc_result_t ns_client_checkaclsilent(ns_client_t *client,dns_acl_t *acl, isc_boolean_t default_allow); -/* +/*% * Convenience function for client request ACL checking. * * Check the current client request against 'acl'. If 'acl' * is NULL, allow the request iff 'default_allow' is ISC_TRUE. * * Notes: - * This is appropriate for checking allow-update, + *\li This is appropriate for checking allow-update, * allow-query, allow-transfer, etc. It is not appropriate * for checking the blackhole list because we treat positive * matches as "allow" and negative matches as "deny"; in * the case of the blackhole list this would be backwards. * * Requires: - * 'client' points to a valid client. - * 'acl' points to a valid ACL, or is NULL. + *\li 'client' points to a valid client. + *\li 'acl' points to a valid ACL, or is NULL. * * Returns: - * ISC_R_SUCCESS if the request should be allowed - * ISC_R_REFUSED if the request should be denied - * No other return values are possible. + *\li ISC_R_SUCCESS if the request should be allowed + * \li ISC_R_REFUSED if the request should be denied + *\li No other return values are possible. */ isc_result_t @@ -292,16 +295,16 @@ ns_client_checkacl(ns_client_t *client, const char *opname, dns_acl_t *acl, isc_boolean_t default_allow, int log_level); -/* +/*% * Like ns_client_checkacl, but also logs the outcome of the * check at log level 'log_level' if denied, and at debug 3 * if approved. Log messages will refer to the request as * an 'opname' request. * * Requires: - * Those of ns_client_checkaclsilent(), and: + *\li Those of ns_client_checkaclsilent(), and: * - * 'opname' points to a null-terminated string. + *\li 'opname' points to a null-terminated string. */ void @@ -323,14 +326,14 @@ ns_client_aclmsg(const char *msg, dns_name_t *name, dns_rdatatype_t type, void ns_client_recursing(ns_client_t *client, isc_boolean_t killoldest); -/* +/*% * Add client to end of recursing list. If 'killoldest' is true * kill the oldest recursive client (list head). */ void ns_client_dumprecursing(FILE *f, ns_clientmgr_t *manager); -/* +/*% * Dump the outstanding recursive queries to 'f'. */ diff --git a/bin/named/include/named/config.h b/bin/named/include/named/config.h index 083d3eb0af..7374de9574 100644 --- a/bin/named/include/named/config.h +++ b/bin/named/include/named/config.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: config.h,v 1.7 2004/04/20 14:11:47 marka Exp $ */ +/* $Id: config.h,v 1.8 2005/04/27 04:55:57 sra Exp $ */ #ifndef NAMED_CONFIG_H #define NAMED_CONFIG_H 1 +/*! \file */ + #include #include diff --git a/bin/named/include/named/control.h b/bin/named/include/named/control.h index 27dfde4d13..525faa35f3 100644 --- a/bin/named/include/named/control.h +++ b/bin/named/include/named/control.h @@ -15,12 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: control.h,v 1.18 2005/01/12 01:56:11 marka Exp $ */ +/* $Id: control.h,v 1.19 2005/04/27 04:55:57 sra Exp $ */ #ifndef NAMED_CONTROL_H #define NAMED_CONTROL_H 1 -/* +/*! \file + * \brief * The name server command channel. */ @@ -56,13 +57,13 @@ isc_result_t ns_controls_create(ns_server_t *server, ns_controls_t **ctrlsp); -/* +/*%< * Create an initial, empty set of command channels for 'server'. */ void ns_controls_destroy(ns_controls_t **ctrlsp); -/* +/*%< * Destroy a set of command channels. * * Requires: @@ -72,7 +73,7 @@ ns_controls_destroy(ns_controls_t **ctrlsp); isc_result_t ns_controls_configure(ns_controls_t *controls, cfg_obj_t *config, cfg_aclconfctx_t *aclconfctx); -/* +/*%< * Configure zero or more command channels into 'controls' * as defined in the configuration parse tree 'config'. * The channels will evaluate ACLs in the context of @@ -81,7 +82,7 @@ ns_controls_configure(ns_controls_t *controls, cfg_obj_t *config, void ns_controls_shutdown(ns_controls_t *controls); -/* +/*%< * Initiate shutdown of all the command channels in 'controls'. */ diff --git a/bin/named/include/named/globals.h b/bin/named/include/named/globals.h index de30308f24..87861ff00f 100644 --- a/bin/named/include/named/globals.h +++ b/bin/named/include/named/globals.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: globals.h,v 1.64 2004/03/05 04:57:55 marka Exp $ */ +/* $Id: globals.h,v 1.65 2005/04/27 04:55:57 sra Exp $ */ #ifndef NAMED_GLOBALS_H #define NAMED_GLOBALS_H 1 +/*! \file */ + #include #include #include diff --git a/bin/named/include/named/interfacemgr.h b/bin/named/include/named/interfacemgr.h index 1838affe95..55904308f1 100644 --- a/bin/named/include/named/interfacemgr.h +++ b/bin/named/include/named/interfacemgr.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: interfacemgr.h,v 1.29 2005/02/11 00:01:57 marka Exp $ */ +/* $Id: interfacemgr.h,v 1.30 2005/04/27 04:55:57 sra Exp $ */ #ifndef NAMED_INTERFACEMGR_H #define NAMED_INTERFACEMGR_H 1 @@ -24,24 +24,23 @@ ***** Module Info *****/ -/* - * Interface manager - * +/*! \file + * \brief * The interface manager monitors the operating system's list * of network interfaces, creating and destroying listeners * as needed. * * Reliability: - * No impact expected. + *\li No impact expected. * * Resources: * * Security: - * The server will only be able to bind to the DNS port on + * \li The server will only be able to bind to the DNS port on * newly discovered interfaces if it is running as root. * * Standards: - * The API for scanning varies greatly among operating systems. + *\li The API for scanning varies greatly among operating systems. * This module attempts to hide the differences. */ @@ -67,21 +66,21 @@ #define NS_INTERFACEFLAG_ANYADDR 0x01U /* bound to "any" address */ +/*% The nameserver interface structure */ struct ns_interface { - unsigned int magic; /* Magic number. */ - ns_interfacemgr_t * mgr; /* Interface manager. */ + unsigned int magic; /*%< Magic number. */ + ns_interfacemgr_t * mgr; /*%< Interface manager. */ isc_mutex_t lock; - int references; /* Locked */ - unsigned int generation; /* Generation number. */ - isc_sockaddr_t addr; /* Address and port. */ - unsigned int flags; /* Interface characteristics */ - char name[32]; /* Null terminated. */ - dns_dispatch_t * udpdispatch; /* UDP dispatcher. */ - isc_socket_t * tcpsocket; /* TCP socket. */ - int ntcptarget; /* Desired number of concurrent - TCP accepts */ - int ntcpcurrent; /* Current ditto, locked */ - ns_clientmgr_t * clientmgr; /* Client manager. */ + int references; /*%< Locked */ + unsigned int generation; /*%< Generation number. */ + isc_sockaddr_t addr; /*%< Address and port. */ + unsigned int flags; /*%< Interface characteristics */ + char name[32]; /*%< Null terminated. */ + dns_dispatch_t * udpdispatch; /*%< UDP dispatcher. */ + isc_socket_t * tcpsocket; /*%< TCP socket. */ + int ntcptarget; /*%< Desired number of concurrent TCP accepts */ + int ntcpcurrent; /*%< Current ditto, locked */ + ns_clientmgr_t * clientmgr; /*%< Client manager. */ ISC_LINK(ns_interface_t) link; }; @@ -94,7 +93,7 @@ ns_interfacemgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr, isc_socketmgr_t *socketmgr, dns_dispatchmgr_t *dispatchmgr, ns_interfacemgr_t **mgrp); -/* +/*% * Create a new interface manager. * * Initially, the new manager will not listen on any interfaces. @@ -113,7 +112,7 @@ ns_interfacemgr_shutdown(ns_interfacemgr_t *mgr); void ns_interfacemgr_scan(ns_interfacemgr_t *mgr, isc_boolean_t verbose); -/* +/*% * Scan the operatings system's list of network interfaces * and create listeners when new interfaces are discovered. * Shut down the sockets for interfaces that go away. @@ -126,7 +125,7 @@ ns_interfacemgr_scan(ns_interfacemgr_t *mgr, isc_boolean_t verbose); void ns_interfacemgr_adjust(ns_interfacemgr_t *mgr, ns_listenlist_t *list, isc_boolean_t verbose); -/* +/*% * Similar to ns_interfacemgr_scan(), but this function also tries to see the * need for an explicit listen-on when a list element in 'list' is going to * override an already-listening a wildcard interface. @@ -139,14 +138,14 @@ ns_interfacemgr_adjust(ns_interfacemgr_t *mgr, ns_listenlist_t *list, void ns_interfacemgr_setlistenon4(ns_interfacemgr_t *mgr, ns_listenlist_t *value); -/* +/*% * Set the IPv4 "listen-on" list of 'mgr' to 'value'. * The previous IPv4 listen-on list is freed. */ void ns_interfacemgr_setlistenon6(ns_interfacemgr_t *mgr, ns_listenlist_t *value); -/* +/*% * Set the IPv6 "listen-on" list of 'mgr' to 'value'. * The previous IPv6 listen-on list is freed. */ @@ -162,7 +161,7 @@ ns_interface_detach(ns_interface_t **targetp); void ns_interface_shutdown(ns_interface_t *ifp); -/* +/*% * Stop listening for queries on interface 'ifp'. * May safely be called multiple times. */ diff --git a/bin/named/include/named/listenlist.h b/bin/named/include/named/listenlist.h index 0bedacd727..10a880ae7d 100644 --- a/bin/named/include/named/listenlist.h +++ b/bin/named/include/named/listenlist.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: listenlist.h,v 1.11 2004/03/05 04:57:56 marka Exp $ */ +/* $Id: listenlist.h,v 1.12 2005/04/27 04:55:58 sra Exp $ */ #ifndef NAMED_LISTENLIST_H #define NAMED_LISTENLIST_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * "Listen lists", as in the "listen-on" configuration statement. */ @@ -62,38 +63,38 @@ struct ns_listenlist { isc_result_t ns_listenelt_create(isc_mem_t *mctx, in_port_t port, dns_acl_t *acl, ns_listenelt_t **target); -/* +/*% * Create a listen-on list element. */ void ns_listenelt_destroy(ns_listenelt_t *elt); -/* +/*% * Destroy a listen-on list element. */ isc_result_t ns_listenlist_create(isc_mem_t *mctx, ns_listenlist_t **target); -/* +/*% * Create a new, empty listen-on list. */ void ns_listenlist_attach(ns_listenlist_t *source, ns_listenlist_t **target); -/* +/*% * Attach '*target' to '*source'. */ void ns_listenlist_detach(ns_listenlist_t **listp); -/* +/*% * Detach 'listp'. */ isc_result_t ns_listenlist_default(isc_mem_t *mctx, in_port_t port, isc_boolean_t enabled, ns_listenlist_t **target); -/* +/*% * Create a listen-on list with default contents, matching * all addresses with port 'port' (if 'enabled' is ISC_TRUE), * or no addresses (if 'enabled' is ISC_FALSE). diff --git a/bin/named/include/named/log.h b/bin/named/include/named/log.h index 011f3a91fd..d9cfb95b38 100644 --- a/bin/named/include/named/log.h +++ b/bin/named/include/named/log.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: log.h,v 1.21 2004/03/05 04:57:56 marka Exp $ */ +/* $Id: log.h,v 1.22 2005/04/27 04:55:58 sra Exp $ */ #ifndef NAMED_LOG_H #define NAMED_LOG_H 1 +/*! \file */ + #include #include @@ -54,7 +56,7 @@ isc_result_t ns_log_init(isc_boolean_t safe); -/* +/*% * Initialize the logging system and set up an initial default * logging default configuration that will be used until the * config file has been read. @@ -66,7 +68,7 @@ ns_log_init(isc_boolean_t safe); isc_result_t ns_log_setdefaultchannels(isc_logconfig_t *lcfg); -/* +/*% * Set up logging channels according to the named defaults, which * may differ from the logging library defaults. Currently, * this just means setting up default_debug. @@ -74,19 +76,19 @@ ns_log_setdefaultchannels(isc_logconfig_t *lcfg); isc_result_t ns_log_setsafechannels(isc_logconfig_t *lcfg); -/* +/*% * Like ns_log_setdefaultchannels(), but omits any logging to files. */ isc_result_t ns_log_setdefaultcategory(isc_logconfig_t *lcfg); -/* +/*% * Set up "category default" to go to the right places. */ isc_result_t ns_log_setunmatchedcategory(isc_logconfig_t *lcfg); -/* +/*% * Set up "category unmatched" to go to the right places. */ diff --git a/bin/named/include/named/logconf.h b/bin/named/include/named/logconf.h index af4510eced..b17cf8c039 100644 --- a/bin/named/include/named/logconf.h +++ b/bin/named/include/named/logconf.h @@ -15,16 +15,18 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: logconf.h,v 1.11 2004/03/05 04:57:56 marka Exp $ */ +/* $Id: logconf.h,v 1.12 2005/04/27 04:55:58 sra Exp $ */ #ifndef NAMED_LOGCONF_H #define NAMED_LOGCONF_H 1 +/*! \file */ + #include isc_result_t ns_log_configure(isc_logconfig_t *logconf, cfg_obj_t *logstmt); -/* +/*%< * Set up the logging configuration in '*logconf' according to * the named.conf data in 'logstmt'. */ diff --git a/bin/named/include/named/lwaddr.h b/bin/named/include/named/lwaddr.h index 2dabb3f36f..1ce4ca59d9 100644 --- a/bin/named/include/named/lwaddr.h +++ b/bin/named/include/named/lwaddr.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwaddr.h,v 1.4 2004/03/05 04:57:56 marka Exp $ */ +/* $Id: lwaddr.h,v 1.5 2005/04/27 04:55:58 sra Exp $ */ + +/*! \file */ #include #include diff --git a/bin/named/include/named/lwdclient.h b/bin/named/include/named/lwdclient.h index aea6f6d650..3fb1ab75f8 100644 --- a/bin/named/include/named/lwdclient.h +++ b/bin/named/include/named/lwdclient.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwdclient.h,v 1.14 2004/03/05 04:57:56 marka Exp $ */ +/* $Id: lwdclient.h,v 1.15 2005/04/27 04:55:58 sra Exp $ */ #ifndef NAMED_LWDCLIENT_H #define NAMED_LWDCLIENT_H 1 +/*! \file */ + #include #include #include @@ -37,23 +39,24 @@ #define LWRD_SHUTDOWN (LWRD_EVENTCLASS + 0x0001) +/*% Lighweight Resolver Daemon Client */ struct ns_lwdclient { - isc_sockaddr_t address; /* where to reply */ + isc_sockaddr_t address; /*%< where to reply */ struct in6_pktinfo pktinfo; isc_boolean_t pktinfo_valid; - ns_lwdclientmgr_t *clientmgr; /* our parent */ + ns_lwdclientmgr_t *clientmgr; /*%< our parent */ ISC_LINK(ns_lwdclient_t) link; unsigned int state; - void *arg; /* packet processing state */ + void *arg; /*%< packet processing state */ /* * Received data info. */ - unsigned char buffer[LWRES_RECVLENGTH]; /* receive buffer */ - isc_uint32_t recvlength; /* length recv'd */ + unsigned char buffer[LWRES_RECVLENGTH]; /*%< receive buffer */ + isc_uint32_t recvlength; /*%< length recv'd */ lwres_lwpacket_t pkt; - /* + /*% * Send data state. If sendbuf != buffer (that is, the send buffer * isn't our receive buffer) it will be freed to the lwres_context_t. */ @@ -61,19 +64,19 @@ struct ns_lwdclient { isc_uint32_t sendlength; isc_buffer_t recv_buffer; - /* + /*% * gabn (get address by name) state info. */ dns_adbfind_t *find; dns_adbfind_t *v4find; dns_adbfind_t *v6find; - unsigned int find_wanted; /* Addresses we want */ + unsigned int find_wanted; /*%< Addresses we want */ dns_fixedname_t query_name; dns_fixedname_t target_name; ns_lwsearchctx_t searchctx; lwres_gabnresponse_t gabn; - /* + /*% * gnba (get name by address) state info. */ lwres_gnbaresponse_t gnba; @@ -81,7 +84,7 @@ struct ns_lwdclient { unsigned int options; isc_netaddr_t na; - /* + /*% * grbn (get rrset by name) state info. * * Note: this also uses target_name and searchctx. @@ -90,7 +93,7 @@ struct ns_lwdclient { dns_lookup_t *lookup; dns_rdatatype_t rdtype; - /* + /*% * Alias and address info. This is copied up to the gabn/gnba * structures eventually. * @@ -103,7 +106,7 @@ struct ns_lwdclient { lwres_addr_t addrs[LWRES_MAX_ADDRS]; }; -/* +/*% * Client states. * * _IDLE The client is not doing anything at all. @@ -156,7 +159,7 @@ struct ns_lwdclient { #define NS_LWDCLIENT_ISSEND(c) \ ((c)->state == NS_LWDCLIENT_STATESEND) -/* +/*% * Overall magic test that means we're not idle. */ #define NS_LWDCLIENT_ISRUNNING(c) (!NS_LWDCLIENT_ISIDLE(c)) @@ -174,17 +177,18 @@ struct ns_lwdclient { #define NS_LWDCLIENT_SETSENDDONE(c) \ ((c)->state = NS_LWDCLIENT_STATESENDDONE) +/*% lightweight daemon client manager */ struct ns_lwdclientmgr { ns_lwreslistener_t *listener; isc_mem_t *mctx; - isc_socket_t *sock; /* socket to use */ + isc_socket_t *sock; /*%< socket to use */ dns_view_t *view; - lwres_context_t *lwctx; /* lightweight proto context */ - isc_task_t *task; /* owning task */ + lwres_context_t *lwctx; /*%< lightweight proto context */ + isc_task_t *task; /*%< owning task */ unsigned int flags; ISC_LINK(ns_lwdclientmgr_t) link; - ISC_LIST(ns_lwdclient_t) idle; /* idle client slots */ - ISC_LIST(ns_lwdclient_t) running; /* running clients */ + ISC_LIST(ns_lwdclient_t) idle; /*%< idle client slots */ + ISC_LIST(ns_lwdclient_t) running; /*%< running clients */ }; #define NS_LWDCLIENTMGR_FLAGRECVPENDING 0x00000001 diff --git a/bin/named/include/named/lwresd.h b/bin/named/include/named/lwresd.h index 1893092ab6..5a757fa0fe 100644 --- a/bin/named/include/named/lwresd.h +++ b/bin/named/include/named/lwresd.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwresd.h,v 1.13 2004/03/05 04:57:56 marka Exp $ */ +/* $Id: lwresd.h,v 1.14 2005/04/27 04:55:58 sra Exp $ */ #ifndef NAMED_LWRESD_H #define NAMED_LWRESD_H 1 +/*! \file */ + #include #include @@ -52,7 +54,7 @@ struct ns_lwreslistener { ISC_LINK(ns_lwreslistener_t) link; }; -/* +/*% * Configure lwresd. */ isc_result_t @@ -62,7 +64,7 @@ isc_result_t ns_lwresd_parseeresolvconf(isc_mem_t *mctx, cfg_parser_t *pctx, cfg_obj_t **configp); -/* +/*% * Trigger shutdown. */ void @@ -71,28 +73,35 @@ ns_lwresd_shutdown(void); /* * Manager functions */ +/*% create manager */ isc_result_t ns_lwdmanager_create(isc_mem_t *mctx, cfg_obj_t *lwres, ns_lwresd_t **lwresdp); +/*% attach to manager */ void ns_lwdmanager_attach(ns_lwresd_t *source, ns_lwresd_t **targetp); +/*% detach from manager */ void ns_lwdmanager_detach(ns_lwresd_t **lwresdp); /* * Listener functions */ +/*% attach to listener */ void ns_lwreslistener_attach(ns_lwreslistener_t *source, ns_lwreslistener_t **targetp); +/*% detach from lister */ void ns_lwreslistener_detach(ns_lwreslistener_t **listenerp); +/*% link client manager */ void ns_lwreslistener_unlinkcm(ns_lwreslistener_t *listener, ns_lwdclientmgr_t *cm); +/*% unlink client manager */ void ns_lwreslistener_linkcm(ns_lwreslistener_t *listener, ns_lwdclientmgr_t *cm); diff --git a/bin/named/include/named/lwsearch.h b/bin/named/include/named/lwsearch.h index a203298fb4..76931999e5 100644 --- a/bin/named/include/named/lwsearch.h +++ b/bin/named/include/named/lwsearch.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwsearch.h,v 1.5 2004/03/05 04:57:56 marka Exp $ */ +/* $Id: lwsearch.h,v 1.6 2005/04/27 04:55:59 sra Exp $ */ #ifndef NAMED_LWSEARCH_H #define NAMED_LWSEARCH_H 1 @@ -28,7 +28,8 @@ #include -/* +/*! \file + * \brief * Lightweight resolver search list types and routines. * * An ns_lwsearchlist_t holds a list of search path elements. @@ -37,6 +38,7 @@ * operation. */ +/*% An ns_lwsearchlist_t holds a list of search path elements. */ struct ns_lwsearchlist { unsigned int magic; @@ -45,7 +47,7 @@ struct ns_lwsearchlist { unsigned int refs; dns_namelist_t names; }; - +/*% An ns_lwsearchctx stores the state of search list during a lookup operation. */ struct ns_lwsearchctx { dns_name_t *relname; dns_name_t *searchname; @@ -57,51 +59,51 @@ struct ns_lwsearchctx { isc_result_t ns_lwsearchlist_create(isc_mem_t *mctx, ns_lwsearchlist_t **listp); -/* +/*%< * Create an empty search list object. */ void ns_lwsearchlist_attach(ns_lwsearchlist_t *source, ns_lwsearchlist_t **target); -/* +/*%< * Attach to a search list object. */ void ns_lwsearchlist_detach(ns_lwsearchlist_t **listp); -/* +/*%< * Detach from a search list object. */ isc_result_t ns_lwsearchlist_append(ns_lwsearchlist_t *list, dns_name_t *name); -/* +/*%< * Append an element to a search list. This creates a copy of the name. */ void ns_lwsearchctx_init(ns_lwsearchctx_t *sctx, ns_lwsearchlist_t *list, dns_name_t *name, unsigned int ndots); -/* +/*%< * Creates a search list context structure. */ void ns_lwsearchctx_first(ns_lwsearchctx_t *sctx); -/* +/*%< * Moves the search list context iterator to the first element, which * is usually the exact name. */ isc_result_t ns_lwsearchctx_next(ns_lwsearchctx_t *sctx); -/* +/*%< * Moves the search list context iterator to the next element. */ isc_result_t ns_lwsearchctx_current(ns_lwsearchctx_t *sctx, dns_name_t *absname); -/* +/*%< * Obtains the current name to be looked up. This involves either * concatenating the name with a search path element, making an * exact name absolute, or doing nothing. diff --git a/bin/named/include/named/main.h b/bin/named/include/named/main.h index 1c4d97682d..6d5aa6bc2a 100644 --- a/bin/named/include/named/main.h +++ b/bin/named/include/named/main.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: main.h,v 1.11 2004/03/05 04:57:56 marka Exp $ */ +/* $Id: main.h,v 1.12 2005/04/27 04:55:59 sra Exp $ */ #ifndef NAMED_MAIN_H #define NAMED_MAIN_H 1 +/*! \file */ + void ns_main_earlyfatal(const char *format, ...) ISC_FORMAT_PRINTF(1, 2); diff --git a/bin/named/include/named/notify.h b/bin/named/include/named/notify.h index 9e215d4708..85078da5a9 100644 --- a/bin/named/include/named/notify.h +++ b/bin/named/include/named/notify.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: notify.h,v 1.10 2004/03/05 04:57:56 marka Exp $ */ +/* $Id: notify.h,v 1.11 2005/04/27 04:55:59 sra Exp $ */ #ifndef NAMED_NOTIFY_H #define NAMED_NOTIFY_H 1 @@ -27,8 +27,9 @@ *** Module Info ***/ -/* - * RFC 1996 +/*! \file + * \brief + * RFC1996 * A Mechanism for Prompt Notification of Zone Changes (DNS NOTIFY) */ @@ -39,7 +40,7 @@ void ns_notify_start(ns_client_t *client); -/* +/*%< * Examines the incoming message to determine apporiate zone. * Returns FORMERR if there is not exactly one question. * Returns REFUSED if we do not serve the listed zone. @@ -47,7 +48,7 @@ ns_notify_start(ns_client_t *client); * and returns the return status. * * Requires - * client to be valid. + *\li client to be valid. */ #endif /* NAMED_NOTIFY_H */ diff --git a/bin/named/include/named/query.h b/bin/named/include/named/query.h index 50ab927f47..f5dbdadb32 100644 --- a/bin/named/include/named/query.h +++ b/bin/named/include/named/query.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: query.h,v 1.36 2004/03/05 04:57:57 marka Exp $ */ +/* $Id: query.h,v 1.37 2005/04/27 04:56:00 sra Exp $ */ #ifndef NAMED_QUERY_H #define NAMED_QUERY_H 1 +/*! \file */ + #include #include #include @@ -28,6 +30,7 @@ #include +/*% nameserver database version structure */ typedef struct ns_dbversion { dns_db_t *db; dns_dbversion_t *version; @@ -35,6 +38,7 @@ typedef struct ns_dbversion { ISC_LINK(struct ns_dbversion) link; } ns_dbversion_t; +/*% nameserver query structure */ struct ns_query { unsigned int attributes; unsigned int restarts; diff --git a/bin/named/include/named/server.h b/bin/named/include/named/server.h index e50f9ab354..40c25761da 100644 --- a/bin/named/include/named/server.h +++ b/bin/named/include/named/server.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: server.h,v 1.76 2004/12/21 10:45:15 jinmei Exp $ */ +/* $Id: server.h,v 1.77 2005/04/27 04:56:00 sra Exp $ */ #ifndef NAMED_SERVER_H #define NAMED_SERVER_H 1 +/*! \file */ + #include #include #include @@ -35,7 +37,7 @@ #define NS_EVENT_RELOAD (NS_EVENTCLASS + 0) #define NS_EVENT_CLIENTCONTROL (NS_EVENTCLASS + 1) -/* +/*% * Name server state. Better here than in lots of separate global variables. */ struct ns_server { @@ -49,21 +51,21 @@ struct ns_server { isc_quota_t tcpquota; isc_quota_t recursionquota; dns_acl_t *blackholeacl; - char * statsfile; /* Statistics file name */ - char * dumpfile; /* Dump file name */ - char * recfile; /* Recursive file name */ - isc_boolean_t version_set; /* User has set version */ - char * version; /* User-specified version */ - isc_boolean_t hostname_set; /* User has set hostname */ - char * hostname; /* User-specified hostname */ - /* Use hostname for server id */ + char * statsfile; /*%< Statistics file name */ + char * dumpfile; /*%< Dump file name */ + char * recfile; /*%< Recursive file name */ + isc_boolean_t version_set; /*%< User has set version */ + char * version; /*%< User-specified version */ + isc_boolean_t hostname_set; /*%< User has set hostname */ + char * hostname; /*%< User-specified hostname */ + /*% Use hostname for server id */ isc_boolean_t server_usehostname; - char * server_id; /* User-specified server id */ + char * server_id; /*%< User-specified server id */ - /* Empty zone SOA ORIGIN and CONTACT */ + /*% Empty zone SOA ORIGIN and CONTACT */ char * empty_contact; char * empty_server; - /* + /*% * Current ACL environment. This defines the * current values of the localhost and localnets * ACLs. @@ -87,11 +89,11 @@ struct ns_server { isc_event_t * reload_event; isc_boolean_t flushonshutdown; - isc_boolean_t log_queries; /* For BIND 8 compatibility */ + isc_boolean_t log_queries; /*%< For BIND 8 compatibility */ - isc_uint64_t * querystats; /* Query statistics counters */ + isc_uint64_t * querystats; /*%< Query statistics counters */ - ns_controls_t * controls; /* Control channels */ + ns_controls_t * controls; /*%< Control channels */ unsigned int dispatchgen; ns_dispatchlist_t dispatches; @@ -103,7 +105,7 @@ struct ns_server { void ns_server_create(isc_mem_t *mctx, ns_server_t **serverp); -/* +/*%< * Create a server object with default settings. * This function either succeeds or causes the program to exit * with a fatal error. @@ -111,13 +113,13 @@ ns_server_create(isc_mem_t *mctx, ns_server_t **serverp); void ns_server_destroy(ns_server_t **serverp); -/* +/*%< * Destroy a server object, freeing its memory. */ void ns_server_reloadwanted(ns_server_t *server); -/* +/*%< * Inform a server that a reload is wanted. This function * may be called asynchronously, from outside the server's task. * If a reload is already scheduled or in progress, the call @@ -126,95 +128,95 @@ ns_server_reloadwanted(ns_server_t *server); void ns_server_flushonshutdown(ns_server_t *server, isc_boolean_t flush); -/* +/*%< * Inform the server that the zones should be flushed to disk on shutdown. */ isc_result_t ns_server_reloadcommand(ns_server_t *server, char *args, isc_buffer_t *text); -/* +/*%< * Act on a "reload" command from the command channel. */ isc_result_t ns_server_reconfigcommand(ns_server_t *server, char *args); -/* +/*%< * Act on a "reconfig" command from the command channel. */ isc_result_t ns_server_notifycommand(ns_server_t *server, char *args, isc_buffer_t *text); -/* +/*%< * Act on a "notify" command from the command channel. */ isc_result_t ns_server_refreshcommand(ns_server_t *server, char *args, isc_buffer_t *text); -/* +/*%< * Act on a "refresh" command from the command channel. */ isc_result_t ns_server_retransfercommand(ns_server_t *server, char *args); -/* +/*%< * Act on a "retransfer" command from the command channel. */ isc_result_t ns_server_togglequerylog(ns_server_t *server); -/* +/*%< * Toggle logging of queries, as in BIND 8. */ -/* +/*% * Dump the current statistics to the statistics file. */ isc_result_t ns_server_dumpstats(ns_server_t *server); -/* +/*% * Dump the current cache to the dump file. */ isc_result_t ns_server_dumpdb(ns_server_t *server, char *args); -/* +/*% * Change or increment the server debug level. */ isc_result_t ns_server_setdebuglevel(ns_server_t *server, char *args); -/* +/*% * Flush the server's cache(s) */ isc_result_t ns_server_flushcache(ns_server_t *server, char *args); -/* +/*% * Flush a particular name from the server's cache(s) */ isc_result_t ns_server_flushname(ns_server_t *server, char *args); -/* +/*% * Report the server's status. */ isc_result_t ns_server_status(ns_server_t *server, isc_buffer_t *text); -/* +/*% * Enable or disable updates for a zone. */ isc_result_t ns_server_freeze(ns_server_t *server, isc_boolean_t freeze, char *args); -/* +/*% * Dump the current recursive queries. */ isc_result_t ns_server_dumprecursing(ns_server_t *server); -/* +/*% * Maintain a list of dispatches that require reserved ports. */ void diff --git a/bin/named/include/named/sortlist.h b/bin/named/include/named/sortlist.h index 90032e0a45..2843042f6c 100644 --- a/bin/named/include/named/sortlist.h +++ b/bin/named/include/named/sortlist.h @@ -15,22 +15,24 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sortlist.h,v 1.5 2004/03/05 04:57:57 marka Exp $ */ +/* $Id: sortlist.h,v 1.6 2005/04/27 04:56:00 sra Exp $ */ #ifndef NAMED_SORTLIST_H #define NAMED_SORTLIST_H 1 +/*! \file */ + #include #include -/* +/*% * Type for callback functions that rank addresses. */ typedef int (*dns_addressorderfunc_t)(isc_netaddr_t *address, void *arg); -/* +/*% * Return value type for setup_sortlist. */ typedef enum { @@ -41,7 +43,7 @@ typedef enum { ns_sortlisttype_t ns_sortlist_setup(dns_acl_t *acl, isc_netaddr_t *clientaddr, void **argp); -/* +/*%< * Find the sortlist statement in 'acl' that applies to 'clientaddr', if any. * * If a 1-element sortlist item applies, return NS_SORTLISTTYPE_1ELEMENT and @@ -56,14 +58,14 @@ ns_sortlist_setup(dns_acl_t *acl, isc_netaddr_t *clientaddr, void **argp); int ns_sortlist_addrorder1(isc_netaddr_t *addr, void *arg); -/* +/*%< * Find the sort order of 'addr' in 'arg', the matching element * of a 1-element top-level sortlist statement. */ int ns_sortlist_addrorder2(isc_netaddr_t *addr, void *arg); -/* +/*%< * Find the sort order of 'addr' in 'arg', a topology-like * ACL forming the second element in a 2-element top-level * sortlist statement. @@ -73,7 +75,7 @@ void ns_sortlist_byaddrsetup(dns_acl_t *sortlist_acl, isc_netaddr_t *client_addr, dns_addressorderfunc_t *orderp, void **argp); -/* +/*%< * Find the sortlist statement in 'acl' that applies to 'clientaddr', if any. * If a sortlist statement applies, return in '*orderp' a pointer to a function * for ranking network addresses based on that sortlist statement, and in diff --git a/bin/named/include/named/tkeyconf.h b/bin/named/include/named/tkeyconf.h index 725fbde935..f91e74f5d1 100644 --- a/bin/named/include/named/tkeyconf.h +++ b/bin/named/include/named/tkeyconf.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: tkeyconf.h,v 1.10 2004/03/05 04:57:57 marka Exp $ */ +/* $Id: tkeyconf.h,v 1.11 2005/04/27 04:56:01 sra Exp $ */ #ifndef NS_TKEYCONF_H #define NS_TKEYCONF_H 1 +/*! \file */ + #include #include @@ -30,20 +32,20 @@ ISC_LANG_BEGINDECLS isc_result_t ns_tkeyctx_fromconfig(cfg_obj_t *options, isc_mem_t *mctx, isc_entropy_t *ectx, dns_tkeyctx_t **tctxp); -/* +/*%< * Create a TKEY context and configure it, including the default DH key * and default domain, according to 'options'. * * Requires: - * 'cfg' is a valid configuration options object. - * 'mctx' is not NULL - * 'ectx' is not NULL - * 'tctx' is not NULL - * '*tctx' is NULL + *\li 'cfg' is a valid configuration options object. + *\li 'mctx' is not NULL + *\li 'ectx' is not NULL + *\li 'tctx' is not NULL + *\li '*tctx' is NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li ISC_R_SUCCESS + *\li ISC_R_NOMEMORY */ ISC_LANG_ENDDECLS diff --git a/bin/named/include/named/tsigconf.h b/bin/named/include/named/tsigconf.h index ea63391d48..98eef92a6f 100644 --- a/bin/named/include/named/tsigconf.h +++ b/bin/named/include/named/tsigconf.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: tsigconf.h,v 1.10 2004/03/05 04:57:57 marka Exp $ */ +/* $Id: tsigconf.h,v 1.11 2005/04/27 04:56:01 sra Exp $ */ #ifndef NS_TSIGCONF_H #define NS_TSIGCONF_H 1 +/*! \file */ + #include #include @@ -28,18 +30,18 @@ ISC_LANG_BEGINDECLS isc_result_t ns_tsigkeyring_fromconfig(cfg_obj_t *config, cfg_obj_t *vconfig, isc_mem_t *mctx, dns_tsig_keyring_t **ringp); -/* +/*%< * Create a TSIG key ring and configure it according to the 'key' * statements in the global and view configuration objects. * * Requires: - * 'config' is not NULL. - * 'mctx' is not NULL - * 'ring' is not NULL, and '*ring' is NULL + * \li 'config' is not NULL. + * \li 'mctx' is not NULL + * \li 'ring' is not NULL, and '*ring' is NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + * \li ISC_R_SUCCESS + * \li ISC_R_NOMEMORY */ ISC_LANG_ENDDECLS diff --git a/bin/named/include/named/types.h b/bin/named/include/named/types.h index 320919a6e5..95beba9186 100644 --- a/bin/named/include/named/types.h +++ b/bin/named/include/named/types.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: types.h,v 1.21 2004/03/05 04:57:57 marka Exp $ */ +/* $Id: types.h,v 1.22 2005/04/27 04:56:01 sra Exp $ */ #ifndef NAMED_TYPES_H #define NAMED_TYPES_H 1 +/*! \file */ + #include typedef struct ns_client ns_client_t; diff --git a/bin/named/include/named/update.h b/bin/named/include/named/update.h index 99c17a6cd0..80a3ae983d 100644 --- a/bin/named/include/named/update.h +++ b/bin/named/include/named/update.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: update.h,v 1.9 2004/03/05 04:57:57 marka Exp $ */ +/* $Id: update.h,v 1.10 2005/04/27 04:56:01 sra Exp $ */ #ifndef NAMED_UPDATE_H #define NAMED_UPDATE_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * RFC2136 Dynamic Update */ diff --git a/bin/named/include/named/xfrout.h b/bin/named/include/named/xfrout.h index f3ea15a101..414ee6cbb3 100644 --- a/bin/named/include/named/xfrout.h +++ b/bin/named/include/named/xfrout.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: xfrout.h,v 1.8 2004/03/05 04:57:57 marka Exp $ */ +/* $Id: xfrout.h,v 1.9 2005/04/27 04:56:01 sra Exp $ */ #ifndef NAMED_XFROUT_H #define NAMED_XFROUT_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * Outgoing zone transfers (AXFR + IXFR). */ diff --git a/bin/named/include/named/zoneconf.h b/bin/named/include/named/zoneconf.h index 61c72d6b2c..d73faab67d 100644 --- a/bin/named/include/named/zoneconf.h +++ b/bin/named/include/named/zoneconf.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: zoneconf.h,v 1.21 2005/01/12 01:56:11 marka Exp $ */ +/* $Id: zoneconf.h,v 1.22 2005/04/27 04:56:01 sra Exp $ */ #ifndef NS_ZONECONF_H #define NS_ZONECONF_H 1 +/*! \file */ + #include #include @@ -31,7 +33,7 @@ ISC_LANG_BEGINDECLS isc_result_t ns_zone_configure(cfg_obj_t *config, cfg_obj_t *vconfig, cfg_obj_t *zconfig, cfg_aclconfctx_t *ac, dns_zone_t *zone); -/* +/*%< * Configure or reconfigure a zone according to the named.conf * data in 'cctx' and 'czone'. * @@ -39,16 +41,16 @@ ns_zone_configure(cfg_obj_t *config, cfg_obj_t *vconfig, cfg_obj_t *zconfig, * at zone creation time. * * Require: - * 'lctx' to be initialized or NULL. - * 'cctx' to be initialized or NULL. - * 'ac' to point to an initialized ns_aclconfctx_t. - * 'czone' to be initialized. - * 'zone' to be initialized. + * \li 'lctx' to be initialized or NULL. + * \li 'cctx' to be initialized or NULL. + * \li 'ac' to point to an initialized ns_aclconfctx_t. + * \li 'czone' to be initialized. + * \li 'zone' to be initialized. */ isc_boolean_t ns_zone_reusable(dns_zone_t *zone, cfg_obj_t *zconfig); -/* +/*%< * If 'zone' can be safely reconfigured according to the configuration * data in 'zconfig', return ISC_TRUE. If the configuration data is so * different from the current zone state that the zone needs to be destroyed diff --git a/bin/named/interfacemgr.c b/bin/named/interfacemgr.c index 1e6a377c67..60072df2e6 100644 --- a/bin/named/interfacemgr.c +++ b/bin/named/interfacemgr.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: interfacemgr.c,v 1.80 2005/02/11 00:01:57 marka Exp $ */ +/* $Id: interfacemgr.c,v 1.81 2005/04/27 04:55:50 sra Exp $ */ + +/*! \file */ #include @@ -37,19 +39,20 @@ #define IFMGR_COMMON_LOGARGS \ ns_g_lctx, NS_LOGCATEGORY_NETWORK, NS_LOGMODULE_INTERFACEMGR +/*% nameserver interface manager structure */ struct ns_interfacemgr { - unsigned int magic; /* Magic number. */ + unsigned int magic; /*% Magic number. */ int references; isc_mutex_t lock; - isc_mem_t * mctx; /* Memory context. */ - isc_taskmgr_t * taskmgr; /* Task manager. */ - isc_socketmgr_t * socketmgr; /* Socket manager. */ + isc_mem_t * mctx; /*% Memory context. */ + isc_taskmgr_t * taskmgr; /*% Task manager. */ + isc_socketmgr_t * socketmgr; /*% Socket manager. */ dns_dispatchmgr_t * dispatchmgr; - unsigned int generation; /* Current generation no. */ + unsigned int generation; /*% Current generation no. */ ns_listenlist_t * listenon4; ns_listenlist_t * listenon6; - dns_aclenv_t aclenv; /* Localhost/localnets ACLs */ - ISC_LIST(ns_interface_t) interfaces; /* List of interfaces. */ + dns_aclenv_t aclenv; /*% Localhost/localnets ACLs */ + ISC_LIST(ns_interface_t) interfaces; /*% List of interfaces. */ ISC_LIST(isc_sockaddr_t) listenon; }; @@ -164,7 +167,7 @@ void ns_interfacemgr_shutdown(ns_interfacemgr_t *mgr) { REQUIRE(NS_INTERFACEMGR_VALID(mgr)); - /* + /*% * Shut down and detach all interfaces. * By incrementing the generation count, we make purge_old_interfaces() * consider all interfaces "old". @@ -437,7 +440,7 @@ ns_interface_detach(ns_interface_t **targetp) { *targetp = NULL; } -/* +/*% * Search the interface list for an interface whose address and port * both match those of 'addr'. Return a pointer to it, or NULL if not found. */ @@ -452,7 +455,7 @@ find_matching_interface(ns_interfacemgr_t *mgr, isc_sockaddr_t *addr) { return (ifp); } -/* +/*% * Remove any interfaces whose generation number is not the current one. */ static void diff --git a/bin/named/listenlist.c b/bin/named/listenlist.c index 6a7dd0d519..3a9146ef3b 100644 --- a/bin/named/listenlist.c +++ b/bin/named/listenlist.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: listenlist.c,v 1.10 2004/03/05 04:57:46 marka Exp $ */ +/* $Id: listenlist.c,v 1.11 2005/04/27 04:55:50 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/log.c b/bin/named/log.c index c099c446b7..2cfcff5bac 100644 --- a/bin/named/log.c +++ b/bin/named/log.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: log.c,v 1.38 2004/11/09 21:24:20 marka Exp $ */ +/* $Id: log.c,v 1.39 2005/04/27 04:55:50 sra Exp $ */ + +/*! \file */ #include @@ -29,7 +31,7 @@ #define ISC_FACILITY LOG_DAEMON #endif -/* +/*% * When adding a new category, be sure to add the appropriate * #define to and to update the list in * bin/check/check-tool.c. @@ -45,7 +47,7 @@ static isc_logcategory_t categories[] = { { NULL, 0 } }; -/* +/*% * When adding a new module, be sure to add the appropriate * #define to . */ diff --git a/bin/named/logconf.c b/bin/named/logconf.c index 73fb80b6ed..21b6f74edb 100644 --- a/bin/named/logconf.c +++ b/bin/named/logconf.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: logconf.c,v 1.35 2004/03/05 04:57:47 marka Exp $ */ +/* $Id: logconf.c,v 1.36 2005/04/27 04:55:51 sra Exp $ */ + +/*! \file */ #include @@ -36,7 +38,7 @@ if (result != ISC_R_SUCCESS) goto cleanup; \ } while (0) -/* +/*% * Set up a logging category according to the named.conf data * in 'ccat' and add it to 'lctx'. */ @@ -84,7 +86,7 @@ category_fromconf(cfg_obj_t *ccat, isc_logconfig_t *lctx) { return (ISC_R_SUCCESS); } -/* +/*% * Set up a logging channel according to the named.conf data * in 'cchan' and add it to 'lctx'. */ diff --git a/bin/named/lwaddr.c b/bin/named/lwaddr.c index 28e1346454..e2cbb6f521 100644 --- a/bin/named/lwaddr.c +++ b/bin/named/lwaddr.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwaddr.c,v 1.4 2004/03/05 04:57:47 marka Exp $ */ +/* $Id: lwaddr.c,v 1.5 2005/04/27 04:55:51 sra Exp $ */ + +/*! \file */ #include @@ -29,7 +31,7 @@ #include -/* +/*% * Convert addresses from lwres to isc format. */ isc_result_t @@ -63,7 +65,7 @@ lwaddr_sockaddr_fromlwresaddr(isc_sockaddr_t *sa, lwres_addr_t *la, return (ISC_R_SUCCESS); } -/* +/*% * Convert addresses from isc to lwres format. */ diff --git a/bin/named/lwdclient.c b/bin/named/lwdclient.c index 7cf997f18e..c0a155fc1f 100644 --- a/bin/named/lwdclient.c +++ b/bin/named/lwdclient.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwdclient.c,v 1.17 2004/03/05 04:57:47 marka Exp $ */ +/* $Id: lwdclient.c,v 1.18 2005/04/27 04:55:51 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/lwderror.c b/bin/named/lwderror.c index b464c2568d..e2cbb97198 100644 --- a/bin/named/lwderror.c +++ b/bin/named/lwderror.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwderror.c,v 1.8 2004/03/05 04:57:47 marka Exp $ */ +/* $Id: lwderror.c,v 1.9 2005/04/27 04:55:51 sra Exp $ */ + +/*! \file */ #include @@ -25,7 +27,7 @@ #include #include -/* +/*% * Generate an error packet for the client, schedule a send, and put us in * the SEND state. * diff --git a/bin/named/lwdgabn.c b/bin/named/lwdgabn.c index 61fb1dc586..e5a85bc962 100644 --- a/bin/named/lwdgabn.c +++ b/bin/named/lwdgabn.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwdgabn.c,v 1.15 2004/03/05 04:57:47 marka Exp $ */ +/* $Id: lwdgabn.c,v 1.16 2005/04/27 04:55:51 sra Exp $ */ + +/*! \file */ #include @@ -47,7 +49,7 @@ static isc_result_t start_find(ns_lwdclient_t *); static void restart_find(ns_lwdclient_t *); static void init_gabn(ns_lwdclient_t *); -/* +/*% * Destroy any finds. This can be used to "start over from scratch" and * should only be called when events are _not_ being generated by the finds. */ diff --git a/bin/named/lwdgnba.c b/bin/named/lwdgnba.c index 0c7c8baad6..02c6b4c4af 100644 --- a/bin/named/lwdgnba.c +++ b/bin/named/lwdgnba.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwdgnba.c,v 1.16 2004/03/05 04:57:47 marka Exp $ */ +/* $Id: lwdgnba.c,v 1.17 2005/04/27 04:55:52 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/lwdgrbn.c b/bin/named/lwdgrbn.c index bd946e7ae7..5209e2f4a7 100644 --- a/bin/named/lwdgrbn.c +++ b/bin/named/lwdgrbn.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwdgrbn.c,v 1.13 2004/03/05 04:57:47 marka Exp $ */ +/* $Id: lwdgrbn.c,v 1.14 2005/04/27 04:55:52 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/lwdnoop.c b/bin/named/lwdnoop.c index 63486889de..e8147fa6a9 100644 --- a/bin/named/lwdnoop.c +++ b/bin/named/lwdnoop.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwdnoop.c,v 1.7 2004/03/05 04:57:47 marka Exp $ */ +/* $Id: lwdnoop.c,v 1.8 2005/04/27 04:55:52 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/lwresd.c b/bin/named/lwresd.c index 95f0c96c2f..c29c48ab15 100644 --- a/bin/named/lwresd.c +++ b/bin/named/lwresd.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwresd.c,v 1.46 2004/03/05 04:57:48 marka Exp $ */ +/* $Id: lwresd.c,v 1.47 2005/04/27 04:55:52 sra Exp $ */ -/* +/*! \file + * \brief * Main program for the Lightweight Resolver Daemon. * * To paraphrase the old saying about X11, "It's not a lightweight deamon @@ -59,11 +60,11 @@ #define LWRESLISTENER_MAGIC ISC_MAGIC('L', 'W', 'R', 'L') #define VALID_LWRESLISTENER(l) ISC_MAGIC_VALID(l, LWRESLISTENER_MAGIC) -/* +/*! * The total number of clients we can handle will be NTASKS * NRECVS. */ -#define NTASKS 2 /* tasks to create to handle lwres queries */ -#define NRECVS 2 /* max clients per task */ +#define NTASKS 2 /*%< tasks to create to handle lwres queries */ +#define NRECVS 2 /*%< max clients per task */ typedef ISC_LIST(ns_lwreslistener_t) ns_lwreslistenerlist_t; @@ -78,7 +79,7 @@ initialize_mutex(void) { } -/* +/*% * Wrappers around our memory management stuff, for the lwres functions. */ void * diff --git a/bin/named/lwsearch.c b/bin/named/lwsearch.c index 52da7493e3..be07a660d4 100644 --- a/bin/named/lwsearch.c +++ b/bin/named/lwsearch.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwsearch.c,v 1.8 2004/03/05 04:57:48 marka Exp $ */ +/* $Id: lwsearch.c,v 1.9 2005/04/27 04:55:53 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/main.c b/bin/named/main.c index 809da4179c..be961e13c2 100644 --- a/bin/named/main.c +++ b/bin/named/main.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: main.c,v 1.144 2005/04/07 03:49:57 marka Exp $ */ +/* $Id: main.c,v 1.145 2005/04/27 04:55:53 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/notify.c b/bin/named/notify.c index ec53476fdc..2e762cd289 100644 --- a/bin/named/notify.c +++ b/bin/named/notify.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: notify.c,v 1.31 2004/08/28 06:16:52 marka Exp $ */ +/* $Id: notify.c,v 1.32 2005/04/27 04:55:53 sra Exp $ */ #include @@ -32,8 +32,9 @@ #include #include -/* - * This module implements notify as in RFC 1996. +/*! \file + * \brief + * This module implements notify as in RFC1996. */ static void diff --git a/bin/named/query.c b/bin/named/query.c index 595c9f8136..b5942c44e9 100644 --- a/bin/named/query.c +++ b/bin/named/query.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: query.c,v 1.264 2005/03/16 00:55:15 marka Exp $ */ +/* $Id: query.c,v 1.265 2005/04/27 04:55:53 sra Exp $ */ + +/*! \file */ #include @@ -51,24 +53,34 @@ #include #include +/*% Partial answer? */ #define PARTIALANSWER(c) (((c)->query.attributes & \ NS_QUERYATTR_PARTIALANSWER) != 0) +/*% Use Cache? */ #define USECACHE(c) (((c)->query.attributes & \ NS_QUERYATTR_CACHEOK) != 0) +/*% Recursion OK? */ #define RECURSIONOK(c) (((c)->query.attributes & \ NS_QUERYATTR_RECURSIONOK) != 0) +/*% Recursing? */ #define RECURSING(c) (((c)->query.attributes & \ NS_QUERYATTR_RECURSING) != 0) +/*% Cache glue ok? */ #define CACHEGLUEOK(c) (((c)->query.attributes & \ NS_QUERYATTR_CACHEGLUEOK) != 0) +/*% Want Recursion? */ #define WANTRECURSION(c) (((c)->query.attributes & \ NS_QUERYATTR_WANTRECURSION) != 0) +/*% Want DNSSEC? */ #define WANTDNSSEC(c) (((c)->attributes & \ NS_CLIENTATTR_WANTDNSSEC) != 0) +/*% No authority? */ #define NOAUTHORITY(c) (((c)->query.attributes & \ NS_QUERYATTR_NOAUTHORITY) != 0) +/*% No additional? */ #define NOADDITIONAL(c) (((c)->query.attributes & \ NS_QUERYATTR_NOADDITIONAL) != 0) +/*% Secure? */ #define SECURE(c) (((c)->query.attributes & \ NS_QUERYATTR_SECURE) != 0) @@ -100,7 +112,7 @@ typedef struct client_additionalctx { static void query_find(ns_client_t *client, dns_fetchevent_t *event, dns_rdatatype_t qtype); -/* +/*% * Increment query statistics counters. */ static inline void @@ -204,7 +216,7 @@ query_reset(ns_client_t *client, isc_boolean_t everything) { isc_buffer_t *dbuf, *dbuf_next; ns_dbversion_t *dbversion, *dbversion_next; - /* + /*% * Reset the query state of a client to its default state. */ @@ -277,7 +289,7 @@ query_newnamebuf(ns_client_t *client) { isc_result_t result; CTRACE("query_newnamebuf"); - /* + /*% * Allocate a name buffer. */ @@ -300,7 +312,7 @@ query_getnamebuf(ns_client_t *client) { isc_region_t r; CTRACE("query_getnamebuf"); - /* + /*% * Return a name buffer with space for a maximal name, allocating * a new one if necessary. */ @@ -336,7 +348,7 @@ query_keepname(ns_client_t *client, dns_name_t *name, isc_buffer_t *dbuf) { isc_region_t r; CTRACE("query_keepname"); - /* + /*% * 'name' is using space in 'dbuf', but 'dbuf' has not yet been * adjusted to take account of that. We do the adjustment. */ @@ -353,7 +365,7 @@ static inline void query_releasename(ns_client_t *client, dns_name_t **namep) { dns_name_t *name = *namep; - /* + /*% * 'name' is no longer needed. Return it to our pool of temporary * names. If it is using a name buffer, relinquish its exclusive * rights on the buffer. @@ -510,7 +522,7 @@ query_findversion(ns_client_t *client, dns_db_t *db, { ns_dbversion_t *dbversion; - /* + /*% * We may already have done a query related to this * database. If so, we must be sure to make subsequent * queries from the same version. @@ -702,7 +714,7 @@ query_getzonedb(ns_client_t *client, dns_name_t *name, dns_rdatatype_t qtype, REQUIRE(zonep != NULL && *zonep == NULL); REQUIRE(dbp != NULL && *dbp == NULL); - /* + /*% * Find a zone database to answer the query. */ ztoptions = ((options & DNS_GETDB_NOEXACT) != 0) ? @@ -751,7 +763,7 @@ query_getcachedb(ns_client_t *client, dns_name_t *name, dns_rdatatype_t qtype, REQUIRE(dbp != NULL && *dbp == NULL); - /* + /*% * Find a cache database to answer the query. * This may fail with DNS_R_REFUSED if the client * is not allowed to use the cache. @@ -1232,7 +1244,7 @@ query_addadditional(void *arg, dns_name_t *name, dns_rdatatype_t qtype) { */ if (type == dns_rdatatype_a || type == dns_rdatatype_aaaa) { /* - * RFC 2535 section 3.5 says that when A or AAAA records are + * RFC2535 section 3.5 says that when A or AAAA records are * retrieved as additional data, any KEY RRs for the owner name * should be added to the additional data section. * @@ -1806,7 +1818,7 @@ query_addrdataset(ns_client_t *client, dns_name_t *fname, (void)dns_rdataset_additionaldata(rdataset, query_addadditional2, &additionalctx); /* - * RFC 2535 section 3.5 says that when NS, SOA, A, or AAAA records + * RFC2535 section 3.5 says that when NS, SOA, A, or AAAA records * are retrieved, any KEY RRs for the owner name should be added * to the additional data section. We treat A6 records the same way. * @@ -1833,7 +1845,7 @@ query_addrrset(ns_client_t *client, dns_name_t **namep, dns_rdataset_t *rdataset, *mrdataset, *sigrdataset; isc_result_t result; - /* + /*% * To the current response for 'client', add the answer RRset * '*rdatasetp' and an optional signature set '*sigrdatasetp', with * owner name '*namep', to section 'section', unless they are @@ -3671,7 +3683,7 @@ query_find(ns_client_t *client, dns_fetchevent_t *event, dns_rdatatype_t qtype) dns_message_puttempname(client->message, &tname); if (result == ISC_R_NOSPACE) { /* - * RFC 2672, section 4.1, subsection 3c says + * RFC2672, section 4.1, subsection 3c says * we should return YXDOMAIN if the constructed * name would be too long. */ diff --git a/bin/named/server.c b/bin/named/server.c index 93515fb809..230f714eb6 100644 --- a/bin/named/server.c +++ b/bin/named/server.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: server.c,v 1.440 2005/04/05 00:58:15 marka Exp $ */ +/* $Id: server.c,v 1.441 2005/04/27 04:55:54 sra Exp $ */ + +/*! \file */ #include @@ -87,7 +89,7 @@ #include #endif -/* +/*% * Check an operation for failure. Assumes that the function * using it has a 'result' variable and a 'cleanup' label. */ @@ -192,7 +194,7 @@ configure_zone(cfg_obj_t *config, cfg_obj_t *zconfig, cfg_obj_t *vconfig, static void end_reserved_dispatches(ns_server_t *server, isc_boolean_t all); -/* +/*% * Configure a single view ACL at '*aclp'. Get its configuration by * calling 'getvcacl' (for per-view configuration) and maybe 'getscacl' * (for a global default). @@ -328,7 +330,7 @@ configure_view_dnsseckey(cfg_obj_t *vconfig, cfg_obj_t *key, return (result); } -/* +/*% * Configure DNSSEC keys for a view. Currently used only for * the security roots. * @@ -416,7 +418,7 @@ mustbesecure(cfg_obj_t *mbs, dns_resolver_t *resolver) return (result); } -/* +/*% * Get a dispatch appropriate for the resolver of a given view. */ static isc_result_t diff --git a/bin/named/sortlist.c b/bin/named/sortlist.c index 3301ca1d71..46ae4eaf21 100644 --- a/bin/named/sortlist.c +++ b/bin/named/sortlist.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sortlist.c,v 1.9 2004/03/05 04:57:49 marka Exp $ */ +/* $Id: sortlist.c,v 1.10 2005/04/27 04:55:54 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/tkeyconf.c b/bin/named/tkeyconf.c index 114e3eddf3..dcc1271654 100644 --- a/bin/named/tkeyconf.c +++ b/bin/named/tkeyconf.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: tkeyconf.c,v 1.21 2004/06/11 00:27:03 marka Exp $ */ +/* $Id: tkeyconf.c,v 1.22 2005/04/27 04:55:55 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/tsigconf.c b/bin/named/tsigconf.c index 7418d12fab..965d61e83c 100644 --- a/bin/named/tsigconf.c +++ b/bin/named/tsigconf.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: tsigconf.c,v 1.22 2004/03/05 04:57:49 marka Exp $ */ +/* $Id: tsigconf.c,v 1.23 2005/04/27 04:55:55 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/named/unix/include/named/os.h b/bin/named/unix/include/named/os.h index 874892ba62..b32973f8cc 100644 --- a/bin/named/unix/include/named/os.h +++ b/bin/named/unix/include/named/os.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: os.h,v 1.23 2004/09/29 06:45:37 marka Exp $ */ +/* $Id: os.h,v 1.24 2005/04/27 04:56:02 sra Exp $ */ #ifndef NS_OS_H #define NS_OS_H 1 +/*! \file */ + #include void diff --git a/bin/named/unix/os.c b/bin/named/unix/os.c index 0d14872362..e453c7b488 100644 --- a/bin/named/unix/os.c +++ b/bin/named/unix/os.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: os.c,v 1.73 2005/04/07 03:49:58 marka Exp $ */ +/* $Id: os.c,v 1.74 2005/04/27 04:56:02 sra Exp $ */ + +/*! \file */ #include #include @@ -114,7 +116,7 @@ static int dfd[2] = { -1, -1 }; static isc_boolean_t non_root = ISC_FALSE; static isc_boolean_t non_root_caps = ISC_FALSE; -/* +/*% * We define _LINUX_FS_H to prevent it from being included. We don't need * anything from it, and the files it includes cause warnings with 2.2 * kernels, and compilation failures (due to conflicts between @@ -176,7 +178,7 @@ static void linux_initialprivs(void) { unsigned int caps; - /* + /*% * We don't need most privileges, so we drop them right away. * Later on linux_minprivs() will be called, which will drop our * capabilities to the minimum needed to run the server. @@ -231,7 +233,7 @@ static void linux_minprivs(void) { unsigned int caps; - /* + /*% * Drop all privileges except the ability to bind() to privileged * ports. * @@ -258,7 +260,7 @@ linux_minprivs(void) { static void linux_keepcaps(void) { char strbuf[ISC_STRERRORSIZE]; - /* + /*% * Ask the kernel to allow us to keep our capabilities after we * setuid(). */ diff --git a/bin/named/update.c b/bin/named/update.c index 2d4c264205..d7ed3c9886 100644 --- a/bin/named/update.c +++ b/bin/named/update.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: update.c,v 1.120 2005/01/10 23:43:17 marka Exp $ */ +/* $Id: update.c,v 1.121 2005/04/27 04:55:55 sra Exp $ */ #include @@ -47,7 +47,8 @@ #include #include -/* +/*! \file + * \brief * This module implements dynamic update as in RFC2136. */ @@ -58,17 +59,17 @@ /**************************************************************************/ -/* +/*% * Log level for tracing dynamic update protocol requests. */ #define LOGLEVEL_PROTOCOL ISC_LOG_INFO -/* +/*% * Log level for low-level debug tracing. */ #define LOGLEVEL_DEBUG ISC_LOG_DEBUG(8) -/* +/*% * Check an operation for failure. These macros all assume that * the function using them has a 'result' variable and a 'failure' * label. @@ -78,7 +79,7 @@ if (result != ISC_R_SUCCESS) goto failure; \ } while (0) -/* +/*% * Fail unconditionally with result 'code', which must not * be ISC_R_SUCCESS. The reason for failure presumably has * been logged already. @@ -93,7 +94,7 @@ if (result != ISC_R_SUCCESS) goto failure; \ } while (0) -/* +/*% * Fail unconditionally and log as a client error. * The test against ISC_R_SUCCESS is there to keep the Solaris compiler * from complaining about "end-of-loop code not reached". @@ -159,7 +160,7 @@ } \ if (result != ISC_R_SUCCESS) goto failure; \ } while (0) -/* +/*% * Fail unconditionally and log as a server error. * The test against ISC_R_SUCCESS is there to keep the Solaris compiler * from complaining about "end-of-loop code not reached". @@ -269,12 +270,12 @@ checkupdateacl(ns_client_t *client, dns_acl_t *acl, const char *message, return (result); } -/* +/*% * Update a single RR in version 'ver' of 'db' and log the * update in 'diff'. * * Ensures: - * '*tuple' == NULL. Either the tuple is freed, or its + * \li '*tuple' == NULL. Either the tuple is freed, or its * ownership has been transferred to the diff. */ static isc_result_t @@ -312,12 +313,12 @@ do_one_tuple(dns_difftuple_t **tuple, return (ISC_R_SUCCESS); } -/* +/*% * Perform the updates in 'updates' in version 'ver' of 'db' and log the * update in 'diff'. * * Ensures: - * 'updates' is empty. + * \li 'updates' is empty. */ static isc_result_t do_diff(dns_diff_t *updates, dns_db_t *db, dns_dbversion_t *ver, @@ -370,17 +371,17 @@ update_one_rr(dns_db_t *db, dns_dbversion_t *ver, dns_diff_t *diff, * XXXRTH We might want to make this public somewhere in libdns. */ -/* +/*% * Function type for foreach_rrset() iterator actions. */ typedef isc_result_t rrset_func(void *data, dns_rdataset_t *rrset); -/* +/*% * Function type for foreach_rr() iterator actions. */ typedef isc_result_t rr_func(void *data, rr_t *rr); -/* +/*% * Internal context struct for foreach_node_rr(). */ typedef struct { @@ -388,7 +389,7 @@ typedef struct { void * rr_action_data; } foreach_node_rr_ctx_t; -/* +/*% * Internal helper function for foreach_node_rr(). */ static isc_result_t @@ -412,7 +413,7 @@ foreach_node_rr_action(void *data, dns_rdataset_t *rdataset) { return (ISC_R_SUCCESS); } -/* +/*% * For each rdataset of 'name' in 'ver' of 'db', call 'action' * with the rdataset and 'action_data' as arguments. If the name * does not exist, do nothing. @@ -470,7 +471,7 @@ foreach_rrset(dns_db_t *db, return (result); } -/* +/*% * For each RR of 'name' in 'ver' of 'db', call 'action' * with the RR and 'action_data' as arguments. If the name * does not exist, do nothing. @@ -493,7 +494,7 @@ foreach_node_rr(dns_db_t *db, } -/* +/*% * For each of the RRs specified by 'db', 'ver', 'name', 'type', * (which can be dns_rdatatype_any to match any type), and 'covers', call * 'action' with the RR and 'action_data' as arguments. If the name @@ -565,13 +566,13 @@ foreach_rr(dns_db_t *db, * Various tests on the database contents (for prerequisites, etc). */ -/* +/*% * Function type for predicate functions that compare a database RR 'db_rr' * against an update RR 'update_rr'. */ typedef isc_boolean_t rr_predicate(dns_rdata_t *update_rr, dns_rdata_t *db_rr); -/* +/*% * Helper function for rrset_exists(). */ static isc_result_t @@ -581,7 +582,7 @@ rrset_exists_action(void *data, rr_t *rr) { return (ISC_R_EXISTS); } -/* +/*% * Utility macro for RR existence checking functions. * * If the variable 'result' has the value ISC_R_EXISTS or @@ -601,7 +602,7 @@ rrset_exists_action(void *data, rr_t *rr) { (*exists = ISC_FALSE, ISC_R_SUCCESS) : \ result)) -/* +/*% * Set '*exists' to true iff an rrset of the given type exists, * to false otherwise. */ @@ -616,7 +617,7 @@ rrset_exists(dns_db_t *db, dns_dbversion_t *ver, RETURN_EXISTENCE_FLAG; } -/* +/*% * Helper function for cname_incompatible_rrset_exists. */ static isc_result_t @@ -628,7 +629,7 @@ cname_compatibility_action(void *data, dns_rdataset_t *rrset) { return (ISC_R_SUCCESS); } -/* +/*% * Check whether there is an rrset incompatible with adding a CNAME RR, * i.e., anything but another CNAME (which can be replaced) or a * DNSSEC RR (which can coexist). @@ -645,7 +646,7 @@ cname_incompatible_rrset_exists(dns_db_t *db, dns_dbversion_t *ver, RETURN_EXISTENCE_FLAG; } -/* +/*% * Helper function for rr_count(). */ static isc_result_t @@ -656,7 +657,7 @@ count_rr_action(void *data, rr_t *rr) { return (ISC_R_SUCCESS); } -/* +/*% * Count the number of RRs of 'type' belonging to 'name' in 'ver' of 'db'. */ static isc_result_t @@ -668,7 +669,7 @@ rr_count(dns_db_t *db, dns_dbversion_t *ver, dns_name_t *name, count_rr_action, countp)); } -/* +/*% * Context struct and helper function for name_exists(). */ @@ -679,7 +680,7 @@ name_exists_action(void *data, dns_rdataset_t *rrset) { return (ISC_R_EXISTS); } -/* +/*% * Set '*exists' to true iff the given name exists, to false otherwise. */ static isc_result_t @@ -740,7 +741,7 @@ ssu_checkall(dns_db_t *db, dns_dbversion_t *ver, dns_name_t *name, */ -/* +/*% * Append a tuple asserting the existence of the RR with * 'name' and 'rdata' to 'diff'. */ @@ -757,7 +758,7 @@ temp_append(dns_diff_t *diff, dns_name_t *name, dns_rdata_t *rdata) { return (result); } -/* +/*% * Compare two rdatasets represented as sorted lists of tuples. * All list elements must have the same owner name and type. * Return ISC_R_SUCCESS if the rdatasets are equal, rcode(dns_rcode_nxrrset) @@ -782,7 +783,7 @@ temp_check_rrset(dns_difftuple_t *a, dns_difftuple_t *b) { return (ISC_R_SUCCESS); } -/* +/*% * A comparison function defining the sorting order for the entries * in the "temp" data structure. The major sort key is the owner name, * followed by the type and rdata. @@ -804,7 +805,7 @@ temp_order(const void *av, const void *bv) { return (r); } -/* +/*% * Check the "RRset exists (value dependent)" prerequisite information * in 'temp' against the contents of the database 'db'. * @@ -947,7 +948,7 @@ temp_check(isc_mem_t *mctx, dns_diff_t *temp, dns_db_t *db, * Conditional deletion of RRs. */ -/* +/*% * Context structure for delete_if(). */ @@ -960,11 +961,11 @@ typedef struct { dns_rdata_t *update_rr; } conditional_delete_ctx_t; -/* +/*% * Predicate functions for delete_if(). */ -/* +/*% * Return true iff 'db_rr' is neither a SOA nor an NS RR nor * an RRSIG nor a NSEC. */ @@ -989,7 +990,7 @@ type_not_dnssec(dns_rdata_t *update_rr, dns_rdata_t *db_rr) { ISC_TRUE : ISC_FALSE); } -/* +/*% * Return true always. */ static isc_boolean_t @@ -999,7 +1000,7 @@ true_p(dns_rdata_t *update_rr, dns_rdata_t *db_rr) { return (ISC_TRUE); } -/* +/*% * Return true iff the two RRs have identical rdata. */ static isc_boolean_t @@ -1013,7 +1014,7 @@ rr_equal_p(dns_rdata_t *update_rr, dns_rdata_t *db_rr) { ISC_TRUE : ISC_FALSE); } -/* +/*% * Return true iff 'update_rr' should replace 'db_rr' according * to the special RFC2136 rules for CNAME, SOA, and WKS records. * @@ -1047,7 +1048,7 @@ replaces_p(dns_rdata_t *update_rr, dns_rdata_t *db_rr) { return (ISC_FALSE); } -/* +/*% * Internal helper function for delete_if(). */ static isc_result_t @@ -1064,7 +1065,7 @@ delete_if_action(void *data, rr_t *rr) { } } -/* +/*% * Conditionally delete RRs. Apply 'predicate' to the RRs * specified by 'db', 'ver', 'name', and 'type' (which can * be dns_rdatatype_any to match any type). Delete those @@ -1093,7 +1094,7 @@ delete_if(rr_predicate *predicate, } /**************************************************************************/ -/* +/*% * Prepare an RR for the addition of the new RR 'ctx->update_rr', * with TTL 'ctx->update_rr_ttl', to its rdataset, by deleting * the RRs if it is replaced by the new RR or has a conflicting TTL. @@ -1174,7 +1175,7 @@ add_rr_prepare_action(void *data, rr_t *rr) { * Miscellaneous subroutines. */ -/* +/*% * Extract a single update RR from 'section' of dynamic update message * 'msg', with consistency checking. * @@ -1204,7 +1205,7 @@ get_current_rr(dns_message_t *msg, dns_section_t section, rdata->rdclass = zoneclass; } -/* +/*% * Increment the SOA serial number of database 'db', version 'ver'. * Replace the SOA record in the database, and log the * change in 'diff'. @@ -1249,7 +1250,7 @@ increment_soa_serial(dns_db_t *db, dns_dbversion_t *ver, return (result); } -/* +/*% * Check that the new SOA record at 'update_rdata' does not * illegally cause the SOA serial number to decrease or stay * unchanged relative to the existing SOA in 'db'. @@ -1299,9 +1300,9 @@ check_soa_increment(dns_db_t *db, dns_dbversion_t *ver, * Incremental updating of NSECs and RRSIGs. */ -#define MAXZONEKEYS 32 /* Maximum number of zone keys supported. */ +#define MAXZONEKEYS 32 /*%< Maximum number of zone keys supported. */ -/* +/*% * We abuse the dns_diff_t type to represent a set of domain names * affected by the update. */ @@ -1352,7 +1353,7 @@ namelist_append_subdomain(dns_db_t *db, dns_name_t *name, dns_diff_t *affected) -/* +/*% * Helper function for non_nsec_rrset_exists(). */ static isc_result_t @@ -1365,7 +1366,7 @@ is_non_nsec_action(void *data, dns_rdataset_t *rrset) { return (ISC_R_SUCCESS); } -/* +/*% * Check whether there is an rrset other than a NSEC or RRSIG NSEC, * i.e., anything that justifies the continued existence of a name * after a secure update. @@ -1383,7 +1384,7 @@ non_nsec_rrset_exists(dns_db_t *db, dns_dbversion_t *ver, RETURN_EXISTENCE_FLAG; } -/* +/*% * A comparison function for sorting dns_diff_t:s by name. */ static int @@ -1448,7 +1449,7 @@ is_glue(dns_db_t *db, dns_dbversion_t *ver, dns_name_t *name, } } -/* +/*% * Find the next/previous name that has a NSEC record. * In other words, skip empty database nodes and names that * have had their NSECs removed because they are obscured by @@ -1511,7 +1512,7 @@ next_active(ns_client_t *client, dns_zone_t *zone, dns_db_t *db, return (result); } -/* +/*% * Add a NSEC record for "name", recording the change in "diff". * The existing NSEC is removed. */ @@ -1563,7 +1564,7 @@ add_nsec(ns_client_t *client, dns_zone_t *zone, dns_db_t *db, return (result); } -/* +/*% * Add a placeholder NSEC record for "name", recording the change in "diff". */ static isc_result_t @@ -1602,7 +1603,7 @@ find_zone_keys(dns_zone_t *zone, dns_db_t *db, dns_dbversion_t *ver, return (result); } -/* +/*% * Add RRSIG records for an RRset, recording the change in "diff". */ static isc_result_t @@ -1650,7 +1651,7 @@ add_sigs(dns_db_t *db, dns_dbversion_t *ver, dns_name_t *name, return (result); } -/* +/*% * Update RRSIG and NSEC records affected by an update. The original * update, including the SOA serial update but exluding the RRSIG & NSEC * changes, is in "diff" and has already been applied to "newver" of "db". @@ -1964,7 +1965,7 @@ update_signatures(ns_client_t *client, dns_zone_t *zone, dns_db_t *db, /**************************************************************************/ -/* +/*% * The actual update code in all its glory. We try to follow * the RFC2136 pseudocode as closely as possible. */ @@ -2093,7 +2094,7 @@ ns_update_start(ns_client_t *client, isc_result_t sigresult) { dns_zone_detach(&zone); } -/* +/*% * DS records are not allowed to exist without corresponding NS records, * draft-ietf-dnsext-delegation-signer-11.txt, 2.2 Protocol Change, * "DS RRsets MUST NOT appear at non-delegation points or at a zone's apex". @@ -2400,7 +2401,7 @@ update_action(isc_task_t *task, isc_event_t *event) { if (update_class == zoneclass) { /* - * RFC 1123 doesn't allow MF and MD in master zones. */ + * RFC1123 doesn't allow MF and MD in master zones. */ if (rdata.type == dns_rdatatype_md || rdata.type == dns_rdatatype_mf) { char typebuf[DNS_RDATATYPE_FORMATSIZE]; @@ -2738,7 +2739,7 @@ updatedone_action(isc_task_t *task, isc_event_t *event) { isc_event_free(&event); } -/* +/*% * Update forwarding support. */ diff --git a/bin/named/xfrout.c b/bin/named/xfrout.c index dc9298e233..3b8e19d5cf 100644 --- a/bin/named/xfrout.c +++ b/bin/named/xfrout.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: xfrout.c,v 1.118 2005/03/06 15:30:36 marka Exp $ */ +/* $Id: xfrout.c,v 1.119 2005/04/27 04:55:55 sra Exp $ */ #include @@ -48,7 +48,8 @@ #include #include -/* +/*! \file + * \brief * Outgoing AXFR and IXFR. */ @@ -71,7 +72,7 @@ #define XFROUT_RR_LOGLEVEL ISC_LOG_DEBUG(8) -/* +/*% * Fail unconditionally and log as a client error. * The test against ISC_R_SUCCESS is there to keep the Solaris compiler * from complaining about "end-of-loop code not reached". @@ -106,13 +107,14 @@ } while (0) /**************************************************************************/ -/* +/*% * A db_rr_iterator_t is an iterator that iterates over an entire database, * returning one RR at a time, in some arbitrary order. */ typedef struct db_rr_iterator db_rr_iterator_t; +/*% db_rr_iterator structure */ struct db_rr_iterator { isc_result_t result; dns_db_t *db; @@ -283,7 +285,7 @@ db_rr_iterator_current(db_rr_iterator_t *it, dns_name_t **name, /**************************************************************************/ -/* Log an RR (for debugging) */ +/*% Log an RR (for debugging) */ static void log_rr(dns_name_t *name, dns_rdata_t *rdata, isc_uint32_t ttl) { diff --git a/bin/named/zoneconf.c b/bin/named/zoneconf.c index cd026617ea..cdbc6d8a1f 100644 --- a/bin/named/zoneconf.c +++ b/bin/named/zoneconf.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: zoneconf.c,v 1.119 2005/02/10 05:53:42 marka Exp $ */ +/* $Id: zoneconf.c,v 1.120 2005/04/27 04:55:56 sra Exp $ */ + +/*% */ #include @@ -42,7 +44,7 @@ #include #include -/* +/*% * These are BIND9 server defaults, not necessarily identical to the * library defaults defined in zone.c. */ @@ -52,7 +54,7 @@ return (_r); \ } while (0) -/* +/*% * Convenience function for configuring a single zone ACL. */ static isc_result_t @@ -95,7 +97,7 @@ configure_zone_acl(cfg_obj_t *zconfig, cfg_obj_t *vconfig, cfg_obj_t *config, return (ISC_R_SUCCESS); } -/* +/*% * Parse the zone update-policy statement. */ static isc_result_t @@ -234,7 +236,7 @@ configure_zone_ssutable(cfg_obj_t *zconfig, dns_zone_t *zone) { return (result); } -/* +/*% * Convert a config file zone type into a server zone type. */ static inline dns_zonetype_t @@ -247,7 +249,7 @@ zonetype_fromconfig(cfg_obj_t *map) { return (ns_config_getzonetype(obj)); } -/* +/*% * Helper function for strtoargv(). Pardon the gratuitous recursion. */ static isc_result_t @@ -281,7 +283,7 @@ strtoargvsub(isc_mem_t *mctx, char *s, unsigned int *argcp, return (ISC_R_SUCCESS); } -/* +/*% * Tokenize the string "s" into whitespace-separated words, * return the number of words in '*argcp' and an array * of pointers to the words in '*argvp'. The caller diff --git a/bin/nsupdate/nsupdate.c b/bin/nsupdate/nsupdate.c index e66dd58a7f..a3c78cfc20 100644 --- a/bin/nsupdate/nsupdate.c +++ b/bin/nsupdate/nsupdate.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: nsupdate.c,v 1.137 2005/03/17 03:56:10 marka Exp $ */ +/* $Id: nsupdate.c,v 1.138 2005/04/27 04:56:03 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/rndc/include/rndc/os.h b/bin/rndc/include/rndc/os.h index 3f3b8765df..feec834c1c 100644 --- a/bin/rndc/include/rndc/os.h +++ b/bin/rndc/include/rndc/os.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: os.h,v 1.5 2004/03/05 04:58:25 marka Exp $ */ +/* $Id: os.h,v 1.6 2005/04/27 04:56:04 sra Exp $ */ + +/*! \file */ #ifndef RNDC_OS_H #define RNDC_OS_H 1 @@ -26,13 +28,13 @@ ISC_LANG_BEGINDECLS FILE *safe_create(const char *filename); -/* +/*%< * Open 'filename' for writing, truncate if necessary. If the file was * created ensure that only the owner can read/write it. */ int set_user(FILE *fd, const char *user); -/* +/*%< * Set the owner of the file refernced by 'fd' to 'user'. * Returns: * 0 success diff --git a/bin/rndc/rndc-confgen.c b/bin/rndc/rndc-confgen.c index 21f41de778..88f6e961cc 100644 --- a/bin/rndc/rndc-confgen.c +++ b/bin/rndc/rndc-confgen.c @@ -15,7 +15,18 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rndc-confgen.c,v 1.19 2004/09/28 07:11:25 marka Exp $ */ +/* $Id: rndc-confgen.c,v 1.20 2005/04/27 04:56:03 sra Exp $ */ + +/*! \file */ + +/** + * rndc-confgen generates configuration files for rndc. It can be used + * as a convenient alternative to writing the rndc.conf file and the + * corresponding controls and key statements in named.conf by hand. + * Alternatively, it can be run with the -a option to set up a + * rndc.key file and avoid the need for a rndc.conf file and a + * controls statement altogether. + */ #include @@ -45,7 +56,7 @@ #include "util.h" -#define DEFAULT_KEYLENGTH 128 /* Bits. */ +#define DEFAULT_KEYLENGTH 128 /*% Bits. */ #define DEFAULT_KEYNAME "rndc-key" #define DEFAULT_SERVER "127.0.0.1" #define DEFAULT_PORT 953 @@ -78,7 +89,7 @@ Usage:\n\ exit (status); } -/* +/*% * Write an rndc.key file to 'keyfile'. If 'user' is non-NULL, * make that user the owner of the file. The key will have * the name 'keyname' and the secret in the buffer 'secret'. diff --git a/bin/rndc/rndc.c b/bin/rndc/rndc.c index 9212e1f394..d0894b9e04 100644 --- a/bin/rndc/rndc.c +++ b/bin/rndc/rndc.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rndc.c,v 1.104 2005/03/14 23:55:57 marka Exp $ */ +/* $Id: rndc.c,v 1.105 2005/04/27 04:56:04 sra Exp $ */ + +/*! \file */ /* * Principal Author: DCL diff --git a/bin/rndc/unix/os.c b/bin/rndc/unix/os.c index 2fb1e26e39..103d4285fc 100644 --- a/bin/rndc/unix/os.c +++ b/bin/rndc/unix/os.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: os.c,v 1.6 2004/03/05 04:58:29 marka Exp $ */ +/* $Id: os.c,v 1.7 2005/04/27 04:56:05 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/rndc/util.c b/bin/rndc/util.c index a68f855083..ec607dd126 100644 --- a/bin/rndc/util.c +++ b/bin/rndc/util.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: util.c,v 1.3 2004/03/05 04:58:20 marka Exp $ */ +/* $Id: util.c,v 1.4 2005/04/27 04:56:04 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/rndc/util.h b/bin/rndc/util.h index 9d17b97ca5..d4a8dabf86 100644 --- a/bin/rndc/util.h +++ b/bin/rndc/util.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: util.h,v 1.6 2004/03/05 04:58:20 marka Exp $ */ +/* $Id: util.h,v 1.7 2005/04/27 04:56:04 sra Exp $ */ #ifndef RNDC_UTIL_H #define RNDC_UTIL_H 1 +/*! \file */ + #include #include diff --git a/bin/tests/adb_test.c b/bin/tests/adb_test.c index 91cdfd2afb..ca905b3b42 100644 --- a/bin/tests/adb_test.c +++ b/bin/tests/adb_test.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: adb_test.c,v 1.63 2004/03/05 04:58:36 marka Exp $ */ +/* $Id: adb_test.c,v 1.64 2005/04/27 04:56:05 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/tests/byaddr_test.c b/bin/tests/byaddr_test.c index 8e1ef8711b..a76c07d7c7 100644 --- a/bin/tests/byaddr_test.c +++ b/bin/tests/byaddr_test.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: byaddr_test.c,v 1.24 2004/03/05 04:58:36 marka Exp $ */ +/* $Id: byaddr_test.c,v 1.25 2005/04/27 04:56:05 sra Exp $ */ -/* +/*! \file + * \author * Principal Author: Bob Halley */ diff --git a/bin/tests/byname_test.c b/bin/tests/byname_test.c index 5d92789e3a..f0b37f7db4 100644 --- a/bin/tests/byname_test.c +++ b/bin/tests/byname_test.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: byname_test.c,v 1.26 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: byname_test.c,v 1.27 2005/04/27 04:56:07 sra Exp $ */ -/* +/*! \file + * \author * Principal Author: Bob Halley */ diff --git a/bin/tests/cfg_test.c b/bin/tests/cfg_test.c index 1043eed6aa..32bdc8914c 100644 --- a/bin/tests/cfg_test.c +++ b/bin/tests/cfg_test.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: cfg_test.c,v 1.15 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: cfg_test.c,v 1.16 2005/04/27 04:56:07 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/tests/compress_test.c b/bin/tests/compress_test.c index 092207388e..8bf48cda2f 100644 --- a/bin/tests/compress_test.c +++ b/bin/tests/compress_test.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: compress_test.c,v 1.27 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: compress_test.c,v 1.28 2005/04/27 04:56:07 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/tests/db_test.c b/bin/tests/db_test.c index 5059a1597a..7bbf4e565f 100644 --- a/bin/tests/db_test.c +++ b/bin/tests/db_test.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: db_test.c,v 1.61 2005/03/17 03:56:11 marka Exp $ */ +/* $Id: db_test.c,v 1.62 2005/04/27 04:56:07 sra Exp $ */ -/* +/*! \file + * \author * Principal Author: Bob Halley */ diff --git a/bin/tests/entropy2_test.c b/bin/tests/entropy2_test.c index 9ebc1b38ae..19f8aa24c1 100644 --- a/bin/tests/entropy2_test.c +++ b/bin/tests/entropy2_test.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: entropy2_test.c,v 1.12 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: entropy2_test.c,v 1.13 2005/04/27 04:56:07 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/tests/entropy_test.c b/bin/tests/entropy_test.c index 2d1a765f48..ede9c0c8c5 100644 --- a/bin/tests/entropy_test.c +++ b/bin/tests/entropy_test.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: entropy_test.c,v 1.19 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: entropy_test.c,v 1.20 2005/04/27 04:56:07 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/tests/fsaccess_test.c b/bin/tests/fsaccess_test.c index 4fa75ee010..91c37c55cd 100644 --- a/bin/tests/fsaccess_test.c +++ b/bin/tests/fsaccess_test.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: fsaccess_test.c,v 1.9 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: fsaccess_test.c,v 1.10 2005/04/27 04:56:08 sra Exp $ */ + +/*! \file */ #include diff --git a/bin/tests/genrandom.c b/bin/tests/genrandom.c index 768d0dfb56..96f482d671 100644 --- a/bin/tests/genrandom.c +++ b/bin/tests/genrandom.c @@ -15,8 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: genrandom.c,v 1.11 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: genrandom.c,v 1.12 2005/04/27 04:56:08 sra Exp $ */ +/*! \file */ #include #include diff --git a/bin/tests/gxba_test.c b/bin/tests/gxba_test.c index 978b0c301a..a11dbfa0f4 100644 --- a/bin/tests/gxba_test.c +++ b/bin/tests/gxba_test.c @@ -15,8 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gxba_test.c,v 1.9 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: gxba_test.c,v 1.10 2005/04/27 04:56:08 sra Exp $ */ +/*! \file */ #include #include diff --git a/bin/tests/gxbn_test.c b/bin/tests/gxbn_test.c index a0e819f516..d08feae6bd 100644 --- a/bin/tests/gxbn_test.c +++ b/bin/tests/gxbn_test.c @@ -15,8 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gxbn_test.c,v 1.12 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: gxbn_test.c,v 1.13 2005/04/27 04:56:08 sra Exp $ */ +/*! \file */ #include #include diff --git a/bin/tests/hash_test.c b/bin/tests/hash_test.c index 420565983e..54ff363afb 100644 --- a/bin/tests/hash_test.c +++ b/bin/tests/hash_test.c @@ -15,8 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: hash_test.c,v 1.14 2005/03/17 03:56:11 marka Exp $ */ +/* $Id: hash_test.c,v 1.15 2005/04/27 04:56:08 sra Exp $ */ +/*! \file */ #include #include @@ -78,7 +79,7 @@ main(int argc, char **argv) { print_digest(buffer, "md5", digest, 4); /* - * The 3 HMAC-MD5 examples from RFC 2104 + * The 3 HMAC-MD5 examples from RFC2104 */ s = "Hi There"; memset(key, 0x0b, 16); diff --git a/bin/tests/inter_test.c b/bin/tests/inter_test.c index 639c59c0d5..6f0f7fa7df 100644 --- a/bin/tests/inter_test.c +++ b/bin/tests/inter_test.c @@ -15,8 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: inter_test.c,v 1.10 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: inter_test.c,v 1.11 2005/04/27 04:56:08 sra Exp $ */ +/*! \file */ #include #include diff --git a/bin/tests/journalprint.c b/bin/tests/journalprint.c index 0a03ecff81..d309895519 100644 --- a/bin/tests/journalprint.c +++ b/bin/tests/journalprint.c @@ -15,8 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: journalprint.c,v 1.6 2005/03/17 03:56:11 marka Exp $ */ +/* $Id: journalprint.c,v 1.7 2005/04/27 04:56:08 sra Exp $ */ +/*! \file */ #include #include diff --git a/bin/tests/keyboard_test.c b/bin/tests/keyboard_test.c index 246b9e237a..21f4390f8c 100644 --- a/bin/tests/keyboard_test.c +++ b/bin/tests/keyboard_test.c @@ -15,8 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: keyboard_test.c,v 1.9 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: keyboard_test.c,v 1.10 2005/04/27 04:56:09 sra Exp $ */ +/*! \file */ #include #include diff --git a/bin/tests/lex_test.c b/bin/tests/lex_test.c index c15478e2a4..f843187ab3 100644 --- a/bin/tests/lex_test.c +++ b/bin/tests/lex_test.c @@ -15,8 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lex_test.c,v 1.19 2004/03/05 04:58:37 marka Exp $ */ +/* $Id: lex_test.c,v 1.20 2005/04/27 04:56:09 sra Exp $ */ +/*! \file */ #include #include diff --git a/bin/tests/lfsr_test.c b/bin/tests/lfsr_test.c index 494ff28c7d..ce0022c691 100644 --- a/bin/tests/lfsr_test.c +++ b/bin/tests/lfsr_test.c @@ -15,8 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lfsr_test.c,v 1.12 2004/03/05 04:58:38 marka Exp $ */ +/* $Id: lfsr_test.c,v 1.13 2005/04/27 04:56:09 sra Exp $ */ +/*! \file */ #include #include diff --git a/bin/tests/names/t_names.c b/bin/tests/names/t_names.c index b2a9188095..22b54f5cb3 100644 --- a/bin/tests/names/t_names.c +++ b/bin/tests/names/t_names.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: t_names.c,v 1.36 2004/03/05 04:58:56 marka Exp $ */ +/* $Id: t_names.c,v 1.37 2005/04/27 04:56:09 sra Exp $ */ #include @@ -38,7 +38,10 @@ static char *Tokens[MAXTOKS + 1]; -/* + +#ifdef NEED_PBUF + +/*% * get a hex formatted dns message from a data * file into an isc_buffer_t * caller supplies data storage and the isc_buffer @@ -46,8 +49,6 @@ static char *Tokens[MAXTOKS + 1]; * and return the data length */ -#ifdef NEED_PBUF - static char * ctoh(unsigned char c) { int val; @@ -85,7 +86,7 @@ pbuf(isc_buffer_t *pbuf) { #endif /* NEED_PBUF */ -/* +/*% * Compare data at buf with data in hex representation at exp_data, * of length exp_data_len, for equality. * Return 0 if equal, else non-zero. @@ -167,7 +168,7 @@ chkdata(unsigned char *buf, size_t buflen, char *exp_data, return (result); } -/* +/*% * Get a hex formatted dns message from a data file into an isc_buffer_t. * Caller supplies data storage and the isc_buffer. We read the file, convert, * setup the buffer and return the data length. @@ -256,14 +257,15 @@ bustline(char *line, char **toks) { return (cnt); } -/* + +#ifdef NEED_HNAME_TO_TNAME + +/*% * convert a name from hex representation to text form * format of hex notation is: * %xXXXXXXXX */ -#ifdef NEED_HNAME_TO_TNAME - static int hname_to_tname(char *src, char *target, size_t len) { int i; @@ -317,7 +319,7 @@ hname_to_tname(char *src, char *target, size_t len) { #endif /* NEED_HNAME_TO_TNAME */ -/* +/*% * initialize a dns_name_t from a text name, hiding all * buffer and other object initialization from the caller * @@ -598,7 +600,7 @@ static const char *a8 = "dns_name_hash(name, case_sensitive) returns " "a hash of 'name' which is case_sensitive if case_sensitive " "is true"; -/* +/*% * a9 merged with a8. */ @@ -718,7 +720,7 @@ static const char *a10 = "and sets nbitsp to the number of bits name1 and name2 " "have in common"; -/* +/*% * a11 thru a22 merged into a10. */ static const char * @@ -880,7 +882,7 @@ static const char *a23 = "the relative ordering under the DNSSEC ordering relationship " "of name1 and name2"; -/* +/*% * a24 thru a29 merged into a23. */ @@ -981,7 +983,7 @@ static const char *a30 = "about the relative ordering of name1 and name2 as if they " "are part of rdata in DNSSEC canonical form"; -/* +/*% * a31, a32 merged into a30. */ @@ -1082,7 +1084,7 @@ static const char *a33 = "dns_name_issubdomain(name1, name2) returns true, " "otherwise it returns false."; -/* +/*% * a34 merged into a33. */ @@ -1255,7 +1257,7 @@ static const char *a36 = "dns_name_getlabel(name, n, labelp) initializes labelp " "to point to the nth label in name"; -/* +/*% * The strategy here is two take two dns names with a shared label in * different positions, get the two labels and compare them for equality. * If they don't match, dns_name_getlabel failed. @@ -1368,7 +1370,7 @@ static const char *a37 = "initializes target to point to the n label sequence of " "labels in source starting with first"; -/* +/*% * We adopt a similiar strategy to that used by the dns_name_getlabel test. */ diff --git a/lib/bind/bsd/daemon.c b/lib/bind/bsd/daemon.c index a1472f969b..54ff83b753 100644 --- a/lib/bind/bsd/daemon.c +++ b/lib/bind/bsd/daemon.c @@ -1,6 +1,6 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)daemon.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: daemon.c,v 1.1 2001/03/29 06:30:31 marka Exp $"; +static const char rcsid[] = "$Id: daemon.c,v 1.2 2005/04/27 04:56:10 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* @@ -77,3 +77,5 @@ daemon(int nochdir, int noclose) { return (0); } #endif + +/*! \file */ diff --git a/lib/bind/bsd/ftruncate.c b/lib/bind/bsd/ftruncate.c index 56ce8d34a9..c59bc01393 100644 --- a/lib/bind/bsd/ftruncate.c +++ b/lib/bind/bsd/ftruncate.c @@ -1,8 +1,9 @@ #ifndef LINT -static const char rcsid[] = "$Id: ftruncate.c,v 1.1 2001/03/29 06:30:32 marka Exp $"; +static const char rcsid[] = "$Id: ftruncate.c,v 1.2 2005/04/27 04:56:10 sra Exp $"; #endif -/* +/*! \file +/*% * ftruncate - set file size, BSD Style * * shortens or enlarges the file as neeeded diff --git a/lib/bind/bsd/gettimeofday.c b/lib/bind/bsd/gettimeofday.c index 343a84b035..75b69430f6 100644 --- a/lib/bind/bsd/gettimeofday.c +++ b/lib/bind/bsd/gettimeofday.c @@ -1,5 +1,5 @@ #ifndef LINT -static const char rcsid[] = "$Id: gettimeofday.c,v 1.3 2001/11/01 05:50:19 marka Exp $"; +static const char rcsid[] = "$Id: gettimeofday.c,v 1.4 2005/04/27 04:56:11 sra Exp $"; #endif #include "port_before.h" @@ -9,7 +9,7 @@ static const char rcsid[] = "$Id: gettimeofday.c,v 1.3 2001/11/01 05:50:19 marka #include "port_after.h" #if !defined(NEED_GETTIMEOFDAY) -/* +/*% * gettimeofday() occasionally returns invalid tv_usec on some platforms. */ #define MILLION 1000000 @@ -60,3 +60,5 @@ gettimeofday(struct timeval *tvp, struct _TIMEZONE *tzp) { return (0); } #endif /*NEED_GETTIMEOFDAY*/ + +/*! \file */ diff --git a/lib/bind/bsd/mktemp.c b/lib/bind/bsd/mktemp.c index 9852a356ac..001b24b58f 100644 --- a/lib/bind/bsd/mktemp.c +++ b/lib/bind/bsd/mktemp.c @@ -1,6 +1,6 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)mktemp.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: mktemp.c,v 1.1 2001/03/29 06:30:33 marka Exp $"; +static const char rcsid[] = "$Id: mktemp.c,v 1.2 2005/04/27 04:56:11 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* @@ -96,7 +96,7 @@ gettemp(char *path, int *doopen) { u_int pid; pid = getpid(); - for (trv = path; *trv; ++trv); /* extra X's get set to 0's */ + for (trv = path; *trv; ++trv); /*%< extra X's get set to 0's */ while (*--trv == 'X') { *trv = (pid % 10) + '0'; pid /= 10; @@ -152,3 +152,5 @@ gettemp(char *path, int *doopen) { } #endif /*NEED_MKTEMP*/ + +/*! \file */ diff --git a/lib/bind/bsd/putenv.c b/lib/bind/bsd/putenv.c index abaa525d36..2dcbc57e6c 100644 --- a/lib/bind/bsd/putenv.c +++ b/lib/bind/bsd/putenv.c @@ -1,11 +1,11 @@ #ifndef LINT -static const char rcsid[] = "$Id: putenv.c,v 1.1 2001/03/29 06:30:33 marka Exp $"; +static const char rcsid[] = "$Id: putenv.c,v 1.2 2005/04/27 04:56:11 sra Exp $"; #endif #include "port_before.h" #include "port_after.h" -/* +/*% * To give a little credit to Sun, SGI, * and many vendors in the SysV world. */ @@ -23,3 +23,5 @@ putenv(char *str) { return (setenv(str, tmp, 1)); } #endif + +/*! \file */ diff --git a/lib/bind/bsd/readv.c b/lib/bind/bsd/readv.c index ccfcb5af33..5fa691a92f 100644 --- a/lib/bind/bsd/readv.c +++ b/lib/bind/bsd/readv.c @@ -1,5 +1,5 @@ #ifndef LINT -static const char rcsid[] = "$Id: readv.c,v 1.1 2001/03/29 06:30:35 marka Exp $"; +static const char rcsid[] = "$Id: readv.c,v 1.2 2005/04/27 04:56:11 sra Exp $"; #endif #include "port_before.h" @@ -36,3 +36,4 @@ __readv(fd, vp, vpcount) return (count); } #endif /* NEED_READV */ +/*! \file */ diff --git a/lib/bind/bsd/setenv.c b/lib/bind/bsd/setenv.c index 6a11c9db82..baf00f6ff2 100644 --- a/lib/bind/bsd/setenv.c +++ b/lib/bind/bsd/setenv.c @@ -1,6 +1,6 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)setenv.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: setenv.c,v 1.1 2001/03/29 06:30:35 marka Exp $"; +static const char rcsid[] = "$Id: setenv.c,v 1.2 2005/04/27 04:56:11 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* @@ -52,40 +52,40 @@ extern char **environ; static char *findenv(const char *name, int *offset); -/* +/*% * setenv -- * Set the value of the environmental variable "name" to be * "value". If rewrite is set, replace any current value. */ setenv(const char *name, const char *value, int rewrite) { extern char **environ; - static int alloced; /* if allocated space before */ + static int alloced; /*%< if allocated space before */ char *c; int l_value, offset; - if (*value == '=') /* no `=' in value */ + if (*value == '=') /*%< no `=' in value */ ++value; l_value = strlen(value); - if ((c = findenv(name, &offset))) { /* find if already exists */ + if ((c = findenv(name, &offset))) { /*%< find if already exists */ if (!rewrite) return (0); - if (strlen(c) >= l_value) { /* old larger; copy over */ + if (strlen(c) >= l_value) { /*%< old larger; copy over */ while (*c++ = *value++); return (0); } - } else { /* create new slot */ + } else { /*%< create new slot */ int cnt; char **p; for (p = environ, cnt = 0; *p; ++p, ++cnt); - if (alloced) { /* just increase size */ + if (alloced) { /*%< just increase size */ environ = (char **)realloc((char *)environ, (size_t)(sizeof(char *) * (cnt + 2))); if (!environ) return (-1); } - else { /* get new space */ - alloced = 1; /* copy old entries into it */ + else { /*%< get new space */ + alloced = 1; /*%< copy old entries into it */ p = malloc((size_t)(sizeof(char *) * (cnt + 2))); if (!p) return (-1); @@ -95,8 +95,8 @@ setenv(const char *name, const char *value, int rewrite) { environ[cnt + 1] = NULL; offset = cnt; } - for (c = (char *)name; *c && *c != '='; ++c); /* no `=' in name */ - if (!(environ[offset] = /* name + `=' + value */ + for (c = (char *)name; *c && *c != '='; ++c); /*%< no `=' in name */ + if (!(environ[offset] = /*%< name + `=' + value */ malloc((size_t)((int)(c - name) + l_value + 2)))) return (-1); for (c = environ[offset]; (*c = *name++) && *c != '='; ++c); @@ -104,7 +104,7 @@ setenv(const char *name, const char *value, int rewrite) { return (0); } -/* +/*% * unsetenv(name) -- * Delete environmental variable "name". */ @@ -113,13 +113,13 @@ unsetenv(const char *name) { char **p; int offset; - while (findenv(name, &offset)) /* if set multiple times */ + while (findenv(name, &offset)) /*%< if set multiple times */ for (p = &environ[offset];; ++p) if (!(*p = *(p + 1))) break; } -/* +/*% * findenv -- * Returns pointer to value associated with name, if any, else NULL. * Sets offset to be the offset of the name/value combination in the @@ -147,3 +147,5 @@ findenv(const char *name, int *offset) { return (NULL); } #endif + +/*! \file */ diff --git a/lib/bind/bsd/setitimer.c b/lib/bind/bsd/setitimer.c index 791846a299..67881d7ca8 100644 --- a/lib/bind/bsd/setitimer.c +++ b/lib/bind/bsd/setitimer.c @@ -1,5 +1,5 @@ #ifndef LINT -static const char rcsid[] = "$Id: setitimer.c,v 1.1 2001/03/29 06:30:35 marka Exp $"; +static const char rcsid[] = "$Id: setitimer.c,v 1.2 2005/04/27 04:56:12 sra Exp $"; #endif #include "port_before.h" @@ -8,7 +8,7 @@ static const char rcsid[] = "$Id: setitimer.c,v 1.1 2001/03/29 06:30:35 marka Ex #include "port_after.h" -/* +/*% * Setitimer emulation routine. */ #ifndef NEED_SETITIMER @@ -25,3 +25,5 @@ __setitimer(int which, const struct itimerval *value, return (-1); } #endif + +/*! \file */ diff --git a/lib/bind/bsd/strcasecmp.c b/lib/bind/bsd/strcasecmp.c index c8c9d056bb..0c9f0dccf0 100644 --- a/lib/bind/bsd/strcasecmp.c +++ b/lib/bind/bsd/strcasecmp.c @@ -1,6 +1,6 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)strcasecmp.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: strcasecmp.c,v 1.1 2001/03/29 06:30:35 marka Exp $"; +static const char rcsid[] = "$Id: strcasecmp.c,v 1.2 2005/04/27 04:56:12 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* @@ -50,7 +50,7 @@ static const char rcsid[] = "$Id: strcasecmp.c,v 1.1 2001/03/29 06:30:35 marka E int __strcasecmp_unneeded__; #else -/* +/*% * This array is designed for mapping upper and lower case letter * together for a case independent comparison. The mappings are * based upon ascii character sequences. @@ -120,3 +120,5 @@ strncasecmp(const char *s1, const char *s2, size_t n) { } #endif /*NEED_STRCASECMP*/ + +/*! \file */ diff --git a/lib/bind/bsd/strdup.c b/lib/bind/bsd/strdup.c index 246bc1f49f..a8d31e9587 100644 --- a/lib/bind/bsd/strdup.c +++ b/lib/bind/bsd/strdup.c @@ -16,3 +16,5 @@ strdup(const char *src) { return (dst); } #endif + +/*! \file */ diff --git a/lib/bind/bsd/strerror.c b/lib/bind/bsd/strerror.c index bddcb9e3ea..416cad4877 100644 --- a/lib/bind/bsd/strerror.c +++ b/lib/bind/bsd/strerror.c @@ -1,6 +1,6 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)strerror.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: strerror.c,v 1.4 2001/11/01 00:48:03 marka Exp $"; +static const char rcsid[] = "$Id: strerror.c,v 1.5 2005/04/27 04:56:12 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* @@ -57,19 +57,19 @@ extern char *sys_errlist[]; const char * isc_strerror(int num) { #define UPREFIX "Unknown error: " - static char ebuf[40] = UPREFIX; /* 64-bit number + slop */ + static char ebuf[40] = UPREFIX; /*%< 64-bit number + slop */ u_int errnum; char *p, *t; const char *ret; char tmp[40]; - errnum = num; /* convert to unsigned */ + errnum = num; /*%< convert to unsigned */ #ifdef USE_SYSERROR_LIST if (errnum < sys_nerr) return (sys_errlist[errnum]); #else #undef strerror - ret = strerror(num); /* call strerror() in libc */ + ret = strerror(num); /*%< call strerror() in libc */ if (ret != NULL) return(ret); #endif @@ -88,3 +88,5 @@ isc_strerror(int num) { } #endif /*NEED_STRERROR*/ + +/*! \file */ diff --git a/lib/bind/bsd/strpbrk.c b/lib/bind/bsd/strpbrk.c index ff039e1594..4c12d88e1c 100644 --- a/lib/bind/bsd/strpbrk.c +++ b/lib/bind/bsd/strpbrk.c @@ -1,6 +1,6 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)strpbrk.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: strpbrk.c,v 1.1 2001/03/29 06:30:36 marka Exp $"; +static const char rcsid[] = "$Id: strpbrk.c,v 1.2 2005/04/27 04:56:12 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* @@ -49,7 +49,7 @@ static const char rcsid[] = "$Id: strpbrk.c,v 1.1 2001/03/29 06:30:36 marka Exp int __strpbrk_unneeded__; #else -/* +/*% * Find the first occurrence in s1 of a character in s2 (excluding NUL). */ char * @@ -66,3 +66,5 @@ strpbrk(const char *s1, const char *s2) { } #endif /*NEED_STRPBRK*/ + +/*! \file */ diff --git a/lib/bind/bsd/strsep.c b/lib/bind/bsd/strsep.c index 3dcee4aab8..c7969f0028 100644 --- a/lib/bind/bsd/strsep.c +++ b/lib/bind/bsd/strsep.c @@ -1,6 +1,6 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "strsep.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: strsep.c,v 1.1 2001/03/29 06:30:36 marka Exp $"; +static const char rcsid[] = "$Id: strsep.c,v 1.2 2005/04/27 04:56:12 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* @@ -46,7 +46,7 @@ static const char rcsid[] = "$Id: strsep.c,v 1.1 2001/03/29 06:30:36 marka Exp $ int __strsep_unneeded__; #else -/* +/*% * Get next token from string *stringp, where tokens are possibly-empty * strings separated by characters from delim. * @@ -84,3 +84,5 @@ strsep(char **stringp, const char *delim) { } #endif /*NEED_STRSEP*/ + +/*! \file */ diff --git a/lib/bind/bsd/strtoul.c b/lib/bind/bsd/strtoul.c index 87bf166218..5d066a93d4 100644 --- a/lib/bind/bsd/strtoul.c +++ b/lib/bind/bsd/strtoul.c @@ -1,6 +1,6 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)strtoul.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: strtoul.c,v 1.2 2003/06/03 04:39:27 marka Exp $"; +static const char rcsid[] = "$Id: strtoul.c,v 1.3 2005/04/27 04:56:12 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* @@ -52,7 +52,7 @@ static const char rcsid[] = "$Id: strtoul.c,v 1.2 2003/06/03 04:39:27 marka Exp int __strtoul_unneeded__; #else -/* +/*% * Convert a string to an unsigned long integer. * * Ignores `locale' stuff. Assumes that the upper and lower case @@ -115,3 +115,5 @@ strtoul(const char *nptr, char **endptr, int base) { } #endif /*NEED_STRTOUL*/ + +/*! \file */ diff --git a/lib/bind/bsd/utimes.c b/lib/bind/bsd/utimes.c index 6a288f4956..2f65cffe25 100644 --- a/lib/bind/bsd/utimes.c +++ b/lib/bind/bsd/utimes.c @@ -37,3 +37,4 @@ __utimes(char *filename, struct timeval *tvp) { } #endif /* NEED_UTIMES */ +/*! \file */ diff --git a/lib/bind/bsd/writev.c b/lib/bind/bsd/writev.c index 5e12302b09..65baa71cfc 100644 --- a/lib/bind/bsd/writev.c +++ b/lib/bind/bsd/writev.c @@ -1,5 +1,5 @@ #ifndef LINT -static const char rcsid[] = "$Id: writev.c,v 1.2 2003/06/03 04:39:27 marka Exp $"; +static const char rcsid[] = "$Id: writev.c,v 1.3 2005/04/27 04:56:13 sra Exp $"; #endif #include "port_before.h" @@ -85,3 +85,5 @@ __writev(fd, vp, vpcount) #endif /*_CRAY*/ #endif /*NEED_WRITEV*/ + +/*! \file */ diff --git a/lib/bind/dst/dst_api.c b/lib/bind/dst/dst_api.c index f3588acb69..ced4aede87 100644 --- a/lib/bind/dst/dst_api.c +++ b/lib/bind/dst/dst_api.c @@ -1,5 +1,5 @@ #ifndef LINT -static const char rcsid[] = "$Header: /u0/home/explorer/proj/ISC/git-conversion/cvsroot/bind9/lib/bind/dst/Attic/dst_api.c,v 1.11 2004/09/16 00:56:12 marka Exp $"; +static const char rcsid[] = "$Header: /u0/home/explorer/proj/ISC/git-conversion/cvsroot/bind9/lib/bind/dst/Attic/dst_api.c,v 1.12 2005/04/27 04:56:13 sra Exp $"; #endif /* @@ -78,7 +78,7 @@ static DST_KEY *dst_s_get_key_struct(const char *name, const int alg, const int flags, const int protocol, const int bits); -/* +/*% * dst_init * This function initializes the Digital Signature Toolkit. * Right now, it just checks the DSTKEYPATH environment variable. @@ -124,7 +124,7 @@ dst_init() dst_hmac_md5_init(); } -/* +/*% * dst_check_algorithm * This function determines if the crypto system for the specified * algorithm is present. @@ -143,7 +143,7 @@ dst_check_algorithm(const int alg) return (dst_t_func[alg] != NULL); } -/* +/*% * dst_s_get_key_struct * This function allocates key structure and fills in some of the * fields of the structure. @@ -163,7 +163,7 @@ dst_s_get_key_struct(const char *name, const int alg, const int flags, { DST_KEY *new_key = NULL; - if (dst_check_algorithm(alg)) /* make sure alg is available */ + if (dst_check_algorithm(alg)) /*%< make sure alg is available */ new_key = (DST_KEY *) malloc(sizeof(*new_key)); if (new_key == NULL) return (NULL); @@ -179,7 +179,7 @@ dst_s_get_key_struct(const char *name, const int alg, const int flags, return (new_key); } -/* +/*% * dst_compare_keys * Compares two keys for equality. * Parameters @@ -205,8 +205,7 @@ dst_compare_keys(const DST_KEY *key1, const DST_KEY *key2) return (key1->dk_func->compare(key1, key2)); } - -/* +/*% * dst_sign_data * An incremental signing function. Data is signed in steps. * First the context must be initialized (SIG_MODE_INIT). @@ -232,8 +231,8 @@ dst_compare_keys(const DST_KEY *key1, const DST_KEY *key2) * sig_len Length of the signature field in bytes. * Return * 0 Successfull INIT or Update operation - * >0 success FINAL (sign) operation - * <0 failure + * >0 success FINAL (sign) operation + * <0 failure */ int @@ -253,8 +252,7 @@ dst_sign_data(const int mode, DST_KEY *in_key, void **context, return (UNKNOWN_KEYALG); } - -/* +/*% * dst_verify_data * An incremental verify function. Data is verified in steps. * First the context must be initialized (SIG_MODE_INIT). @@ -296,8 +294,7 @@ dst_verify_data(const int mode, DST_KEY *in_key, void **context, signature, sig_len)); } - -/* +/*% * dst_read_private_key * Access a private key. First the list of private keys that have * already been read in is searched, then the key accessed on disk. @@ -326,7 +323,7 @@ dst_read_key(const char *in_keyname, const u_int16_t in_id, char keyname[PATH_MAX]; DST_KEY *dg_key = NULL, *pubkey = NULL; - if (!dst_check_algorithm(in_alg)) { /* make sure alg is available */ + if (!dst_check_algorithm(in_alg)) { /*%< make sure alg is available */ EREPORT(("dst_read_private_key(): Algorithm %d not suppored\n", in_alg)); return (NULL); @@ -366,7 +363,7 @@ dst_write_key(const DST_KEY *key, const int type) if (key == NULL) return (0); - if (!dst_check_algorithm(key->dk_alg)) { /* make sure alg is available */ + if (!dst_check_algorithm(key->dk_alg)) { /*%< make sure alg is available */ EREPORT(("dst_write_key(): Algorithm %d not suppored\n", key->dk_alg)); return (UNSUPPORTED_KEYALG); @@ -383,19 +380,19 @@ dst_write_key(const DST_KEY *key, const int type) return (priv+pub); } -/* +/*% * dst_write_private_key * Write a private key to disk. The filename will be of the form: - * Kdk_name>+dk_alg>+dk_id>.. + * K<key->dk_name>+<key->dk_alg+><key-d>k_id.><private key suffix>. * If there is already a file with this name, an error is returned. * * Parameters * key A DST managed key structure that contains * all information needed about a key. * Return - * >= 0 Correct behavior. Returns length of encoded key value + * >= 0 Correct behavior. Returns length of encoded key value * written to disk. - * < 0 error. + * < 0 error. */ static int @@ -410,8 +407,7 @@ dst_s_write_private_key(const DST_KEY *key) if (key == NULL) return (-1); if (key->dk_KEY_struct == NULL) - return (0); /* null key has no private key */ - + return (0); /*%< null key has no private key */ if (key->dk_func == NULL || key->dk_func->to_file_fmt == NULL) { EREPORT(("dst_write_private_key(): Unsupported operation %d\n", key->dk_alg)); @@ -443,12 +439,12 @@ dst_s_write_private_key(const DST_KEY *key) return (len); } -/* +/*% * * dst_read_public_key * Read a public key from disk and store in a DST key structure. * Parameters - * in_name K. is the + * in_name K<in_name><in_id>.<public key suffix> is the * filename of the key file to be read. * Returns * NULL If the key does not exist or no name is supplied. @@ -477,7 +473,7 @@ dst_s_read_public_key(const char *in_name, const u_int16_t in_id, int in_alg) /* * Open the file and read it's formatted contents up to key * File format: - * domain.name [ttl] [IN] KEY + * domain.name [ttl] [IN] KEY <flags> <protocol> <algorithm> <key> * flags, proto, alg stored as decimal (or hex numbers FIXME). * (FIXME: handle parentheses for line continuation.) */ @@ -524,7 +520,7 @@ dst_s_read_public_key(const char *in_name, const u_int16_t in_id, int in_alg) while ((c = getc(fp)) != EOF) if (!isspace(c)) break; - ungetc(c, fp); /* return the charcter to the input field */ + ungetc(c, fp); /*%< return the charcter to the input field */ /* Handle hex!! FIXME. */ if (fscanf(fp, "%d %d %d", &flags, &proto, &alg) != 3) { @@ -567,8 +563,7 @@ dst_s_read_public_key(const char *in_name, const u_int16_t in_id, int in_alg) return dst_buffer_to_key(in_name, alg, flags, proto, deckey, dlen); } - -/* +/*% * dst_write_public_key * Write a key to disk in DNS format. * Parameters @@ -622,8 +617,7 @@ dst_s_write_public_key(const DST_KEY *key) return (1); } - -/* +/*% * dst_dnskey_to_public_key * This function converts the contents of a DNS KEY RR into a DST * key structure. @@ -644,10 +638,10 @@ dst_dnskey_to_key(const char *in_name, const u_char *rdata, const int len) int alg ; int start = DST_KEY_START; - if (rdata == NULL || len <= DST_KEY_ALG) /* no data */ + if (rdata == NULL || len <= DST_KEY_ALG) /*%< no data */ return (NULL); alg = (u_int8_t) rdata[DST_KEY_ALG]; - if (!dst_check_algorithm(alg)) { /* make sure alg is available */ + if (!dst_check_algorithm(alg)) { /*%< make sure alg is available */ EREPORT(("dst_dnskey_to_key(): Algorithm %d not suppored\n", alg)); return (NULL); @@ -682,8 +676,7 @@ dst_dnskey_to_key(const char *in_name, const u_char *rdata, const int len) return (key_st); } - -/* +/*% * dst_public_key_to_dnskey * Function to encode a public key into DNS KEY wire format * Parameters @@ -705,7 +698,7 @@ dst_key_to_dnskey(const DST_KEY *key, u_char *out_storage, if (key == NULL) return (-1); - if (!dst_check_algorithm(key->dk_alg)) { /* make sure alg is available */ + if (!dst_check_algorithm(key->dk_alg)) { /*%< make sure alg is available */ EREPORT(("dst_key_to_dnskey(): Algorithm %d not suppored\n", key->dk_alg)); return (UNSUPPORTED_KEYALG); @@ -718,7 +711,7 @@ dst_key_to_dnskey(const DST_KEY *key, u_char *out_storage, out_storage[loc++] = (u_char) key->dk_proto; out_storage[loc++] = (u_char) key->dk_alg; - if (key->dk_flags > 0xffff) { /* Extended flags */ + if (key->dk_flags > 0xffff) { /*%< Extended flags */ val = (u_int16_t)((key->dk_flags >> 16) & 0xffff); dst_s_put_int16(&out_storage[loc], val); loc += 2; @@ -739,8 +732,7 @@ dst_key_to_dnskey(const DST_KEY *key, u_char *out_storage, return (-1); } - -/* +/*% * dst_buffer_to_key * Function to encode a string of raw data into a DST key * Parameters @@ -752,19 +744,19 @@ dst_key_to_dnskey(const DST_KEY *key, u_char *out_storage, * NON-NULL the DST key */ DST_KEY * -dst_buffer_to_key(const char *key_name, /* name of the key */ - const int alg, /* algorithm */ - const int flags, /* dns flags */ - const int protocol, /* dns protocol */ - const u_char *key_buf, /* key in dns wire fmt */ - const int key_len) /* size of key */ +dst_buffer_to_key(const char *key_name, /*!< name of the key */ + const int alg, /*!< algorithm */ + const int flags, /*!< dns flags */ + const int protocol, /*!< dns protocol */ + const u_char *key_buf, /*!< key in dns wire fmt */ + const int key_len) /*!< size of key */ { DST_KEY *dkey = NULL; int dnslen; u_char dns[2048]; - if (!dst_check_algorithm(alg)) { /* make sure alg is available */ + if (!dst_check_algorithm(alg)) { /*%< make sure alg is available */ EREPORT(("dst_buffer_to_key(): Algorithm %d not suppored\n", alg)); return (NULL); } @@ -803,8 +795,7 @@ dst_key_to_buffer(DST_KEY *key, u_char *out_buff, int buf_len) return (0); } - -/* +/*% * dst_s_read_private_key_file * Function reads in private key from a file. * Fills out the KEY structure. @@ -878,14 +869,14 @@ dst_s_read_private_key_file(char *name, DST_KEY *pk_key, u_int16_t in_id, "dst_s_read_private_key_file(): Keyfile %s version higher than mine %d.%d MAY FAIL\n", name, file_major, file_minor)); - while (*p++ != '\n') ; /* skip to end of line */ + while (*p++ != '\n') ; /*%< skip to end of line */ if (!dst_s_verify_str((const char **) (void *)&p, "Algorithm: ")) goto fail; if (sscanf((char *)p, "%d", &alg) != 1) goto fail; - while (*p++ != '\n') ; /* skip to end of line */ + while (*p++ != '\n') ; /*%< skip to end of line */ if (pk_key->dk_key_name && !strcmp(pk_key->dk_key_name, name)) SAFE_FREE2(pk_key->dk_key_name, strlen(pk_key->dk_key_name)); @@ -918,34 +909,34 @@ dst_s_read_private_key_file(char *name, DST_KEY *pk_key, u_int16_t in_id, return (0); } - -/* - * dst_generate_key +/*% * Generate and store a public/private keypair. * Keys will be stored in formatted files. + * * Parameters - * name Name of the new key. Used to create key files - * K++.public and K++.private. - * bits Size of the new key in bits. - * exp What exponent to use: - * 0 use exponent 3 - * non-zero use Fermant4 - * flags The default value of the DNS Key flags. - * The DNS Key RR Flag field is defined in RFC 2065, + & + *\par name Name of the new key. Used to create key files + *\li K<name>+<alg>+<id>.public and K<name>+<alg>+<id>.private. + *\par bits Size of the new key in bits. + *\par exp What exponent to use: + *\li 0 use exponent 3 + *\li non-zero use Fermant4 + *\par flags The default value of the DNS Key flags. + *\li The DNS Key RR Flag field is defined in RFC2065, * section 3.3. The field has 16 bits. - * protocol - * Default value of the DNS Key protocol field. - * The DNS Key protocol field is defined in RFC 2065, + *\par protocol + *\li Default value of the DNS Key protocol field. + *\li The DNS Key protocol field is defined in RFC2065, * section 3.4. The field has 8 bits. - * alg What algorithm to use. Currently defined: - * KEY_RSA 1 - * KEY_DSA 3 - * KEY_HMAC 157 - * out_id The key tag is returned. + *\par alg What algorithm to use. Currently defined: + *\li KEY_RSA 1 + *\li KEY_DSA 3 + *\li KEY_HMAC 157 + *\par out_id The key tag is returned. * * Return - * NULL Failure - * non-NULL the generated key pair + *\li NULL Failure + *\li non-NULL the generated key pair * Caller frees the result, and its dk_name pointer. */ DST_KEY * @@ -960,7 +951,7 @@ dst_generate_key(const char *name, const int bits, const int exp, if (name == NULL) return (NULL); - if (!dst_check_algorithm(alg)) { /* make sure alg is available */ + if (!dst_check_algorithm(alg)) { /*%< make sure alg is available */ EREPORT(("dst_generate_key(): Algorithm %d not suppored\n", alg)); return (NULL); } @@ -968,7 +959,7 @@ dst_generate_key(const char *name, const int bits, const int exp, new_key = dst_s_get_key_struct(name, alg, flags, protocol, bits); if (new_key == NULL) return (NULL); - if (bits == 0) /* null key we are done */ + if (bits == 0) /*%< null key we are done */ return (new_key); if (new_key->dk_func == NULL || new_key->dk_func->generate == NULL) { EREPORT(("dst_generate_key_pair():Unsupported algorithm %d\n", @@ -991,12 +982,11 @@ dst_generate_key(const char *name, const int bits, const int exp, return (new_key); } - -/* - * dst_free_key +/*% * Release all data structures pointed to by a key structure. + * * Parameters - * f_key Key structure to be freed. + *\li f_key Key structure to be freed. */ DST_KEY * @@ -1011,7 +1001,7 @@ dst_free_key(DST_KEY *f_key) else { EREPORT(("dst_free_key(): Unknown key alg %d\n", f_key->dk_alg)); - free(f_key->dk_KEY_struct); /* SHOULD NOT happen */ + free(f_key->dk_KEY_struct); /*%< SHOULD NOT happen */ } if (f_key->dk_KEY_struct) { free(f_key->dk_KEY_struct); @@ -1023,13 +1013,14 @@ dst_free_key(DST_KEY *f_key) return (NULL); } -/* - * dst_sig_size +/*% * Return the maximim size of signature from the key specified in bytes + * * Parameters - * key + *\li key + * * Returns - * bytes + * \li bytes */ int dst_sig_size(DST_KEY *key) { @@ -1047,3 +1038,5 @@ dst_sig_size(DST_KEY *key) { return -1; } } + +/*! \file */ diff --git a/lib/bind/dst/dst_internal.h b/lib/bind/dst/dst_internal.h index 928650a726..e9bc6fc08d 100644 --- a/lib/bind/dst/dst_internal.h +++ b/lib/bind/dst/dst_internal.h @@ -29,19 +29,19 @@ # ifdef POSIX_PATH_MAX # define PATH_MAX POSIX_PATH_MAX # else -# define PATH_MAX 255 /* this is the value of POSIX_PATH_MAX */ +# define PATH_MAX 255 /*%< this is the value of POSIX_PATH_MAX */ # endif #endif typedef struct dst_key { - char *dk_key_name; /* name of the key */ - int dk_key_size; /* this is the size of the key in bits */ - int dk_proto; /* what protocols this key can be used for */ - int dk_alg; /* algorithm number from key record */ - u_int32_t dk_flags; /* and the flags of the public key */ - u_int16_t dk_id; /* identifier of the key */ - void *dk_KEY_struct; /* pointer to key in crypto pkg fmt */ - struct dst_func *dk_func; /* point to cryptto pgk specific function table */ + char *dk_key_name; /*%< name of the key */ + int dk_key_size; /*%< this is the size of the key in bits */ + int dk_proto; /*%< what protocols this key can be used for */ + int dk_alg; /*%< algorithm number from key record */ + u_int32_t dk_flags; /*%< and the flags of the public key */ + u_int16_t dk_id; /*%< identifier of the key */ + void *dk_KEY_struct; /*%< pointer to key in crypto pkg fmt */ + struct dst_func *dk_func; /*%< point to cryptto pgk specific function table */ } DST_KEY; #define HAS_DST_KEY @@ -103,7 +103,7 @@ extern const char *key_file_fmt_str; extern const char *dst_path; #ifndef DST_HASH_SIZE -#define DST_HASH_SIZE 20 /* RIPEMD160 and SHA-1 are 20 bytes MD5 is 16 */ +#define DST_HASH_SIZE 20 /*%< RIPEMD160 and SHA-1 are 20 bytes MD5 is 16 */ #endif int dst_bsafe_init(void); @@ -129,7 +129,7 @@ int dst_s_build_filename( char *filename, const char *name, FILE *dst_s_fopen (const char *filename, const char *mode, int perm); -/* +/*% * read and write network byte order into u_int?_t * all of these should be retired */ @@ -152,3 +152,4 @@ dst_s_dump(const int mode, const u_char *data, const int size, #endif /* DST_INTERNAL_H */ +/*! \file */ diff --git a/lib/bind/dst/hmac_link.c b/lib/bind/dst/hmac_link.c index 4f042b44a8..aab94c57ae 100644 --- a/lib/bind/dst/hmac_link.c +++ b/lib/bind/dst/hmac_link.c @@ -1,6 +1,6 @@ #ifdef HMAC_MD5 #ifndef LINT -static const char rcsid[] = "$Header: /u0/home/explorer/proj/ISC/git-conversion/cvsroot/bind9/lib/bind/dst/Attic/hmac_link.c,v 1.3 2003/06/03 04:39:27 marka Exp $"; +static const char rcsid[] = "$Header: /u0/home/explorer/proj/ISC/git-conversion/cvsroot/bind9/lib/bind/dst/Attic/hmac_link.c,v 1.4 2005/04/27 04:56:13 sra Exp $"; #endif /* * Portions Copyright (c) 1995-1998 by Trusted Information Systems, Inc. @@ -19,7 +19,7 @@ static const char rcsid[] = "$Header: /u0/home/explorer/proj/ISC/git-conversion/ * WITH THE USE OR PERFORMANCE OF THE SOFTWARE. */ -/* +/*% * This file contains an implementation of the HMAC-MD5 algorithm. */ #include "port_before.h" @@ -39,7 +39,7 @@ static const char rcsid[] = "$Header: /u0/home/explorer/proj/ISC/git-conversion/ #ifdef USE_MD5 # include "md5.h" # ifndef _MD5_H_ -# define _MD5_H_ 1 /* make sure we do not include rsaref md5.h file */ +# define _MD5_H_ 1 /*%< make sure we do not include rsaref md5.h file */ # endif #endif @@ -275,10 +275,9 @@ dst_hmac_md5_key_to_file_format(const DST_KEY *dkey, char *buff, if (dkey == NULL || dkey->dk_KEY_struct == NULL) return (0); if (buff == NULL || buff_len <= (int) strlen(key_file_fmt_str)) - return (-1); /* no OR not enough space in output area */ - + return (-1); /*%< no OR not enough space in output area */ hkey = (HMAC_Key *) dkey->dk_KEY_struct; - memset(buff, 0, buff_len); /* just in case */ + memset(buff, 0, buff_len); /*%< just in case */ /* write file header */ sprintf(buff, key_file_fmt_str, KEY_FILE_FORMAT, KEY_HMAC_MD5, "HMAC"); @@ -350,7 +349,7 @@ dst_hmac_md5_key_from_file_format(DST_KEY *dkey, const char *buff, tmp = malloc(len + 2); memcpy(tmp, p, len); *(tmp + len) = 0x0; - key_len = b64_pton((char *)tmp, key, HMAC_LEN+1); /* see above */ + key_len = b64_pton((char *)tmp, key, HMAC_LEN+1); /*%< see above */ SAFE_FREE2(tmp, len + 2); if (dst_buffer_to_hmac_md5(dkey, key, key_len) < 0) { @@ -359,7 +358,7 @@ dst_hmac_md5_key_from_file_format(DST_KEY *dkey, const char *buff, return (0); } -/* +/*% * dst_hmac_md5_to_dns_key() * function to extract hmac key from DST_KEY structure * intput: @@ -433,7 +432,7 @@ dst_hmac_md5_generate_key(DST_KEY *key, const int nothing) return (-1); } -/* +/*% * dst_hmac_md5_init() Function to answer set up function pointers for HMAC * related functions */ @@ -466,3 +465,5 @@ dst_hmac_md5_init(){ return (0); } #endif + +/*! \file */ diff --git a/lib/bind/dst/md5.h b/lib/bind/dst/md5.h index c886d17bb0..f1e2ae1eeb 100644 --- a/lib/bind/dst/md5.h +++ b/lib/bind/dst/md5.h @@ -99,3 +99,5 @@ unsigned char *MD5(); #endif #endif + +/*! \file */ diff --git a/lib/bind/dst/md5_dgst.c b/lib/bind/dst/md5_dgst.c index 48c327eac3..d839087b03 100644 --- a/lib/bind/dst/md5_dgst.c +++ b/lib/bind/dst/md5_dgst.c @@ -56,7 +56,7 @@ * [including the GNU Public Licence.] */ -#ifdef USE_MD5 /* Added by ogud@tis.com 1998/1/26 */ +#ifdef USE_MD5 /*%< Added by ogud@tis.com 1998/1/26 */ #include #include #include "md5_locl.h" @@ -64,7 +64,9 @@ const char *MD5_version="MD5 part of SSLeay 0.8.1 19-Jul-1997"; -/* Implemented from RFC1321 The MD5 Message-Digest Algorithm +/*! \file + * \brief + * Implemented from RFC1321 The MD5 Message-Digest Algorithm */ #define INIT_DATA_A (unsigned long)0x67452301L @@ -104,7 +106,7 @@ unsigned long len; l=(c->Nl+(len<<3))&0xffffffffL; /* 95-05-24 eay Fixed a bug with the overflow handling, thanks to * Wei Dai for pointing it out. */ - if (l < c->Nl) /* overflow */ + if (l < c->Nl) /*%< overflow */ c->Nh++; c->Nh+=(len>>29); c->Nl=l; @@ -136,7 +138,7 @@ unsigned long len; int ew,ec; c->num+=(int)len; - if ((sc+len) < 4U) /* ugly, add char's to a word */ + if ((sc+len) < 4U) /*%< ugly, add char's to a word */ { l= p[sw]; p_c2l_p(data,l,sc,len); @@ -195,7 +197,7 @@ unsigned long len; c->num=sc; if (sc) { - sw=sc>>2; /* words to copy */ + sw=sc>>2; /*%< words to copy */ #ifdef L_ENDIAN p[sw]=0; memcpy(p,data,sc); diff --git a/lib/bind/dst/md5_locl.h b/lib/bind/dst/md5_locl.h index ce4c765c1b..657fe8c3de 100644 --- a/lib/bind/dst/md5_locl.h +++ b/lib/bind/dst/md5_locl.h @@ -147,7 +147,8 @@ (a)=ROTATE(l,16L); \ } #endif -/* + +/*% #define F(x,y,z) (((x) & (y)) | ((~(x)) & (z))) #define G(x,y,z) (((x) & (z)) | ((y) & (~(z)))) */ @@ -188,3 +189,5 @@ a+=((k)+(t)+I((b),(c),(d))); \ a=ROTATE(a,s); \ a+=b; }; + +/*! \file */ diff --git a/lib/bind/dst/support.c b/lib/bind/dst/support.c index 25361547e7..b6dab01e53 100644 --- a/lib/bind/dst/support.c +++ b/lib/bind/dst/support.c @@ -1,4 +1,4 @@ -static const char rcsid[] = "$Header: /u0/home/explorer/proj/ISC/git-conversion/cvsroot/bind9/lib/bind/dst/Attic/support.c,v 1.3 2001/11/01 06:51:25 marka Exp $"; +static const char rcsid[] = "$Header: /u0/home/explorer/proj/ISC/git-conversion/cvsroot/bind9/lib/bind/dst/Attic/support.c,v 1.4 2005/04/27 04:56:14 sra Exp $"; /* @@ -34,7 +34,7 @@ static const char rcsid[] = "$Header: /u0/home/explorer/proj/ISC/git-conversion/ #include "port_after.h" -/* +/*% * dst_s_verify_str() * Validate that the input string(*str) is at the head of the input * buffer(**buf). If so, move the buffer head pointer (*buf) to @@ -52,20 +52,20 @@ int dst_s_verify_str(const char **buf, const char *str) { int b, s; - if (*buf == NULL) /* error checks */ + if (*buf == NULL) /*%< error checks */ return (0); if (str == NULL || *str == '\0') return (1); - b = strlen(*buf); /* get length of strings */ + b = strlen(*buf); /*%< get length of strings */ s = strlen(str); - if (s > b || strncmp(*buf, str, s)) /* check if same */ - return (0); /* not a match */ - (*buf) += s; /* advance pointer */ + if (s > b || strncmp(*buf, str, s)) /*%< check if same */ + return (0); /*%< not a match */ + (*buf) += s; /*%< advance pointer */ return (1); } -/* +/*% * dst_s_calculate_bits * Given a binary number represented in a u_char[], determine * the number of significant bits used. @@ -89,8 +89,7 @@ dst_s_calculate_bits(const u_char *str, const int max_bits) return (bits); } - -/* +/*% * calculates a checksum used in dst for an id. * takes an array of bytes and a length. * returns a 16 bit checksum. @@ -115,7 +114,7 @@ dst_s_id_calc(const u_char *key, const int keysize) return (ac & 0xffff); } -/* +/*% * dst_s_dns_key_id() Function to calculate DNSSEC footprint from KEY record * rdata * Input: @@ -131,7 +130,7 @@ dst_s_dns_key_id(const u_char *dns_key_rdata, const int rdata_len) return 0; /* compute id */ - if (dns_key_rdata[3] == KEY_RSA) /* Algorithm RSA */ + if (dns_key_rdata[3] == KEY_RSA) /*%< Algorithm RSA */ return dst_s_get_int16((const u_char *) &dns_key_rdata[rdata_len - 3]); else if (dns_key_rdata[3] == KEY_HMAC_MD5) @@ -142,7 +141,7 @@ dst_s_dns_key_id(const u_char *dns_key_rdata, const int rdata_len) return dst_s_id_calc(dns_key_rdata, rdata_len); } -/* +/*% * dst_s_get_int16 * This routine extracts a 16 bit integer from a two byte character * string. The character string is assumed to be in network byte @@ -161,8 +160,7 @@ dst_s_get_int16(const u_char *buf) return (a); } - -/* +/*% * dst_s_get_int32 * This routine extracts a 32 bit integer from a four byte character * string. The character string is assumed to be in network byte @@ -182,8 +180,7 @@ dst_s_get_int32(const u_char *buf) return (a); } - -/* +/*% * dst_s_put_int16 * Take a 16 bit integer and store the value in a two byte * character string. The integer is assumed to be in network @@ -201,8 +198,7 @@ dst_s_put_int16(u_int8_t *buf, const u_int16_t val) buf[1] = (u_int8_t)(val); } - -/* +/*% * dst_s_put_int32 * Take a 32 bit integer and store the value in a four byte * character string. The integer is assumed to be in network @@ -222,13 +218,12 @@ dst_s_put_int32(u_int8_t *buf, const u_int32_t val) buf[3] = (u_int8_t)(val); } - -/* +/*% * dst_s_filename_length * * This function returns the number of bytes needed to hold the * filename for a key file. '/', '\' and ':' are not allowed. - * form: K++. + * form: K<keyname>+<alg>+<id>.<suffix> * * Returns 0 if the filename would contain either '\', '/' or ':' */ @@ -254,13 +249,12 @@ dst_s_filename_length(const char *name, const char *suffix) return (1 + strlen(name) + 6 + strlen(suffix)); } - -/* +/*% * dst_s_build_filename () * Builds a key filename from the key name, it's id, and a * suffix. '\', '/' and ':' are not allowed. fA filename is of the - * form: K. - * form: K++. + * form: K<keyname><id>.<suffix> + * form: K<keyname>+<alg>+<id>.<suffix> * * Returns -1 if the conversion fails: * if the filename would be too long for space allotted @@ -294,7 +288,7 @@ dst_s_build_filename(char *filename, const char *name, u_int16_t id, return (0); } -/* +/*% * dst_s_fopen () * Open a file in the dst_path directory. If perm is specified, the * file is checked for existence first, and not opened if it exists. @@ -348,3 +342,5 @@ dst_s_dump(const int mode, const u_char *data, const int size, #endif } } + +/*! \file */ diff --git a/lib/bind/include/arpa/inet.h b/lib/bind/include/arpa/inet.h index 34d11fb8b8..d40ccfce00 100644 --- a/lib/bind/include/arpa/inet.h +++ b/lib/bind/include/arpa/inet.h @@ -53,9 +53,9 @@ * --Copyright-- */ -/* +/*% * @(#)inet.h 8.1 (Berkeley) 6/2/93 - * $Id: inet.h,v 1.2 2004/03/09 06:29:53 marka Exp $ + * $Id: inet.h,v 1.3 2005/04/27 04:56:16 sra Exp $ */ #ifndef _INET_H_ @@ -122,3 +122,5 @@ __END_DECLS #endif #endif /* !_INET_H_ */ + +/*! \file */ diff --git a/lib/bind/include/arpa/nameser.h b/lib/bind/include/arpa/nameser.h index dc3ec9ab4e..b6d34aab0f 100644 --- a/lib/bind/include/arpa/nameser.h +++ b/lib/bind/include/arpa/nameser.h @@ -49,12 +49,14 @@ */ /* - * $Id: nameser.h,v 1.7 2004/03/09 06:29:54 marka Exp $ + * $Id: nameser.h,v 1.8 2005/04/27 04:56:16 sra Exp $ */ #ifndef _ARPA_NAMESER_H_ #define _ARPA_NAMESER_H_ +/*! \file */ + #define BIND_4_COMPAT #include @@ -65,7 +67,7 @@ #endif #include -/* +/*% * Revision information. This is the release date in YYYYMMDD format. * It can change every day so the right thing to do with it is use it * in preprocessor commands such as "#if (__NAMESER > 19931104)". Do not @@ -73,43 +75,41 @@ * contains a new enough lib/nameser/ to support the feature you need. */ -#define __NAMESER 19991006 /* New interface version stamp. */ - +#define __NAMESER 19991006 /*%< New interface version stamp. */ /* - * Define constants based on RFC 883, RFC 1034, RFC 1035 + * Define constants based on RFC0883, RFC1034, RFC 1035 */ -#define NS_PACKETSZ 512 /* default UDP packet size */ -#define NS_MAXDNAME 1025 /* maximum domain name */ -#define NS_MAXMSG 65535 /* maximum message size */ -#define NS_MAXCDNAME 255 /* maximum compressed domain name */ -#define NS_MAXLABEL 63 /* maximum length of domain label */ -#define NS_HFIXEDSZ 12 /* #/bytes of fixed data in header */ -#define NS_QFIXEDSZ 4 /* #/bytes of fixed data in query */ -#define NS_RRFIXEDSZ 10 /* #/bytes of fixed data in r record */ -#define NS_INT32SZ 4 /* #/bytes of data in a u_int32_t */ -#define NS_INT16SZ 2 /* #/bytes of data in a u_int16_t */ -#define NS_INT8SZ 1 /* #/bytes of data in a u_int8_t */ -#define NS_INADDRSZ 4 /* IPv4 T_A */ -#define NS_IN6ADDRSZ 16 /* IPv6 T_AAAA */ -#define NS_CMPRSFLGS 0xc0 /* Flag bits indicating name compression. */ -#define NS_DEFAULTPORT 53 /* For both TCP and UDP. */ - +#define NS_PACKETSZ 512 /*%< default UDP packet size */ +#define NS_MAXDNAME 1025 /*%< maximum domain name */ +#define NS_MAXMSG 65535 /*%< maximum message size */ +#define NS_MAXCDNAME 255 /*%< maximum compressed domain name */ +#define NS_MAXLABEL 63 /*%< maximum length of domain label */ +#define NS_HFIXEDSZ 12 /*%< #/bytes of fixed data in header */ +#define NS_QFIXEDSZ 4 /*%< #/bytes of fixed data in query */ +#define NS_RRFIXEDSZ 10 /*%< #/bytes of fixed data in r record */ +#define NS_INT32SZ 4 /*%< #/bytes of data in a u_int32_t */ +#define NS_INT16SZ 2 /*%< #/bytes of data in a u_int16_t */ +#define NS_INT8SZ 1 /*%< #/bytes of data in a u_int8_t */ +#define NS_INADDRSZ 4 /*%< IPv4 T_A */ +#define NS_IN6ADDRSZ 16 /*%< IPv6 T_AAAA */ +#define NS_CMPRSFLGS 0xc0 /*%< Flag bits indicating name compression. */ +#define NS_DEFAULTPORT 53 /*%< For both TCP and UDP. */ /* * These can be expanded with synonyms, just keep ns_parse.c:ns_parserecord() * in synch with it. */ typedef enum __ns_sect { - ns_s_qd = 0, /* Query: Question. */ - ns_s_zn = 0, /* Update: Zone. */ - ns_s_an = 1, /* Query: Answer. */ - ns_s_pr = 1, /* Update: Prerequisites. */ - ns_s_ns = 2, /* Query: Name servers. */ - ns_s_ud = 2, /* Update: Update. */ - ns_s_ar = 3, /* Query|Update: Additional records. */ + ns_s_qd = 0, /*%< Query: Question. */ + ns_s_zn = 0, /*%< Update: Zone. */ + ns_s_an = 1, /*%< Query: Answer. */ + ns_s_pr = 1, /*%< Update: Prerequisites. */ + ns_s_ns = 2, /*%< Query: Name servers. */ + ns_s_ud = 2, /*%< Update: Update. */ + ns_s_ar = 3, /*%< Query|Update: Additional records. */ ns_s_max = 4 } ns_sect; -/* +/*% * This is a message handle. It is caller allocated and has no dynamic data. * This structure is intended to be opaque to all but ns_parse.c, thus the * leading _'s on the member names. Use the accessor functions, not the _'s. @@ -135,7 +135,7 @@ extern struct _ns_flagdata _ns_flagdata[]; #define ns_msg_size(handle) ((handle)._eom - (handle)._msg) #define ns_msg_count(handle, section) ((handle)._counts[section] + 0) -/* +/*% * This is a parsed record. It is caller allocated and has no dynamic data. */ typedef struct __ns_rr { @@ -155,54 +155,54 @@ typedef struct __ns_rr { #define ns_rr_rdlen(rr) ((rr).rdlength + 0) #define ns_rr_rdata(rr) ((rr).rdata + 0) -/* +/*% * These don't have to be in the same order as in the packet flags word, * and they can even overlap in some cases, but they will need to be kept * in synch with ns_parse.c:ns_flagdata[]. */ typedef enum __ns_flag { - ns_f_qr, /* Question/Response. */ - ns_f_opcode, /* Operation code. */ - ns_f_aa, /* Authoritative Answer. */ - ns_f_tc, /* Truncation occurred. */ - ns_f_rd, /* Recursion Desired. */ - ns_f_ra, /* Recursion Available. */ - ns_f_z, /* MBZ. */ - ns_f_ad, /* Authentic Data (DNSSEC). */ - ns_f_cd, /* Checking Disabled (DNSSEC). */ - ns_f_rcode, /* Response code. */ + ns_f_qr, /*%< Question/Response. */ + ns_f_opcode, /*%< Operation code. */ + ns_f_aa, /*%< Authoritative Answer. */ + ns_f_tc, /*%< Truncation occurred. */ + ns_f_rd, /*%< Recursion Desired. */ + ns_f_ra, /*%< Recursion Available. */ + ns_f_z, /*%< MBZ. */ + ns_f_ad, /*%< Authentic Data (DNSSEC). */ + ns_f_cd, /*%< Checking Disabled (DNSSEC). */ + ns_f_rcode, /*%< Response code. */ ns_f_max } ns_flag; -/* +/*% * Currently defined opcodes. */ typedef enum __ns_opcode { - ns_o_query = 0, /* Standard query. */ - ns_o_iquery = 1, /* Inverse query (deprecated/unsupported). */ - ns_o_status = 2, /* Name server status query (unsupported). */ + ns_o_query = 0, /*%< Standard query. */ + ns_o_iquery = 1, /*%< Inverse query (deprecated/unsupported). */ + ns_o_status = 2, /*%< Name server status query (unsupported). */ /* Opcode 3 is undefined/reserved. */ - ns_o_notify = 4, /* Zone change notification. */ - ns_o_update = 5, /* Zone update message. */ + ns_o_notify = 4, /*%< Zone change notification. */ + ns_o_update = 5, /*%< Zone update message. */ ns_o_max = 6 } ns_opcode; -/* +/*% * Currently defined response codes. */ typedef enum __ns_rcode { - ns_r_noerror = 0, /* No error occurred. */ - ns_r_formerr = 1, /* Format error. */ - ns_r_servfail = 2, /* Server failure. */ - ns_r_nxdomain = 3, /* Name error. */ - ns_r_notimpl = 4, /* Unimplemented. */ - ns_r_refused = 5, /* Operation refused. */ + ns_r_noerror = 0, /*%< No error occurred. */ + ns_r_formerr = 1, /*%< Format error. */ + ns_r_servfail = 2, /*%< Server failure. */ + ns_r_nxdomain = 3, /*%< Name error. */ + ns_r_notimpl = 4, /*%< Unimplemented. */ + ns_r_refused = 5, /*%< Operation refused. */ /* these are for BIND_UPDATE */ - ns_r_yxdomain = 6, /* Name exists */ - ns_r_yxrrset = 7, /* RRset exists */ - ns_r_nxrrset = 8, /* RRset does not exist */ - ns_r_notauth = 9, /* Not authoritative for zone */ - ns_r_notzone = 10, /* Zone of record different from zone section */ + ns_r_yxdomain = 6, /*%< Name exists */ + ns_r_yxrrset = 7, /*%< RRset exists */ + ns_r_nxrrset = 8, /*%< RRset does not exist */ + ns_r_notauth = 9, /*%< Not authoritative for zone */ + ns_r_notzone = 10, /*%< Zone of record different from zone section */ ns_r_max = 11, /* The following are EDNS extended rcodes */ ns_r_badvers = 16, @@ -219,7 +219,7 @@ typedef enum __ns_update_operation { ns_uop_max = 2 } ns_update_operation; -/* +/*% * This structure is used for TSIG authenticated messages */ struct ns_tsig_key { @@ -229,7 +229,7 @@ struct ns_tsig_key { }; typedef struct ns_tsig_key ns_tsig_key; -/* +/*% * This structure is used for TSIG authenticated TCP messages */ struct ns_tcp_tsig_state { @@ -249,61 +249,61 @@ typedef struct ns_tcp_tsig_state ns_tcp_tsig_state; #define NS_TSIG_ERROR_NO_SPACE -11 #define NS_TSIG_ERROR_FORMERR -12 -/* +/*% * Currently defined type values for resources and queries. */ typedef enum __ns_type { - ns_t_invalid = 0, /* Cookie. */ - ns_t_a = 1, /* Host address. */ - ns_t_ns = 2, /* Authoritative server. */ - ns_t_md = 3, /* Mail destination. */ - ns_t_mf = 4, /* Mail forwarder. */ - ns_t_cname = 5, /* Canonical name. */ - ns_t_soa = 6, /* Start of authority zone. */ - ns_t_mb = 7, /* Mailbox domain name. */ - ns_t_mg = 8, /* Mail group member. */ - ns_t_mr = 9, /* Mail rename name. */ - ns_t_null = 10, /* Null resource record. */ - ns_t_wks = 11, /* Well known service. */ - ns_t_ptr = 12, /* Domain name pointer. */ - ns_t_hinfo = 13, /* Host information. */ - ns_t_minfo = 14, /* Mailbox information. */ - ns_t_mx = 15, /* Mail routing information. */ - ns_t_txt = 16, /* Text strings. */ - ns_t_rp = 17, /* Responsible person. */ - ns_t_afsdb = 18, /* AFS cell database. */ - ns_t_x25 = 19, /* X_25 calling address. */ - ns_t_isdn = 20, /* ISDN calling address. */ - ns_t_rt = 21, /* Router. */ - ns_t_nsap = 22, /* NSAP address. */ - ns_t_nsap_ptr = 23, /* Reverse NSAP lookup (deprecated). */ - ns_t_sig = 24, /* Security signature. */ - ns_t_key = 25, /* Security key. */ - ns_t_px = 26, /* X.400 mail mapping. */ - ns_t_gpos = 27, /* Geographical position (withdrawn). */ - ns_t_aaaa = 28, /* Ip6 Address. */ - ns_t_loc = 29, /* Location Information. */ - ns_t_nxt = 30, /* Next domain (security). */ - ns_t_eid = 31, /* Endpoint identifier. */ - ns_t_nimloc = 32, /* Nimrod Locator. */ - ns_t_srv = 33, /* Server Selection. */ - ns_t_atma = 34, /* ATM Address */ - ns_t_naptr = 35, /* Naming Authority PoinTeR */ - ns_t_kx = 36, /* Key Exchange */ - ns_t_cert = 37, /* Certification record */ - ns_t_a6 = 38, /* IPv6 address (deprecates AAAA) */ - ns_t_dname = 39, /* Non-terminal DNAME (for IPv6) */ - ns_t_sink = 40, /* Kitchen sink (experimentatl) */ - ns_t_opt = 41, /* EDNS0 option (meta-RR) */ - ns_t_apl = 42, /* Address prefix list (RFC 3123) */ - ns_t_tkey = 249, /* Transaction key */ - ns_t_tsig = 250, /* Transaction signature. */ - ns_t_ixfr = 251, /* Incremental zone transfer. */ - ns_t_axfr = 252, /* Transfer zone of authority. */ - ns_t_mailb = 253, /* Transfer mailbox records. */ - ns_t_maila = 254, /* Transfer mail agent records. */ - ns_t_any = 255, /* Wildcard match. */ - ns_t_zxfr = 256, /* BIND-specific, nonstandard. */ + ns_t_invalid = 0, /*%< Cookie. */ + ns_t_a = 1, /*%< Host address. */ + ns_t_ns = 2, /*%< Authoritative server. */ + ns_t_md = 3, /*%< Mail destination. */ + ns_t_mf = 4, /*%< Mail forwarder. */ + ns_t_cname = 5, /*%< Canonical name. */ + ns_t_soa = 6, /*%< Start of authority zone. */ + ns_t_mb = 7, /*%< Mailbox domain name. */ + ns_t_mg = 8, /*%< Mail group member. */ + ns_t_mr = 9, /*%< Mail rename name. */ + ns_t_null = 10, /*%< Null resource record. */ + ns_t_wks = 11, /*%< Well known service. */ + ns_t_ptr = 12, /*%< Domain name pointer. */ + ns_t_hinfo = 13, /*%< Host information. */ + ns_t_minfo = 14, /*%< Mailbox information. */ + ns_t_mx = 15, /*%< Mail routing information. */ + ns_t_txt = 16, /*%< Text strings. */ + ns_t_rp = 17, /*%< Responsible person. */ + ns_t_afsdb = 18, /*%< AFS cell database. */ + ns_t_x25 = 19, /*%< X_25 calling address. */ + ns_t_isdn = 20, /*%< ISDN calling address. */ + ns_t_rt = 21, /*%< Router. */ + ns_t_nsap = 22, /*%< NSAP address. */ + ns_t_nsap_ptr = 23, /*%< Reverse NSAP lookup (deprecated). */ + ns_t_sig = 24, /*%< Security signature. */ + ns_t_key = 25, /*%< Security key. */ + ns_t_px = 26, /*%< X.400 mail mapping. */ + ns_t_gpos = 27, /*%< Geographical position (withdrawn). */ + ns_t_aaaa = 28, /*%< Ip6 Address. */ + ns_t_loc = 29, /*%< Location Information. */ + ns_t_nxt = 30, /*%< Next domain (security). */ + ns_t_eid = 31, /*%< Endpoint identifier. */ + ns_t_nimloc = 32, /*%< Nimrod Locator. */ + ns_t_srv = 33, /*%< Server Selection. */ + ns_t_atma = 34, /*%< ATM Address */ + ns_t_naptr = 35, /*%< Naming Authority PoinTeR */ + ns_t_kx = 36, /*%< Key Exchange */ + ns_t_cert = 37, /*%< Certification record */ + ns_t_a6 = 38, /*%< IPv6 address (deprecates AAAA) */ + ns_t_dname = 39, /*%< Non-terminal DNAME (for IPv6) */ + ns_t_sink = 40, /*%< Kitchen sink (experimentatl) */ + ns_t_opt = 41, /*%< EDNS0 option (meta-RR) */ + ns_t_apl = 42, /*%< Address prefix list (RFC3123) */ + ns_t_tkey = 249, /*%< Transaction key */ + ns_t_tsig = 250, /*%< Transaction signature. */ + ns_t_ixfr = 251, /*%< Incremental zone transfer. */ + ns_t_axfr = 252, /*%< Transfer zone of authority. */ + ns_t_mailb = 253, /*%< Transfer mailbox records. */ + ns_t_maila = 254, /*%< Transfer mail agent records. */ + ns_t_any = 255, /*%< Wildcard match. */ + ns_t_zxfr = 256, /*%< BIND-specific, nonstandard. */ ns_t_max = 65536 } ns_type; @@ -318,61 +318,61 @@ typedef enum __ns_type { #define ns_t_xfr_p(t) ((t) == ns_t_axfr || (t) == ns_t_ixfr || \ (t) == ns_t_zxfr) -/* +/*% * Values for class field */ typedef enum __ns_class { - ns_c_invalid = 0, /* Cookie. */ - ns_c_in = 1, /* Internet. */ - ns_c_2 = 2, /* unallocated/unsupported. */ - ns_c_chaos = 3, /* MIT Chaos-net. */ - ns_c_hs = 4, /* MIT Hesiod. */ + ns_c_invalid = 0, /*%< Cookie. */ + ns_c_in = 1, /*%< Internet. */ + ns_c_2 = 2, /*%< unallocated/unsupported. */ + ns_c_chaos = 3, /*%< MIT Chaos-net. */ + ns_c_hs = 4, /*%< MIT Hesiod. */ /* Query class values which do not appear in resource records */ - ns_c_none = 254, /* for prereq. sections in update requests */ - ns_c_any = 255, /* Wildcard match. */ + ns_c_none = 254, /*%< for prereq. sections in update requests */ + ns_c_any = 255, /*%< Wildcard match. */ ns_c_max = 65536 } ns_class; /* DNSSEC constants. */ typedef enum __ns_key_types { - ns_kt_rsa = 1, /* key type RSA/MD5 */ - ns_kt_dh = 2, /* Diffie Hellman */ - ns_kt_dsa = 3, /* Digital Signature Standard (MANDATORY) */ - ns_kt_private = 254 /* Private key type starts with OID */ + ns_kt_rsa = 1, /*%< key type RSA/MD5 */ + ns_kt_dh = 2, /*%< Diffie Hellman */ + ns_kt_dsa = 3, /*%< Digital Signature Standard (MANDATORY) */ + ns_kt_private = 254 /*%< Private key type starts with OID */ } ns_key_types; typedef enum __ns_cert_types { - cert_t_pkix = 1, /* PKIX (X.509v3) */ - cert_t_spki = 2, /* SPKI */ - cert_t_pgp = 3, /* PGP */ - cert_t_url = 253, /* URL private type */ - cert_t_oid = 254 /* OID private type */ + cert_t_pkix = 1, /*%< PKIX (X.509v3) */ + cert_t_spki = 2, /*%< SPKI */ + cert_t_pgp = 3, /*%< PGP */ + cert_t_url = 253, /*%< URL private type */ + cert_t_oid = 254 /*%< OID private type */ } ns_cert_types; /* Flags field of the KEY RR rdata. */ -#define NS_KEY_TYPEMASK 0xC000 /* Mask for "type" bits */ -#define NS_KEY_TYPE_AUTH_CONF 0x0000 /* Key usable for both */ -#define NS_KEY_TYPE_CONF_ONLY 0x8000 /* Key usable for confidentiality */ -#define NS_KEY_TYPE_AUTH_ONLY 0x4000 /* Key usable for authentication */ -#define NS_KEY_TYPE_NO_KEY 0xC000 /* No key usable for either; no key */ +#define NS_KEY_TYPEMASK 0xC000 /*%< Mask for "type" bits */ +#define NS_KEY_TYPE_AUTH_CONF 0x0000 /*%< Key usable for both */ +#define NS_KEY_TYPE_CONF_ONLY 0x8000 /*%< Key usable for confidentiality */ +#define NS_KEY_TYPE_AUTH_ONLY 0x4000 /*%< Key usable for authentication */ +#define NS_KEY_TYPE_NO_KEY 0xC000 /*%< No key usable for either; no key */ /* The type bits can also be interpreted independently, as single bits: */ -#define NS_KEY_NO_AUTH 0x8000 /* Key unusable for authentication */ -#define NS_KEY_NO_CONF 0x4000 /* Key unusable for confidentiality */ +#define NS_KEY_NO_AUTH 0x8000 /*%< Key unusable for authentication */ +#define NS_KEY_NO_CONF 0x4000 /*%< Key unusable for confidentiality */ #define NS_KEY_RESERVED2 0x2000 /* Security is *mandatory* if bit=0 */ -#define NS_KEY_EXTENDED_FLAGS 0x1000 /* reserved - must be zero */ -#define NS_KEY_RESERVED4 0x0800 /* reserved - must be zero */ -#define NS_KEY_RESERVED5 0x0400 /* reserved - must be zero */ -#define NS_KEY_NAME_TYPE 0x0300 /* these bits determine the type */ -#define NS_KEY_NAME_USER 0x0000 /* key is assoc. with user */ -#define NS_KEY_NAME_ENTITY 0x0200 /* key is assoc. with entity eg host */ -#define NS_KEY_NAME_ZONE 0x0100 /* key is zone key */ -#define NS_KEY_NAME_RESERVED 0x0300 /* reserved meaning */ -#define NS_KEY_RESERVED8 0x0080 /* reserved - must be zero */ -#define NS_KEY_RESERVED9 0x0040 /* reserved - must be zero */ -#define NS_KEY_RESERVED10 0x0020 /* reserved - must be zero */ -#define NS_KEY_RESERVED11 0x0010 /* reserved - must be zero */ -#define NS_KEY_SIGNATORYMASK 0x000F /* key can sign RR's of same name */ +#define NS_KEY_EXTENDED_FLAGS 0x1000 /*%< reserved - must be zero */ +#define NS_KEY_RESERVED4 0x0800 /*%< reserved - must be zero */ +#define NS_KEY_RESERVED5 0x0400 /*%< reserved - must be zero */ +#define NS_KEY_NAME_TYPE 0x0300 /*%< these bits determine the type */ +#define NS_KEY_NAME_USER 0x0000 /*%< key is assoc. with user */ +#define NS_KEY_NAME_ENTITY 0x0200 /*%< key is assoc. with entity eg host */ +#define NS_KEY_NAME_ZONE 0x0100 /*%< key is zone key */ +#define NS_KEY_NAME_RESERVED 0x0300 /*%< reserved meaning */ +#define NS_KEY_RESERVED8 0x0080 /*%< reserved - must be zero */ +#define NS_KEY_RESERVED9 0x0040 /*%< reserved - must be zero */ +#define NS_KEY_RESERVED10 0x0020 /*%< reserved - must be zero */ +#define NS_KEY_RESERVED11 0x0010 /*%< reserved - must be zero */ +#define NS_KEY_SIGNATORYMASK 0x000F /*%< key can sign RR's of same name */ #define NS_KEY_RESERVED_BITMASK ( NS_KEY_RESERVED2 | \ NS_KEY_RESERVED4 | \ NS_KEY_RESERVED5 | \ @@ -380,16 +380,14 @@ typedef enum __ns_cert_types { NS_KEY_RESERVED9 | \ NS_KEY_RESERVED10 | \ NS_KEY_RESERVED11 ) -#define NS_KEY_RESERVED_BITMASK2 0xFFFF /* no bits defined here */ - +#define NS_KEY_RESERVED_BITMASK2 0xFFFF /*%< no bits defined here */ /* The Algorithm field of the KEY and SIG RR's is an integer, {1..254} */ -#define NS_ALG_MD5RSA 1 /* MD5 with RSA */ -#define NS_ALG_DH 2 /* Diffie Hellman KEY */ -#define NS_ALG_DSA 3 /* DSA KEY */ +#define NS_ALG_MD5RSA 1 /*%< MD5 with RSA */ +#define NS_ALG_DH 2 /*%< Diffie Hellman KEY */ +#define NS_ALG_DSA 3 /*%< DSA KEY */ #define NS_ALG_DSS NS_ALG_DSA -#define NS_ALG_EXPIRE_ONLY 253 /* No alg, no security */ -#define NS_ALG_PRIVATE_OID 254 /* Key begins with OID giving alg */ - +#define NS_ALG_EXPIRE_ONLY 253 /*%< No alg, no security */ +#define NS_ALG_PRIVATE_OID 254 /*%< Key begins with OID giving alg */ /* Protocol values */ /* value 0 is reserved */ #define NS_KEY_PROT_TLS 1 @@ -399,7 +397,7 @@ typedef enum __ns_cert_types { #define NS_KEY_PROT_ANY 255 /* Signatures */ -#define NS_MD5RSA_MIN_BITS 512 /* Size of a mod or exp in bits */ +#define NS_MD5RSA_MIN_BITS 512 /*%< Size of a mod or exp in bits */ #define NS_MD5RSA_MAX_BITS 4096 /* Total of binary mod and exp */ #define NS_MD5RSA_MAX_BYTES ((NS_MD5RSA_MAX_BITS+7/8)*2+3) @@ -413,15 +411,14 @@ typedef enum __ns_cert_types { #define NS_DSA_MAX_BYTES 405 /* Offsets into SIG record rdata to find various values */ -#define NS_SIG_TYPE 0 /* Type flags */ -#define NS_SIG_ALG 2 /* Algorithm */ -#define NS_SIG_LABELS 3 /* How many labels in name */ -#define NS_SIG_OTTL 4 /* Original TTL */ -#define NS_SIG_EXPIR 8 /* Expiration time */ -#define NS_SIG_SIGNED 12 /* Signature time */ -#define NS_SIG_FOOT 16 /* Key footprint */ -#define NS_SIG_SIGNER 18 /* Domain name of who signed it */ - +#define NS_SIG_TYPE 0 /*%< Type flags */ +#define NS_SIG_ALG 2 /*%< Algorithm */ +#define NS_SIG_LABELS 3 /*%< How many labels in name */ +#define NS_SIG_OTTL 4 /*%< Original TTL */ +#define NS_SIG_EXPIR 8 /*%< Expiration time */ +#define NS_SIG_SIGNED 12 /*%< Signature time */ +#define NS_SIG_FOOT 16 /*%< Key footprint */ +#define NS_SIG_SIGNER 18 /*%< Domain name of who signed it */ /* How RR types are represented as bit-flags in NXT records */ #define NS_NXT_BITS 8 #define NS_NXT_BIT_SET( n,p) (p[(n)/NS_NXT_BITS] |= (0x80>>((n)%NS_NXT_BITS))) @@ -429,12 +426,12 @@ typedef enum __ns_cert_types { #define NS_NXT_BIT_ISSET(n,p) (p[(n)/NS_NXT_BITS] & (0x80>>((n)%NS_NXT_BITS))) #define NS_NXT_MAX 127 -/* +/*% * EDNS0 extended flags, host order. */ #define NS_OPT_DNSSEC_OK 0x8000U -/* +/*% * Inline versions of get/put short/long. Pointer is advanced. */ #define NS_GET16(s, cp) do { \ @@ -473,7 +470,7 @@ typedef enum __ns_cert_types { (cp) += NS_INT32SZ; \ } while (0) -/* +/*% * ANSI C identifier hiding for bind's lib/nameser. */ #define ns_msg_getflag __ns_msg_getflag @@ -574,3 +571,4 @@ __END_DECLS #endif #endif /* !_ARPA_NAMESER_H_ */ +/*! \file */ diff --git a/lib/bind/include/arpa/nameser_compat.h b/lib/bind/include/arpa/nameser_compat.h index d7aaf3f9cf..8778bf9ad4 100644 --- a/lib/bind/include/arpa/nameser_compat.h +++ b/lib/bind/include/arpa/nameser_compat.h @@ -30,16 +30,15 @@ * SUCH DAMAGE. */ -/* +/*% * from nameser.h 8.1 (Berkeley) 6/2/93 - * $Id: nameser_compat.h,v 1.6 2004/07/01 04:41:20 marka Exp $ + * $Id: nameser_compat.h,v 1.7 2005/04/27 04:56:16 sra Exp $ */ #ifndef _ARPA_NAMESER_COMPAT_ #define _ARPA_NAMESER_COMPAT_ -#define __BIND 19950621 /* (DEAD) interface version stamp. */ - +#define __BIND 19950621 /*%< (DEAD) interface version stamp. */ #ifndef BYTE_ORDER #if (BSD >= 199103) # include @@ -47,10 +46,9 @@ #ifdef __linux # include #else -#define LITTLE_ENDIAN 1234 /* least-significant byte first (vax, pc) */ -#define BIG_ENDIAN 4321 /* most-significant byte first (IBM, net) */ -#define PDP_ENDIAN 3412 /* LSB first in word, MSW first in long (pdp)*/ - +#define LITTLE_ENDIAN 1234 /*%< least-significant byte first (vax, pc) */ +#define BIG_ENDIAN 4321 /*%< most-significant byte first (IBM, net) */ +#define PDP_ENDIAN 3412 /*%< LSB first in word, MSW first in long (pdp) */ #if defined(vax) || defined(ns32000) || defined(sun386) || defined(i386) || \ defined(MIPSEL) || defined(_MIPSEL) || defined(BIT_ZERO_ON_RIGHT) || \ defined(__alpha__) || defined(__alpha) || \ @@ -85,7 +83,7 @@ error "Undefined or invalid BYTE_ORDER"; #endif -/* +/*% * Structure for query header. The order of the fields is machine- and * compiler-dependent, depending on the byte/bit order and the layout * of bit fields. We use bit fields only in int variables, as this @@ -93,40 +91,40 @@ */ typedef struct { - unsigned id :16; /* query identification number */ + unsigned id :16; /*%< query identification number */ #if BYTE_ORDER == BIG_ENDIAN /* fields in third byte */ - unsigned qr: 1; /* response flag */ - unsigned opcode: 4; /* purpose of message */ - unsigned aa: 1; /* authoritive answer */ - unsigned tc: 1; /* truncated message */ - unsigned rd: 1; /* recursion desired */ + unsigned qr: 1; /*%< response flag */ + unsigned opcode: 4; /*%< purpose of message */ + unsigned aa: 1; /*%< authoritive answer */ + unsigned tc: 1; /*%< truncated message */ + unsigned rd: 1; /*%< recursion desired */ /* fields in fourth byte */ - unsigned ra: 1; /* recursion available */ - unsigned unused :1; /* unused bits (MBZ as of 4.9.3a3) */ - unsigned ad: 1; /* authentic data from named */ - unsigned cd: 1; /* checking disabled by resolver */ - unsigned rcode :4; /* response code */ + unsigned ra: 1; /*%< recursion available */ + unsigned unused :1; /*%< unused bits (MBZ as of 4.9.3a3) */ + unsigned ad: 1; /*%< authentic data from named */ + unsigned cd: 1; /*%< checking disabled by resolver */ + unsigned rcode :4; /*%< response code */ #endif #if BYTE_ORDER == LITTLE_ENDIAN || BYTE_ORDER == PDP_ENDIAN /* fields in third byte */ - unsigned rd :1; /* recursion desired */ - unsigned tc :1; /* truncated message */ - unsigned aa :1; /* authoritive answer */ - unsigned opcode :4; /* purpose of message */ - unsigned qr :1; /* response flag */ + unsigned rd :1; /*%< recursion desired */ + unsigned tc :1; /*%< truncated message */ + unsigned aa :1; /*%< authoritive answer */ + unsigned opcode :4; /*%< purpose of message */ + unsigned qr :1; /*%< response flag */ /* fields in fourth byte */ - unsigned rcode :4; /* response code */ - unsigned cd: 1; /* checking disabled by resolver */ - unsigned ad: 1; /* authentic data from named */ - unsigned unused :1; /* unused bits (MBZ as of 4.9.3a3) */ - unsigned ra :1; /* recursion available */ + unsigned rcode :4; /*%< response code */ + unsigned cd: 1; /*%< checking disabled by resolver */ + unsigned ad: 1; /*%< authentic data from named */ + unsigned unused :1; /*%< unused bits (MBZ as of 4.9.3a3) */ + unsigned ra :1; /*%< recursion available */ #endif /* remaining bytes */ - unsigned qdcount :16; /* number of question entries */ - unsigned ancount :16; /* number of answer entries */ - unsigned nscount :16; /* number of authority entries */ - unsigned arcount :16; /* number of resource entries */ + unsigned qdcount :16; /*%< number of question entries */ + unsigned ancount :16; /*%< number of answer entries */ + unsigned nscount :16; /*%< number of authority entries */ + unsigned arcount :16; /*%< number of resource entries */ } HEADER; #define PACKETSZ NS_PACKETSZ @@ -230,3 +228,4 @@ typedef struct { #define PUTLONG NS_PUT32 #endif /* _ARPA_NAMESER_COMPAT_ */ +/*! \file */ diff --git a/lib/bind/include/fd_setsize.h b/lib/bind/include/fd_setsize.h index 235b1ad1c2..0e21049742 100644 --- a/lib/bind/include/fd_setsize.h +++ b/lib/bind/include/fd_setsize.h @@ -1,9 +1,10 @@ #ifndef _FD_SETSIZE_H #define _FD_SETSIZE_H -/* +/*% * If you need a bigger FD_SETSIZE, this is NOT the place to set it. * This file is a fallback for BIND ports which don't specify their own. */ #endif /* _FD_SETSIZE_H */ +/*! \file */ diff --git a/lib/bind/include/hesiod.h b/lib/bind/include/hesiod.h index 11ce4ae509..d64c0c5e80 100644 --- a/lib/bind/include/hesiod.h +++ b/lib/bind/include/hesiod.h @@ -15,12 +15,13 @@ * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* +/*! \file + * \brief * This file is primarily maintained by and . */ /* - * $Id: hesiod.h,v 1.3 2004/03/09 06:29:53 marka Exp $ + * $Id: hesiod.h,v 1.4 2005/04/27 04:56:14 sra Exp $ */ #ifndef _HESIOD_H_INCLUDED diff --git a/lib/bind/include/irp.h b/lib/bind/include/irp.h index 31035289ad..1290bd068f 100644 --- a/lib/bind/include/irp.h +++ b/lib/bind/include/irp.h @@ -16,16 +16,18 @@ */ /* - * $Id: irp.h,v 1.3 2004/03/09 06:29:53 marka Exp $ + * $Id: irp.h,v 1.4 2005/04/27 04:56:15 sra Exp $ */ #ifndef _IRP_H_INCLUDED #define _IRP_H_INCLUDED -#define IRPD_TIMEOUT 30 /* seconds */ -#define IRPD_MAXSESS 50 /* number of simultaneous sessions. */ -#define IRPD_PORT 6660 /* 10 times the number of the beast. */ -#define IRPD_PATH "/var/run/irpd" /* af_unix socket path */ +/*! \file */ + +#define IRPD_TIMEOUT 30 /*%< seconds */ +#define IRPD_MAXSESS 50 /*%< number of simultaneous sessions. */ +#define IRPD_PORT 6660 /*%< 10 times the number of the beast. */ +#define IRPD_PATH "/var/run/irpd" /*%< af_unix socket path */ /* If sets the environment variable IRPDSERVER to an IP address (e.g. "192.5.5.1"), then that's the host the client expects irpd to be @@ -101,3 +103,5 @@ int irs_irp_get_full_response(struct irp_p *, int *, char *, size_t, int irs_irp_read_line(struct irp_p *, char *, int); #endif + +/*! \file */ diff --git a/lib/bind/include/irs.h b/lib/bind/include/irs.h index cc62774be2..42d4890dfd 100644 --- a/lib/bind/include/irs.h +++ b/lib/bind/include/irs.h @@ -16,12 +16,14 @@ */ /* - * $Id: irs.h,v 1.4 2004/03/09 06:29:53 marka Exp $ + * $Id: irs.h,v 1.5 2005/04/27 04:56:15 sra Exp $ */ #ifndef _IRS_H_INCLUDED #define _IRS_H_INCLUDED +/*! \file */ + #include #include @@ -31,7 +33,7 @@ #include #include -/* +/*% * This is the group map class. */ struct irs_gr { @@ -49,7 +51,7 @@ struct irs_gr { void (*)(void *))); }; -/* +/*% * This is the password map class. */ struct irs_pw { @@ -65,7 +67,7 @@ struct irs_pw { void (*)(void *))); }; -/* +/*% * This is the service map class. */ struct irs_sv { @@ -82,7 +84,7 @@ struct irs_sv { void (*)(void *))); }; -/* +/*% * This is the protocols map class. */ struct irs_pr { @@ -98,7 +100,7 @@ struct irs_pr { void (*)(void *))); }; -/* +/*% * This is the hosts map class. */ struct irs_ho { @@ -118,7 +120,7 @@ struct irs_ho { const struct addrinfo *)); }; -/* +/*% * This is the networks map class. */ struct irs_nw { @@ -134,7 +136,7 @@ struct irs_nw { void (*)(void *))); }; -/* +/*% * This is the netgroups map class. */ struct irs_ng { @@ -149,7 +151,7 @@ struct irs_ng { void (*minimize) __P((struct irs_ng *)); }; -/* +/*% * This is the generic map class, which copies the front of all others. */ struct irs_map { @@ -157,7 +159,7 @@ struct irs_map { void (*close) __P((void *)); }; -/* +/*% * This is the accessor class. It contains pointers to all of the * initializers for the map classes for a particular accessor. */ @@ -176,21 +178,21 @@ struct irs_acc { void (*)(void *))); }; -/* +/*% * This is because the official definition of "struct netent" has no * concept of CIDR even though it allows variant address families (on * output but not input). The compatibility stubs convert the structs * below into "struct netent"'s. */ struct nwent { - char *n_name; /* official name of net */ - char **n_aliases; /* alias list */ - int n_addrtype; /* net address type */ - void *n_addr; /* network address */ - int n_length; /* address length, in bits */ + char *n_name; /*%< official name of net */ + char **n_aliases; /*%< alias list */ + int n_addrtype; /*%< net address type */ + void *n_addr; /*%< network address */ + int n_length; /*%< address length, in bits */ }; -/* +/*% * Hide external function names from POSIX. */ #define irs_gen_acc __irs_gen_acc @@ -240,7 +242,7 @@ struct nwent { #define net_data_destroy __net_data_destroy #define net_data_minimize __net_data_minimize -/* +/*% * Externs. */ extern struct irs_acc * irs_gen_acc __P((const char *, const char *)); @@ -251,7 +253,7 @@ extern struct irs_acc * irs_irp_acc __P((const char *)); extern void irs_destroy __P((void)); -/* +/*% * These forward declarations are for the semi-private functions in * the get*.c files. Each of these funcs implements the real get* * functionality and the standard versions are just wrappers that @@ -260,8 +262,7 @@ extern void irs_destroy __P((void)); * the /usr/include replacements. */ -struct net_data; /* forward */ - +struct net_data; /*%< forward */ /* * net_data_create gets a singleton net_data object. net_data_init * creates as many net_data objects as times it is called. Clients using @@ -343,3 +344,5 @@ extern void setservent_p __P((int, struct net_data *)); extern void endservent_p __P((struct net_data *)); #endif /*_IRS_H_INCLUDED*/ + +/*! \file */ diff --git a/lib/bind/include/isc/assertions.h b/lib/bind/include/isc/assertions.h index e5dbedd692..b885f6475b 100644 --- a/lib/bind/include/isc/assertions.h +++ b/lib/bind/include/isc/assertions.h @@ -16,7 +16,7 @@ */ /* - * $Id: assertions.h,v 1.2 2004/03/09 06:29:54 marka Exp $ + * $Id: assertions.h,v 1.3 2005/04/27 04:56:17 sra Exp $ */ #ifndef ASSERTIONS_H @@ -118,5 +118,5 @@ const char *assertion_type_to_text(assertion_type type); #define INVARIANT(cond) ((void) (cond)) #define INVARIANT_ERR(cond) ((void) (cond)) #endif /* CHECK_INVARIANT */ - #endif /* ASSERTIONS_H */ +/*! \file */ diff --git a/lib/bind/include/isc/ctl.h b/lib/bind/include/isc/ctl.h index f7a8a47e7a..e2ba20201d 100644 --- a/lib/bind/include/isc/ctl.h +++ b/lib/bind/include/isc/ctl.h @@ -19,9 +19,11 @@ */ /* - * $Id: ctl.h,v 1.4 2004/03/09 06:29:54 marka Exp $ + * $Id: ctl.h,v 1.5 2005/04/27 04:56:17 sra Exp $ */ +/*! \file */ + #include #include @@ -29,10 +31,9 @@ /* Macros. */ -#define CTL_MORE 0x0001 /* More will be / should be sent. */ -#define CTL_EXIT 0x0002 /* Close connection after this. */ -#define CTL_DATA 0x0004 /* Go into / this is DATA mode. */ - +#define CTL_MORE 0x0001 /*%< More will be / should be sent. */ +#define CTL_EXIT 0x0002 /*%< Close connection after this. */ +#define CTL_DATA 0x0004 /*%< Go into / this is DATA mode. */ /* Types. */ struct ctl_cctx; @@ -107,3 +108,5 @@ void * ctl_getcsctx(struct ctl_sess *); void * ctl_setcsctx(struct ctl_sess *, void *); #endif /*ISC_CTL_H*/ + +/*! \file */ diff --git a/lib/bind/include/isc/dst.h b/lib/bind/include/isc/dst.h index fe9229725a..90a9e67468 100644 --- a/lib/bind/include/isc/dst.h +++ b/lib/bind/include/isc/dst.h @@ -3,15 +3,14 @@ #ifndef HAS_DST_KEY typedef struct dst_key { - char *dk_key_name; /* name of the key */ - int dk_key_size; /* this is the size of the key in bits */ - int dk_proto; /* what protocols this key can be used for */ - int dk_alg; /* algorithm number from key record */ - u_int32_t dk_flags; /* and the flags of the public key */ - u_int16_t dk_id; /* identifier of the key */ + char *dk_key_name; /*%< name of the key */ + int dk_key_size; /*%< this is the size of the key in bits */ + int dk_proto; /*%< what protocols this key can be used for */ + int dk_alg; /*%< algorithm number from key record */ + u_int32_t dk_flags; /*%< and the flags of the public key */ + u_int16_t dk_id; /*%< identifier of the key */ } DST_KEY; #endif /* HAS_DST_KEY */ - /* * do not taint namespace */ @@ -59,58 +58,47 @@ typedef struct dst_key { void dst_init(void); int dst_check_algorithm(const int); -int dst_sign_data(const int, /* specifies INIT/UPDATE/FINAL/ALL */ - DST_KEY *, /* the key to use */ - void **, /* pointer to state structure */ - const u_char *, /* data to be signed */ - const int, /* length of input data */ - u_char *, /* buffer to write signature to */ - const int); /* size of output buffer */ - -int dst_verify_data(const int, /* specifies INIT/UPDATE/FINAL/ALL */ - DST_KEY *, /* the key to use */ - void **, /* pointer to state structure */ - const u_char *, /* data to be verified */ - const int, /* length of input data */ - const u_char *, /* buffer containing signature */ - const int); /* length of signature */ - - -DST_KEY *dst_read_key(const char *, /* name of key */ - const u_int16_t, /* key tag identifier */ - const int, /* key algorithm */ - const int); /* Private/PublicKey wanted*/ - -int dst_write_key(const DST_KEY *, /* key to write out */ - const int); /* Public/Private */ - -DST_KEY *dst_dnskey_to_key(const char *, /* KEY record name */ - const u_char *, /* KEY RDATA */ - const int); /* size of input buffer*/ - - -int dst_key_to_dnskey(const DST_KEY *, /* key to translate */ - u_char *, /* output buffer */ - const int); /* size of out_storage*/ - - -DST_KEY *dst_buffer_to_key(const char *, /* name of the key */ - const int, /* algorithm */ - const int, /* dns flags */ - const int, /* dns protocol */ - const u_char *, /* key in dns wire fmt */ - const int); /* size of key */ - +int dst_sign_data(const int, /*!< specifies INIT/UPDATE/FINAL/ALL */ + DST_KEY *, /*!< the key to use */ + void **, /*!< pointer to state structure */ + const u_char *, /*!< data to be signed */ + const int, /*!< length of input data */ + u_char *, /*!< buffer to write signature to */ + const int); /*!< size of output buffer */ +int dst_verify_data(const int, /*!< specifies INIT/UPDATE/FINAL/ALL */ + DST_KEY *, /*!< the key to use */ + void **, /*!< pointer to state structure */ + const u_char *, /*!< data to be verified */ + const int, /*!< length of input data */ + const u_char *, /*!< buffer containing signature */ + const int); /*!< length of signature */ +DST_KEY *dst_read_key(const char *, /*!< name of key */ + const u_int16_t, /*!< key tag identifier */ + const int, /*!< key algorithm */ + const int); /*!< Private/PublicKey wanted */ +int dst_write_key(const DST_KEY *, /*!< key to write out */ + const int); /*!< Public/Private */ +DST_KEY *dst_dnskey_to_key(const char *, /*!< KEY record name */ + const u_char *, /*!< KEY RDATA */ + const int); /*!< size of input buffer */ +int dst_key_to_dnskey(const DST_KEY *, /*!< key to translate */ + u_char *, /*!< output buffer */ + const int); /*!< size of out_storage */ +DST_KEY *dst_buffer_to_key(const char *, /*!< name of the key */ + const int, /*!< algorithm */ + const int, /*!< dns flags */ + const int, /*!< dns protocol */ + const u_char *, /*!< key in dns wire fmt */ + const int); /*!< size of key */ int dst_key_to_buffer(DST_KEY *, u_char *, int); -DST_KEY *dst_generate_key(const char *, /* name of new key */ - const int, /* key algorithm to generate */ - const int, /* size of new key */ - const int, /* alg dependent parameter*/ - const int, /* key DNS flags */ - const int); /* key DNS protocol */ - +DST_KEY *dst_generate_key(const char *, /*!< name of new key */ + const int, /*!< key algorithm to generate */ + const int, /*!< size of new key */ + const int, /*!< alg dependent parameter */ + const int, /*!< key DNS flags */ + const int); /*!< key DNS protocol */ DST_KEY *dst_free_key(DST_KEY *); int dst_compare_keys(const DST_KEY *, const DST_KEY *); @@ -122,13 +110,12 @@ u_int16_t dst_s_dns_key_id(const u_char *, const int); u_int16_t dst_s_id_calc(const u_char *, const int); /* Used by callers as well as by the library. */ -#define RAW_KEY_SIZE 8192 /* large enough to store any key */ - +#define RAW_KEY_SIZE 8192 /*%< large enough to store any key */ /* DST_API control flags */ /* These are used used in functions dst_sign_data and dst_verify_data */ -#define SIG_MODE_INIT 1 /* initialize digest */ -#define SIG_MODE_UPDATE 2 /* add data to digest */ -#define SIG_MODE_FINAL 4 /* generate/verify signature */ +#define SIG_MODE_INIT 1 /*%< initialize digest */ +#define SIG_MODE_UPDATE 2 /*%< add data to digest */ +#define SIG_MODE_FINAL 4 /*%< generate/verify signature */ #define SIG_MODE_ALL (SIG_MODE_INIT|SIG_MODE_UPDATE|SIG_MODE_FINAL) /* Flags for dst_read_private_key() */ @@ -178,3 +165,4 @@ u_int16_t dst_s_id_calc(const u_char *, const int); #define UNSUPPORTED_KEYALG (-31) #endif /* DST_H */ +/*! \file */ diff --git a/lib/bind/include/isc/eventlib.h b/lib/bind/include/isc/eventlib.h index 281976b5aa..62b443aafe 100644 --- a/lib/bind/include/isc/eventlib.h +++ b/lib/bind/include/isc/eventlib.h @@ -18,7 +18,7 @@ /* eventlib.h - exported interfaces for eventlib * vix 09sep95 [initial] * - * $Id: eventlib.h,v 1.3 2004/03/09 06:29:55 marka Exp $ + * $Id: eventlib.h,v 1.4 2005/04/27 04:56:17 sra Exp $ */ #ifndef _EVENTLIB_H @@ -198,3 +198,5 @@ int evDefer __P((evContext, evWaitFunc, void *)); #endif #endif /*_EVENTLIB_H*/ + +/*! \file */ diff --git a/lib/bind/include/isc/heap.h b/lib/bind/include/isc/heap.h index 691c821d1e..384d507cf5 100644 --- a/lib/bind/include/isc/heap.h +++ b/lib/bind/include/isc/heap.h @@ -45,3 +45,5 @@ int heap_increased(heap_context, int); int heap_decreased(heap_context, int); void * heap_element(heap_context, int); int heap_for_each(heap_context, heap_for_each_func, void *); + +/*! \file */ diff --git a/lib/bind/include/isc/irpmarshall.h b/lib/bind/include/isc/irpmarshall.h index e0b0267415..244b3e3460 100644 --- a/lib/bind/include/isc/irpmarshall.h +++ b/lib/bind/include/isc/irpmarshall.h @@ -16,7 +16,7 @@ */ /* - * $Id: irpmarshall.h,v 1.3 2004/03/09 06:29:56 marka Exp $ + * $Id: irpmarshall.h,v 1.4 2005/04/27 04:56:17 sra Exp $ */ #ifndef _IRPMARSHALL_H_INCLUDED @@ -63,7 +63,8 @@ int irp_unmarshall_nw(struct nwent *, char *); int irp_marshall_ne(struct netent *, char **, size_t *); int irp_unmarshall_ne(struct netent *, char *); -/* +/*! \file + * \brief * Functions to marshall and unmarshall various system data structures. We * use a printable ascii format that is as close to various system config * files as reasonable (e.g. /etc/passwd format). @@ -79,9 +80,7 @@ int irp_unmarshall_ne(struct netent *, char *); * * The following description is true for all the marshalling functions: * - */ - -/* int irp_marshall_XX(struct yyyy *XX, char **buffer, size_t *len); + * int irp_marshall_XX(struct yyyy *XX, char **buffer, size_t *len); * * The argument XX (of type struct passwd for example) is marshalled in the * buffer pointed at by *BUFFER, which is of length *LEN. Returns 0 @@ -101,9 +100,7 @@ int irp_unmarshall_ne(struct netent *, char *); * to separate fields). Fields that have multiple subfields (like the * gr_mem field in struct group) have their subparts separated by * commas. - */ - -/* + * * int irp_unmarshall_XX(struct YYYYY *XX, char *buffer); * * The unmashalling functions break apart the buffer and store the diff --git a/lib/bind/include/isc/list.h b/lib/bind/include/isc/list.h index ad574ac2b5..816709b723 100644 --- a/lib/bind/include/isc/list.h +++ b/lib/bind/include/isc/list.h @@ -110,3 +110,4 @@ #define DEQUEUE(list, elt, link) UNLINK(list, elt, link) #endif /* LIST_H */ +/*! \file */ diff --git a/lib/bind/include/isc/logging.h b/lib/bind/include/isc/logging.h index 574fd8a257..c539443ff8 100644 --- a/lib/bind/include/isc/logging.h +++ b/lib/bind/include/isc/logging.h @@ -110,3 +110,4 @@ int log_free_channel(log_channel); void log_close_debug_channels(log_context); #endif /* !LOGGING_H */ +/*! \file */ diff --git a/lib/bind/include/isc/memcluster.h b/lib/bind/include/isc/memcluster.h index 11e1fa381d..0923deb5e7 100644 --- a/lib/bind/include/isc/memcluster.h +++ b/lib/bind/include/isc/memcluster.h @@ -47,3 +47,4 @@ void memstats(FILE *); int memactive(void); #endif /* MEMCLUSTER_H */ +/*! \file */ diff --git a/lib/bind/include/isc/misc.h b/lib/bind/include/isc/misc.h index 07c7263e42..e9ad2c552d 100644 --- a/lib/bind/include/isc/misc.h +++ b/lib/bind/include/isc/misc.h @@ -16,12 +16,14 @@ */ /* - * $Id: misc.h,v 1.4 2004/03/09 06:29:56 marka Exp $ + * $Id: misc.h,v 1.5 2005/04/27 04:56:18 sra Exp $ */ #ifndef _ISC_MISC_H #define _ISC_MISC_H +/*! \file */ + #include #define bitncmp __bitncmp @@ -37,3 +39,5 @@ extern void isc_puthexstring(FILE *, const unsigned char *, size_t, extern void isc_tohex(const unsigned char *, size_t, char *); #endif /*_ISC_MISC_H*/ + +/*! \file */ diff --git a/lib/bind/include/isc/tree.h b/lib/bind/include/isc/tree.h index 80df6cfa12..96feaca68d 100644 --- a/lib/bind/include/isc/tree.h +++ b/lib/bind/include/isc/tree.h @@ -3,7 +3,7 @@ * vix 22jan93 [revisited; uses RCS, ANSI, POSIX; has bug fixes] * vix 27jun86 [broken out of tree.c] * - * $Id: tree.h,v 1.2 2003/06/03 04:39:30 marka Exp $ + * $Id: tree.h,v 1.3 2005/04/27 04:56:18 sra Exp $ */ @@ -19,7 +19,7 @@ # endif #endif -/* +/*% * tree_t is our package-specific anonymous pointer. */ #if defined(__STDC__) || defined(__GNUC__) @@ -28,7 +28,7 @@ typedef void *tree_t; typedef char *tree_t; #endif -/* +/*% * Do not taint namespace */ #define tree_add __tree_add @@ -56,3 +56,4 @@ void tree_mung __P((tree **, void (*)())); #endif /* _TREE_H_INCLUDED */ +/*! \file */ diff --git a/lib/bind/include/netdb.h b/lib/bind/include/netdb.h index d5c17de059..f2751b00c2 100644 --- a/lib/bind/include/netdb.h +++ b/lib/bind/include/netdb.h @@ -86,7 +86,7 @@ /* * @(#)netdb.h 8.1 (Berkeley) 6/2/93 - * $Id: netdb.h,v 1.16 2004/11/30 01:08:50 marka Exp $ + * $Id: netdb.h,v 1.17 2005/04/27 04:56:15 sra Exp $ */ #ifndef _NETDB_H_ @@ -131,99 +131,98 @@ __END_DECLS extern int h_errno; #endif -/* +/*% * Structures returned by network data base library. All addresses are * supplied in host order, and returned in network order (suitable for * use in system calls). */ struct hostent { - char *h_name; /* official name of host */ - char **h_aliases; /* alias list */ - int h_addrtype; /* host address type */ - int h_length; /* length of address */ - char **h_addr_list; /* list of addresses from name server */ -#define h_addr h_addr_list[0] /* address, for backward compatiblity */ + char *h_name; /*%< official name of host */ + char **h_aliases; /*%< alias list */ + int h_addrtype; /*%< host address type */ + int h_length; /*%< length of address */ + char **h_addr_list; /*%< list of addresses from name server */ +#define h_addr h_addr_list[0] /*%< address, for backward compatiblity */ }; -/* +/*% * Assumption here is that a network number * fits in an unsigned long -- probably a poor one. */ struct netent { - char *n_name; /* official name of net */ - char **n_aliases; /* alias list */ - int n_addrtype; /* net address type */ - unsigned long n_net; /* network # */ + char *n_name; /*%< official name of net */ + char **n_aliases; /*%< alias list */ + int n_addrtype; /*%< net address type */ + unsigned long n_net; /*%< network # */ }; struct servent { - char *s_name; /* official service name */ - char **s_aliases; /* alias list */ - int s_port; /* port # */ - char *s_proto; /* protocol to use */ + char *s_name; /*%< official service name */ + char **s_aliases; /*%< alias list */ + int s_port; /*%< port # */ + char *s_proto; /*%< protocol to use */ }; struct protoent { - char *p_name; /* official protocol name */ - char **p_aliases; /* alias list */ - int p_proto; /* protocol # */ + char *p_name; /*%< official protocol name */ + char **p_aliases; /*%< alias list */ + int p_proto; /*%< protocol # */ }; struct addrinfo { - int ai_flags; /* AI_PASSIVE, AI_CANONNAME */ - int ai_family; /* PF_xxx */ - int ai_socktype; /* SOCK_xxx */ - int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ + int ai_flags; /*%< AI_PASSIVE, AI_CANONNAME */ + int ai_family; /*%< PF_xxx */ + int ai_socktype; /*%< SOCK_xxx */ + int ai_protocol; /*%< 0 or IPPROTO_xxx for IPv4 and IPv6 */ #if defined(sun) && defined(_SOCKLEN_T) #ifdef __sparc9 int _ai_pad; #endif socklen_t ai_addrlen; #else - size_t ai_addrlen; /* length of ai_addr */ + size_t ai_addrlen; /*%< length of ai_addr */ #endif #ifdef __linux - struct sockaddr *ai_addr; /* binary address */ - char *ai_canonname; /* canonical name for hostname */ + struct sockaddr *ai_addr; /*%< binary address */ + char *ai_canonname; /*%< canonical name for hostname */ #else - char *ai_canonname; /* canonical name for hostname */ - struct sockaddr *ai_addr; /* binary address */ + char *ai_canonname; /*%< canonical name for hostname */ + struct sockaddr *ai_addr; /*%< binary address */ #endif - struct addrinfo *ai_next; /* next structure in linked list */ + struct addrinfo *ai_next; /*%< next structure in linked list */ }; -/* +/*% * Error return codes from gethostbyname() and gethostbyaddr() * (left in extern int h_errno). */ -#define NETDB_INTERNAL -1 /* see errno */ -#define NETDB_SUCCESS 0 /* no problem */ -#define HOST_NOT_FOUND 1 /* Authoritative Answer Host not found */ -#define TRY_AGAIN 2 /* Non-Authoritive Host not found, or SERVERFAIL */ -#define NO_RECOVERY 3 /* Non recoverable errors, FORMERR, REFUSED, NOTIMP */ -#define NO_DATA 4 /* Valid name, no data record of requested type */ -#define NO_ADDRESS NO_DATA /* no address, look for MX record */ - +#define NETDB_INTERNAL -1 /*%< see errno */ +#define NETDB_SUCCESS 0 /*%< no problem */ +#define HOST_NOT_FOUND 1 /*%< Authoritative Answer Host not found */ +#define TRY_AGAIN 2 /*%< Non-Authoritive Host not found, or SERVERFAIL */ +#define NO_RECOVERY 3 /*%< Non recoverable errors, FORMERR, REFUSED, NOTIMP */ +#define NO_DATA 4 /*%< Valid name, no data record of requested type */ +#define NO_ADDRESS NO_DATA /*%< no address, look for MX record */ /* * Error return codes from getaddrinfo() */ -#define EAI_ADDRFAMILY 1 /* address family for hostname not supported */ -#define EAI_AGAIN 2 /* temporary failure in name resolution */ -#define EAI_BADFLAGS 3 /* invalid value for ai_flags */ -#define EAI_FAIL 4 /* non-recoverable failure in name resolution */ -#define EAI_FAMILY 5 /* ai_family not supported */ -#define EAI_MEMORY 6 /* memory allocation failure */ -#define EAI_NODATA 7 /* no address associated with hostname */ -#define EAI_NONAME 8 /* hostname nor servname provided, or not known */ -#define EAI_SERVICE 9 /* servname not supported for ai_socktype */ -#define EAI_SOCKTYPE 10 /* ai_socktype not supported */ -#define EAI_SYSTEM 11 /* system error returned in errno */ +#define EAI_ADDRFAMILY 1 /*%< address family for hostname not supported */ +#define EAI_AGAIN 2 /*%< temporary failure in name resolution */ +#define EAI_BADFLAGS 3 /*%< invalid value for ai_flags */ +#define EAI_FAIL 4 /*%< non-recoverable failure in name resolution */ +#define EAI_FAMILY 5 /*%< ai_family not supported */ +#define EAI_MEMORY 6 /*%< memory allocation failure */ +#define EAI_NODATA 7 /*%< no address associated with hostname */ +#define EAI_NONAME 8 /*%< hostname nor servname provided, or not known */ +#define EAI_SERVICE 9 /*%< servname not supported for ai_socktype */ +#define EAI_SOCKTYPE 10 /*%< ai_socktype not supported */ +#define EAI_SYSTEM 11 /*%< system error returned in errno */ #define EAI_BADHINTS 12 #define EAI_PROTOCOL 13 #define EAI_MAX 14 -/* +/*% * Flag values for getaddrinfo() */ #define AI_PASSIVE 0x00000001 @@ -231,7 +230,7 @@ struct addrinfo { #define AI_NUMERICHOST 0x00000004 #define AI_MASK 0x00000007 -/* +/*% * Flag values for getipnodebyname() */ #define AI_V4MAPPED 0x00000008 @@ -239,13 +238,13 @@ struct addrinfo { #define AI_ADDRCONFIG 0x00000020 #define AI_DEFAULT (AI_V4MAPPED|AI_ADDRCONFIG) -/* +/*% * Constants for getnameinfo() */ #define NI_MAXHOST 1025 #define NI_MAXSERV 32 -/* +/*% * Flag values for getnameinfo() */ #define NI_NOFQDN 0x00000001 @@ -256,7 +255,7 @@ struct addrinfo { #define NI_WITHSCOPEID 0x00000020 #define NI_NUMERICSCOPE 0x00000040 -/* +/*% * Scope delimit character */ #define SCOPE_DELIMITER '%' @@ -541,12 +540,12 @@ __END_DECLS #include #else struct rpcent { - char *r_name; /* name of server for this rpc program */ - char **r_aliases; /* alias list */ - int r_number; /* rpc program number */ + char *r_name; /*%< name of server for this rpc program */ + char **r_aliases; /*%< alias list */ + int r_number; /*%< rpc program number */ }; struct rpcent *getrpcbyname(), *getrpcbynumber(), *getrpcent(); #endif /* __GNU_LIBRARY__ */ #endif /* sun */ - #endif /* !_NETDB_H_ */ +/*! \file */ diff --git a/lib/bind/include/netgroup.h b/lib/bind/include/netgroup.h index 2296208c15..e4be459fdf 100644 --- a/lib/bind/include/netgroup.h +++ b/lib/bind/include/netgroup.h @@ -22,3 +22,5 @@ int innetgr __P((const char *, const char *, const char *, const char *)); #endif #endif #endif + +/*! \file */ diff --git a/lib/bind/include/res_update.h b/lib/bind/include/res_update.h index 2c5f9adeed..d6cbabc34c 100644 --- a/lib/bind/include/res_update.h +++ b/lib/bind/include/res_update.h @@ -16,34 +16,36 @@ */ /* - * $Id: res_update.h,v 1.2 2004/03/09 06:29:53 marka Exp $ + * $Id: res_update.h,v 1.3 2005/04/27 04:56:15 sra Exp $ */ #ifndef __RES_UPDATE_H #define __RES_UPDATE_H +/*! \file */ + #include #include #include #include -/* +/*% * This RR-like structure is particular to UPDATE. */ struct ns_updrec { LINK(struct ns_updrec) r_link, r_glink; - ns_sect r_section; /* ZONE/PREREQUISITE/UPDATE */ - char * r_dname; /* owner of the RR */ - ns_class r_class; /* class number */ - ns_type r_type; /* type number */ - u_int32_t r_ttl; /* time to live */ - u_char * r_data; /* rdata fields as text string */ - u_int r_size; /* size of r_data field */ - int r_opcode; /* type of operation */ + ns_sect r_section; /*%< ZONE/PREREQUISITE/UPDATE */ + char * r_dname; /*%< owner of the RR */ + ns_class r_class; /*%< class number */ + ns_type r_type; /*%< type number */ + u_int32_t r_ttl; /*%< time to live */ + u_char * r_data; /*%< rdata fields as text string */ + u_int r_size; /*%< size of r_data field */ + int r_opcode; /*%< type of operation */ /* following fields for private use by the resolver/server routines */ - struct databuf *r_dp; /* databuf to process */ - struct databuf *r_deldp; /* databuf's deleted/overwritten */ - u_int r_zone; /* zone number on server */ + struct databuf *r_dp; /*%< databuf to process */ + struct databuf *r_deldp; /*%< databuf's deleted/overwritten */ + u_int r_zone; /*%< zone number on server */ }; typedef struct ns_updrec ns_updrec; typedef LIST(ns_updrec) ns_updque; @@ -63,3 +65,5 @@ int res_nmkupdate __P((res_state, ns_updrec *, u_char *, int)); int res_nupdate __P((res_state, ns_updrec *, ns_tsig_key *)); #endif /*__RES_UPDATE_H*/ + +/*! \file */ diff --git a/lib/bind/include/resolv.h b/lib/bind/include/resolv.h index c28bd789fc..483fe10ca2 100644 --- a/lib/bind/include/resolv.h +++ b/lib/bind/include/resolv.h @@ -48,9 +48,9 @@ * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* +/*% * @(#)resolv.h 8.1 (Berkeley) 6/2/93 - * $Id: resolv.h,v 1.20 2004/06/25 00:39:54 marka Exp $ + * $Id: resolv.h,v 1.21 2005/04/27 04:56:16 sra Exp $ */ #ifndef _RESOLV_H_ @@ -67,7 +67,7 @@ #include #include -/* +/*% * Revision information. This is the release date in YYYYMMDD format. * It can change every day so the right thing to do with it is use it * in preprocessor commands such as "#if (__RES > 19931104)". Do not @@ -77,7 +77,7 @@ #define __RES 20030124 -/* +/*% * This used to be defined in res_query.c, now it's in herror.c. * [XXX no it's not. It's in irs/irs_data.c] * It was @@ -97,12 +97,12 @@ */ #define RES_SET_H_ERRNO(r,x) __h_errno_set(r,x) -struct __res_state; /* forward */ +struct __res_state; /*%< forward */ __BEGIN_DECLS void __h_errno_set(struct __res_state *res, int err); __END_DECLS -/* +/*% * Resolver configuration file. * Normally not present, but may contain the address of the * initial name server(s) to query and the domain search list. @@ -132,70 +132,68 @@ typedef res_sendhookact (*res_send_rhook)__PMT((const struct sockaddr *, int, int *)); struct res_sym { - int number; /* Identifying number, like T_MX */ - const char * name; /* Its symbolic name, like "MX" */ - const char * humanname; /* Its fun name, like "mail exchanger" */ + int number; /*%< Identifying number, like T_MX */ + const char * name; /*%< Its symbolic name, like "MX" */ + const char * humanname; /*%< Its fun name, like "mail exchanger" */ }; -/* +/*% * Global defines and variables for resolver stub. */ -#define MAXNS 3 /* max # name servers we'll track */ -#define MAXDFLSRCH 3 /* # default domain levels to try */ -#define MAXDNSRCH 6 /* max # domains in search path */ -#define LOCALDOMAINPARTS 2 /* min levels in name that is "local" */ - -#define RES_TIMEOUT 5 /* min. seconds between retries */ -#define MAXRESOLVSORT 10 /* number of net to sort on */ -#define RES_MAXNDOTS 15 /* should reflect bit field size */ -#define RES_MAXRETRANS 30 /* only for resolv.conf/RES_OPTIONS */ -#define RES_MAXRETRY 5 /* only for resolv.conf/RES_OPTIONS */ -#define RES_DFLRETRY 2 /* Default #/tries. */ -#define RES_MAXTIME 65535 /* Infinity, in milliseconds. */ - +#define MAXNS 3 /*%< max # name servers we'll track */ +#define MAXDFLSRCH 3 /*%< # default domain levels to try */ +#define MAXDNSRCH 6 /*%< max # domains in search path */ +#define LOCALDOMAINPARTS 2 /*%< min levels in name that is "local" */ +#define RES_TIMEOUT 5 /*%< min. seconds between retries */ +#define MAXRESOLVSORT 10 /*%< number of net to sort on */ +#define RES_MAXNDOTS 15 /*%< should reflect bit field size */ +#define RES_MAXRETRANS 30 /*%< only for resolv.conf/RES_OPTIONS */ +#define RES_MAXRETRY 5 /*%< only for resolv.conf/RES_OPTIONS */ +#define RES_DFLRETRY 2 /*%< Default #/tries. */ +#define RES_MAXTIME 65535 /*%< Infinity, in milliseconds. */ struct __res_state_ext; struct __res_state { - int retrans; /* retransmission time interval */ - int retry; /* number of times to retransmit */ + int retrans; /*%< retransmission time interval */ + int retry; /*%< number of times to retransmit */ #ifdef sun - u_int options; /* option flags - see below. */ + u_int options; /*%< option flags - see below. */ #else - u_long options; /* option flags - see below. */ + u_long options; /*%< option flags - see below. */ #endif - int nscount; /* number of name servers */ + int nscount; /*%< number of name servers */ struct sockaddr_in - nsaddr_list[MAXNS]; /* address of name server */ -#define nsaddr nsaddr_list[0] /* for backward compatibility */ - u_short id; /* current message id */ - char *dnsrch[MAXDNSRCH+1]; /* components of domain to search */ - char defdname[256]; /* default domain (deprecated) */ + nsaddr_list[MAXNS]; /*%< address of name server */ +#define nsaddr nsaddr_list[0] /*%< for backward compatibility */ + u_short id; /*%< current message id */ + char *dnsrch[MAXDNSRCH+1]; /*%< components of domain to search */ + char defdname[256]; /*%< default domain (deprecated) */ #ifdef sun - u_int pfcode; /* RES_PRF_ flags - see below. */ + u_int pfcode; /*%< RES_PRF_ flags - see below. */ #else - u_long pfcode; /* RES_PRF_ flags - see below. */ + u_long pfcode; /*%< RES_PRF_ flags - see below. */ #endif - unsigned ndots:4; /* threshold for initial abs. query */ - unsigned nsort:4; /* number of elements in sort_list[] */ + unsigned ndots:4; /*%< threshold for initial abs. query */ + unsigned nsort:4; /*%< number of elements in sort_list[] */ char unused[3]; struct { struct in_addr addr; u_int32_t mask; } sort_list[MAXRESOLVSORT]; - res_send_qhook qhook; /* query hook */ - res_send_rhook rhook; /* response hook */ - int res_h_errno; /* last one set for this context */ - int _vcsock; /* PRIVATE: for res_send VC i/o */ - u_int _flags; /* PRIVATE: see below */ - u_int _pad; /* make _u 64 bit aligned */ + res_send_qhook qhook; /*%< query hook */ + res_send_rhook rhook; /*%< response hook */ + int res_h_errno; /*%< last one set for this context */ + int _vcsock; /*%< PRIVATE: for res_send VC i/o */ + u_int _flags; /*%< PRIVATE: see below */ + u_int _pad; /*%< make _u 64 bit aligned */ union { /* On an 32-bit arch this means 512b total. */ char pad[72 - 4*sizeof (int) - 2*sizeof (void *)]; struct { u_int16_t nscount; - u_int16_t nstimes[MAXNS]; /* ms. */ + u_int16_t nstimes[MAXNS]; /*%< ms. */ int nssocks[MAXNS]; - struct __res_state_ext *ext; /* extention for IPv6 */ + struct __res_state_ext *ext; /*%< extention for IPv6 */ } _ext; } _u; }; @@ -208,62 +206,62 @@ union res_sockaddr_union { struct sockaddr_in6 sin6; #endif #ifdef ISC_ALIGN64 - int64_t __align64; /* 64bit alignment */ + int64_t __align64; /*%< 64bit alignment */ #else - int32_t __align32; /* 32bit alignment */ + int32_t __align32; /*%< 32bit alignment */ #endif - char __space[128]; /* max size */ + char __space[128]; /*%< max size */ }; -/* +/*% * Resolver flags (used to be discrete per-module statics ints). */ -#define RES_F_VC 0x00000001 /* socket is TCP */ -#define RES_F_CONN 0x00000002 /* socket is connected */ -#define RES_F_EDNS0ERR 0x00000004 /* EDNS0 caused errors */ -#define RES_F__UNUSED 0x00000008 /* (unused) */ -#define RES_F_LASTMASK 0x000000F0 /* ordinal server of last res_nsend */ -#define RES_F_LASTSHIFT 4 /* bit position of LASTMASK "flag" */ +#define RES_F_VC 0x00000001 /*%< socket is TCP */ +#define RES_F_CONN 0x00000002 /*%< socket is connected */ +#define RES_F_EDNS0ERR 0x00000004 /*%< EDNS0 caused errors */ +#define RES_F__UNUSED 0x00000008 /*%< (unused) */ +#define RES_F_LASTMASK 0x000000F0 /*%< ordinal server of last res_nsend */ +#define RES_F_LASTSHIFT 4 /*%< bit position of LASTMASK "flag" */ #define RES_GETLAST(res) (((res)._flags & RES_F_LASTMASK) >> RES_F_LASTSHIFT) /* res_findzonecut2() options */ -#define RES_EXHAUSTIVE 0x00000001 /* always do all queries */ -#define RES_IPV4ONLY 0x00000002 /* IPv4 only */ -#define RES_IPV6ONLY 0x00000004 /* IPv6 only */ +#define RES_EXHAUSTIVE 0x00000001 /*%< always do all queries */ +#define RES_IPV4ONLY 0x00000002 /*%< IPv4 only */ +#define RES_IPV6ONLY 0x00000004 /*%< IPv6 only */ /* * Resolver options (keep these in synch with res_debug.c, please) */ -#define RES_INIT 0x00000001 /* address initialized */ -#define RES_DEBUG 0x00000002 /* print debug messages */ -#define RES_AAONLY 0x00000004 /* authoritative answers only (!IMPL)*/ -#define RES_USEVC 0x00000008 /* use virtual circuit */ -#define RES_PRIMARY 0x00000010 /* query primary server only (!IMPL) */ -#define RES_IGNTC 0x00000020 /* ignore trucation errors */ -#define RES_RECURSE 0x00000040 /* recursion desired */ -#define RES_DEFNAMES 0x00000080 /* use default domain name */ -#define RES_STAYOPEN 0x00000100 /* Keep TCP socket open */ -#define RES_DNSRCH 0x00000200 /* search up local domain tree */ -#define RES_INSECURE1 0x00000400 /* type 1 security disabled */ -#define RES_INSECURE2 0x00000800 /* type 2 security disabled */ -#define RES_NOALIASES 0x00001000 /* shuts off HOSTALIASES feature */ -#define RES_USE_INET6 0x00002000 /* use/map IPv6 in gethostbyname() */ -#define RES_ROTATE 0x00004000 /* rotate ns list after each query */ -#define RES_NOCHECKNAME 0x00008000 /* do not check names for sanity. */ -#define RES_KEEPTSIG 0x00010000 /* do not strip TSIG records */ -#define RES_BLAST 0x00020000 /* blast all recursive servers */ -#define RES_NOTLDQUERY 0x00100000 /* don't unqualified name as a tld */ -#define RES_USE_DNSSEC 0x00200000 /* use DNSSEC using OK bit in OPT */ +#define RES_INIT 0x00000001 /*%< address initialized */ +#define RES_DEBUG 0x00000002 /*%< print debug messages */ +#define RES_AAONLY 0x00000004 /*%< authoritative answers only (!IMPL)*/ +#define RES_USEVC 0x00000008 /*%< use virtual circuit */ +#define RES_PRIMARY 0x00000010 /*%< query primary server only (!IMPL) */ +#define RES_IGNTC 0x00000020 /*%< ignore trucation errors */ +#define RES_RECURSE 0x00000040 /*%< recursion desired */ +#define RES_DEFNAMES 0x00000080 /*%< use default domain name */ +#define RES_STAYOPEN 0x00000100 /*%< Keep TCP socket open */ +#define RES_DNSRCH 0x00000200 /*%< search up local domain tree */ +#define RES_INSECURE1 0x00000400 /*%< type 1 security disabled */ +#define RES_INSECURE2 0x00000800 /*%< type 2 security disabled */ +#define RES_NOALIASES 0x00001000 /*%< shuts off HOSTALIASES feature */ +#define RES_USE_INET6 0x00002000 /*%< use/map IPv6 in gethostbyname() */ +#define RES_ROTATE 0x00004000 /*%< rotate ns list after each query */ +#define RES_NOCHECKNAME 0x00008000 /*%< do not check names for sanity. */ +#define RES_KEEPTSIG 0x00010000 /*%< do not strip TSIG records */ +#define RES_BLAST 0x00020000 /*%< blast all recursive servers */ +#define RES_NOTLDQUERY 0x00100000 /*%< don't unqualified name as a tld */ +#define RES_USE_DNSSEC 0x00200000 /*%< use DNSSEC using OK bit in OPT */ /* #define RES_DEBUG2 0x00400000 */ /* nslookup internal */ /* KAME extensions: use higher bit to avoid conflict with ISC use */ -#define RES_USE_DNAME 0x10000000 /* use DNAME */ -#define RES_USE_EDNS0 0x40000000 /* use EDNS0 if configured */ -#define RES_NO_NIBBLE2 0x80000000 /* disable alternate nibble lookup */ +#define RES_USE_DNAME 0x10000000 /*%< use DNAME */ +#define RES_USE_EDNS0 0x40000000 /*%< use EDNS0 if configured */ +#define RES_NO_NIBBLE2 0x80000000 /*%< disable alternate nibble lookup */ #define RES_DEFAULT (RES_RECURSE | RES_DEFNAMES | \ RES_DNSRCH | RES_NO_NIBBLE2) -/* +/*% * Resolver "pfcode" values. Used by dig. */ #define RES_PRF_STATS 0x00000001 @@ -499,3 +497,4 @@ int res_getservers __P((res_state, __END_DECLS #endif /* !_RESOLV_H_ */ +/*! \file */ diff --git a/lib/bind/inet/inet_addr.c b/lib/bind/inet/inet_addr.c index a821b19a8b..56270ffa3a 100644 --- a/lib/bind/inet/inet_addr.c +++ b/lib/bind/inet/inet_addr.c @@ -70,7 +70,7 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)inet_addr.c 8.1 (Berkeley) 6/17/93"; -static const char rcsid[] = "$Id: inet_addr.c,v 1.4 2004/03/18 02:57:56 marka Exp $"; +static const char rcsid[] = "$Id: inet_addr.c,v 1.5 2005/04/27 04:56:19 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -85,7 +85,7 @@ static const char rcsid[] = "$Id: inet_addr.c,v 1.4 2004/03/18 02:57:56 marka Ex #include "port_after.h" -/* +/*% * Ascii internet address interpretation routine. * The value returned is in network order. */ @@ -98,7 +98,7 @@ inet_addr(const char *cp) { return (INADDR_NONE); } -/* +/*% * Check whether "cp" is a valid ascii representation * of an Internet address and convert to a binary address. * Returns 1 if the address is valid, 0 if not. @@ -179,22 +179,22 @@ inet_aton(const char *cp, struct in_addr *addr) { */ n = pp - parts + 1; switch (n) { - case 1: /* a -- 32 bits */ + case 1: /*%< a -- 32 bits */ break; - case 2: /* a.b -- 8.24 bits */ + case 2: /*%< a.b -- 8.24 bits */ if (val > 0xffffffU) return (0); val |= parts[0] << 24; break; - case 3: /* a.b.c -- 8.8.16 bits */ + case 3: /*%< a.b.c -- 8.8.16 bits */ if (val > 0xffffU) return (0); val |= (parts[0] << 24) | (parts[1] << 16); break; - case 4: /* a.b.c.d -- 8.8.8.8 bits */ + case 4: /*%< a.b.c.d -- 8.8.8.8 bits */ if (val > 0xffU) return (0); val |= (parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8); @@ -204,3 +204,5 @@ inet_aton(const char *cp, struct in_addr *addr) { addr->s_addr = htonl(val); return (1); } + +/*! \file */ diff --git a/lib/bind/inet/inet_cidr_ntop.c b/lib/bind/inet/inet_cidr_ntop.c index 48685393ce..454204a464 100644 --- a/lib/bind/inet/inet_cidr_ntop.c +++ b/lib/bind/inet/inet_cidr_ntop.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: inet_cidr_ntop.c,v 1.4 2004/03/18 02:57:56 marka Exp $"; +static const char rcsid[] = "$Id: inet_cidr_ntop.c,v 1.5 2005/04/27 04:56:19 sra Exp $"; #endif #include "port_before.h" @@ -45,7 +45,7 @@ static char * inet_cidr_ntop_ipv4 __P((const u_char *src, int bits, static char * inet_cidr_ntop_ipv6 __P((const u_char *src, int bits, char *dst, size_t size)); -/* +/*% * char * * inet_cidr_ntop(af, src, bits, dst, size) * convert network address from network to presentation format. @@ -92,7 +92,7 @@ decoct(const u_char *src, int bytes, char *dst, size_t size) { return (dst - odst); } -/* +/*% * static char * * inet_cidr_ntop_ipv4(src, bits, dst, size) * convert IPv4 network address from network to presentation format. @@ -257,3 +257,5 @@ inet_cidr_ntop_ipv6(const u_char *src, int bits, char *dst, size_t size) { strcpy(dst, tmp); return (dst); } + +/*! \file */ diff --git a/lib/bind/inet/inet_cidr_pton.c b/lib/bind/inet/inet_cidr_pton.c index 0eec171399..07652af463 100644 --- a/lib/bind/inet/inet_cidr_pton.c +++ b/lib/bind/inet/inet_cidr_pton.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: inet_cidr_pton.c,v 1.5 2004/03/18 02:57:57 marka Exp $"; +static const char rcsid[] = "$Id: inet_cidr_pton.c,v 1.6 2005/04/27 04:56:19 sra Exp $"; #endif #include "port_before.h" @@ -49,7 +49,7 @@ static int inet_cidr_pton_ipv6 __P((const char *src, u_char *dst, static int getbits(const char *, int ipv6); -/* +/*% * int * inet_cidr_pton(af, src, dst, *bits) * convert network address from presentation to network format. @@ -204,7 +204,7 @@ inet_cidr_pton_ipv6(const char *src, u_char *dst, int *pbits) { inet_cidr_pton_ipv4(curtok, tp, &bits, 1) == 0) { tp += NS_INADDRSZ; saw_xdigit = 0; - break; /* '\0' was seen by inet_pton4(). */ + break; /*%< '\\0' was seen by inet_pton4(). */ } if (ch == '/') { bits = getbits(src, 1); @@ -256,20 +256,22 @@ getbits(const char *src, int ipv6) { int bits = 0; char *cp, ch; - if (*src == '\0') /* syntax */ + if (*src == '\0') /*%< syntax */ return (-2); do { ch = *src++; cp = strchr(digits, ch); - if (cp == NULL) /* syntax */ + if (cp == NULL) /*%< syntax */ return (-2); bits *= 10; bits += cp - digits; - if (bits == 0 && *src != '\0') /* no leading zeros */ + if (bits == 0 && *src != '\0') /*%< no leading zeros */ return (-2); - if (bits > (ipv6 ? 128 : 32)) /* range error */ + if (bits > (ipv6 ? 128 : 32)) /*%< range error */ return (-2); } while (*src != '\0'); return (bits); } + +/*! \file */ diff --git a/lib/bind/inet/inet_data.c b/lib/bind/inet/inet_data.c index 96a4eebc07..4373a171a0 100644 --- a/lib/bind/inet/inet_data.c +++ b/lib/bind/inet/inet_data.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static char rcsid[] = "$Id: inet_data.c,v 1.3 2004/03/09 06:29:57 marka Exp $"; +static char rcsid[] = "$Id: inet_data.c,v 1.4 2005/04/27 04:56:19 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -42,3 +42,5 @@ static char rcsid[] = "$Id: inet_data.c,v 1.3 2004/03/09 06:29:57 marka Exp $"; const struct in6_addr isc_in6addr_any = IN6ADDR_ANY_INIT; const struct in6_addr isc_in6addr_loopback = IN6ADDR_LOOPBACK_INIT; + +/*! \file */ diff --git a/lib/bind/inet/inet_lnaof.c b/lib/bind/inet/inet_lnaof.c index 97b80cffdb..70ac409512 100644 --- a/lib/bind/inet/inet_lnaof.c +++ b/lib/bind/inet/inet_lnaof.c @@ -43,7 +43,7 @@ static const char sccsid[] = "@(#)inet_lnaof.c 8.1 (Berkeley) 6/4/93"; #include "port_after.h" -/* +/*% * Return the local network address portion of an * internet address; handles class a/b/c network * number formats. @@ -61,3 +61,5 @@ inet_lnaof(in) else return ((i)&IN_CLASSC_HOST); } + +/*! \file */ diff --git a/lib/bind/inet/inet_makeaddr.c b/lib/bind/inet/inet_makeaddr.c index 6e4ecc37cc..c56cb3eaeb 100644 --- a/lib/bind/inet/inet_makeaddr.c +++ b/lib/bind/inet/inet_makeaddr.c @@ -43,7 +43,7 @@ static const char sccsid[] = "@(#)inet_makeaddr.c 8.1 (Berkeley) 6/4/93"; #include "port_after.h" -/* +/*% * Formulate an Internet address from network + host. Used in * building addresses stored in the ifnet structure. */ @@ -64,3 +64,5 @@ inet_makeaddr(net, host) a.s_addr = htonl(a.s_addr); return (a); } + +/*! \file */ diff --git a/lib/bind/inet/inet_net_ntop.c b/lib/bind/inet/inet_net_ntop.c index a407349fd9..a4b81aafad 100644 --- a/lib/bind/inet/inet_net_ntop.c +++ b/lib/bind/inet/inet_net_ntop.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: inet_net_ntop.c,v 1.3 2004/03/09 06:29:57 marka Exp $"; +static const char rcsid[] = "$Id: inet_net_ntop.c,v 1.4 2005/04/27 04:56:20 sra Exp $"; #endif #include "port_before.h" @@ -44,7 +44,7 @@ static char * inet_net_ntop_ipv4 __P((const u_char *src, int bits, static char * inet_net_ntop_ipv6 __P((const u_char *src, int bits, char *dst, size_t size)); -/* +/*% * char * * inet_net_ntop(af, src, bits, dst, size) * convert network number from network to presentation format. @@ -73,7 +73,7 @@ inet_net_ntop(af, src, bits, dst, size) } } -/* +/*% * static char * * inet_net_ntop_ipv4(src, bits, dst, size) * convert IPv4 network number from network to presentation format. @@ -148,7 +148,7 @@ inet_net_ntop_ipv4(src, bits, dst, size) return (NULL); } -/* +/*% * static char * * inet_net_ntop_ipv6(src, bits, fakebits, dst, size) * convert IPv6 network number from network to presentation format. @@ -275,3 +275,5 @@ emsgsize: errno = EMSGSIZE; return (NULL); } + +/*! \file */ diff --git a/lib/bind/inet/inet_net_pton.c b/lib/bind/inet/inet_net_pton.c index 6950a01cee..154ff65275 100644 --- a/lib/bind/inet/inet_net_pton.c +++ b/lib/bind/inet/inet_net_pton.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: inet_net_pton.c,v 1.7 2004/03/18 02:57:57 marka Exp $"; +static const char rcsid[] = "$Id: inet_net_pton.c,v 1.8 2005/04/27 04:56:20 sra Exp $"; #endif #include "port_before.h" @@ -42,7 +42,7 @@ static const char rcsid[] = "$Id: inet_net_pton.c,v 1.7 2004/03/18 02:57:57 mark # define SPRINTF(x) ((size_t)sprintf x) #endif -/* +/*% * static int * inet_net_pton_ipv4(src, dst, size) * convert IPv4 network number from presentation to network format. @@ -73,7 +73,7 @@ inet_net_pton_ipv4(const char *src, u_char *dst, size_t size) { if (size <= 0U) goto emsgsize; dirty = 0; - src++; /* skip x or X. */ + src++; /*%< skip x or X. */ while ((ch = *src++) != '\0' && isascii(ch) && isxdigit(ch)) { if (isupper(ch)) ch = tolower(ch); @@ -90,7 +90,7 @@ inet_net_pton_ipv4(const char *src, u_char *dst, size_t size) { dirty = 0; } } - if (dirty) { /* Odd trailing nybble? */ + if (dirty) { /*%< Odd trailing nybble? */ if (size-- <= 0U) goto emsgsize; *dst++ = (u_char) (tmp << 4); @@ -126,7 +126,7 @@ inet_net_pton_ipv4(const char *src, u_char *dst, size_t size) { if (ch == '/' && isascii((unsigned char)(src[0])) && isdigit((unsigned char)(src[0])) && dst > odst) { /* CIDR width specifier. Nothing can follow it. */ - ch = *src++; /* Skip over the /. */ + ch = *src++; /*%< Skip over the /. */ bits = 0; do { n = strchr(digits, ch) - digits; @@ -149,15 +149,15 @@ inet_net_pton_ipv4(const char *src, u_char *dst, size_t size) { goto enoent; /* If no CIDR spec was given, infer width from net class. */ if (bits == -1) { - if (*odst >= 240) /* Class E */ + if (*odst >= 240) /*%< Class E */ bits = 32; - else if (*odst >= 224) /* Class D */ + else if (*odst >= 224) /*%< Class D */ bits = 8; - else if (*odst >= 192) /* Class C */ + else if (*odst >= 192) /*%< Class C */ bits = 24; - else if (*odst >= 128) /* Class B */ + else if (*odst >= 128) /*%< Class B */ bits = 16; - else /* Class A */ + else /*%< Class A */ bits = 8; /* If imputed mask is narrower than specified octets, widen. */ if (bits < ((dst - odst) * 8)) @@ -200,11 +200,11 @@ getbits(const char *src, int *bitsp) { pch = strchr(digits, ch); if (pch != NULL) { - if (n++ != 0 && val == 0) /* no leading zeros */ + if (n++ != 0 && val == 0) /*%< no leading zeros */ return (0); val *= 10; val += (pch - digits); - if (val > 128) /* range */ + if (val > 128) /*%< range */ return (0); continue; } @@ -231,16 +231,16 @@ getv4(const char *src, u_char *dst, int *bitsp) { pch = strchr(digits, ch); if (pch != NULL) { - if (n++ != 0 && val == 0) /* no leading zeros */ + if (n++ != 0 && val == 0) /*%< no leading zeros */ return (0); val *= 10; val += (pch - digits); - if (val > 255) /* range */ + if (val > 255) /*%< range */ return (0); continue; } if (ch == '.' || ch == '/') { - if (dst - odst > 3) /* too many octets? */ + if (dst - odst > 3) /*%< too many octets? */ return (0); *dst++ = val; if (ch == '/') @@ -253,7 +253,7 @@ getv4(const char *src, u_char *dst, int *bitsp) { } if (n == 0) return (0); - if (dst - odst > 3) /* too many octets? */ + if (dst - odst > 3) /*%< too many octets? */ return (0); *dst++ = val; return (1); @@ -322,7 +322,7 @@ inet_net_pton_ipv6(const char *src, u_char *dst, size_t size) { tp += NS_INADDRSZ; saw_xdigit = 0; ipv4 = 1; - break; /* '\0' was seen by inet_pton4(). */ + break; /*%< '\\0' was seen by inet_pton4(). */ } if (ch == '/' && getbits(src, &bits) > 0) break; @@ -378,7 +378,7 @@ inet_net_pton_ipv6(const char *src, u_char *dst, size_t size) { return (-1); } -/* +/*% * int * inet_net_pton(af, src, dst, size) * convert network number from presentation to network format. @@ -403,3 +403,5 @@ inet_net_pton(int af, const char *src, void *dst, size_t size) { return (-1); } } + +/*! \file */ diff --git a/lib/bind/inet/inet_neta.c b/lib/bind/inet/inet_neta.c index 8cb3ddc9db..63a6c201a4 100644 --- a/lib/bind/inet/inet_neta.c +++ b/lib/bind/inet/inet_neta.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: inet_neta.c,v 1.2 2004/03/09 06:29:57 marka Exp $"; +static const char rcsid[] = "$Id: inet_neta.c,v 1.3 2005/04/27 04:56:20 sra Exp $"; #endif #include "port_before.h" @@ -38,7 +38,7 @@ static const char rcsid[] = "$Id: inet_neta.c,v 1.2 2004/03/09 06:29:57 marka Ex # define SPRINTF(x) ((size_t)sprintf x) #endif -/* +/*% * char * * inet_neta(src, dst, size) * format a u_long network number into presentation format. @@ -85,3 +85,5 @@ inet_neta(src, dst, size) errno = EMSGSIZE; return (NULL); } + +/*! \file */ diff --git a/lib/bind/inet/inet_netof.c b/lib/bind/inet/inet_netof.c index e887530088..c228e3d818 100644 --- a/lib/bind/inet/inet_netof.c +++ b/lib/bind/inet/inet_netof.c @@ -43,7 +43,7 @@ static const char sccsid[] = "@(#)inet_netof.c 8.1 (Berkeley) 6/4/93"; #include "port_after.h" -/* +/*% * Return the network number from an internet * address; handles class a/b/c network #'s. */ @@ -60,3 +60,5 @@ inet_netof(in) else return (((i)&IN_CLASSC_NET) >> IN_CLASSC_NSHIFT); } + +/*! \file */ diff --git a/lib/bind/inet/inet_network.c b/lib/bind/inet/inet_network.c index aaa50c8315..4758a00f26 100644 --- a/lib/bind/inet/inet_network.c +++ b/lib/bind/inet/inet_network.c @@ -44,7 +44,7 @@ static const char sccsid[] = "@(#)inet_network.c 8.1 (Berkeley) 6/4/93"; #include "port_after.h" -/* +/*% * Internet network address interpretation routine. * The library routines call this routine to interpret * network numbers. @@ -102,3 +102,5 @@ again: } return (val); } + +/*! \file */ diff --git a/lib/bind/inet/inet_ntoa.c b/lib/bind/inet/inet_ntoa.c index 7fad4b8902..983121e89d 100644 --- a/lib/bind/inet/inet_ntoa.c +++ b/lib/bind/inet/inet_ntoa.c @@ -33,7 +33,7 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)inet_ntoa.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: inet_ntoa.c,v 1.1 2001/03/29 06:31:38 marka Exp $"; +static const char rcsid[] = "$Id: inet_ntoa.c,v 1.2 2005/04/27 04:56:21 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -48,7 +48,7 @@ static const char rcsid[] = "$Id: inet_ntoa.c,v 1.1 2001/03/29 06:31:38 marka Ex #include "port_after.h" -/* +/*% * Convert network-format internet address * to base 256 d.d.d.d representation. */ @@ -60,3 +60,5 @@ inet_ntoa(struct in_addr in) { (void) inet_ntop(AF_INET, &in, ret, sizeof ret); return (ret); } + +/*! \file */ diff --git a/lib/bind/inet/inet_ntop.c b/lib/bind/inet/inet_ntop.c index e00b863398..5063fced1d 100644 --- a/lib/bind/inet/inet_ntop.c +++ b/lib/bind/inet/inet_ntop.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: inet_ntop.c,v 1.3 2004/03/09 06:29:58 marka Exp $"; +static const char rcsid[] = "$Id: inet_ntop.c,v 1.4 2005/04/27 04:56:21 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -41,7 +41,7 @@ static const char rcsid[] = "$Id: inet_ntop.c,v 1.3 2004/03/09 06:29:58 marka Ex # define SPRINTF(x) ((size_t)sprintf x) #endif -/* +/*% * WARNING: Don't even consider trying to compile this on a system where * sizeof(int) < 4. sizeof(int) > 4 is fine; all the world's not a VAX. */ @@ -201,3 +201,5 @@ inet_ntop6(src, dst, size) strcpy(dst, tmp); return (dst); } + +/*! \file */ diff --git a/lib/bind/inet/inet_pton.c b/lib/bind/inet/inet_pton.c index 17a58b5146..5f654ae635 100644 --- a/lib/bind/inet/inet_pton.c +++ b/lib/bind/inet/inet_pton.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: inet_pton.c,v 1.3 2004/03/09 06:29:58 marka Exp $"; +static const char rcsid[] = "$Id: inet_pton.c,v 1.4 2005/04/27 04:56:21 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -30,7 +30,7 @@ static const char rcsid[] = "$Id: inet_pton.c,v 1.3 2004/03/09 06:29:58 marka Ex #include #include "port_after.h" -/* +/*% * WARNING: Don't even consider trying to compile this on a system where * sizeof(int) < 4. sizeof(int) > 4 is fine; all the world's not a VAX. */ @@ -189,7 +189,7 @@ inet_pton6(src, dst) inet_pton4(curtok, tp) > 0) { tp += NS_INADDRSZ; saw_xdigit = 0; - break; /* '\0' was seen by inet_pton4(). */ + break; /*%< '\\0' was seen by inet_pton4(). */ } return (0); } @@ -220,3 +220,5 @@ inet_pton6(src, dst) memcpy(dst, tmp, NS_IN6ADDRSZ); return (1); } + +/*! \file */ diff --git a/lib/bind/inet/nsap_addr.c b/lib/bind/inet/nsap_addr.c index a89fa442cd..e2c2ccf9a5 100644 --- a/lib/bind/inet/nsap_addr.c +++ b/lib/bind/inet/nsap_addr.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nsap_addr.c,v 1.3 2004/03/09 06:29:58 marka Exp $"; +static const char rcsid[] = "$Id: nsap_addr.c,v 1.4 2005/04/27 04:56:21 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -106,3 +106,5 @@ inet_nsap_ntoa(int binlen, const u_char *binary, char *ascii) { *ascii = '\0'; return (start); } + +/*! \file */ diff --git a/lib/bind/irs/dns.c b/lib/bind/irs/dns.c index a04fcf8ba2..d2d3373861 100644 --- a/lib/bind/irs/dns.c +++ b/lib/bind/irs/dns.c @@ -16,10 +16,11 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: dns.c,v 1.3 2004/03/18 02:57:58 marka Exp $"; +static const char rcsid[] = "$Id: dns.c,v 1.4 2005/04/27 04:56:21 sra Exp $"; #endif -/* +/*! \file + * \brief * dns.c --- this is the top-level accessor function for the dns */ diff --git a/lib/bind/irs/dns_gr.c b/lib/bind/irs/dns_gr.c index 8d43e9648e..629d2fb173 100644 --- a/lib/bind/irs/dns_gr.c +++ b/lib/bind/irs/dns_gr.c @@ -16,10 +16,11 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: dns_gr.c,v 1.3 2004/03/09 06:29:59 marka Exp $"; +static const char rcsid[] = "$Id: dns_gr.c,v 1.4 2005/04/27 04:56:21 sra Exp $"; #endif -/* +/*! \file + * \brief * dns_gr.c --- this file contains the functions for accessing * group information from Hesiod. */ @@ -69,7 +70,7 @@ struct pvt { * we keep one buffer and resize it as needed. */ struct group group; - size_t nmemb; /* Malloc'd max index of gr_mem[]. */ + size_t nmemb; /*%< Malloc'd max index of gr_mem[]. */ char * membuf; size_t membufsize; }; diff --git a/lib/bind/irs/dns_ho.c b/lib/bind/irs/dns_ho.c index 2e19f1a927..1efd6b8240 100644 --- a/lib/bind/irs/dns_ho.c +++ b/lib/bind/irs/dns_ho.c @@ -52,7 +52,7 @@ /* BIND Id: gethnamaddr.c,v 8.15 1996/05/22 04:56:30 vixie Exp $ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: dns_ho.c,v 1.16 2004/08/24 00:33:35 marka Exp $"; +static const char rcsid[] = "$Id: dns_ho.c,v 1.17 2005/04/27 04:56:21 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports. */ @@ -95,8 +95,7 @@ static const char rcsid[] = "$Id: dns_ho.c,v 1.16 2004/08/24 00:33:35 marka Exp #define MAXALIASES 35 #define MAXADDRS 35 -#define MAXPACKET (65535) /* Maximum TCP message size */ - +#define MAXPACKET (65535) /*%< Maximum TCP message size */ #define BOUNDS_CHECK(ptr, count) \ if ((ptr) + (count) > eom) { \ had_error++; \ @@ -110,14 +109,14 @@ typedef union { struct dns_res_target { struct dns_res_target *next; - querybuf qbuf; /* query buffer */ - u_char *answer; /* buffer to put answer */ - int anslen; /* size of answer buffer */ - int qclass, qtype; /* class and type of query */ - int action; /* condition whether query is really issued */ - char qname[MAXDNAME +1]; /* domain name */ + querybuf qbuf; /*%< query buffer */ + u_char *answer; /*%< buffer to put answer */ + int anslen; /*%< size of answer buffer */ + int qclass, qtype; /*%< class and type of query */ + int action; /*%< condition whether query is really issued */ + char qname[MAXDNAME +1]; /*%< domain name */ #if 0 - int n; /* result length */ + int n; /*%< result length */ #endif }; enum {RESTGT_DOALWAYS, RESTGT_AFTERFAILURE, RESTGT_IGNORE}; @@ -128,7 +127,7 @@ struct pvt { char * h_addr_ptrs[MAXADDRS + 1]; char * host_aliases[MAXALIASES]; char hostbuf[8*1024]; - u_char host_addr[16]; /* IPv4 or IPv6 */ + u_char host_addr[16]; /*%< IPv4 or IPv6 */ struct __res_state *res; void (*free_res)(void *); }; @@ -141,8 +140,7 @@ typedef union { static const u_char mapped[] = { 0,0, 0,0, 0,0, 0,0, 0,0, 0xff,0xff }; static const u_char tunnelled[] = { 0,0, 0,0, 0,0, 0,0, 0,0, 0,0 }; /* Note: the IPv6 loopback address is in the "tunnel" space */ -static const u_char v6local[] = { 0,0, 0,1 }; /* last 4 bytes of IPv6 addr */ - +static const u_char v6local[] = { 0,0, 0,1 }; /*%< last 4 bytes of IPv6 addr */ /* Forwards. */ static void ho_close(struct irs_ho *this); @@ -318,8 +316,7 @@ ho_byname2(struct irs_ho *this, const char *name, int af) if ((hp = gethostans(this, p->answer, n, name, p->qtype, af, size, NULL, (const struct addrinfo *)&ai)) != NULL) - goto cleanup; /* no more loop is necessary */ - + goto cleanup; /*%< no more loop is necessary */ querystate = RESQRY_FAIL; continue; } @@ -496,10 +493,9 @@ ho_byaddr(struct irs_ho *this, const void *addr, int len, int af) } RES_SET_H_ERRNO(pvt->res, NETDB_SUCCESS); - goto cleanup; /* no more loop is necessary. */ + goto cleanup; /*%< no more loop is necessary. */ } - hp = NULL; /* H_ERRNO was set by subroutines */ - + hp = NULL; /*%< H_ERRNO was set by subroutines */ cleanup: if (q != NULL) memput(q, sizeof(*q)); @@ -611,7 +607,7 @@ ho_addrinfo(struct irs_ho *this, const char *name, const struct addrinfo *pai) q->action = RESTGT_DOALWAYS; break; default: - RES_SET_H_ERRNO(pvt->res, NO_RECOVERY); /* better error? */ + RES_SET_H_ERRNO(pvt->res, NO_RECOVERY); /*%< better error? */ goto cleanup; } @@ -644,7 +640,7 @@ ho_addrinfo(struct irs_ho *this, const char *name, const struct addrinfo *pai) continue; } (void)gethostans(this, p->answer, n, name, p->qtype, - pai->ai_family, /* XXX: meaningless */ + pai->ai_family, /*%< XXX: meaningless */ 0, &ai, pai); if (ai) { querystate = RESQRY_SUCCESS; @@ -683,7 +679,7 @@ ho_res_set(struct irs_ho *this, struct __res_state *res, static struct hostent * gethostans(struct irs_ho *this, const u_char *ansbuf, int anslen, const char *qname, int qtype, - int af, int size, /* meaningless for addrinfo cases */ + int af, int size, /*!< meaningless for addrinfo cases */ struct addrinfo **ret_aip, const struct addrinfo *pai) { struct pvt *pvt = (struct pvt *)this->private; @@ -711,7 +707,7 @@ gethostans(struct irs_ho *this, switch (qtype) { case T_A: case T_AAAA: - case T_ANY: /* use T_ANY only for T_A/T_AAAA lookup */ + case T_ANY: /*%< use T_ANY only for T_A/T_AAAA lookup */ name_ok = res_hnok; break; case T_PTR: @@ -758,7 +754,7 @@ gethostans(struct irs_ho *this, * same as the one we sent; this just gets the expanded name * (i.e., with the succeeding search-domain tacked on). */ - n = strlen(bp) + 1; /* for the \0 */ + n = strlen(bp) + 1; /*%< for the \\0 */ if (n > MAXHOSTNAMELEN) { RES_SET_H_ERRNO(pvt->res, NO_RECOVERY); return (NULL); @@ -783,14 +779,14 @@ gethostans(struct irs_ho *this, had_error++; continue; } - cp += n; /* name */ + cp += n; /*%< name */ BOUNDS_CHECK(cp, 3 * INT16SZ + INT32SZ); type = ns_get16(cp); - cp += INT16SZ; /* type */ + cp += INT16SZ; /*%< type */ class = ns_get16(cp); - cp += INT16SZ + INT32SZ; /* class, TTL */ + cp += INT16SZ + INT32SZ; /*%< class, TTL */ n = ns_get16(cp); - cp += INT16SZ; /* len */ + cp += INT16SZ; /*%< len */ BOUNDS_CHECK(cp, n); if (class != C_IN) { cp += n; @@ -818,10 +814,10 @@ gethostans(struct irs_ho *this, if (ap >= &pvt->host_aliases[MAXALIASES-1]) continue; *ap++ = bp; - n = strlen(bp) + 1; /* for the \0 */ + n = strlen(bp) + 1; /*%< for the \\0 */ bp += n; /* Get canonical name. */ - n = strlen(tbuf) + 1; /* for the \0 */ + n = strlen(tbuf) + 1; /*%< for the \\0 */ if (n > (ep - bp) || n > MAXHOSTNAMELEN) { had_error++; continue; @@ -853,7 +849,7 @@ gethostans(struct irs_ho *this, continue; } /* Get canonical name. */ - n = strlen(tbuf) + 1; /* for the \0 */ + n = strlen(tbuf) + 1; /*%< for the \\0 */ if (n > (ep - bp)) { had_error++; continue; @@ -899,7 +895,7 @@ gethostans(struct irs_ho *this, else n = -1; if (n != -1) { - n = strlen(bp) + 1; /* for the \0 */ + n = strlen(bp) + 1; /*%< for the \\0 */ bp += n; } break; @@ -930,7 +926,7 @@ gethostans(struct irs_ho *this, if (!haveanswer) { int nn; - nn = strlen(bp) + 1; /* for the \0 */ + nn = strlen(bp) + 1; /*%< for the \\0 */ if (nn >= MAXHOSTNAMELEN) { cp += n; had_error++; @@ -948,10 +944,10 @@ gethostans(struct irs_ho *this, had_error++; continue; } - if (ret_aip) { /* need addrinfo. keep it. */ + if (ret_aip) { /*%< need addrinfo. keep it. */ while (cur && cur->ai_next) cur = cur->ai_next; - } else if (cur->ai_next) { /* need hostent */ + } else if (cur->ai_next) { /*%< need hostent */ struct addrinfo *aip = cur->ai_next; for (aip = cur->ai_next; aip; @@ -991,7 +987,7 @@ gethostans(struct irs_ho *this, addrsort(pvt->res, pvt->h_addr_ptrs, haveanswer); if (pvt->host.h_name == NULL) { - n = strlen(qname) + 1; /* for the \0 */ + n = strlen(qname) + 1; /*%< for the \\0 */ if (n > (ep - bp) || n >= MAXHOSTNAMELEN) goto no_recovery; strcpy(bp, qname); /* (checked) */ @@ -1047,7 +1043,7 @@ add_hostent(struct pvt *pvt, char *bp, char **hap, struct addrinfo *ai) addrp = (char *)&((struct sockaddr_in *)ai->ai_addr)->sin_addr; break; default: - return(-1); /* abort? */ + return(-1); /*%< abort? */ } /* Ensure alignment. */ @@ -1057,8 +1053,7 @@ add_hostent(struct pvt *pvt, char *bp, char **hap, struct addrinfo *ai) if (bp + addrlen >= &pvt->hostbuf[sizeof pvt->hostbuf]) return(-1); if (hap >= &pvt->h_addr_ptrs[MAXADDRS-1]) - return(0); /* fail, but not treat it as an error. */ - + return(0); /*%< fail, but not treat it as an error. */ /* Suppress duplicates. */ for (tap = (const char **)pvt->h_addr_ptrs; *tap != NULL; diff --git a/lib/bind/irs/dns_nw.c b/lib/bind/irs/dns_nw.c index 8ac89a47c4..dc1e61739b 100644 --- a/lib/bind/irs/dns_nw.c +++ b/lib/bind/irs/dns_nw.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: dns_nw.c,v 1.11 2004/09/16 00:56:12 marka Exp $"; +static const char rcsid[] = "$Id: dns_nw.c,v 1.12 2005/04/27 04:56:22 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports. */ @@ -377,16 +377,16 @@ get1101answer(struct irs_nw *this, while (--ancount >= 0 && cp < eom) { int n = dn_expand(ansbuf, eom, cp, bp, ep - bp); - cp += n; /* Owner */ + cp += n; /*%< Owner */ if (n < 0 || !maybe_dnok(pvt->res, bp) || cp + 3 * INT16SZ + INT32SZ > eom) { RES_SET_H_ERRNO(pvt->res, NO_RECOVERY); return (NULL); } - GETSHORT(type, cp); /* Type */ - GETSHORT(class, cp); /* Class */ - cp += INT32SZ; /* TTL */ - GETSHORT(n, cp); /* RDLENGTH */ + GETSHORT(type, cp); /*%< Type */ + GETSHORT(class, cp); /*%< Class */ + cp += INT32SZ; /*%< TTL */ + GETSHORT(n, cp); /*%< RDLENGTH */ if (class == C_IN && type == T_PTR) { int nn; @@ -430,7 +430,7 @@ get1101answer(struct irs_nw *this, } } } - cp += n; /* RDATA */ + cp += n; /*%< RDATA */ } if (!haveanswer) { RES_SET_H_ERRNO(pvt->res, TRY_AGAIN); @@ -491,13 +491,13 @@ get1101mask(struct irs_nw *this, struct nwent *nwent) { if (n < 0 || !maybe_dnok(pvt->res, owner)) break; - cp += n; /* Owner */ + cp += n; /*%< Owner */ if (cp + 3 * INT16SZ + INT32SZ > eom) break; - GETSHORT(type, cp); /* Type */ - GETSHORT(class, cp); /* Class */ - cp += INT32SZ; /* TTL */ - GETSHORT(n, cp); /* RDLENGTH */ + GETSHORT(type, cp); /*%< Type */ + GETSHORT(class, cp); /*%< Class */ + cp += INT32SZ; /*%< TTL */ + GETSHORT(n, cp); /*%< RDLENGTH */ if (cp + n > eom) break; if (n == INADDRSZ && class == C_IN && type == T_A && @@ -513,7 +513,7 @@ get1101mask(struct irs_nw *this, struct nwent *nwent) { else break; } - cp += n; /* RDATA */ + cp += n; /*%< RDATA */ } memput(ansbuf, MAXPACKET); return (nwent); @@ -587,3 +587,5 @@ init(struct irs_nw *this) { return (-1); return (0); } + +/*! \file */ diff --git a/lib/bind/irs/dns_p.h b/lib/bind/irs/dns_p.h index 451ce566de..d85ae2a238 100644 --- a/lib/bind/irs/dns_p.h +++ b/lib/bind/irs/dns_p.h @@ -16,7 +16,7 @@ */ /* - * $Id: dns_p.h,v 1.3 2004/03/18 02:57:58 marka Exp $ + * $Id: dns_p.h,v 1.4 2005/04/27 04:56:22 sra Exp $ */ #ifndef _DNS_P_H_INCLUDED @@ -27,7 +27,7 @@ #define maybe_hnok(res, hn) maybe_ok((res), (hn), res_hnok) #define maybe_dnok(res, dn) maybe_ok((res), (dn), res_dnok) -/* +/*% * Object state. */ struct dns_p { @@ -48,3 +48,5 @@ extern struct irs_ho * irs_dns_ho __P((struct irs_acc *)); extern struct irs_nw * irs_dns_nw __P((struct irs_acc *)); #endif /*_DNS_P_H_INCLUDED*/ + +/*! \file */ diff --git a/lib/bind/irs/dns_pr.c b/lib/bind/irs/dns_pr.c index 815849be97..137f306218 100644 --- a/lib/bind/irs/dns_pr.c +++ b/lib/bind/irs/dns_pr.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: dns_pr.c,v 1.4 2004/03/09 06:29:59 marka Exp $"; +static const char rcsid[] = "$Id: dns_pr.c,v 1.5 2005/04/27 04:56:22 sra Exp $"; #endif /* Imports */ @@ -264,3 +264,5 @@ parse_hes_list(struct irs_pr *this, char **hes_list) { } return (NULL); } + +/*! \file */ diff --git a/lib/bind/irs/dns_pw.c b/lib/bind/irs/dns_pw.c index 8dd17962c5..4ea97adfdb 100644 --- a/lib/bind/irs/dns_pw.c +++ b/lib/bind/irs/dns_pw.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: dns_pw.c,v 1.2 2004/03/09 06:29:59 marka Exp $"; +static const char rcsid[] = "$Id: dns_pw.c,v 1.3 2005/04/27 04:56:22 sra Exp $"; #endif #include "port_before.h" @@ -229,3 +229,4 @@ getpwcommon(struct irs_pw *this, const char *arg, const char *type) { } #endif /* WANT_IRS_PW */ +/*! \file */ diff --git a/lib/bind/irs/dns_sv.c b/lib/bind/irs/dns_sv.c index 3e4b2990a9..c3294255b8 100644 --- a/lib/bind/irs/dns_sv.c +++ b/lib/bind/irs/dns_sv.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: dns_sv.c,v 1.4 2004/03/09 06:30:00 marka Exp $"; +static const char rcsid[] = "$Id: dns_sv.c,v 1.5 2005/04/27 04:56:23 sra Exp $"; #endif /* Imports */ @@ -111,8 +111,8 @@ irs_dns_sv(struct irs_acc *this) { sv->res_get = sv_res_get; sv->res_set = sv_res_set; #else - sv->res_get = NULL; /* sv_res_get; */ - sv->res_set = NULL; /* sv_res_set; */ + sv->res_get = NULL; /*%< sv_res_get; */ + sv->res_set = NULL; /*%< sv_res_set; */ #endif return (sv); } @@ -296,3 +296,5 @@ sv_res_set(struct irs_sv *this, struct __res_state * res, __hesiod_res_set(dns->hes_ctx, res, free_res); } #endif + +/*! \file */ diff --git a/lib/bind/irs/gai_strerror.c b/lib/bind/irs/gai_strerror.c index 6aeaaa1910..dc2e341749 100644 --- a/lib/bind/irs/gai_strerror.c +++ b/lib/bind/irs/gai_strerror.c @@ -26,21 +26,20 @@ static const char *gai_errlist[] = { "no error", - "address family not supported for name",/* EAI_ADDRFAMILY */ - "temporary failure", /* EAI_AGAIN */ - "invalid flags", /* EAI_BADFLAGS */ - "permanent failure", /* EAI_FAIL */ - "address family not supported", /* EAI_FAMILY */ - "memory failure", /* EAI_MEMORY */ - "no address", /* EAI_NODATA */ - "unknown name or service", /* EAI_NONAME */ - "service not supported for socktype", /* EAI_SERVICE */ - "socktype not supported", /* EAI_SOCKTYPE */ - "system failure", /* EAI_SYSTEM */ - "bad hints", /* EAI_BADHINTS */ - "bad protocol", /* EAI_PROTOCOL */ - - "unknown error" /* Must be last. */ + "address family not supported for name",/*%< EAI_ADDRFAMILY */ + "temporary failure", /*%< EAI_AGAIN */ + "invalid flags", /*%< EAI_BADFLAGS */ + "permanent failure", /*%< EAI_FAIL */ + "address family not supported", /*%< EAI_FAMILY */ + "memory failure", /*%< EAI_MEMORY */ + "no address", /*%< EAI_NODATA */ + "unknown name or service", /*%< EAI_NONAME */ + "service not supported for socktype", /*%< EAI_SERVICE */ + "socktype not supported", /*%< EAI_SOCKTYPE */ + "system failure", /*%< EAI_SYSTEM */ + "bad hints", /*%< EAI_BADHINTS */ + "bad protocol", /*%< EAI_PROTOCOL */ + "unknown error" /*%< Must be last. */ }; static const int gai_nerr = (sizeof(gai_errlist)/sizeof(*gai_errlist)); @@ -87,3 +86,5 @@ gai_strerror(int ecode) { sprintf(buf, "%s: %d", gai_errlist[gai_nerr - 1], ecode); return (buf); } + +/*! \file */ diff --git a/lib/bind/irs/gen.c b/lib/bind/irs/gen.c index ec360df7ae..04105b3025 100644 --- a/lib/bind/irs/gen.c +++ b/lib/bind/irs/gen.c @@ -16,10 +16,11 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: gen.c,v 1.6 2004/09/16 00:56:12 marka Exp $"; +static const char rcsid[] = "$Id: gen.c,v 1.7 2005/04/27 04:56:23 sra Exp $"; #endif -/* +/*! \file + * \brief * this is the top level dispatcher * * The dispatcher is implemented as an accessor class; it is an diff --git a/lib/bind/irs/gen_gr.c b/lib/bind/irs/gen_gr.c index 34fec98ad8..d689e19319 100644 --- a/lib/bind/irs/gen_gr.c +++ b/lib/bind/irs/gen_gr.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: gen_gr.c,v 1.7 2004/05/17 07:52:46 marka Exp $"; +static const char rcsid[] = "$Id: gen_gr.c,v 1.8 2005/04/27 04:56:23 sra Exp $"; #endif /* Imports */ @@ -61,7 +61,7 @@ struct pvt { * we keep one buffer and resize it as needed. */ struct group group; - size_t nmemb; /* Malloc'd max index of gr_mem[]. */ + size_t nmemb; /*%< Malloc'd max index of gr_mem[]. */ char * membuf; size_t membufsize; struct __res_state * res; @@ -490,3 +490,4 @@ newgid(int ngroups, gid_t *groups, gid_t group) { } #endif /* WANT_IRS_GR */ +/*! \file */ diff --git a/lib/bind/irs/gen_ho.c b/lib/bind/irs/gen_ho.c index e2b76a8a80..59060cd3b3 100644 --- a/lib/bind/irs/gen_ho.c +++ b/lib/bind/irs/gen_ho.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: gen_ho.c,v 1.3 2004/03/18 02:57:58 marka Exp $"; +static const char rcsid[] = "$Id: gen_ho.c,v 1.4 2005/04/27 04:56:23 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports */ @@ -348,7 +348,7 @@ ho_addrinfo(struct irs_ho *this, const char *name, const struct addrinfo *pai) ho = rule->inst->ho; RES_SET_H_ERRNO(pvt->res, NETDB_INTERNAL); errno = 0; - if (ho->addrinfo == NULL) /* for safety */ + if (ho->addrinfo == NULL) /*%< for safety */ continue; rval = (*ho->addrinfo)(ho, name, pai); if (rval != NULL) @@ -389,3 +389,5 @@ init(struct irs_ho *this) { return (0); } + +/*! \file */ diff --git a/lib/bind/irs/gen_ng.c b/lib/bind/irs/gen_ng.c index 9f0cdddf43..c617c7c9f5 100644 --- a/lib/bind/irs/gen_ng.c +++ b/lib/bind/irs/gen_ng.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: gen_ng.c,v 1.2 2004/03/09 06:30:00 marka Exp $"; +static const char rcsid[] = "$Id: gen_ng.c,v 1.3 2005/04/27 04:56:23 sra Exp $"; #endif /* Imports */ @@ -170,3 +170,5 @@ ng_minimize(struct irs_ng *this) { (*ng->minimize)(ng); } } + +/*! \file */ diff --git a/lib/bind/irs/gen_nw.c b/lib/bind/irs/gen_nw.c index 10567e370b..480a435478 100644 --- a/lib/bind/irs/gen_nw.c +++ b/lib/bind/irs/gen_nw.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: gen_nw.c,v 1.3 2004/03/18 02:57:58 marka Exp $"; +static const char rcsid[] = "$Id: gen_nw.c,v 1.4 2005/04/27 04:56:23 sra Exp $"; #endif /* Imports */ @@ -260,3 +260,5 @@ init(struct irs_nw *this) { return (-1); return (0); } + +/*! \file */ diff --git a/lib/bind/irs/gen_p.h b/lib/bind/irs/gen_p.h index 5fe61b2170..1adc5909bb 100644 --- a/lib/bind/irs/gen_p.h +++ b/lib/bind/irs/gen_p.h @@ -16,10 +16,11 @@ */ /* - * $Id: gen_p.h,v 1.2 2004/03/09 06:30:00 marka Exp $ + * $Id: gen_p.h,v 1.3 2005/04/27 04:56:23 sra Exp $ */ -/* Notes: +/*! \file + * Notes: * We hope to create a complete set of thread-safe entry points someday, * which will mean a set of getXbyY() functions that take as an argument * a pointer to the map class, which will have a pointer to the private @@ -36,32 +37,32 @@ #ifndef _GEN_P_H_INCLUDED #define _GEN_P_H_INCLUDED -/* +/*% * These are the access methods. */ enum irs_acc_id { - irs_lcl, /* Local. */ - irs_dns, /* DNS or Hesiod. */ - irs_nis, /* Sun NIS ("YP"). */ - irs_irp, /* IR protocol. */ + irs_lcl, /*%< Local. */ + irs_dns, /*%< DNS or Hesiod. */ + irs_nis, /*%< Sun NIS ("YP"). */ + irs_irp, /*%< IR protocol. */ irs_nacc }; -/* +/*% * These are the map types. */ enum irs_map_id { - irs_gr, /* "group" */ - irs_pw, /* "passwd" */ - irs_sv, /* "services" */ - irs_pr, /* "protocols" */ - irs_ho, /* "hosts" */ - irs_nw, /* "networks" */ - irs_ng, /* "netgroup" */ + irs_gr, /*%< "group" */ + irs_pw, /*%< "passwd" */ + irs_sv, /*%< "services" */ + irs_pr, /*%< "protocols" */ + irs_ho, /*%< "hosts" */ + irs_nw, /*%< "networks" */ + irs_ng, /*%< "netgroup" */ irs_nmap }; -/* +/*% * This is an accessor instance. */ struct irs_inst { @@ -75,7 +76,7 @@ struct irs_inst { struct irs_ng * ng; }; -/* +/*% * This is a search rule for some map type. */ struct irs_rule { @@ -83,9 +84,8 @@ struct irs_rule { struct irs_inst * inst; int flags; }; -#define IRS_MERGE 0x0001 /* Don't stop if acc. has data? */ -#define IRS_CONTINUE 0x0002 /* Don't stop if acc. has no data? */ - +#define IRS_MERGE 0x0001 /*%< Don't stop if acc. has data? */ +#define IRS_CONTINUE 0x0002 /*%< Don't stop if acc. has no data? */ /* * This is the private data for a search access class. */ diff --git a/lib/bind/irs/gen_pr.c b/lib/bind/irs/gen_pr.c index 7f24d2d7c2..93c0426c78 100644 --- a/lib/bind/irs/gen_pr.c +++ b/lib/bind/irs/gen_pr.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: gen_pr.c,v 1.2 2004/03/09 06:30:00 marka Exp $"; +static const char rcsid[] = "$Id: gen_pr.c,v 1.3 2005/04/27 04:56:24 sra Exp $"; #endif /* Imports */ @@ -224,3 +224,5 @@ pr_res_set(struct irs_pr *this, struct __res_state *res, (*pr->res_set)(pr, pvt->res, NULL); } } + +/*! \file */ diff --git a/lib/bind/irs/gen_pw.c b/lib/bind/irs/gen_pw.c index f4fe2daf6d..512b011518 100644 --- a/lib/bind/irs/gen_pw.c +++ b/lib/bind/irs/gen_pw.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: gen_pw.c,v 1.2 2004/03/09 06:30:01 marka Exp $"; +static const char rcsid[] = "$Id: gen_pw.c,v 1.3 2005/04/27 04:56:24 sra Exp $"; #endif /* Imports */ @@ -231,3 +231,4 @@ pw_res_set(struct irs_pw *this, struct __res_state *res, } #endif /* WANT_IRS_PW */ +/*! \file */ diff --git a/lib/bind/irs/gen_sv.c b/lib/bind/irs/gen_sv.c index d5a049d497..4cad166d2f 100644 --- a/lib/bind/irs/gen_sv.c +++ b/lib/bind/irs/gen_sv.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: gen_sv.c,v 1.2 2004/03/09 06:30:01 marka Exp $"; +static const char rcsid[] = "$Id: gen_sv.c,v 1.3 2005/04/27 04:56:24 sra Exp $"; #endif /* Imports */ @@ -225,3 +225,5 @@ sv_res_set(struct irs_sv *this, struct __res_state *res, (*sv->res_set)(sv, pvt->res, NULL); } } + +/*! \file */ diff --git a/lib/bind/irs/getaddrinfo.c b/lib/bind/irs/getaddrinfo.c index e08cf78424..23b06c3969 100644 --- a/lib/bind/irs/getaddrinfo.c +++ b/lib/bind/irs/getaddrinfo.c @@ -29,48 +29,52 @@ * SUCH DAMAGE. */ -/* +/*! \file * Issues to be discussed: - * - Thread safe-ness must be checked. - * - Return values. There are nonstandard return values defined and used + *\li Thread safe-ness must be checked. + *\li Return values. There are nonstandard return values defined and used * in the source code. This is because RFC2553 is silent about which error * code must be returned for which situation. - * - IPv4 classful (shortened) form. RFC2553 is silent about it. XNET 5.2 + *\li IPv4 classful (shortened) form. RFC2553 is silent about it. XNET 5.2 * says to use inet_aton() to convert IPv4 numeric to binary (allows * classful form as a result). * current code - disallow classful form for IPv4 (due to use of inet_pton). - * - freeaddrinfo(NULL). RFC2553 is silent about it. XNET 5.2 says it is + *\li freeaddrinfo(NULL). RFC2553 is silent about it. XNET 5.2 says it is * invalid. * current code - SEGV on freeaddrinfo(NULL) * Note: - * - We use getipnodebyname() just for thread-safeness. There's no intent + *\li We use getipnodebyname() just for thread-safeness. There's no intent * to let it do PF_UNSPEC (actually we never pass PF_UNSPEC to * getipnodebyname(). - * - The code filters out AFs that are not supported by the kernel, + *\li The code filters out AFs that are not supported by the kernel, * when globbing NULL hostname (to loopback, or wildcard). Is it the right * thing to do? What is the relationship with post-RFC2553 AI_ADDRCONFIG * in ai_flags? - * - (post-2553) semantics of AI_ADDRCONFIG itself is too vague. + *\li (post-2553) semantics of AI_ADDRCONFIG itself is too vague. * (1) what should we do against numeric hostname (2) what should we do * against NULL hostname (3) what is AI_ADDRCONFIG itself. AF not ready? * non-loopback address configured? global address configured? - * - To avoid search order issue, we have a big amount of code duplicate + * \par Additional Issue: + * To avoid search order issue, we have a big amount of code duplicate * from gethnamaddr.c and some other places. The issues that there's no * lower layer function to lookup "IPv4 or IPv6" record. Calling * gethostbyname2 from getaddrinfo will end up in wrong search order, as * follows: - * - The code makes use of following calls when asked to resolver with + * \li The code makes use of following calls when asked to resolver with * ai_family = PF_UNSPEC: - * getipnodebyname(host, AF_INET6); + *\code getipnodebyname(host, AF_INET6); * getipnodebyname(host, AF_INET); - * This will result in the following queries if the node is configure to + *\endcode + * \li This will result in the following queries if the node is configure to * prefer /etc/hosts than DNS: + *\code * lookup /etc/hosts for IPv6 address * lookup DNS for IPv6 address * lookup /etc/hosts for IPv4 address * lookup DNS for IPv4 address + *\endcode * which may not meet people's requirement. - * The right thing to happen is to have underlying layer which does + * \li The right thing to happen is to have underlying layer which does * PF_UNSPEC lookup (lookup both) and return chain of addrinfos. * This would result in a bit of code duplicate with _dns_ghbyname() and * friends. @@ -199,20 +203,20 @@ struct addrinfo *addr2addrinfo __P((const struct addrinfo *, #if 0 static const char *ai_errlist[] = { "Success", - "Address family for hostname not supported", /* EAI_ADDRFAMILY */ - "Temporary failure in name resolution", /* EAI_AGAIN */ - "Invalid value for ai_flags", /* EAI_BADFLAGS */ - "Non-recoverable failure in name resolution", /* EAI_FAIL */ - "ai_family not supported", /* EAI_FAMILY */ - "Memory allocation failure", /* EAI_MEMORY */ - "No address associated with hostname", /* EAI_NODATA */ - "hostname nor servname provided, or not known", /* EAI_NONAME */ - "servname not supported for ai_socktype", /* EAI_SERVICE */ - "ai_socktype not supported", /* EAI_SOCKTYPE */ - "System error returned in errno", /* EAI_SYSTEM */ - "Invalid value for hints", /* EAI_BADHINTS */ - "Resolved protocol is unknown", /* EAI_PROTOCOL */ - "Unknown error", /* EAI_MAX */ + "Address family for hostname not supported", /*%< EAI_ADDRFAMILY */ + "Temporary failure in name resolution", /*%< EAI_AGAIN */ + "Invalid value for ai_flags", /*%< EAI_BADFLAGS */ + "Non-recoverable failure in name resolution", /*%< EAI_FAIL */ + "ai_family not supported", /*%< EAI_FAMILY */ + "Memory allocation failure", /*%< EAI_MEMORY */ + "No address associated with hostname", /*%< EAI_NODATA */ + "hostname nor servname provided, or not known", /*%< EAI_NONAME */ + "servname not supported for ai_socktype", /*%< EAI_SERVICE */ + "ai_socktype not supported", /*%< EAI_SOCKTYPE */ + "System error returned in errno", /*%< EAI_SYSTEM */ + "Invalid value for hints", /*%< EAI_BADHINTS */ + "Resolved protocol is unknown", /*%< EAI_PROTOCOL */ + "Unknown error", /*%< EAI_MAX */ }; #endif @@ -257,7 +261,7 @@ do { \ #define MATCH(x, y, w) \ ((x) == (y) || (/*CONSTCOND*/(w) && ((x) == ANY || (y) == ANY))) -#if 0 /* bind8 has its own version */ +#if 0 /*%< bind8 has its own version */ char * gai_strerror(ecode) int ecode; @@ -332,7 +336,7 @@ getaddrinfo(hostname, servname, hints, res) /* error check for hints */ if (hints->ai_addrlen || hints->ai_canonname || hints->ai_addr || hints->ai_next) - ERR(EAI_BADHINTS); /* xxx */ + ERR(EAI_BADHINTS); /*%< xxx */ if (hints->ai_flags & ~AI_MASK) ERR(EAI_BADFLAGS); switch (hints->ai_family) { @@ -490,7 +494,7 @@ getaddrinfo(hostname, servname, hints, res) goto free; } if (afai == NULL) { - error = EAI_NONAME; /* we've had no errors. */ + error = EAI_NONAME; /*%< we've had no errors. */ goto free; } @@ -547,10 +551,9 @@ getaddrinfo(hostname, servname, hints, res) cur = cur->ai_next; } - freeaddrinfo(afai); /* afai must not be NULL at this point. */ - + freeaddrinfo(afai); /*%< afai must not be NULL at this point. */ /* we must not have got any errors. */ - if (error != 0) /* just for diagnosis */ + if (error != 0) /*%< just for diagnosis */ abort(); if (sentinel.ai_next) { @@ -574,7 +577,7 @@ bad: return(error); } -/* +/*% * FQDN hostname, DNS lookup */ static int @@ -602,7 +605,7 @@ explore_fqdn(pai, hostname, servname, res) if (!net_data || !(ho = net_data->ho)) return(0); -#if 0 /* XXX (notyet) */ +#if 0 /*%< XXX (notyet) */ if (net_data->ho_stayopen && net_data->ho_last && net_data->ho_last->h_addrtype == af) { if (ns_samename(name, net_data->ho_last->h_name) == 1) @@ -638,7 +641,7 @@ explore_fqdn(pai, hostname, servname, res) error = EAI_NONAME; break; default: - case NETDB_SUCCESS: /* should be impossible... */ + case NETDB_SUCCESS: /*%< should be impossible... */ error = EAI_NONAME; break; } @@ -646,7 +649,7 @@ explore_fqdn(pai, hostname, servname, res) } for (cur = result; cur; cur = cur->ai_next) { - GET_PORT(cur, servname); /* XXX: redundant lookups... */ + GET_PORT(cur, servname); /*%< XXX: redundant lookups... */ /* canonname should already be filled. */ } @@ -662,8 +665,8 @@ free: static int explore_copy(pai, src0, res) - const struct addrinfo *pai; /* seed */ - const struct addrinfo *src0; /* source */ + const struct addrinfo *pai; /*%< seed */ + const struct addrinfo *src0; /*%< source */ struct addrinfo **res; { int error; @@ -697,7 +700,7 @@ fail: return error; } -/* +/*% * hostname == NULL. * passive socket -> anyaddr (0.0.0.0 or ::) * non-passive socket -> localhost (127.0.0.1 or ::1) @@ -745,7 +748,7 @@ free: return error; } -/* +/*% * numeric hostname */ static int @@ -808,7 +811,7 @@ bad: return error; } -/* +/*% * numeric hostname with scope */ static int @@ -859,7 +862,7 @@ explore_numeric_scope(pai, hostname, servname, res) sin6 = (struct sockaddr_in6 *)(void *)cur->ai_addr; if (!ip6_str2scopeid(scope, sin6, &scopeid)) { free(hostname2); - return(EAI_NONAME); /* XXX: is return OK? */ + return(EAI_NONAME); /*%< XXX: is return OK? */ } #ifdef HAVE_SIN6_SCOPE_ID sin6->sin6_scope_id = scopeid; @@ -1055,7 +1058,7 @@ find_afd(af) return NULL; } -/* +/*% * post-2553: AI_ADDRCONFIG check. if we use getipnodeby* as backend, backend * will take care of it. * the semantics of AI_ADDRCONFIG is not defined well. we are not sure @@ -1113,8 +1116,7 @@ ip6_str2scopeid(char *scope, struct sockaddr_in6 *sin6, if (IN6_IS_ADDR_MC_ORGLOCAL(a6)) goto trynumeric; else - goto trynumeric; /* global */ - + goto trynumeric; /*%< global */ /* try to convert to a numeric id as a last resort */ trynumeric: errno = 0; @@ -1151,7 +1153,7 @@ hostent2addrinfo(hp, pai) cur = &sentinel; for (i = 0; (ap = aplist[i]) != NULL; i++) { -#if 0 /* the trick seems too much */ +#if 0 /*%< the trick seems too much */ af = hp->h_addr_list; if (af == AF_INET6 && IN6_IS_ADDR_V4MAPPED((struct in6_addr *)ap)) { @@ -1175,7 +1177,7 @@ hostent2addrinfo(hp, pai) */ GET_CANONNAME(cur->ai_next, hp->h_name); } - while (cur && cur->ai_next) /* no need to loop, actually. */ + while (cur && cur->ai_next) /*%< no need to loop, actually. */ cur = cur->ai_next; continue; diff --git a/lib/bind/irs/getgrent.c b/lib/bind/irs/getgrent.c index 296c8fdc2a..e6c6c42147 100644 --- a/lib/bind/irs/getgrent.c +++ b/lib/bind/irs/getgrent.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: getgrent.c,v 1.4 2004/03/09 06:30:01 marka Exp $"; +static const char rcsid[] = "$Id: getgrent.c,v 1.5 2005/04/27 04:56:24 sra Exp $"; #endif /* Imports */ @@ -221,3 +221,4 @@ init() { } #endif /* WANT_IRS_GR */ +/*! \file */ diff --git a/lib/bind/irs/getgrent_r.c b/lib/bind/irs/getgrent_r.c index 509167ddec..eb9c7947cd 100644 --- a/lib/bind/irs/getgrent_r.c +++ b/lib/bind/irs/getgrent_r.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: getgrent_r.c,v 1.6 2004/03/09 06:30:01 marka Exp $"; +static const char rcsid[] = "$Id: getgrent_r.c,v 1.7 2005/04/27 04:56:24 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -120,7 +120,7 @@ getgrgid_r(gid_t gid, struct group *gptr, } #endif -/* +/*% * These assume a single context is in operation per thread. * If this is not the case we will need to call irs directly * rather than through the base functions. @@ -180,7 +180,7 @@ copy_group(struct group *ge, struct group *gptr, char *buf, int buflen) { int numptr, len; /* Find out the amount of space required to store the answer. */ - numptr = 1; /* NULL ptr */ + numptr = 1; /*%< NULL ptr */ len = (char *)ALIGN(buf) - buf; for (i = 0; ge->gr_mem[i]; i++, numptr++) { len += strlen(ge->gr_mem[i]) + 1; @@ -227,3 +227,4 @@ copy_group(struct group *ge, struct group *gptr, char *buf, int buflen) { static int getgrent_r_unknown_system = 0; #endif /* GROUP_R_RETURN */ #endif /* !def(_REENTRANT) || !def(DO_PTHREADS) || !def(WANT_IRS_PW) */ +/*! \file */ diff --git a/lib/bind/irs/gethostent.c b/lib/bind/irs/gethostent.c index 59343e25c6..6ef639fe1a 100644 --- a/lib/bind/irs/gethostent.c +++ b/lib/bind/irs/gethostent.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: gethostent.c,v 1.6 2004/03/18 02:57:59 marka Exp $"; +static const char rcsid[] = "$Id: gethostent.c,v 1.7 2005/04/27 04:56:24 sra Exp $"; #endif /* Imports */ @@ -235,11 +235,11 @@ static const unsigned char in6addr_mapped[12] = { static int scan_interfaces(int *, int *); static struct hostent *copyandmerge(struct hostent *, struct hostent *, int, int *); -/* +/*% * Public functions */ -/* +/*% * AI_V4MAPPED + AF_INET6 * If no IPv6 address then a query for IPv4 and map returned values. * @@ -445,11 +445,11 @@ freehostent(struct hostent *he) { memput(he, sizeof *he); } -/* +/*% * Private */ -/* +/*% * Scan the interface table and set have_v4 and have_v6 depending * upon whether there are IPv4 and IPv6 interface addresses. * @@ -505,7 +505,7 @@ scan_interfaces6(int *have_v4, int *have_v6) { if (buf == NULL) goto cleanup; #ifdef SETFAMILYFLAGS - lifc.lifc_family = AF_UNSPEC; /* request all families */ + lifc.lifc_family = AF_UNSPEC; /*%< request all families */ lifc.lifc_flags = 0; #endif lifc.lifc_len = bufsiz; @@ -533,7 +533,7 @@ scan_interfaces6(int *have_v4, int *have_v6) { } /* Parse system's interface list. */ - cplim = buf + lifc.lifc_len; /* skip over if's with big ifr_addr's */ + cplim = buf + lifc.lifc_len; /*%< skip over if's with big ifr_addr's */ for (cp = buf; (*have_v4 == 0 || *have_v6 == 0) && cp < cplim; cp += cpsize) { @@ -639,7 +639,7 @@ static int scan_interfaces(int *have_v4, int *have_v6) { struct ifconf ifc; union { - char _pad[256]; /* leave space for IPv6 addresses */ + char _pad[256]; /*%< leave space for IPv6 addresses */ struct ifreq ifreq; } u; struct in_addr in4; @@ -712,7 +712,7 @@ scan_interfaces(int *have_v4, int *have_v6) { } /* Parse system's interface list. */ - cplim = buf + ifc.ifc_len; /* skip over if's with big ifr_addr's */ + cplim = buf + ifc.ifc_len; /*%< skip over if's with big ifr_addr's */ for (cp = buf; (*have_v4 == 0 || *have_v6 == 0) && cp < cplim; cp += cpsize) { @@ -792,8 +792,8 @@ scan_interfaces(int *have_v4, int *have_v6) { static struct hostent * copyandmerge(struct hostent *he1, struct hostent *he2, int af, int *error_num) { struct hostent *he = NULL; - int addresses = 1; /* NULL terminator */ - int names = 1; /* NULL terminator */ + int addresses = 1; /*%< NULL terminator */ + int names = 1; /*%< NULL terminator */ int len = 0; char **cpp, **npp; @@ -1034,7 +1034,7 @@ fakeaddr(const char *name, int af, struct net_data *net_data) { return (&pvt->host); } -#ifdef grot /* for future use in gethostbyaddr(), for "SUNSECURITY" */ +#ifdef grot /*%< for future use in gethostbyaddr(), for "SUNSECURITY" */ struct hostent *rhp; char **haddr; u_long old_options; @@ -1065,5 +1065,6 @@ fakeaddr(const char *name, int af, struct net_data *net_data) { } } #endif /* grot */ - #endif /*__BIND_NOSTATIC*/ + +/*! \file */ diff --git a/lib/bind/irs/gethostent_r.c b/lib/bind/irs/gethostent_r.c index 26be3e8360..e07069d737 100644 --- a/lib/bind/irs/gethostent_r.c +++ b/lib/bind/irs/gethostent_r.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: gethostent_r.c,v 1.7 2004/09/01 02:04:50 marka Exp $"; +static const char rcsid[] = "$Id: gethostent_r.c,v 1.8 2005/04/27 04:56:24 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -86,7 +86,7 @@ gethostbyaddr_r(const char *addr, int len, int type, #endif } -/* +/*% * These assume a single context is in operation per thread. * If this is not the case we will need to call irs directly * rather than through the base functions. @@ -151,7 +151,7 @@ copy_hostent(struct hostent *he, struct hostent *hptr, HOST_R_COPY_ARGS) { int nptr, len; /* Find out the amount of space required to store the answer. */ - nptr = 2; /* NULL ptrs */ + nptr = 2; /*%< NULL ptrs */ len = (char *)ALIGN(buf) - buf; for (i = 0; he->h_addr_list[i]; i++, nptr++) { len += he->h_length; @@ -260,3 +260,4 @@ copy_hostent(struct hostent *he, struct hostent *hptr, HOST_R_COPY_ARGS) { static int gethostent_r_unknown_system = 0; #endif /* HOST_R_RETURN */ #endif /* !defined(_REENTRANT) || !defined(DO_PTHREADS) */ +/*! \file */ diff --git a/lib/bind/irs/getnameinfo.c b/lib/bind/irs/getnameinfo.c index 5947c03898..147adc7fbe 100644 --- a/lib/bind/irs/getnameinfo.c +++ b/lib/bind/irs/getnameinfo.c @@ -53,7 +53,7 @@ #include -/* +/*% * Note that a_off will be dynamically adjusted so that to be consistent * with the definition of sockaddr_in{,6}. * The value presented below is just a guess. @@ -129,7 +129,7 @@ getnameinfo(sa, salen, host, hostlen, serv, servlen, flags) found: if (salen != afd->a_socklen) return EAI_FAIL; - port = ((const struct sockinet *)sa)->si_port; /* network byte order */ + port = ((const struct sockinet *)sa)->si_port; /*%< network byte order */ addr = (const char *)sa + afd->a_off; if (serv == NULL || servlen == 0U) { @@ -241,13 +241,13 @@ ip6_parsenumeric(const struct sockaddr *sa, const char *addr, char *host, return EAI_SYSTEM; numaddrlen = strlen(numaddr); - if (numaddrlen + 1 > hostlen) /* don't forget terminator */ + if (numaddrlen + 1 > hostlen) /*%< don't forget terminator */ return EAI_MEMORY; strcpy(host, numaddr); #ifdef HAVE_SIN6_SCOPE_ID if (((const struct sockaddr_in6 *)sa)->sin6_scope_id) { - char scopebuf[MAXHOSTNAMELEN]; /* XXX */ + char scopebuf[MAXHOSTNAMELEN]; /*%< XXX */ int scopelen; /* ip6_sa2str never fails */ @@ -320,3 +320,5 @@ ip6_sa2str(const struct sockaddr_in6 *sa6, char *buf, return(strlen(tmp)); } #endif + +/*! \file */ diff --git a/lib/bind/irs/getnetent.c b/lib/bind/irs/getnetent.c index 1926dabf97..a6abe7175b 100644 --- a/lib/bind/irs/getnetent.c +++ b/lib/bind/irs/getnetent.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: getnetent.c,v 1.6 2004/03/18 02:57:59 marka Exp $"; +static const char rcsid[] = "$Id: getnetent.c,v 1.7 2005/04/27 04:56:25 sra Exp $"; #endif /* Imports */ @@ -321,7 +321,7 @@ nw_to_net(struct nwent *nwent, struct net_data *net_data) { pvt->netent.n_aliases = nwent->n_aliases; pvt->netent.n_addrtype = nwent->n_addrtype; -/* +/*% * What this code does: Converts net addresses from network to host form. * * msbyte: the index of the most significant byte in the n_addr array. @@ -341,3 +341,5 @@ nw_to_net(struct nwent *nwent, struct net_data *net_data) { } #endif /*__BIND_NOSTATIC*/ + +/*! \file */ diff --git a/lib/bind/irs/getnetent_r.c b/lib/bind/irs/getnetent_r.c index 4677a33406..dbb742d7b1 100644 --- a/lib/bind/irs/getnetent_r.c +++ b/lib/bind/irs/getnetent_r.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: getnetent_r.c,v 1.4 2004/03/09 06:30:01 marka Exp $"; +static const char rcsid[] = "$Id: getnetent_r.c,v 1.5 2005/04/27 04:56:25 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -83,7 +83,7 @@ getnetbyaddr_r(GETNETBYADDR_ADDR_T addr, int type, struct netent *nptr, NET_R_AR #endif } -/* +/*% * These assume a single context is in operation per thread. * If this is not the case we will need to call irs directly * rather than through the base functions. @@ -145,7 +145,7 @@ copy_netent(struct netent *ne, struct netent *nptr, NET_R_COPY_ARGS) { int numptr, len; /* Find out the amount of space required to store the answer. */ - numptr = 1; /* NULL ptr */ + numptr = 1; /*%< NULL ptr */ len = (char *)ALIGN(buf) - buf; for (i = 0; ne->n_aliases[i]; i++, numptr++) { len += strlen(ne->n_aliases[i]) + 1; @@ -225,3 +225,4 @@ copy_netent(struct netent *ne, struct netent *nptr, NET_R_COPY_ARGS) { static int getnetent_r_unknown_system = 0; #endif /* NET_R_RETURN */ #endif /* !defined(_REENTRANT) || !defined(DO_PTHREADS) */ +/*! \file */ diff --git a/lib/bind/irs/getnetgrent.c b/lib/bind/irs/getnetgrent.c index 5547f677b8..0adeb616a7 100644 --- a/lib/bind/irs/getnetgrent.c +++ b/lib/bind/irs/getnetgrent.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: getnetgrent.c,v 1.3 2004/03/09 06:30:01 marka Exp $"; +static const char rcsid[] = "$Id: getnetgrent.c,v 1.4 2005/04/27 04:56:25 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports */ @@ -154,3 +154,5 @@ init(void) { } #endif /*__BIND_NOSTATIC*/ + +/*! \file */ diff --git a/lib/bind/irs/getnetgrent_r.c b/lib/bind/irs/getnetgrent_r.c index 237379a08f..5cb47a04cd 100644 --- a/lib/bind/irs/getnetgrent_r.c +++ b/lib/bind/irs/getnetgrent_r.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: getnetgrent_r.c,v 1.9 2004/11/30 01:08:51 marka Exp $"; +static const char rcsid[] = "$Id: getnetgrent_r.c,v 1.10 2005/04/27 04:56:26 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -51,7 +51,7 @@ innetgr_r(const char *netgroup, const char *host, const char *user, return (innetgr(ng, ho, us, dom)); } -/* +/*% * These assume a single context is in operation per thread. * If this is not the case we will need to call irs directly * rather than through the base functions. @@ -164,3 +164,4 @@ copy_protoent(char **machinep, char **userp, char **domainp, static int getnetgrent_r_unknown_system = 0; #endif /* NGR_R_RETURN */ #endif /* !defined(_REENTRANT) || !defined(DO_PTHREADS) */ +/*! \file */ diff --git a/lib/bind/irs/getprotoent.c b/lib/bind/irs/getprotoent.c index 722aab326f..1e109f9659 100644 --- a/lib/bind/irs/getprotoent.c +++ b/lib/bind/irs/getprotoent.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: getprotoent.c,v 1.3 2004/03/09 06:30:02 marka Exp $"; +static const char rcsid[] = "$Id: getprotoent.c,v 1.4 2005/04/27 04:56:26 sra Exp $"; #endif /* Imports */ @@ -172,3 +172,5 @@ init() { } #endif /*__BIND_NOSTATIC*/ + +/*! \file */ diff --git a/lib/bind/irs/getprotoent_r.c b/lib/bind/irs/getprotoent_r.c index 2a396ffd05..648bfef450 100644 --- a/lib/bind/irs/getprotoent_r.c +++ b/lib/bind/irs/getprotoent_r.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: getprotoent_r.c,v 1.4 2004/03/09 06:30:02 marka Exp $"; +static const char rcsid[] = "$Id: getprotoent_r.c,v 1.5 2005/04/27 04:56:26 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -76,7 +76,7 @@ getprotobynumber_r(int proto, struct protoent *pptr, PROTO_R_ARGS) { #endif } -/* +/*% * These assume a single context is in operation per thread. * If this is not the case we will need to call irs directly * rather than through the base functions. @@ -136,7 +136,7 @@ copy_protoent(struct protoent *pe, struct protoent *pptr, PROTO_R_COPY_ARGS) { int numptr, len; /* Find out the amount of space required to store the answer. */ - numptr = 1; /* NULL ptr */ + numptr = 1; /*%< NULL ptr */ len = (char *)ALIGN(buf) - buf; for (i = 0; pe->p_aliases[i]; i++, numptr++) { len += strlen(pe->p_aliases[i]) + 1; @@ -214,3 +214,4 @@ copy_protoent(struct protoent *pe, struct protoent *pptr, PROTO_R_COPY_ARGS) { static int getprotoent_r_unknown_system = 0; #endif /* PROTO_R_RETURN */ #endif /* !defined(_REENTRANT) || !defined(DO_PTHREADS) */ +/*! \file */ diff --git a/lib/bind/irs/getpwent.c b/lib/bind/irs/getpwent.c index 8bd6bfcd19..c70f99e64c 100644 --- a/lib/bind/irs/getpwent.c +++ b/lib/bind/irs/getpwent.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: getpwent.c,v 1.2 2004/03/09 06:30:02 marka Exp $"; +static const char rcsid[] = "$Id: getpwent.c,v 1.3 2005/04/27 04:56:26 sra Exp $"; #endif /* Imports */ @@ -198,3 +198,4 @@ init() { } #endif /* WANT_IRS_PW */ +/*! \file */ diff --git a/lib/bind/irs/getpwent_r.c b/lib/bind/irs/getpwent_r.c index d299f7a68b..f754084317 100644 --- a/lib/bind/irs/getpwent_r.c +++ b/lib/bind/irs/getpwent_r.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: getpwent_r.c,v 1.7 2004/09/17 13:33:58 marka Exp $"; +static const char rcsid[] = "$Id: getpwent_r.c,v 1.8 2005/04/27 04:56:26 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -121,7 +121,7 @@ getpwuid_r(uid_t uid, struct passwd *pwptr, char *buf, int buflen) { } #endif -/* +/*% * These assume a single context is in operation per thread. * If this is not the case we will need to call irs directly * rather than through the base functions. @@ -273,3 +273,4 @@ copy_passwd(struct passwd *pw, struct passwd *pwptr, char *buf, int buflen) { static int getpwent_r_unknown_system = 0; #endif /* PASS_R_RETURN */ #endif /* !def(_REENTRANT) || !def(DO_PTHREADS) || !def(WANT_IRS_PW) */ +/*! \file */ diff --git a/lib/bind/irs/getservent.c b/lib/bind/irs/getservent.c index 25abe1b2d0..8de0db3058 100644 --- a/lib/bind/irs/getservent.c +++ b/lib/bind/irs/getservent.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: getservent.c,v 1.3 2004/03/09 06:30:02 marka Exp $"; +static const char rcsid[] = "$Id: getservent.c,v 1.4 2005/04/27 04:56:26 sra Exp $"; #endif /* Imports */ @@ -175,3 +175,5 @@ init() { } #endif /*__BIND_NOSTATIC*/ + +/*! \file */ diff --git a/lib/bind/irs/getservent_r.c b/lib/bind/irs/getservent_r.c index e9c52c04c8..aa12d5dbab 100644 --- a/lib/bind/irs/getservent_r.c +++ b/lib/bind/irs/getservent_r.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: getservent_r.c,v 1.4 2004/03/09 06:30:02 marka Exp $"; +static const char rcsid[] = "$Id: getservent_r.c,v 1.5 2005/04/27 04:56:27 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -79,7 +79,7 @@ getservbyport_r(int port, const char *proto, #endif } -/* +/*% * These assume a single context is in operation per thread. * If this is not the case we will need to call irs directly * rather than through the base functions. @@ -141,7 +141,7 @@ copy_servent(struct servent *se, struct servent *sptr, SERV_R_COPY_ARGS) { int numptr, len; /* Find out the amount of space required to store the answer. */ - numptr = 1; /* NULL ptr */ + numptr = 1; /*%< NULL ptr */ len = (char *)ALIGN(buf) - buf; for (i = 0; se->s_aliases[i]; i++, numptr++) { len += strlen(se->s_aliases[i]) + 1; @@ -235,3 +235,4 @@ copy_servent(struct servent *se, struct servent *sptr, SERV_R_COPY_ARGS) { static int getservent_r_unknown_system = 0; #endif /*SERV_R_RETURN */ #endif /* !defined(_REENTRANT) || !defined(DO_PTHREADS) */ +/*! \file */ diff --git a/lib/bind/irs/hesiod.c b/lib/bind/irs/hesiod.c index b6ffbfaf8f..f4e7cfa972 100644 --- a/lib/bind/irs/hesiod.c +++ b/lib/bind/irs/hesiod.c @@ -1,5 +1,5 @@ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: hesiod.c,v 1.5 2004/05/17 07:52:46 marka Exp $"; +static const char rcsid[] = "$Id: hesiod.c,v 1.6 2005/04/27 04:56:27 sra Exp $"; #endif /* @@ -19,16 +19,16 @@ static const char rcsid[] = "$Id: hesiod.c,v 1.5 2004/05/17 07:52:46 marka Exp $ * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* - * This file is primarily maintained by and . - */ -/* +/*! \file + * \brief * hesiod.c --- the core portion of the hesiod resolver. * * This file is derived from the hesiod library from Project Athena; * It has been extensively rewritten by Theodore Ts'o to have a more * thread-safe interface. + * \author + * This file is primarily maintained by <tytso@mit.edu> and <ghudson@mit.edu>. */ /* Imports */ @@ -69,7 +69,7 @@ static int init(struct hesiod_p *ctx); /* Public */ -/* +/*% * This function is called to initialize a hesiod_p. */ int @@ -147,7 +147,7 @@ hesiod_init(void **context) { return (-1); } -/* +/*% * This function deallocates the hesiod_p */ void @@ -167,7 +167,7 @@ hesiod_end(void *context) { errno = save_errno; } -/* +/*% * This function takes a hesiod (name, type) and returns a DNS * name which is to be resolved. */ @@ -226,7 +226,7 @@ hesiod_to_bind(void *context, const char *name, const char *type) { return (bindname); } -/* +/*% * This is the core function. Given a hesiod (name, type), it * returns an array of strings returned by the resolver. */ @@ -267,7 +267,7 @@ hesiod_free_list(void *context, char **list) { free(list); } -/* +/*% * This function parses the /etc/hesiod.conf file */ static int @@ -337,17 +337,17 @@ parse_config_file(struct hesiod_p *ctx, const char *filename) { return (-1); } -/* +/*% * Given a DNS class and a DNS name, do a lookup for TXT records, and * return a list of them. */ static char ** get_txt_records(struct hesiod_p *ctx, int class, const char *name) { struct { - int type; /* RR type */ - int class; /* RR class */ - int dlen; /* len of data section */ - u_char *data; /* pointer to data */ + int type; /*%< RR type */ + int class; /*%< RR class */ + int dlen; /*%< len of data section */ + u_char *data; /*%< pointer to data */ } rr; HEADER *hp; u_char qbuf[MAX_HESRESP], abuf[MAX_HESRESP]; @@ -414,7 +414,7 @@ get_txt_records(struct hesiod_p *ctx, int class, const char *name) { rr.type = ns_get16(cp); cp += INT16SZ; rr.class = ns_get16(cp); - cp += INT16SZ + INT32SZ; /* skip the ttl, too */ + cp += INT16SZ + INT32SZ; /*%< skip the ttl, too */ rr.dlen = ns_get16(cp); cp += INT16SZ; if (cp + rr.dlen > eom) { diff --git a/lib/bind/irs/hesiod_p.h b/lib/bind/irs/hesiod_p.h index eb35e6e899..99da15d0cd 100644 --- a/lib/bind/irs/hesiod_p.h +++ b/lib/bind/irs/hesiod_p.h @@ -16,27 +16,27 @@ */ /* - * This file is primarily maintained by and . - */ - -/* - * $Id: hesiod_p.h,v 1.2 2004/03/09 06:30:02 marka Exp $ - */ - -/* - * hesiod_p.h -- private definitions for the hesiod library + * $Id: hesiod_p.h,v 1.3 2005/04/27 04:56:27 sra Exp $ */ #ifndef _HESIOD_P_H_INCLUDED #define _HESIOD_P_H_INCLUDED -#define DEF_RHS ".Athena.MIT.EDU" /* Defaults if HESIOD_CONF */ -#define DEF_LHS ".ns" /* file is not */ - /* present. */ +/** \file + * \brief + * hesiod_p.h -- private definitions for the hesiod library. + * + * \author + * This file is primarily maintained by tytso@mit.edu and ghudson@mit.edu. + */ + +#define DEF_RHS ".Athena.MIT.EDU" /*%< Defaults if HESIOD_CONF */ +#define DEF_LHS ".ns" /*%< file is not */ + /*%< present. */ struct hesiod_p { - char * LHS; /* normally ".ns" */ - char * RHS; /* AKA the default hesiod domain */ - struct __res_state * res; /* resolver context */ + char * LHS; /*%< normally ".ns" */ + char * RHS; /*%< AKA the default hesiod domain */ + struct __res_state * res; /*%< resolver context */ void (*free_res)(void *); void (*res_set)(struct hesiod_p *, struct __res_state *, void (*)(void *)); diff --git a/lib/bind/irs/irp.c b/lib/bind/irs/irp.c index b85e349680..15eb261b05 100644 --- a/lib/bind/irs/irp.c +++ b/lib/bind/irs/irp.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: irp.c,v 1.6 2004/03/18 02:57:59 marka Exp $"; +static const char rcsid[] = "$Id: irp.c,v 1.7 2005/04/27 04:56:27 sra Exp $"; #endif /* Imports */ @@ -66,7 +66,7 @@ static void irp_close(struct irs_acc *); /* send errors to syslog if true. */ int irp_log_errors = 1; -/* +/*% * This module handles the irp module connection to irpd. * * The client expects a synchronous interface to functions like @@ -74,7 +74,7 @@ int irp_log_errors = 1; * the wire (it's used in the server). */ -/* +/*% * irs_acc *irs_irp_acc(const char *options); * * Initialize the irp module. @@ -137,8 +137,7 @@ irs_irp_connection_setup(struct irp_p *cxndata, int *warned) { return (0); } - -/* +/*% * int irs_irp_connect(void); * * Sets up the connection to the remote irpd server. @@ -245,9 +244,7 @@ irs_irp_connect(struct irp_p *pvt) { return (0); } - - -/* +/*% * int irs_irp_is_connected(struct irp_p *pvt); * * Returns: @@ -261,9 +258,7 @@ irs_irp_is_connected(struct irp_p *pvt) { return (pvt->fdCxn >= 0); } - - -/* +/*% * void * irs_irp_disconnect(struct irp_p *pvt); * @@ -355,11 +350,7 @@ irs_irp_read_line(struct irp_p *pvt, char *buffer, int len) { return (buffpos); } - - - - -/* +/*% * int irp_read_response(struct irp_p *pvt); * * Returns: @@ -399,9 +390,7 @@ irs_irp_read_response(struct irp_p *pvt, char *text, size_t textlen) { return (code); } - - -/* +/*% * char *irp_read_body(struct irp_p *pvt, size_t *size); * * Read in the body of a response. Terminated by a line with @@ -468,8 +457,7 @@ irs_irp_read_body(struct irp_p *pvt, size_t *size) { return (NULL); } - -/* +/*% * int irs_irp_get_full_response(struct irp_p *pvt, int *code, * char **body, size_t *bodylen); * @@ -512,8 +500,7 @@ irs_irp_get_full_response(struct irp_p *pvt, int *code, char *text, return (0); } - -/* +/*% * int irs_irp_send_command(struct irp_p *pvt, const char *fmt, ...); * * Sends command to remote connected via the PVT @@ -569,9 +556,7 @@ irs_irp_send_command(struct irp_p *pvt, const char *fmt, ...) { /* Methods */ - - -/* +/*% * void irp_close(struct irs_acc *this) * */ @@ -590,3 +575,5 @@ irp_close(struct irs_acc *this) { + +/*! \file */ diff --git a/lib/bind/irs/irp_gr.c b/lib/bind/irs/irp_gr.c index b88aabf883..1f40e76022 100644 --- a/lib/bind/irs/irp_gr.c +++ b/lib/bind/irs/irp_gr.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: irp_gr.c,v 1.3 2004/03/09 06:30:03 marka Exp $"; +static const char rcsid[] = "$Id: irp_gr.c,v 1.4 2005/04/27 04:56:27 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* extern */ @@ -54,16 +54,17 @@ static int __bind_irs_gr_unneeded; /* Types. */ -/* +/*! \file + * \brief * Module for the getnetgrent(3) family to use when connected to a * remote irp daemon. - * + * \brief * See irpd.c for justification of caching done here. * */ struct pvt { - struct irp_p *girpdata; /* global IRP data */ + struct irp_p *girpdata; /*%< global IRP data */ int warned; struct group group; }; @@ -83,21 +84,9 @@ static void free_group(struct group *gr); /* Public. */ - - - - -/* - * struct irs_gr * irs_irp_gr(struct irs_acc *this) - * - * Notes: - * +/*% * Initialize the group sub-module. * - * Notes: - * - * Module data. - * */ struct irs_gr * @@ -132,13 +121,7 @@ irs_irp_gr(struct irs_acc *this) { /* Methods. */ - - -/* - * void gr_close(struct irs_gr *this) - * - * Notes: - * +/*% * Close the sub-module. * */ @@ -153,14 +136,7 @@ gr_close(struct irs_gr *this) { memput(this, sizeof *this); } - - - -/* - * struct group * gr_next(struct irs_gr *this) - * - * Notes: - * +/*% * Gets the next group out of the cached data and returns it. * */ @@ -207,15 +183,7 @@ gr_next(struct irs_gr *this) { return (gr); } - - - - -/* - * struct group * gr_byname(struct irs_gr *this, const char *name) - * - * Notes: - * +/*% * Gets a group by name from irpd and returns it. * */ @@ -263,15 +231,7 @@ gr_byname(struct irs_gr *this, const char *name) { return (gr); } - - - - -/* - * struct group * gr_bygid(struct irs_gr *this, gid_t gid) - * - * Notes: - * +/*% * Gets a group by gid from irpd and returns it. * */ @@ -318,10 +278,7 @@ gr_bygid(struct irs_gr *this, gid_t gid) { return (gr); } - - - -/* +/*% * void gr_rewind(struct irs_gr *this) * */ @@ -350,14 +307,7 @@ gr_rewind(struct irs_gr *this) { return; } - - - -/* - * void gr_minimize(struct irs_gr *this) - * - * Notes: - * +/*% * Frees up cached data and disconnects(if necessary) from the remote. * */ @@ -372,9 +322,7 @@ gr_minimize(struct irs_gr *this) { /* Private. */ - - -/* +/*% * static void free_group(struct group *gr); * * Deallocate all the memory irp_unmarshall_gr allocated. @@ -406,3 +354,4 @@ free_group(struct group *gr) { #endif /* WANT_IRS_GR */ +/*! \file */ diff --git a/lib/bind/irs/irp_ho.c b/lib/bind/irs/irp_ho.c index 194084dabe..d4ce5c3bbe 100644 --- a/lib/bind/irs/irp_ho.c +++ b/lib/bind/irs/irp_ho.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: irp_ho.c,v 1.2 2004/03/09 06:30:03 marka Exp $"; +static const char rcsid[] = "$Id: irp_ho.c,v 1.3 2005/04/27 04:56:28 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports. */ @@ -84,9 +84,7 @@ static struct addrinfo * ho_addrinfo(struct irs_ho *this, const char *name, /* Public. */ - - -/* +/*% * struct irs_ho * irs_irp_ho(struct irs_acc *this) * * Notes: @@ -129,13 +127,7 @@ irs_irp_ho(struct irs_acc *this) { /* Methods. */ - - -/* - * void ho_close(struct irs_ho *this) - * - * Notes: - * +/*% * Closes down the module. * */ @@ -281,15 +273,7 @@ ho_byaddr(struct irs_ho *this, const void *addr, int len, int af) { return (ho); } - - - - -/* - * struct hostent * ho_next(struct irs_ho *this) - * - * Notes: - * +/*% * The implementation for gethostent(3). The first time it's * called all the data is pulled from the remote(i.e. what * the maximum number of gethostent(3) calls would return) @@ -336,11 +320,7 @@ ho_next(struct irs_ho *this) { return (ho); } - - - - -/* +/*% * void ho_rewind(struct irs_ho *this) * */ @@ -369,10 +349,7 @@ ho_rewind(struct irs_ho *this) { return; } - - - -/* +/*% * void ho_minimize(struct irs_ho *this) * */ @@ -386,10 +363,7 @@ ho_minimize(struct irs_ho *this) { irs_irp_disconnect(pvt->girpdata); } - - - -/* +/*% * void free_host(struct hostent *ho) * */ @@ -427,3 +401,5 @@ ho_addrinfo(struct irs_ho *this, const char *name, const struct addrinfo *pai) UNUSED(pai); return(NULL); } + +/*! \file */ diff --git a/lib/bind/irs/irp_ng.c b/lib/bind/irs/irp_ng.c index 5f700713cf..02a957adf0 100644 --- a/lib/bind/irs/irp_ng.c +++ b/lib/bind/irs/irp_ng.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: irp_ng.c,v 1.2 2004/03/09 06:30:03 marka Exp $"; +static const char rcsid[] = "$Id: irp_ng.c,v 1.3 2005/04/27 04:56:28 sra Exp $"; #endif /* Imports */ @@ -62,13 +62,7 @@ static void ng_minimize(struct irs_ng *); /* Public */ - - -/* - * struct irs_ng * irs_irp_ng(struct irs_acc *this) - * - * Notes: - * +/*% * Intialize the irp netgroup module. * */ @@ -155,15 +149,7 @@ ng_rewind(struct irs_ng *this, const char *group) { return; } - - - /* - * int ng_next(struct irs_ng *this, const char **host, const char **user, - * const char **domain) - * - * Notes: - * * Get the next netgroup item from the cache. * */ @@ -205,14 +191,7 @@ ng_next(struct irs_ng *this, const char **host, const char **user, return (rval); } - - /* - * int ng_test(struct irs_ng *this, const char *name, const char *host, - * const char *user, const char *domain) - * - * Notes: - * * Search for a match in a netgroup. * */ @@ -270,3 +249,5 @@ ng_minimize(struct irs_ng *this) { /* Private */ + +/*! \file */ diff --git a/lib/bind/irs/irp_nw.c b/lib/bind/irs/irp_nw.c index 814b55f209..7146817f3b 100644 --- a/lib/bind/irs/irp_nw.c +++ b/lib/bind/irs/irp_nw.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: irp_nw.c,v 1.2 2004/03/09 06:30:03 marka Exp $"; +static const char rcsid[] = "$Id: irp_nw.c,v 1.3 2005/04/27 04:56:28 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #if 0 @@ -79,9 +79,7 @@ static void free_nw(struct nwent *nw); /* Public */ - - -/* +/*% * struct irs_nw * irs_irp_nw(struct irs_acc *this) * */ @@ -117,9 +115,7 @@ irs_irp_nw(struct irs_acc *this) { /* Methods */ - - -/* +/*% * void nw_close(struct irs_nw *this) * */ @@ -136,10 +132,7 @@ nw_close(struct irs_nw *this) { memput(this, sizeof *this); } - - - -/* +/*% * struct nwent * nw_byaddr(struct irs_nw *this, void *net, * int length, int type) * @@ -152,7 +145,7 @@ nw_byaddr(struct irs_nw *this, void *net, int length, int type) { char *body = NULL; size_t bodylen; int code; - char paddr[24]; /* bigenough for ip4 w/ cidr spec. */ + char paddr[24]; /*%< bigenough for ip4 w/ cidr spec. */ char text[256]; if (inet_net_ntop(type, net, length, paddr, sizeof paddr) == NULL) { @@ -189,10 +182,7 @@ nw_byaddr(struct irs_nw *this, void *net, int length, int type) { return (nw); } - - - -/* +/*% * struct nwent * nw_byname(struct irs_nw *this, const char *name, int type) * */ @@ -241,10 +231,7 @@ nw_byname(struct irs_nw *this, const char *name, int type) { return (nw); } - - - -/* +/*% * void nw_rewind(struct irs_nw *this) * */ @@ -273,16 +260,7 @@ nw_rewind(struct irs_nw *this) { return; } - - - - - -/* - * struct nwent * nw_next(struct irs_nw *this) - * - * Notes: - * +/*% * Prepares the cache if necessary and returns the first, or * next item from it. */ @@ -322,12 +300,7 @@ nw_next(struct irs_nw *this) { return (nw); } - - - - - -/* +/*% * void nw_minimize(struct irs_nw *this) * */ @@ -344,11 +317,7 @@ nw_minimize(struct irs_nw *this) { /* private. */ - - -/* - * static void free_passwd(struct passwd *pw); - * +/*% * deallocate all the memory irp_unmarshall_pw allocated. * */ @@ -373,3 +342,5 @@ free_nw(struct nwent *nw) { if (nw->n_addr != NULL) free(nw->n_addr); } + +/*! \file */ diff --git a/lib/bind/irs/irp_p.h b/lib/bind/irs/irp_p.h index 37cc9c9ae0..4f943f81bd 100644 --- a/lib/bind/irs/irp_p.h +++ b/lib/bind/irs/irp_p.h @@ -16,7 +16,7 @@ */ /* - * $Id: irp_p.h,v 1.4 2004/03/09 06:30:03 marka Exp $ + * $Id: irp_p.h,v 1.5 2005/04/27 04:56:28 sra Exp $ */ #ifndef _IRP_P_H_INCLUDED @@ -26,9 +26,8 @@ struct irp_p { char inbuffer[1024]; - int inlast; /* index of one past the last char in buffer */ - int incurr; /* index of the next char to be read from buffer */ - + int inlast; /*%< index of one past the last char in buffer */ + int incurr; /*%< index of the next char to be read from buffer */ int fdCxn; }; @@ -57,3 +56,5 @@ int irs_irp_get_full_response(struct irp_p *pvt, int *code, extern int irp_log_errors; #endif + +/*! \file */ diff --git a/lib/bind/irs/irp_pr.c b/lib/bind/irs/irp_pr.c index 712a3a8b3a..ea876e8281 100644 --- a/lib/bind/irs/irp_pr.c +++ b/lib/bind/irs/irp_pr.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: irp_pr.c,v 1.2 2004/03/09 06:30:03 marka Exp $"; +static const char rcsid[] = "$Id: irp_pr.c,v 1.3 2005/04/27 04:56:29 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* extern */ @@ -69,9 +69,7 @@ static void free_proto(struct protoent *pr); /* Public */ - - -/* +/*% * struct irs_pr * irs_irp_pr(struct irs_acc *this) * */ @@ -107,9 +105,7 @@ irs_irp_pr(struct irs_acc *this) { /* Methods */ - - -/* +/*% * void pr_close(struct irs_pr *this) * */ @@ -126,9 +122,7 @@ pr_close(struct irs_pr *this) { memput(this, sizeof *this); } - - -/* +/*% * struct protoent * pr_byname(struct irs_pr *this, const char *name) * */ @@ -177,9 +171,7 @@ pr_byname(struct irs_pr *this, const char *name) { return (pr); } - - -/* +/*% * struct protoent * pr_bynumber(struct irs_pr *this, int proto) * */ @@ -228,10 +220,7 @@ pr_bynumber(struct irs_pr *this, int proto) { return (pr); } - - - -/* +/*% * void pr_rewind(struct irs_pr *this) * */ @@ -260,14 +249,7 @@ pr_rewind(struct irs_pr *this) { return; } - - - -/* - * struct protoent * pr_next(struct irs_pr *this) - * - * Notes: - * +/*% * Prepares the cache if necessary and returns the next item in it. * */ @@ -311,10 +293,7 @@ pr_next(struct irs_pr *this) { return (pr); } - - - -/* +/*% * void pr_minimize(struct irs_pr *this) * */ @@ -326,14 +305,7 @@ pr_minimize(struct irs_pr *this) { irs_irp_disconnect(pvt->girpdata); } - - - - - -/* - * static void free_proto(struct protoent *pw); - * +/*% * Deallocate all the memory irp_unmarshall_pr allocated. * */ @@ -351,3 +323,5 @@ free_proto(struct protoent *pr) { for (p = pr->p_aliases ; p != NULL && *p != NULL ; p++) free(*p); } + +/*! \file */ diff --git a/lib/bind/irs/irp_pw.c b/lib/bind/irs/irp_pw.c index 3d62dc2c55..3722e5974d 100644 --- a/lib/bind/irs/irp_pw.c +++ b/lib/bind/irs/irp_pw.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: irp_pw.c,v 1.3 2004/03/09 06:30:03 marka Exp $"; +static const char rcsid[] = "$Id: irp_pw.c,v 1.4 2005/04/27 04:56:29 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Extern */ @@ -55,9 +55,9 @@ static int __bind_irs_pw_unneeded; /* Types */ struct pvt { - struct irp_p *girpdata; /* global IRP data */ + struct irp_p *girpdata; /*%< global IRP data */ int warned; - struct passwd passwd; /* password structure */ + struct passwd passwd; /*%< password structure */ }; /* Forward */ @@ -104,9 +104,7 @@ irs_irp_pw(struct irs_acc *this) { /* Methods */ - - -/* +/*% * void pw_close(struct irs_pw *this) * */ @@ -123,10 +121,7 @@ pw_close(struct irs_pw *this) { memput(this, sizeof *this); } - - - -/* +/*% * struct passwd * pw_next(struct irs_pw *this) * */ @@ -170,10 +165,7 @@ pw_next(struct irs_pw *this) { return (pw); } - - - -/* +/*% * struct passwd * pw_byname(struct irs_pw *this, const char *name) * */ @@ -221,10 +213,7 @@ pw_byname(struct irs_pw *this, const char *name) { return (pw); } - - - -/* +/*% * struct passwd * pw_byuid(struct irs_pw *this, uid_t uid) * */ @@ -272,10 +261,7 @@ pw_byuid(struct irs_pw *this, uid_t uid) { return (pw); } - - - -/* +/*% * void pw_rewind(struct irs_pw *this) * */ @@ -304,8 +290,7 @@ pw_rewind(struct irs_pw *this) { return; } - -/* +/*% * void pw_minimize(struct irs_pw *this) * */ @@ -320,11 +305,7 @@ pw_minimize(struct irs_pw *this) { /* Private. */ - - -/* - * static void free_passwd(struct passwd *pw); - * +/*% * Deallocate all the memory irp_unmarshall_pw allocated. * */ @@ -356,3 +337,4 @@ free_passwd(struct passwd *pw) { } #endif /* WANT_IRS_PW */ +/*! \file */ diff --git a/lib/bind/irs/irp_sv.c b/lib/bind/irs/irp_sv.c index a4533a3eb6..577e697fe6 100644 --- a/lib/bind/irs/irp_sv.c +++ b/lib/bind/irs/irp_sv.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: irp_sv.c,v 1.2 2004/03/09 06:30:03 marka Exp $"; +static const char rcsid[] = "$Id: irp_sv.c,v 1.3 2005/04/27 04:56:29 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* extern */ @@ -73,9 +73,7 @@ static void free_service(struct servent *sv); /* Public */ - - -/* +/*% * struct irs_sv * irs_irp_sv(struct irs_acc *this) * */ @@ -112,9 +110,7 @@ irs_irp_sv(struct irs_acc *this) { /* Methods */ - - -/* +/*% * void sv_close(struct irs_sv *this) * */ @@ -131,14 +127,7 @@ sv_close(struct irs_sv *this) { memput(this, sizeof *this); } - - - -/* - * struct servent * sv_next(struct irs_sv *this) - * - * Notes: - * +/*% * Fills the cache if necessary and returns the next item from it. * */ @@ -182,10 +171,7 @@ sv_next(struct irs_sv *this) { return (sv); } - - - -/* +/*% * struct servent * sv_byname(struct irs_sv *this, const char *name, * const char *proto) * @@ -236,10 +222,7 @@ sv_byname(struct irs_sv *this, const char *name, const char *proto) { return (sv); } - - - -/* +/*% * struct servent * sv_byport(struct irs_sv *this, int port, * const char *proto) * @@ -291,11 +274,7 @@ sv_byport(struct irs_sv *this, int port, const char *proto) { return (sv); } - - - - -/* +/*% * void sv_rewind(struct irs_sv *this) * */ @@ -324,11 +303,7 @@ sv_rewind(struct irs_sv *this) { return; } - - - - -/* +/*% * void sv_minimize(struct irs_sv *this) * */ @@ -367,3 +342,5 @@ free_service(struct servent *sv) { } + +/*! \file */ diff --git a/lib/bind/irs/irpmarshall.c b/lib/bind/irs/irpmarshall.c index a86c394f55..4f0a9fbfb6 100644 --- a/lib/bind/irs/irpmarshall.c +++ b/lib/bind/irs/irpmarshall.c @@ -49,7 +49,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: irpmarshall.c,v 1.5 2004/03/18 02:57:59 marka Exp $"; +static const char rcsid[] = "$Id: irpmarshall.c,v 1.6 2005/04/27 04:56:29 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #if 0 @@ -118,15 +118,14 @@ static const char *COLONSTR = ":"; #ifdef WANT_IRS_PW /* +++++++++++++++++++++++++ struct passwd +++++++++++++++++++++++++ */ - -/* +/*% * int irp_marshall_pw(const struct passwd *pw, char **buffer, size_t *len) * - * notes: + * notes: \li * - * See above + * See irpmarshall.h * - * return: + * return: \li * * 0 on sucess, -1 on failure. * @@ -134,7 +133,7 @@ static const char *COLONSTR = ":"; int irp_marshall_pw(const struct passwd *pw, char **buffer, size_t *len) { - size_t need = 1 ; /* for null byte */ + size_t need = 1 ; /*%< for null byte */ char pwUid[24]; char pwGid[24]; char pwChange[24]; @@ -170,7 +169,7 @@ irp_marshall_pw(const struct passwd *pw, char **buffer, size_t *len) { pwClass = ""; #endif - need += strlen(pw->pw_name) + 1; /* one for fieldsep */ + need += strlen(pw->pw_name) + 1; /*%< one for fieldsep */ need += strlen(pw->pw_passwd) + 1; need += strlen(pwUid) + 1; need += strlen(pwGid) + 1; @@ -192,7 +191,7 @@ irp_marshall_pw(const struct passwd *pw, char **buffer, size_t *len) { } if (*buffer == NULL) { - need += 2; /* for CRLF */ + need += 2; /*%< for CRLF */ *buffer = memget(need); if (*buffer == NULL) { errno = ENOMEM; @@ -216,18 +215,14 @@ irp_marshall_pw(const struct passwd *pw, char **buffer, size_t *len) { return (0); } - - - - -/* +/*% * int irp_unmarshall_pw(struct passwd *pw, char *buffer) * - * notes: + * notes: \li * - * see above + * See irpmarshall.h * - * return: + * return: \li * * 0 on success, -1 on failure * @@ -258,7 +253,7 @@ irp_unmarshall_pw(struct passwd *pw, char *buffer) { /* pw_passwd field */ pass = NULL; - if (getfield(&pass, 0, &p, fieldsep) == NULL) { /* field can be empty */ + if (getfield(&pass, 0, &p, fieldsep) == NULL) { /*%< field can be empty */ goto error; } @@ -271,10 +266,10 @@ irp_unmarshall_pw(struct passwd *pw, char *buffer) { } t = strtol(tmpbuf, &tb, 10); if (*tb) { - goto error; /* junk in value */ + goto error; /*%< junk in value */ } pwuid = (uid_t)t; - if ((long) pwuid != t) { /* value must have been too big. */ + if ((long) pwuid != t) { /*%< value must have been too big. */ goto error; } @@ -288,10 +283,10 @@ irp_unmarshall_pw(struct passwd *pw, char *buffer) { } t = strtol(tmpbuf, &tb, 10); if (*tb) { - goto error; /* junk in value */ + goto error; /*%< junk in value */ } pwgid = (gid_t)t; - if ((long)pwgid != t) { /* value must have been too big. */ + if ((long)pwgid != t) { /*%< value must have been too big. */ goto error; } @@ -313,10 +308,10 @@ irp_unmarshall_pw(struct passwd *pw, char *buffer) { } t = strtol(tmpbuf, &tb, 10); if (*tb) { - goto error; /* junk in value */ + goto error; /*%< junk in value */ } pwchange = (time_t)t; - if ((long)pwchange != t) { /* value must have been too big. */ + if ((long)pwchange != t) { /*%< value must have been too big. */ goto error; } @@ -330,10 +325,10 @@ irp_unmarshall_pw(struct passwd *pw, char *buffer) { } t = strtol(tmpbuf, &tb, 10); if (*tb) { - goto error; /* junk in value */ + goto error; /*%< junk in value */ } pwexpire = (time_t)t; - if ((long) pwexpire != t) { /* value must have been too big. */ + if ((long) pwexpire != t) { /*%< value must have been too big. */ goto error; } @@ -397,28 +392,23 @@ irp_unmarshall_pw(struct passwd *pw, char *buffer) { /* ------------------------- struct passwd ------------------------- */ #endif /* WANT_IRS_PW */ - - - /* +++++++++++++++++++++++++ struct group +++++++++++++++++++++++++ */ - - -/* +/*% * int irp_marshall_gr(const struct group *gr, char **buffer, size_t *len) * - * notes: + * notes: \li * - * see above. + * See irpmarshall.h. * - * return: + * return: \li * * 0 on success, -1 on failure */ int irp_marshall_gr(const struct group *gr, char **buffer, size_t *len) { - size_t need = 1; /* for null byte */ + size_t need = 1; /*%< for null byte */ char grGid[24]; const char *fieldsep = COLONSTR; @@ -449,7 +439,7 @@ irp_marshall_gr(const struct group *gr, char **buffer, size_t *len) { } if (*buffer == NULL) { - need += 2; /* for CRLF */ + need += 2; /*%< for CRLF */ *buffer = memget(need); if (*buffer == NULL) { errno = ENOMEM; @@ -470,17 +460,14 @@ irp_marshall_gr(const struct group *gr, char **buffer, size_t *len) { return (0); } - - - -/* +/*% * int irp_unmarshall_gr(struct group *gr, char *buffer) * - * notes: + * notes: \li * - * see above + * See irpmarshall.h * - * return: + * return: \li * * 0 on success and -1 on failure. * @@ -528,10 +515,10 @@ irp_unmarshall_gr(struct group *gr, char *buffer) { } t = strtol(tmpbuf, &tb, 10); if (*tb) { - goto error; /* junk in value */ + goto error; /*%< junk in value */ } grgid = (gid_t)t; - if ((long) grgid != t) { /* value must have been too big. */ + if ((long) grgid != t) { /*%< value must have been too big. */ goto error; } @@ -575,16 +562,14 @@ irp_unmarshall_gr(struct group *gr, char *buffer) { /* +++++++++++++++++++++++++ struct servent +++++++++++++++++++++++++ */ - - -/* +/*% * int irp_marshall_sv(const struct servent *sv, char **buffer, size_t *len) * - * notes: + * notes: \li * - * see above + * See irpmarshall.h * - * return: + * return: \li * * 0 on success, -1 on failure. * @@ -592,7 +577,7 @@ irp_unmarshall_gr(struct group *gr, char *buffer) { int irp_marshall_sv(const struct servent *sv, char **buffer, size_t *len) { - size_t need = 1; /* for null byte */ + size_t need = 1; /*%< for null byte */ char svPort[24]; const char *fieldsep = COLONSTR; short realport; @@ -623,7 +608,7 @@ irp_marshall_sv(const struct servent *sv, char **buffer, size_t *len) { } if (*buffer == NULL) { - need += 2; /* for CRLF */ + need += 2; /*%< for CRLF */ *buffer = memget(need); if (*buffer == NULL) { errno = ENOMEM; @@ -641,18 +626,14 @@ irp_marshall_sv(const struct servent *sv, char **buffer, size_t *len) { return (0); } - - - - -/* +/*% * int irp_unmarshall_sv(struct servent *sv, char *buffer) * - * notes: + * notes: \li * - * see above + * See irpmarshall.h * - * return: + * return: \li * * 0 on success, -1 on failure. * @@ -705,10 +686,10 @@ irp_unmarshall_sv(struct servent *sv, char *buffer) { } t = strtol(tmpbuf, &tb, 10); if (*tb) { - goto error; /* junk in value */ + goto error; /*%< junk in value */ } svport = (short)t; - if ((long) svport != t) { /* value must have been too big. */ + if ((long) svport != t) { /*%< value must have been too big. */ goto error; } svport = htons(svport); @@ -741,16 +722,14 @@ irp_unmarshall_sv(struct servent *sv, char *buffer) { /* +++++++++++++++++++++++++ struct protoent +++++++++++++++++++++++++ */ - - -/* +/*% * int irp_marshall_pr(struct protoent *pr, char **buffer, size_t *len) * - * notes: + * notes: \li * - * see above + * See irpmarshall.h * - * return: + * return: \li * * 0 on success and -1 on failure. * @@ -758,7 +737,7 @@ irp_unmarshall_sv(struct servent *sv, char *buffer) { int irp_marshall_pr(struct protoent *pr, char **buffer, size_t *len) { - size_t need = 1; /* for null byte */ + size_t need = 1; /*%< for null byte */ char prProto[24]; const char *fieldsep = COLONSTR; @@ -784,7 +763,7 @@ irp_marshall_pr(struct protoent *pr, char **buffer, size_t *len) { } if (*buffer == NULL) { - need += 2; /* for CRLF */ + need += 2; /*%< for CRLF */ *buffer = memget(need); if (*buffer == NULL) { errno = ENOMEM; @@ -802,16 +781,14 @@ irp_marshall_pr(struct protoent *pr, char **buffer, size_t *len) { } - - -/* +/*% * int irp_unmarshall_pr(struct protoent *pr, char *buffer) * - * notes: + * notes: \li * - * See above + * See irpmarshall.h * - * return: + * return: \li * * 0 on success, -1 on failure * @@ -863,10 +840,10 @@ int irp_unmarshall_pr(struct protoent *pr, char *buffer) { } t = strtol(tmpbuf, &tb, 10); if (*tb) { - goto error; /* junk in value */ + goto error; /*%< junk in value */ } prproto = (int)t; - if ((long) prproto != t) { /* value must have been too big. */ + if ((long) prproto != t) { /*%< value must have been too big. */ goto error; } @@ -891,15 +868,14 @@ int irp_unmarshall_pr(struct protoent *pr, char *buffer) { /* +++++++++++++++++++++++++ struct hostent +++++++++++++++++++++++++ */ - -/* +/*% * int irp_marshall_ho(struct hostent *ho, char **buffer, size_t *len) * - * notes: + * notes: \li * - * see above. + * See irpmarshall.h. * - * return: + * return: \li * * 0 on success, -1 on failure. * @@ -907,7 +883,7 @@ int irp_unmarshall_pr(struct protoent *pr, char *buffer) { int irp_marshall_ho(struct hostent *ho, char **buffer, size_t *len) { - size_t need = 1; /* for null byte */ + size_t need = 1; /*%< for null byte */ char hoaddrtype[24]; char holength[24]; char **av; @@ -945,7 +921,7 @@ irp_marshall_ho(struct hostent *ho, char **buffer, size_t *len) { /* we determine an upper bound on the string length needed, not an exact length. */ - addrlen = (ho->h_addrtype == AF_INET ? 16 : 46) ; /* XX other AF's?? */ + addrlen = (ho->h_addrtype == AF_INET ? 16 : 46) ; /*%< XX other AF's?? */ for (av = ho->h_addr_list; av != NULL && *av != NULL ; av++) need += addrlen; @@ -960,7 +936,7 @@ irp_marshall_ho(struct hostent *ho, char **buffer, size_t *len) { } if (*buffer == NULL) { - need += 2; /* for CRLF */ + need += 2; /*%< for CRLF */ *buffer = memget(need); if (*buffer == NULL) { errno = ENOMEM; @@ -999,16 +975,14 @@ irp_marshall_ho(struct hostent *ho, char **buffer, size_t *len) { return (-1); } - - -/* +/*% * int irp_unmarshall_ho(struct hostent *ho, char *buffer) * - * notes: + * notes: \li * - * See above. + * See irpmarshall.h. * - * return: + * return: \li * * 0 on success, -1 on failure. * @@ -1080,10 +1054,10 @@ irp_unmarshall_ho(struct hostent *ho, char *buffer) { } t = strtol(tmpbuf, &tb, 10); if (*tb) { - goto error; /* junk in value */ + goto error; /*%< junk in value */ } holength = (int)t; - if ((long) holength != t) { /* value must have been too big. */ + if ((long) holength != t) { /*%< value must have been too big. */ goto error; } @@ -1154,16 +1128,15 @@ irp_unmarshall_ho(struct hostent *ho, char *buffer) { /* +++++++++++++++++++++++++ struct netgrp +++++++++++++++++++++++++ */ - -/* +/*% * int irp_marshall_ng(const char *host, const char *user, * const char *domain, char *buffer, size_t *len) * - * notes: + * notes: \li * * See note for irp_marshall_ng_start * - * return: + * return: \li * * 0 on success, 0 on failure. * @@ -1172,7 +1145,7 @@ irp_unmarshall_ho(struct hostent *ho, char *buffer) { int irp_marshall_ng(const char *host, const char *user, const char *domain, char **buffer, size_t *len) { - size_t need = 1; /* for nul byte */ + size_t need = 1; /*%< for nul byte */ const char *fieldsep = ","; if (len == NULL) { @@ -1180,7 +1153,7 @@ irp_marshall_ng(const char *host, const char *user, const char *domain, return (-1); } - need += 4; /* two parens and two commas */ + need += 4; /*%< two parens and two commas */ need += (host == NULL ? 0 : strlen(host)); need += (user == NULL ? 0 : strlen(user)); need += (domain == NULL ? 0 : strlen(domain)); @@ -1194,7 +1167,7 @@ irp_marshall_ng(const char *host, const char *user, const char *domain, } if (*buffer == NULL) { - need += 2; /* for CRLF */ + need += 2; /*%< for CRLF */ *buffer = memget(need); if (*buffer == NULL) { errno = ENOMEM; @@ -1226,18 +1199,17 @@ irp_marshall_ng(const char *host, const char *user, const char *domain, /* ---------- */ - -/* +/*% * int irp_unmarshall_ng(const char **host, const char **user, * const char **domain, char *buffer) * - * notes: + * notes: \li * * Unpacks the BUFFER into 3 character arrays it allocates and assigns * to *HOST, *USER and *DOMAIN. If any field of the value is empty, * then the corresponding paramater value will be set to NULL. * - * return: + * return: \li * * 0 on success and -1 on failure. */ @@ -1325,15 +1297,14 @@ irp_unmarshall_ng(const char **hostp, const char **userp, const char **domainp, /* +++++++++++++++++++++++++ struct nwent +++++++++++++++++++++++++ */ - -/* +/*% * int irp_marshall_nw(struct nwent *ne, char **buffer, size_t *len) * - * notes: + * notes: \li * * See at top. * - * return: + * return: \li * * 0 on success and -1 on failure. * @@ -1341,7 +1312,7 @@ irp_unmarshall_ng(const char **hostp, const char **userp, const char **domainp, int irp_marshall_nw(struct nwent *ne, char **buffer, size_t *len) { - size_t need = 1; /* for null byte */ + size_t need = 1; /*%< for null byte */ char nAddrType[24]; char nNet[MAXPADDRSIZE]; const char *fieldsep = COLONSTR; @@ -1374,7 +1345,7 @@ irp_marshall_nw(struct nwent *ne, char **buffer, size_t *len) { } if (*buffer == NULL) { - need += 2; /* for CRLF */ + need += 2; /*%< for CRLF */ *buffer = memget(need); if (*buffer == NULL) { errno = ENOMEM; @@ -1392,16 +1363,14 @@ irp_marshall_nw(struct nwent *ne, char **buffer, size_t *len) { return (0); } - - -/* +/*% * int irp_unmarshall_nw(struct nwent *ne, char *buffer) * - * notes: + * notes: \li * * See note up top. * - * return: + * return: \li * * 0 on success and -1 on failure. * @@ -1502,15 +1471,14 @@ irp_unmarshall_nw(struct nwent *ne, char *buffer) { /* +++++++++++++++++++++++++ struct netent +++++++++++++++++++++++++ */ - -/* +/*% * int irp_marshall_ne(struct netent *ne, char **buffer, size_t *len) * - * notes: + * notes: \li * * See at top. * - * return: + * return: \li * * 0 on success and -1 on failure. * @@ -1518,7 +1486,7 @@ irp_unmarshall_nw(struct nwent *ne, char *buffer) { int irp_marshall_ne(struct netent *ne, char **buffer, size_t *len) { - size_t need = 1; /* for null byte */ + size_t need = 1; /*%< for null byte */ char nAddrType[24]; char nNet[MAXPADDRSIZE]; const char *fieldsep = COLONSTR; @@ -1551,7 +1519,7 @@ irp_marshall_ne(struct netent *ne, char **buffer, size_t *len) { } if (*buffer == NULL) { - need += 2; /* for CRLF */ + need += 2; /*%< for CRLF */ *buffer = memget(need); if (*buffer == NULL) { errno = ENOMEM; @@ -1569,16 +1537,14 @@ irp_marshall_ne(struct netent *ne, char **buffer, size_t *len) { return (0); } - - -/* +/*% * int irp_unmarshall_ne(struct netent *ne, char *buffer) * - * notes: + * notes: \li * * See note up top. * - * return: + * return: \li * * 0 on success and -1 on failure. * @@ -1671,11 +1637,10 @@ irp_unmarshall_ne(struct netent *ne, char *buffer) { /* =========================================================================== */ - -/* +/*% * static char ** splitarray(const char *buffer, const char *buffend, char delim) * - * notes: + * notes: \li * * Split a delim separated astring. Not allowed * to have two delims next to each other. BUFFER points to begining of @@ -1683,7 +1648,7 @@ irp_unmarshall_ne(struct netent *ne, char *buffer) { * (i.e. points at where the null byte would be if null * terminated). * - * return: + * return: \li * * Returns a malloced array of pointers, each pointer pointing to a * malloced string. If BUFEER is an empty string, then return values is @@ -1719,7 +1684,7 @@ splitarray(const char *buffer, const char *buffend, char delim) { } if (count > 0) { - count++ ; /* for NULL at end */ + count++ ; /*%< for NULL at end */ aptr = arr = malloc(count * sizeof (char *)); if (aptr == NULL) { errno = ENOMEM; @@ -1749,13 +1714,10 @@ splitarray(const char *buffer, const char *buffend, char delim) { return (arr); } - - - -/* +/*% * static size_t joinlength(char * const *argv) * - * return: + * return: \li * * the number of bytes in all the arrays pointed at * by argv, including their null bytes(which will usually be turned @@ -1776,18 +1738,16 @@ joinlength(char * const *argv) { return (len); } - - -/* +/*% * int joinarray(char * const *argv, char *buffer, char delim) * - * notes: + * notes: \li * * Copy all the ARGV strings into the end of BUFFER * separating them with DELIM. BUFFER is assumed to have * enough space to hold everything and to be already null-terminated. * - * return: + * return: \li * * 0 unless argv or buffer is NULL. * @@ -1817,11 +1777,10 @@ joinarray(char * const *argv, char *buffer, char delim) { return (0); } - -/* +/*% * static char * getfield(char **res, size_t reslen, char **ptr, char delim) * - * notes: + * notes: \li * * Stores in *RES, which is a buffer of length RESLEN, a * copy of the bytes from *PTR up to and including the first @@ -1829,7 +1788,7 @@ joinarray(char * const *argv, char *buffer, char delim) { * assigned a malloced buffer to hold the copy. *PTR is * modified to point at the found delimiter. * - * return: + * return: \li * * If there was no delimiter, then NULL is returned, * otherewise *RES is returned. @@ -1854,7 +1813,7 @@ getfield(char **res, size_t reslen, char **ptr, char delim) { if (*res == NULL) { *res = strndup(*ptr, q - *ptr); } else { - if ((size_t)(q - *ptr + 1) > reslen) { /* to big for res */ + if ((size_t)(q - *ptr + 1) > reslen) { /*%< to big for res */ errno = EINVAL; return (NULL); } else { @@ -1876,12 +1835,12 @@ getfield(char **res, size_t reslen, char **ptr, char delim) { /* * static char * strndup(const char *str, size_t len) * - * notes: + * notes: \li * * like strdup, except do len bytes instead of the whole string. Always * null-terminates. * - * return: + * return: \li * * The newly malloced string. * @@ -1901,14 +1860,14 @@ strndup(const char *str, size_t len) { #if WANT_MAIN -/* +/*% * static int strcmp_nws(const char *a, const char *b) * - * notes: + * notes: \li * * do a strcmp, except uneven lengths of whitespace compare the same * - * return: + * return: \li * */ @@ -1942,14 +1901,10 @@ strcmp_nws(const char *a, const char *b) { #endif - - - - -/* +/*% * static void free_array(char **argv, size_t entries) * - * notes: + * notes: \li * * Free argv and each of the pointers inside it. The end of * the array is when a NULL pointer is found inside. If @@ -1984,7 +1939,7 @@ free_array(char **argv, size_t entries) { #if WANT_MAIN -/* takes an option to indicate what sort of marshalling(read the code) and +/*% takes an option to indicate what sort of marshalling(read the code) and an argument. If the argument looks like a marshalled buffer(has a ':' embedded) then it's unmarshalled and the remarshalled and the new string is compared to the old one. @@ -2342,3 +2297,5 @@ main(int argc, char **argv) { } #endif + +/*! \file */ diff --git a/lib/bind/irs/irs_data.c b/lib/bind/irs/irs_data.c index 471c30fc80..ed484d2209 100644 --- a/lib/bind/irs/irs_data.c +++ b/lib/bind/irs/irs_data.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: irs_data.c,v 1.8 2004/11/30 01:08:51 marka Exp $"; +static const char rcsid[] = "$Id: irs_data.c,v 1.9 2005/04/27 04:56:30 sra Exp $"; #endif #include "port_before.h" @@ -113,7 +113,8 @@ net_data_destroy(void *p) { memput(net_data, sizeof *net_data); } -/* applications that need a specific config file other than +/*% + * applications that need a specific config file other than * _PATH_IRS_CONF should call net_data_init directly rather than letting * the various wrapper functions make the first call. - brister */ @@ -231,3 +232,5 @@ __h_errno_set(struct __res_state *res, int err) { } #endif /*__BIND_NOSTATIC*/ + +/*! \file */ diff --git a/lib/bind/irs/irs_data.h b/lib/bind/irs/irs_data.h index 7caac8f1c3..cb814fd8b1 100644 --- a/lib/bind/irs/irs_data.h +++ b/lib/bind/irs/irs_data.h @@ -16,7 +16,7 @@ */ /* - * $Id: irs_data.h,v 1.2 2004/03/09 06:30:03 marka Exp $ + * $Id: irs_data.h,v 1.3 2005/04/27 04:56:30 sra Exp $ */ #ifndef __BIND_NOSTATIC @@ -38,7 +38,7 @@ struct net_data { struct passwd * pw_last; struct servent * sv_last; struct protoent * pr_last; - struct netent * nw_last; /* should have been ne_last */ + struct netent * nw_last; /*%< should have been ne_last */ struct nwent * nww_last; struct hostent * ho_last; @@ -52,11 +52,12 @@ struct net_data { void * nw_data; void * ho_data; - struct __res_state * res; /* for gethostent.c */ - + struct __res_state * res; /*%< for gethostent.c */ }; extern struct net_data * net_data_init(const char *conf_file); extern void net_data_minimize(struct net_data *); #endif /*__BIND_NOSTATIC*/ + +/*! \file */ diff --git a/lib/bind/irs/irs_p.h b/lib/bind/irs/irs_p.h index 478d5ef621..2a0a933fce 100644 --- a/lib/bind/irs/irs_p.h +++ b/lib/bind/irs/irs_p.h @@ -16,7 +16,7 @@ */ /* - * $Id: irs_p.h,v 1.2 2004/03/09 06:30:03 marka Exp $ + * $Id: irs_p.h,v 1.3 2005/04/27 04:56:30 sra Exp $ */ #ifndef _IRS_P_H_INCLUDED @@ -47,3 +47,5 @@ extern struct irs_ng * irs_nul_ng(struct irs_acc *); extern struct servent * irs_lclsv_fnxt(struct lcl_sv *); #endif + +/*! \file */ diff --git a/lib/bind/irs/lcl.c b/lib/bind/irs/lcl.c index 1de99915f0..ea78a258a6 100644 --- a/lib/bind/irs/lcl.c +++ b/lib/bind/irs/lcl.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: lcl.c,v 1.3 2004/03/18 02:57:59 marka Exp $"; +static const char rcsid[] = "$Id: lcl.c,v 1.4 2005/04/27 04:56:30 sra Exp $"; #endif /* Imports */ @@ -138,3 +138,5 @@ lcl_close(struct irs_acc *this) { } memput(this, sizeof *this); } + +/*! \file */ diff --git a/lib/bind/irs/lcl_gr.c b/lib/bind/irs/lcl_gr.c index 033510a47a..ce7e347b2d 100644 --- a/lib/bind/irs/lcl_gr.c +++ b/lib/bind/irs/lcl_gr.c @@ -49,7 +49,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: lcl_gr.c,v 1.2 2004/03/09 06:30:04 marka Exp $"; +static const char rcsid[] = "$Id: lcl_gr.c,v 1.3 2005/04/27 04:56:30 sra Exp $"; /* from getgrent.c 8.2 (Berkeley) 3/21/94"; */ /* from BSDI Id: getgrent.c,v 2.8 1996/05/28 18:15:14 bostic Exp $ */ #endif /* LIBC_SCCS and not lint */ @@ -90,7 +90,7 @@ static int __bind_irs_gr_unneeded; struct pvt { FILE * fp; - /* + /*%< * Need space to store the entries read from the group file. * The members list also needs space per member, and the * strings making up the user names must be allocated @@ -98,7 +98,7 @@ struct pvt { * we keep one buffer and resize it as needed. */ struct group group; - size_t nmemb; /* Malloc'd max index of gr_mem[]. */ + size_t nmemb; /*%< Malloc'd max index of gr_mem[]. */ char * membuf; size_t membufsize; }; @@ -227,9 +227,8 @@ grstart(struct pvt *pvt) { return (1); } -#define INITIAL_NMEMB 30 /* about 120 bytes */ -#define INITIAL_BUFSIZ (INITIAL_NMEMB * 8) /* about 240 bytes */ - +#define INITIAL_NMEMB 30 /*%< about 120 bytes */ +#define INITIAL_BUFSIZ (INITIAL_NMEMB * 8) /*%< about 240 bytes */ static char * grnext(struct pvt *pvt) { char *w, *e; @@ -352,3 +351,4 @@ grscan(struct irs_gr *this, int search, gid_t gid, const char *name) { } #endif /* WANT_IRS_GR */ +/*! \file */ diff --git a/lib/bind/irs/lcl_ho.c b/lib/bind/irs/lcl_ho.c index a311db2281..806ffcda67 100644 --- a/lib/bind/irs/lcl_ho.c +++ b/lib/bind/irs/lcl_ho.c @@ -52,7 +52,7 @@ /* BIND Id: gethnamaddr.c,v 8.15 1996/05/22 04:56:30 vixie Exp $ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: lcl_ho.c,v 1.3 2004/03/18 02:57:59 marka Exp $"; +static const char rcsid[] = "$Id: lcl_ho.c,v 1.4 2005/04/27 04:56:30 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports. */ @@ -109,7 +109,7 @@ struct pvt { char * h_addr_ptrs[MAXADDRS + 1]; char * host_aliases[MAXALIASES]; char hostbuf[8*1024]; - u_char host_addr[16]; /* IPv4 or IPv6 */ + u_char host_addr[16]; /*%< IPv4 or IPv6 */ struct __res_state *res; void (*free_res)(void *); }; @@ -508,7 +508,7 @@ ho_addrinfo(struct irs_ho *this, const char *name, const struct addrinfo *pai) cur = &sentinel; switch(pai->ai_family) { - case AF_UNSPEC: /* INET6 then INET4 */ + case AF_UNSPEC: /*%< INET6 then INET4 */ q.family = AF_INET6; q.next = &q2; q2.family = AF_INET; @@ -520,7 +520,7 @@ ho_addrinfo(struct irs_ho *this, const char *name, const struct addrinfo *pai) q.family = AF_INET; break; default: - RES_SET_H_ERRNO(pvt->res, NO_RECOVERY); /* ??? */ + RES_SET_H_ERRNO(pvt->res, NO_RECOVERY); /*%< ??? */ return(NULL); } @@ -574,3 +574,5 @@ init(struct irs_ho *this) { return (-1); return (0); } + +/*! \file */ diff --git a/lib/bind/irs/lcl_ng.c b/lib/bind/irs/lcl_ng.c index a72671b0d8..70e0b4563f 100644 --- a/lib/bind/irs/lcl_ng.c +++ b/lib/bind/irs/lcl_ng.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: lcl_ng.c,v 1.2 2004/03/09 06:30:04 marka Exp $"; +static const char rcsid[] = "$Id: lcl_ng.c,v 1.3 2005/04/27 04:56:31 sra Exp $"; #endif /* Imports */ @@ -43,11 +43,10 @@ static const char rcsid[] = "$Id: lcl_ng.c,v 1.2 2004/03/09 06:30:04 marka Exp $ /* Definitions */ -#define NG_HOST 0 /* Host name */ -#define NG_USER 1 /* User name */ -#define NG_DOM 2 /* and Domain name */ -#define LINSIZ 1024 /* Length of netgroup file line */ - +#define NG_HOST 0 /*%< Host name */ +#define NG_USER 1 /*%< User name */ +#define NG_DOM 2 /*%< and Domain name */ +#define LINSIZ 1024 /*%< Length of netgroup file line */ /* * XXX Warning XXX * This code is a hack-and-slash special. It realy needs to be @@ -55,24 +54,25 @@ static const char rcsid[] = "$Id: lcl_ng.c,v 1.2 2004/03/09 06:30:04 marka Exp $ * More reasonable data structures would not be a bad thing. */ -/* +/*% * Static Variables and functions used by setnetgrent(), getnetgrent() and * endnetgrent(). + * * There are two linked lists: - * - linelist is just used by setnetgrent() to parse the net group file via. + * \li linelist is just used by setnetgrent() to parse the net group file via. * parse_netgrp() - * - netgrp is the list of entries for the current netgroup + * \li netgrp is the list of entries for the current netgroup */ struct linelist { - struct linelist *l_next; /* Chain ptr. */ - int l_parsed; /* Flag for cycles */ - char * l_groupname; /* Name of netgroup */ - char * l_line; /* Netgroup entrie(s) to be parsed */ + struct linelist *l_next; /*%< Chain ptr. */ + int l_parsed; /*%< Flag for cycles */ + char * l_groupname; /*%< Name of netgroup */ + char * l_line; /*%< Netgroup entrie(s) to be parsed */ }; struct ng_old_struct { - struct ng_old_struct *ng_next; /* Chain ptr */ - char * ng_str[3]; /* Field pointers, see below */ + struct ng_old_struct *ng_next; /*%< Chain ptr */ + char * ng_str[3]; /*%< Field pointers, see below */ }; struct pvt { @@ -142,7 +142,7 @@ ng_close(struct irs_ng *this) { memput(this, sizeof *this); } -/* +/*% * Parse the netgroup file looking for the netgroup and build the list * of netgrp structures. Let parse_netgrp() and read_for_group() do * most of the work. @@ -174,7 +174,7 @@ ng_rewind(struct irs_ng *this, const char *group) { pvt->nextgrp = pvt->grouphead.gr; } -/* +/*% * Get the next netgroup off the list. */ static int @@ -193,7 +193,7 @@ ng_next(struct irs_ng *this, const char **host, const char **user, return (0); } -/* +/*% * Search for a match in a netgroup. */ static int @@ -229,7 +229,7 @@ ng_minimize(struct irs_ng *this) { /* Private */ -/* +/*% * endnetgrent() - cleanup */ static void @@ -266,7 +266,7 @@ freelists(struct irs_ng *this) { pvt->grouphead.gr = NULL; } -/* +/*% * Parse the netgroup file setting up the linked lists. */ static int @@ -349,7 +349,7 @@ parse_netgrp(struct irs_ng *this, const char *group) { return (1); } -/* +/*% * Read the netgroup file and save lines until the line for the netgroup * is found. Return 1 if eof is encountered. */ @@ -442,3 +442,5 @@ read_for_group(struct irs_ng *this, const char *group) { } return (NULL); } + +/*! \file */ diff --git a/lib/bind/irs/lcl_nw.c b/lib/bind/irs/lcl_nw.c index 6c625b4161..79b55a0c04 100644 --- a/lib/bind/irs/lcl_nw.c +++ b/lib/bind/irs/lcl_nw.c @@ -49,7 +49,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: lcl_nw.c,v 1.3 2004/03/18 02:57:59 marka Exp $"; +static const char rcsid[] = "$Id: lcl_nw.c,v 1.4 2005/04/27 04:56:31 sra Exp $"; /* from getgrent.c 8.2 (Berkeley) 3/21/94"; */ /* from BSDI Id: getgrent.c,v 2.8 1996/05/28 18:15:14 bostic Exp $ */ #endif /* LIBC_SCCS and not lint */ @@ -369,3 +369,5 @@ init(struct irs_nw *this) { return (-1); return (0); } + +/*! \file */ diff --git a/lib/bind/irs/lcl_p.h b/lib/bind/irs/lcl_p.h index 9e84f5db4d..e3f4f009cb 100644 --- a/lib/bind/irs/lcl_p.h +++ b/lib/bind/irs/lcl_p.h @@ -16,17 +16,18 @@ */ /* - * $Id: lcl_p.h,v 1.2 2004/03/09 06:30:04 marka Exp $ + * $Id: lcl_p.h,v 1.3 2005/04/27 04:56:31 sra Exp $ */ -/* +/*! \file + * \brief * lcl_p.h - private include file for the local accessor functions. */ #ifndef _LCL_P_H_INCLUDED #define _LCL_P_H_INCLUDED -/* +/*% * Object state. */ struct lcl_p { diff --git a/lib/bind/irs/lcl_pr.c b/lib/bind/irs/lcl_pr.c index a9e6ae6b63..92e399051e 100644 --- a/lib/bind/irs/lcl_pr.c +++ b/lib/bind/irs/lcl_pr.c @@ -49,7 +49,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: lcl_pr.c,v 1.2 2004/03/09 06:30:04 marka Exp $"; +static const char rcsid[] = "$Id: lcl_pr.c,v 1.3 2005/04/27 04:56:31 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* extern */ @@ -282,3 +282,5 @@ pr_minimize(struct irs_pr *this) { pvt->fp = NULL; } } + +/*! \file */ diff --git a/lib/bind/irs/lcl_pw.c b/lib/bind/irs/lcl_pw.c index c6089e57a6..ffca5541bb 100644 --- a/lib/bind/irs/lcl_pw.c +++ b/lib/bind/irs/lcl_pw.c @@ -49,7 +49,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: lcl_pw.c,v 1.2 2004/03/09 06:30:04 marka Exp $"; +static const char rcsid[] = "$Id: lcl_pw.c,v 1.3 2005/04/27 04:56:31 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Extern */ @@ -85,7 +85,8 @@ static int __bind_irs_pw_unneeded; #include "irs_p.h" #include "lcl_p.h" -/* +/*! \file + * \brief * The lookup techniques and data extraction code here must be kept * in sync with that in `pwd_mkdb'. */ @@ -94,9 +95,9 @@ static int __bind_irs_pw_unneeded; /* Types */ struct pvt { - struct passwd passwd; /* password structure */ - DB *pw_db; /* password database */ - int pw_keynum; /* key counter */ + struct passwd passwd; /*%< password structure */ + DB *pw_db; /*%< password database */ + int pw_keynum; /*%< key counter */ int warned; u_int max; char * line; diff --git a/lib/bind/irs/lcl_sv.c b/lib/bind/irs/lcl_sv.c index 6762ac943c..8d0049bb46 100644 --- a/lib/bind/irs/lcl_sv.c +++ b/lib/bind/irs/lcl_sv.c @@ -49,7 +49,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: lcl_sv.c,v 1.3 2004/03/09 06:30:04 marka Exp $"; +static const char rcsid[] = "$Id: lcl_sv.c,v 1.4 2005/04/27 04:56:31 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* extern */ @@ -387,8 +387,7 @@ sv_db_rec(struct lcl_sv *sv, DBT *key, DBT *data) { int n; p = data->data; - p[data->size - 1] = '\0'; /* should be, but we depend on it */ - + p[data->size - 1] = '\0'; /*%< should be, but we depend on it */ if (((char *)key->data)[0] == '\0') { if (key->size < sizeof(u_short)*2 || data->size < 2) return (NULL); @@ -429,3 +428,5 @@ sv_db_rec(struct lcl_sv *sv, DBT *key, DBT *data) { return (&sv->serv); } #endif + +/*! \file */ diff --git a/lib/bind/irs/nis.c b/lib/bind/irs/nis.c index 8a6595ae2b..9abc47403a 100644 --- a/lib/bind/irs/nis.c +++ b/lib/bind/irs/nis.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nis.c,v 1.2 2004/03/09 06:30:04 marka Exp $"; +static const char rcsid[] = "$Id: nis.c,v 1.3 2005/04/27 04:56:32 sra Exp $"; #endif /* Imports */ @@ -152,3 +152,5 @@ nis_close(struct irs_acc *this) { } #endif /*WANT_IRS_NIS*/ + +/*! \file */ diff --git a/lib/bind/irs/nis_gr.c b/lib/bind/irs/nis_gr.c index 88612a4b23..c7c8d83043 100644 --- a/lib/bind/irs/nis_gr.c +++ b/lib/bind/irs/nis_gr.c @@ -49,7 +49,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nis_gr.c,v 1.3 2004/03/09 06:30:05 marka Exp $"; +static const char rcsid[] = "$Id: nis_gr.c,v 1.4 2005/04/27 04:56:32 sra Exp $"; /* from getgrent.c 8.2 (Berkeley) 3/21/94"; */ /* from BSDI Id: getgrent.c,v 2.8 1996/05/28 18:15:14 bostic Exp $ */ #endif /* LIBC_SCCS and not lint */ @@ -99,7 +99,7 @@ struct pvt { int curkey_len; char * curval_data; int curval_len; - /* + /*%< * Need space to store the entries read from the group file. * The members list also needs space per member, and the * strings making up the user names must be allocated @@ -107,7 +107,7 @@ struct pvt { * we keep one buffer and resize it as needed. */ struct group group; - size_t nmemb; /* Malloc'd max index of gr_mem[]. */ + size_t nmemb; /*%< Malloc'd max index of gr_mem[]. */ char * membuf; size_t membufsize; }; @@ -351,3 +351,4 @@ nisfree(struct pvt *pvt, enum do_what do_what) { } #endif /* WANT_IRS_GR && WANT_IRS_NIS */ +/*! \file */ diff --git a/lib/bind/irs/nis_ho.c b/lib/bind/irs/nis_ho.c index 33d622d70e..0799613f49 100644 --- a/lib/bind/irs/nis_ho.c +++ b/lib/bind/irs/nis_ho.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nis_ho.c,v 1.4 2004/03/09 06:30:05 marka Exp $"; +static const char rcsid[] = "$Id: nis_ho.c,v 1.5 2005/04/27 04:56:32 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports */ @@ -79,7 +79,7 @@ struct pvt { char * h_addr_ptrs[MAXADDRS + 1]; char * host_aliases[MAXALIASES + 1]; char hostbuf[8*1024]; - u_char host_addr[16]; /* IPv4 or IPv6 */ + u_char host_addr[16]; /*%< IPv4 or IPv6 */ struct __res_state *res; void (*free_res)(void *); }; @@ -369,7 +369,7 @@ ho_addrinfo(struct irs_ho *this, const char *name, const struct addrinfo *pai) cur = &sentinel; switch(pai->ai_family) { - case AF_UNSPEC: /* INET6 then INET4 */ + case AF_UNSPEC: /*%< INET6 then INET4 */ q.family = AF_INET6; q.next = &q2; q2.family = AF_INET; @@ -381,7 +381,7 @@ ho_addrinfo(struct irs_ho *this, const char *name, const struct addrinfo *pai) q.family = AF_INET; break; default: - RES_SET_H_ERRNO(pvt->res, NO_RECOVERY); /* ??? */ + RES_SET_H_ERRNO(pvt->res, NO_RECOVERY); /*%< ??? */ return(NULL); } @@ -414,7 +414,7 @@ ho_addrinfo(struct irs_ho *this, const char *name, const struct addrinfo *pai) /* Private */ -/* +/*% ipnodes: ::1 localhost 127.0.0.1 localhost @@ -531,3 +531,5 @@ init(struct irs_ho *this) { return (0); } #endif /*WANT_IRS_NIS*/ + +/*! \file */ diff --git a/lib/bind/irs/nis_ng.c b/lib/bind/irs/nis_ng.c index ae8512269a..ac6330536a 100644 --- a/lib/bind/irs/nis_ng.c +++ b/lib/bind/irs/nis_ng.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nis_ng.c,v 1.3 2004/03/09 06:30:05 marka Exp $"; +static const char rcsid[] = "$Id: nis_ng.c,v 1.4 2005/04/27 04:56:32 sra Exp $"; #endif /* Imports */ @@ -300,3 +300,5 @@ tmpfree(struct pvt *pvt) { } #endif /*WANT_IRS_NIS*/ + +/*! \file */ diff --git a/lib/bind/irs/nis_nw.c b/lib/bind/irs/nis_nw.c index 9552c031ca..c61e871ea9 100644 --- a/lib/bind/irs/nis_nw.c +++ b/lib/bind/irs/nis_nw.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nis_nw.c,v 1.3 2004/03/09 06:30:05 marka Exp $"; +static const char rcsid[] = "$Id: nis_nw.c,v 1.4 2005/04/27 04:56:33 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports */ @@ -381,3 +381,5 @@ init(struct irs_nw *this) { } #endif /*WANT_IRS_NIS*/ + +/*! \file */ diff --git a/lib/bind/irs/nis_p.h b/lib/bind/irs/nis_p.h index ed8fdf10d0..70e2948d67 100644 --- a/lib/bind/irs/nis_p.h +++ b/lib/bind/irs/nis_p.h @@ -16,14 +16,15 @@ */ /* - * $Id: nis_p.h,v 1.2 2004/03/09 06:30:05 marka Exp $ + * $Id: nis_p.h,v 1.3 2005/04/27 04:56:33 sra Exp $ */ -/* +/*! \file + * \brief * nis_p.h - private include file for the NIS functions. */ -/* +/*% * Object state. */ struct nis_p { diff --git a/lib/bind/irs/nis_pr.c b/lib/bind/irs/nis_pr.c index 462c9f67cc..4995550f82 100644 --- a/lib/bind/irs/nis_pr.c +++ b/lib/bind/irs/nis_pr.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nis_pr.c,v 1.3 2004/03/09 06:30:05 marka Exp $"; +static const char rcsid[] = "$Id: nis_pr.c,v 1.4 2005/04/27 04:56:33 sra Exp $"; #endif /* Imports */ @@ -298,3 +298,5 @@ nisfree(struct pvt *pvt, enum do_what do_what) { } #endif /*WANT_IRS_NIS*/ + +/*! \file */ diff --git a/lib/bind/irs/nis_pw.c b/lib/bind/irs/nis_pw.c index 3854777ed0..8f27e4bd93 100644 --- a/lib/bind/irs/nis_pw.c +++ b/lib/bind/irs/nis_pw.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nis_pw.c,v 1.3 2004/03/09 06:30:05 marka Exp $"; +static const char rcsid[] = "$Id: nis_pw.c,v 1.4 2005/04/27 04:56:33 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports */ @@ -230,7 +230,7 @@ makepasswdent(struct irs_pw *this) { if (!(cp = strchr(cp, ':'))) goto cleanup; #ifdef HAS_PW_CLASS - pvt->passwd.pw_class = cp; /* Needs to point at a \0. */ + pvt->passwd.pw_class = cp; /*%< Needs to point at a \0. */ #endif *cp++ = '\0'; @@ -285,3 +285,4 @@ nisfree(struct pvt *pvt, enum do_what do_what) { } #endif /* WANT_IRS_PW && WANT_IRS_NIS */ +/*! \file */ diff --git a/lib/bind/irs/nis_sv.c b/lib/bind/irs/nis_sv.c index 55c94c626e..bb24600f0d 100644 --- a/lib/bind/irs/nis_sv.c +++ b/lib/bind/irs/nis_sv.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nis_sv.c,v 1.3 2004/03/09 06:30:05 marka Exp $"; +static const char rcsid[] = "$Id: nis_sv.c,v 1.4 2005/04/27 04:56:34 sra Exp $"; #endif /* LIBC_SCCS and not lint */ /* Imports */ @@ -306,3 +306,5 @@ nisfree(struct pvt *pvt, enum do_what do_what) { } #endif /*WANT_IRS_NIS*/ + +/*! \file */ diff --git a/lib/bind/irs/nul_ng.c b/lib/bind/irs/nul_ng.c index 3ad36330e9..e5811b563c 100644 --- a/lib/bind/irs/nul_ng.c +++ b/lib/bind/irs/nul_ng.c @@ -16,10 +16,11 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: nul_ng.c,v 1.2 2004/03/09 06:30:05 marka Exp $"; +static const char rcsid[] = "$Id: nul_ng.c,v 1.3 2005/04/27 04:56:34 sra Exp $"; #endif -/* +/*! \file + * \brief * nul_ng.c - the netgroup accessor null map */ diff --git a/lib/bind/irs/pathnames.h b/lib/bind/irs/pathnames.h index 07b891cd14..1646842155 100644 --- a/lib/bind/irs/pathnames.h +++ b/lib/bind/irs/pathnames.h @@ -16,7 +16,7 @@ */ /* - * $Id: pathnames.h,v 1.2 2004/03/09 06:30:06 marka Exp $ + * $Id: pathnames.h,v 1.3 2005/04/27 04:56:34 sra Exp $ */ #ifndef _PATH_IRS_CONF @@ -48,3 +48,5 @@ #ifndef _PATH_HESIOD_CONF #define _PATH_HESIOD_CONF "/etc/hesiod.conf" #endif + +/*! \file */ diff --git a/lib/bind/irs/util.c b/lib/bind/irs/util.c index d689b7a1b9..794c10b107 100644 --- a/lib/bind/irs/util.c +++ b/lib/bind/irs/util.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: util.c,v 1.2 2004/03/09 06:30:06 marka Exp $"; +static const char rcsid[] = "$Id: util.c,v 1.3 2005/04/27 04:56:34 sra Exp $"; #endif #include "port_before.h" @@ -105,3 +105,5 @@ make_group_list(struct irs_gr *this, const char *name, *ngroups = ng; return (ret); } + +/*! \file */ diff --git a/lib/bind/isc/assertions.c b/lib/bind/isc/assertions.c index 32f726516f..393c97fe11 100644 --- a/lib/bind/isc/assertions.c +++ b/lib/bind/isc/assertions.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: assertions.c,v 1.2 2004/03/09 06:30:06 marka Exp $"; +static const char rcsid[] = "$Id: assertions.c,v 1.3 2005/04/27 04:56:34 sra Exp $"; #endif #include "port_before.h" @@ -89,3 +89,5 @@ default_assertion_failed(const char *file, int line, assertion_type type, abort(); /* NOTREACHED */ } + +/*! \file */ diff --git a/lib/bind/isc/base64.c b/lib/bind/isc/base64.c index 9553ac8c90..60b20bca5a 100644 --- a/lib/bind/isc/base64.c +++ b/lib/bind/isc/base64.c @@ -41,7 +41,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: base64.c,v 1.3 2004/03/18 02:57:59 marka Exp $"; +static const char rcsid[] = "$Id: base64.c,v 1.4 2005/04/27 04:56:34 sra Exp $"; #endif /* not lint */ #include "port_before.h" @@ -69,7 +69,7 @@ static const char Base64[] = static const char Pad64 = '='; /* (From RFC1521 and draft-ietf-dnssec-secext-03.txt) - The following encoding technique is taken from RFC 1521 by Borenstein + The following encoding technique is taken from RFC1521 by Borenstein and Freed. It is reproduced here in a slightly edited form for convenience. @@ -187,7 +187,7 @@ b64_ntop(u_char const *src, size_t srclength, char *target, size_t targsize) { } if (datalength >= targsize) return (-1); - target[datalength] = '\0'; /* Returned value doesn't count \0. */ + target[datalength] = '\0'; /*%< Returned value doesn't count \\0. */ return (datalength); } @@ -210,14 +210,14 @@ b64_pton(src, target, targsize) tarindex = 0; while ((ch = *src++) != '\0') { - if (isspace(ch)) /* Skip whitespace anywhere. */ + if (isspace(ch)) /*%< Skip whitespace anywhere. */ continue; if (ch == Pad64) break; pos = strchr(Base64, ch); - if (pos == 0) /* A non-base64 character. */ + if (pos == 0) /*%< A non-base64 character. */ return (-1); switch (state) { @@ -270,14 +270,14 @@ b64_pton(src, target, targsize) * on a byte boundary, and/or with erroneous trailing characters. */ - if (ch == Pad64) { /* We got a pad char. */ - ch = *src++; /* Skip it, get next. */ + if (ch == Pad64) { /*%< We got a pad char. */ + ch = *src++; /*%< Skip it, get next. */ switch (state) { - case 0: /* Invalid = in first position */ - case 1: /* Invalid = in second position */ + case 0: /*%< Invalid = in first position */ + case 1: /*%< Invalid = in second position */ return (-1); - case 2: /* Valid, means one byte of info */ + case 2: /*%< Valid, means one byte of info */ /* Skip any number of spaces. */ for ((void)NULL; ch != '\0'; ch = *src++) if (!isspace(ch)) @@ -285,11 +285,11 @@ b64_pton(src, target, targsize) /* Make sure there is another trailing = sign. */ if (ch != Pad64) return (-1); - ch = *src++; /* Skip the = */ + ch = *src++; /*%< Skip the = */ /* Fall through to "single trailing =" case. */ /* FALLTHROUGH */ - case 3: /* Valid, means two bytes of info */ + case 3: /*%< Valid, means two bytes of info */ /* * We know this char is an =. Is there anything but * whitespace after it? @@ -318,3 +318,5 @@ b64_pton(src, target, targsize) return (tarindex); } + +/*! \file */ diff --git a/lib/bind/isc/bitncmp.c b/lib/bind/isc/bitncmp.c index 0a98a1d17b..7f9a55f19e 100644 --- a/lib/bind/isc/bitncmp.c +++ b/lib/bind/isc/bitncmp.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: bitncmp.c,v 1.2 2004/03/09 06:30:06 marka Exp $"; +static const char rcsid[] = "$Id: bitncmp.c,v 1.3 2005/04/27 04:56:35 sra Exp $"; #endif #include "port_before.h" @@ -29,7 +29,7 @@ static const char rcsid[] = "$Id: bitncmp.c,v 1.2 2004/03/09 06:30:06 marka Exp #include -/* +/*% * int * bitncmp(l, r, n) * compare bit masks l and r, for n bits. @@ -64,3 +64,5 @@ bitncmp(const void *l, const void *r, int n) { } return (0); } + +/*! \file */ diff --git a/lib/bind/isc/ctl_clnt.c b/lib/bind/isc/ctl_clnt.c index 0d26e5090a..a53d8d1e82 100644 --- a/lib/bind/isc/ctl_clnt.c +++ b/lib/bind/isc/ctl_clnt.c @@ -1,5 +1,5 @@ #if !defined(lint) && !defined(SABER) -static const char rcsid[] = "$Id: ctl_clnt.c,v 1.7 2004/03/18 02:58:00 marka Exp $"; +static const char rcsid[] = "$Id: ctl_clnt.c,v 1.8 2005/04/27 04:56:35 sra Exp $"; #endif /* not lint */ /* @@ -122,7 +122,7 @@ static const char * const state_names[] = { /* Public. */ -/* +/*% * void * ctl_client() * create, condition, and connect to a listener on the control port. @@ -198,7 +198,7 @@ ctl_client(evContext lev, const struct sockaddr *cap, size_t cap_len, return (ctx); } -/* +/*% * void * ctl_endclient(ctx) * close a client and release all of its resources. @@ -210,7 +210,7 @@ ctl_endclient(struct ctl_cctx *ctx) { memput(ctx, sizeof *ctx); } -/* +/*% * int * ctl_command(ctx, cmd, len, donefunc, uap) * Queue a transaction, which will begin with sending cmd @@ -600,3 +600,5 @@ timer(evContext ev, void *uap, struct timespec due, struct timespec itv) { ctx->timeout.tv_sec, state_names[ctx->state]); error(ctx); } + +/*! \file */ diff --git a/lib/bind/isc/ctl_p.c b/lib/bind/isc/ctl_p.c index 2604475615..7ab719a5e6 100644 --- a/lib/bind/isc/ctl_p.c +++ b/lib/bind/isc/ctl_p.c @@ -1,5 +1,5 @@ #if !defined(lint) && !defined(SABER) -static const char rcsid[] = "$Id: ctl_p.c,v 1.3 2004/03/18 02:58:00 marka Exp $"; +static const char rcsid[] = "$Id: ctl_p.c,v 1.4 2005/04/27 04:56:35 sra Exp $"; #endif /* not lint */ /* @@ -56,7 +56,7 @@ const char * const ctl_sevnames[] = { /* Public. */ -/* +/*% * ctl_logger() * if ctl_startup()'s caller didn't specify a logger, this one * is used. this pollutes stderr with all kinds of trash so it will @@ -184,3 +184,5 @@ ctl_sa_copy(const struct sockaddr *src, struct sockaddr *dst) { break; } } + +/*! \file */ diff --git a/lib/bind/isc/ctl_p.h b/lib/bind/isc/ctl_p.h index 42aade7d66..18a52ae39c 100644 --- a/lib/bind/isc/ctl_p.h +++ b/lib/bind/isc/ctl_p.h @@ -3,7 +3,7 @@ struct ctl_buf { size_t used; }; -#define MAX_LINELEN 990 /* Like SMTP. */ +#define MAX_LINELEN 990 /*%< Like SMTP. */ #ifndef NO_SOCKADDR_UN #define MAX_NTOP PATH_MAX #else @@ -24,3 +24,5 @@ const char * ctl_sa_ntop(const struct sockaddr *, char *, size_t, ctl_logfunc); void ctl_sa_copy(const struct sockaddr *, struct sockaddr *); + +/*! \file */ diff --git a/lib/bind/isc/ctl_srvr.c b/lib/bind/isc/ctl_srvr.c index 4c3934fcd5..1bf4893804 100644 --- a/lib/bind/isc/ctl_srvr.c +++ b/lib/bind/isc/ctl_srvr.c @@ -1,5 +1,5 @@ #if !defined(lint) && !defined(SABER) -static const char rcsid[] = "$Id: ctl_srvr.c,v 1.6 2004/03/18 02:58:00 marka Exp $"; +static const char rcsid[] = "$Id: ctl_srvr.c,v 1.7 2005/04/27 04:56:35 sra Exp $"; #endif /* not lint */ /* @@ -158,7 +158,7 @@ static const struct ctl_verb fakehelpverb = { /* Public. */ -/* +/*% * void * ctl_server() * create, condition, and start a listener on the control port. @@ -263,7 +263,7 @@ ctl_server(evContext lev, const struct sockaddr *sap, size_t sap_len, return (ctx); } -/* +/*% * void * ctl_endserver(ctx) * if the control listener is open, close it. clean out all eventlib @@ -291,7 +291,7 @@ ctl_endserver(struct ctl_sctx *ctx) { memput(ctx, sizeof *ctx); } -/* +/*% * If body is non-NULL then it we add a "." line after it. * Caller must have escaped lines with leading ".". */ @@ -778,3 +778,5 @@ ctl_signal_done(struct ctl_sctx *ctx, struct ctl_sess *sess) { sess->donefunc = NULL; } } + +/*! \file */ diff --git a/lib/bind/isc/ev_connects.c b/lib/bind/isc/ev_connects.c index 378beb5e17..6baf22a2dc 100644 --- a/lib/bind/isc/ev_connects.c +++ b/lib/bind/isc/ev_connects.c @@ -20,7 +20,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: ev_connects.c,v 1.5 2004/03/09 06:30:07 marka Exp $"; +static const char rcsid[] = "$Id: ev_connects.c,v 1.6 2005/04/27 04:56:35 sra Exp $"; #endif /* Import. */ @@ -69,7 +69,7 @@ evListen(evContext opaqueCtx, int fd, int maxconn, OKNEW(new); new->flags = EV_CONN_LISTEN; - OK(mode = fcntl(fd, F_GETFL, NULL)); /* side effect: validate fd. */ + OK(mode = fcntl(fd, F_GETFL, NULL)); /*%< side effect: validate fd. */ /* * Remember the nonblocking status. We assume that either evSelectFD * has not been done to this fd, or that if it has then the caller @@ -359,9 +359,11 @@ connector(evContext opaqueCtx, void *uap, int fd, int evmask) { GETXXXNAME(getpeername, fd, ra.sa, ralen) < 0) { int save = errno; - (void) close(fd); /* XXX closing caller's fd */ + (void) close(fd); /*%< XXX closing caller's fd */ errno = save; fd = -1; } (*conn_func)(opaqueCtx, conn_uap, fd, &la.sa, lalen, &ra.sa, ralen); } + +/*! \file */ diff --git a/lib/bind/isc/ev_files.c b/lib/bind/isc/ev_files.c index db7e70f08d..bb36cccb5b 100644 --- a/lib/bind/isc/ev_files.c +++ b/lib/bind/isc/ev_files.c @@ -20,7 +20,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: ev_files.c,v 1.5 2004/03/09 06:30:07 marka Exp $"; +static const char rcsid[] = "$Id: ev_files.c,v 1.6 2005/04/27 04:56:35 sra Exp $"; #endif #include "port_before.h" @@ -60,8 +60,7 @@ evSelectFD(evContext opaqueCtx, EV_ERR(EINVAL); if (fd > ctx->highestFD) EV_ERR(EINVAL); - OK(mode = fcntl(fd, F_GETFL, NULL)); /* side effect: validate fd. */ - + OK(mode = fcntl(fd, F_GETFL, NULL)); /*%< side effect: validate fd. */ /* * The first time we touch a file descriptor, we need to check to see * if the application already had it in O_NONBLOCK mode and if so, all @@ -281,3 +280,5 @@ FindFD(const evContext_p *ctx, int fd, int eventmask) { break; return (id); } + +/*! \file */ diff --git a/lib/bind/isc/ev_streams.c b/lib/bind/isc/ev_streams.c index 87506350c5..5dad36d04a 100644 --- a/lib/bind/isc/ev_streams.c +++ b/lib/bind/isc/ev_streams.c @@ -20,7 +20,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: ev_streams.c,v 1.4 2004/03/18 02:58:00 marka Exp $"; +static const char rcsid[] = "$Id: ev_streams.c,v 1.5 2005/04/27 04:56:36 sra Exp $"; #endif #include "port_before.h" @@ -304,3 +304,5 @@ readable(evContext opaqueCtx, void *uap, int fd, int evmask) { if (str->ioDone <= 0 || str->ioDone == str->ioTotal) done(opaqueCtx, str); } + +/*! \file */ diff --git a/lib/bind/isc/ev_timers.c b/lib/bind/isc/ev_timers.c index 16dbc06468..12ac2cebca 100644 --- a/lib/bind/isc/ev_timers.c +++ b/lib/bind/isc/ev_timers.c @@ -20,7 +20,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: ev_timers.c,v 1.5 2004/03/18 02:58:00 marka Exp $"; +static const char rcsid[] = "$Id: ev_timers.c,v 1.6 2005/04/27 04:56:36 sra Exp $"; #endif /* Import. */ @@ -495,3 +495,5 @@ idle_timeout(evContext opaqueCtx, this->timer->inter = evSubTime(this->max_idle, idle); } } + +/*! \file */ diff --git a/lib/bind/isc/ev_waits.c b/lib/bind/isc/ev_waits.c index c9ffd7c9c5..99da1526c7 100644 --- a/lib/bind/isc/ev_waits.c +++ b/lib/bind/isc/ev_waits.c @@ -20,7 +20,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: ev_waits.c,v 1.3 2004/03/09 06:30:07 marka Exp $"; +static const char rcsid[] = "$Id: ev_waits.c,v 1.4 2005/04/27 04:56:36 sra Exp $"; #endif #include "port_before.h" @@ -44,7 +44,7 @@ static evWaitList * evGetWaitList(evContext_p *, const void *, int); /* Public. */ -/* +/*% * Enter a new wait function on the queue. */ int @@ -72,7 +72,7 @@ evWaitFor(evContext opaqueCtx, const void *tag, return (0); } -/* +/*% * Mark runnable all waiting functions having a certain tag. */ int @@ -99,7 +99,7 @@ evDo(evContext opaqueCtx, const void *tag) { return (0); } -/* +/*% * Remove a waiting (or ready to run) function from the queue. */ int @@ -243,3 +243,5 @@ evGetWaitList(evContext_p *ctx, const void *tag, int should_create) { this = evNewWaitList(ctx); return (this); } + +/*! \file */ diff --git a/lib/bind/isc/eventlib.c b/lib/bind/isc/eventlib.c index 31382bf068..1a01dd8fcf 100644 --- a/lib/bind/isc/eventlib.c +++ b/lib/bind/isc/eventlib.c @@ -20,7 +20,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: eventlib.c,v 1.7 2004/12/09 01:40:58 marka Exp $"; +static const char rcsid[] = "$Id: eventlib.c,v 1.8 2005/04/27 04:56:36 sra Exp $"; #endif #include "port_before.h" @@ -85,7 +85,7 @@ evCreate(evContext *opaqueCtx) { FD_ZERO(&ctx->nonblockBefore); ctx->fdMax = -1; ctx->fdNext = NULL; - ctx->fdCount = 0; /* Invalidate {rd,wr,ex}Last. */ + ctx->fdCount = 0; /*%< Invalidate {rd,wr,ex}Last. */ ctx->highestFD = FD_SETSIZE - 1; #ifdef EVENTLIB_TIME_CHECKS ctx->lastFdCount = 0; @@ -126,7 +126,7 @@ evSetDebug(evContext opaqueCtx, int level, FILE *output) { int evDestroy(evContext opaqueCtx) { evContext_p *ctx = opaqueCtx.opaque; - int revs = 424242; /* Doug Adams. */ + int revs = 424242; /*%< Doug Adams. */ evWaitList *this_wl, *next_wl; evWait *this_wait, *next_wait; @@ -242,8 +242,7 @@ evGetNext(evContext opaqueCtx, evEvent *opaqueEv, int options) { nextTime = nextTimer->due; timerPast = (evCmpTime(nextTime, ctx->lastEventTime) <= 0); } else - timerPast = 0; /* Make gcc happy. */ - + timerPast = 0; /*%< Make gcc happy. */ evPrintf(ctx, 9, "evGetNext: fdCount %d\n", ctx->fdCount); if (ctx->fdCount == 0) { static const struct timespec NoTime = {0, 0L}; @@ -730,3 +729,5 @@ pselect(int nfds, void *rfds, void *wfds, void *efds, return (n); } #endif + +/*! \file */ diff --git a/lib/bind/isc/eventlib_p.h b/lib/bind/isc/eventlib_p.h index f56cb5ada1..8244087efa 100644 --- a/lib/bind/isc/eventlib_p.h +++ b/lib/bind/isc/eventlib_p.h @@ -15,10 +15,11 @@ * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* eventlib_p.h - private interfaces for eventlib - * vix 09sep95 [initial] +/*! \file + * \brief private interfaces for eventlib + * \author vix 09sep95 [initial] * - * $Id: eventlib_p.h,v 1.6 2004/12/05 22:41:16 marka Exp $ + * $Id: eventlib_p.h,v 1.7 2005/04/27 04:56:38 sra Exp $ */ #ifndef _EVENTLIB_P_H @@ -68,9 +69,9 @@ typedef struct evConn { void * uap; int fd; int flags; -#define EV_CONN_LISTEN 0x0001 /* Connection is a listener. */ -#define EV_CONN_SELECTED 0x0002 /* evSelectFD(conn->file). */ -#define EV_CONN_BLOCK 0x0004 /* Listener fd was blocking. */ +#define EV_CONN_LISTEN 0x0001 /*%< Connection is a listener. */ +#define EV_CONN_SELECTED 0x0002 /*%< evSelectFD(conn->file). */ +#define EV_CONN_BLOCK 0x0004 /*%< Listener fd was blocking. */ evFileID file; struct evConn * prev; struct evConn * next; @@ -117,7 +118,7 @@ typedef struct evStream { evFileID file; evTimerID timer; int flags; -#define EV_STR_TIMEROK 0x0001 /* IFF timer valid. */ +#define EV_STR_TIMEROK 0x0001 /*%< IFF timer valid. */ int fd; struct iovec * iovOrig; int iovOrigCount; diff --git a/lib/bind/isc/heap.c b/lib/bind/isc/heap.c index 18899f19cb..ae645ae966 100644 --- a/lib/bind/isc/heap.c +++ b/lib/bind/isc/heap.c @@ -15,7 +15,7 @@ * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* +/*% * Heap implementation of priority queues adapted from the following: * * _Introduction to Algorithms_, Cormen, Leiserson, and Rivest, @@ -26,7 +26,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: heap.c,v 1.2 2004/03/09 06:30:08 marka Exp $"; +static const char rcsid[] = "$Id: heap.c,v 1.3 2005/04/27 04:56:38 sra Exp $"; #endif /* not lint */ #include "port_before.h" @@ -39,7 +39,7 @@ static const char rcsid[] = "$Id: heap.c,v 1.2 2004/03/09 06:30:08 marka Exp $"; #include -/* +/*% * Note: to make heap_parent and heap_left easy to compute, the first * element of the heap array is not used; i.e. heap subscripts are 1-based, * not 0-based. @@ -228,3 +228,5 @@ heap_for_each(heap_context ctx, heap_for_each_func action, void *uap) { (action)(ctx->heap[i], uap); return (0); } + +/*! \file */ diff --git a/lib/bind/isc/hex.c b/lib/bind/isc/hex.c index c177ca0fa3..e98a71fcdb 100644 --- a/lib/bind/isc/hex.c +++ b/lib/bind/isc/hex.c @@ -33,7 +33,7 @@ isc_gethexstring(unsigned char *buf, size_t len, int count, FILE *fp, char *s; int result = count; - x = 0; /* silence compiler */ + x = 0; /*%< silence compiler */ n = 0; while (count > 0) { c = fgetc(fp); @@ -114,3 +114,5 @@ isc_tohex(const unsigned char *buf, size_t buflen, char *t) { } *t = '\0'; } + +/*! \file */ diff --git a/lib/bind/isc/logging.c b/lib/bind/isc/logging.c index e27f01d8cb..b2daff40a4 100644 --- a/lib/bind/isc/logging.c +++ b/lib/bind/isc/logging.c @@ -16,7 +16,7 @@ */ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: logging.c,v 1.6 2004/03/18 02:58:00 marka Exp $"; +static const char rcsid[] = "$Id: logging.c,v 1.7 2005/04/27 04:56:38 sra Exp $"; #endif /* not lint */ #include "port_before.h" @@ -258,7 +258,7 @@ log_check(log_context lc, int category, int level) { return (0); if (category < 0 || category > lc->num_categories) - category = 0; /* use default */ + category = 0; /*%< use default */ lcl = lc->categories[category]; if (lcl == NULL) { category = 0; @@ -302,7 +302,7 @@ log_vwrite(log_context lc, int category, int level, const char *format, return; if (category < 0 || category > lc->num_categories) - category = 0; /* use default */ + category = 0; /*%< use default */ original_category = category; lcl = lc->categories[category]; if (lcl == NULL) { @@ -441,7 +441,7 @@ log_write(log_context lc, int category, int level, const char *format, ...) { va_end(args); } -/* +/*% * Functions to create, set, or destroy contexts */ @@ -718,3 +718,5 @@ log_free_channel(log_channel chan) { } return (0); } + +/*! \file */ diff --git a/lib/bind/isc/logging_p.h b/lib/bind/isc/logging_p.h index 99f6976f6c..5e6314f190 100644 --- a/lib/bind/isc/logging_p.h +++ b/lib/bind/isc/logging_p.h @@ -34,7 +34,7 @@ typedef union log_output { } log_output; struct log_channel { - int level; /* don't log messages > level */ + int level; /*%< don't log messages > level */ log_channel_type type; log_output out; unsigned int flags; @@ -58,3 +58,4 @@ struct log_context { }; #endif /* !LOGGING_P_H */ +/*! \file */ diff --git a/lib/bind/isc/memcluster.c b/lib/bind/isc/memcluster.c index 110b904e20..8e25886e30 100644 --- a/lib/bind/isc/memcluster.c +++ b/lib/bind/isc/memcluster.c @@ -24,7 +24,7 @@ #if !defined(LINT) && !defined(CODECENTER) -static const char rcsid[] = "$Id: memcluster.c,v 1.6 2004/09/16 00:56:12 marka Exp $"; +static const char rcsid[] = "$Id: memcluster.c,v 1.7 2005/04/27 04:56:39 sra Exp $"; #endif /* not lint */ #include "port_before.h" @@ -325,7 +325,7 @@ __memget_record(size_t size, const char *file, int line) { #endif } -/* +/*% * This is a call from an external caller, * so we want to count this as a user "put". */ @@ -377,7 +377,7 @@ __memput_record(void *mem, size_t size, const char *file, int line) { prev = el; el = el->next; } - INSIST(el != NULL); /* double free */ + INSIST(el != NULL); /*%< double free */ if (prev == NULL) { if (size == max_size || new_size >= max_size) activelists[max_size] = el->next; @@ -403,8 +403,8 @@ __memput_record(void *mem, size_t size, const char *file, int line) { /* The free list uses the "rounded-up" size "new_size": */ #if defined(DEBUGGING_MEMCLUSTER) - memset(mem, 0xa5, new_size - sizeof *e); /* catch write after free */ - e->size = 0; /* catch double memput() */ + memset(mem, 0xa5, new_size - sizeof *e); /*%< catch write after free */ + e->size = 0; /*%< catch double memput() */ #ifdef MEMCLUSTER_RECORD e->file = file; e->line = line; @@ -454,7 +454,7 @@ __memput_debug(void *ptr, size_t size, const char *file, int line) { __memput_record(ptr, size, file, line); } -/* +/*% * Print the stats[] on the stream "out" with suitable formatting. */ void @@ -508,7 +508,7 @@ memactive(void) { /* Private. */ -/* +/*% * Round up size to a multiple of sizeof(void *). This guarantees that a * block is at least sizeof void *, and that we won't violate alignment * restrictions, both of which are needed to make lists of blocks. @@ -543,3 +543,5 @@ check(unsigned char *a, int value, size_t len) { INSIST(a[i] == value); } #endif + +/*! \file */ diff --git a/lib/bind/isc/movefile.c b/lib/bind/isc/movefile.c index 8582aa72bd..191c46ed4a 100644 --- a/lib/bind/isc/movefile.c +++ b/lib/bind/isc/movefile.c @@ -33,3 +33,5 @@ isc_movefile(const char *oldname, const char *newname) { #else static int os_port_has_isc_movefile = 1; #endif + +/*! \file */ diff --git a/lib/bind/isc/tree.c b/lib/bind/isc/tree.c index 269f206d2d..8ba675fbe8 100644 --- a/lib/bind/isc/tree.c +++ b/lib/bind/isc/tree.c @@ -1,8 +1,8 @@ #ifndef LINT -static const char rcsid[] = "$Id: tree.c,v 1.3 2004/03/09 06:30:09 marka Exp $"; +static const char rcsid[] = "$Id: tree.c,v 1.4 2005/04/27 04:56:39 sra Exp $"; #endif -/* +/*% * tree - balanced binary tree library * * vix 05apr94 [removed vixie.h dependencies; cleaned up formatting, names] @@ -14,7 +14,7 @@ static const char rcsid[] = "$Id: tree.c,v 1.3 2004/03/09 06:30:09 marka Exp $"; * vix 14dec85 [written] */ -/* +/*% * This program text was created by Paul Vixie using examples from the book: * "Algorithms & Data Structures," Niklaus Wirth, Prentice-Hall, 1986, ISBN * 0-13-022005-1. Any errors in the conversion from Modula-2 to C are Paul @@ -215,7 +215,7 @@ sprout(tree **ppr, tree_t p_data, int *pi_balance, MSG("LESS. sprouting left.") sub = sprout(&(*ppr)->left, p_data, pi_balance, pfi_compare, pfv_delete); - if (sub && *pi_balance) { /* left branch has grown */ + if (sub && *pi_balance) { /*%< left branch has grown */ MSG("LESS: left branch has grown") switch ((*ppr)->bal) { case 1: @@ -233,13 +233,13 @@ sprout(tree **ppr, tree_t p_data, int *pi_balance, /* left branch was already too long. rebal */ MSG("LESS: case -1: rebalancing") p1 = (*ppr)->left; - if (p1->bal == -1) { /* LL */ + if (p1->bal == -1) { /*%< LL */ MSG("LESS: single LL") (*ppr)->left = p1->right; p1->right = *ppr; (*ppr)->bal = 0; *ppr = p1; - } else { /* double LR */ + } else { /*%< double LR */ MSG("LESS: double LR") p2 = p1->right; @@ -289,13 +289,13 @@ sprout(tree **ppr, tree_t p_data, int *pi_balance, case 1: MSG("MORE: balance was off, need to rebalance") p1 = (*ppr)->right; - if (p1->bal == 1) { /* RR */ + if (p1->bal == 1) { /*%< RR */ MSG("MORE: single RR") (*ppr)->right = p1->left; p1->left = *ppr; (*ppr)->bal = 0; *ppr = p1; - } else { /* double RL */ + } else { /*%< double RL */ MSG("MORE: double RL") p2 = p1->left; @@ -530,3 +530,5 @@ bal_R(tree **ppr_p, int *pi_balance) { } RETV } + +/*! \file */ diff --git a/lib/bind/nameser/ns_date.c b/lib/bind/nameser/ns_date.c index fa301d7b13..292375af63 100644 --- a/lib/bind/nameser/ns_date.c +++ b/lib/bind/nameser/ns_date.c @@ -16,7 +16,7 @@ */ #ifndef lint -static const char rcsid[] = "$Id: ns_date.c,v 1.5 2004/03/18 02:58:01 marka Exp $"; +static const char rcsid[] = "$Id: ns_date.c,v 1.6 2005/04/27 04:56:39 sra Exp $"; #endif /* Import. */ @@ -45,9 +45,11 @@ static int datepart(const char *, int, int, int, int *); /* Public. */ -/* Convert a date in ASCII into the number of seconds since - 1 January 1970 (GMT assumed). Format is yyyymmddhhmmss, all - digits required, no spaces allowed. */ +/*% + * Convert a date in ASCII into the number of seconds since + * 1 January 1970 (GMT assumed). Format is yyyymmddhhmmss, all + * digits required, no spaces allowed. + */ u_int32_t ns_datetosecs(const char *cp, int *errp) { @@ -70,7 +72,7 @@ ns_datetosecs(const char *cp, int *errp) { time.tm_hour = datepart(cp + 8, 2, 00, 23, errp); time.tm_min = datepart(cp + 10, 2, 00, 59, errp); time.tm_sec = datepart(cp + 12, 2, 00, 59, errp); - if (*errp) /* Any parse errors? */ + if (*errp) /*%< Any parse errors? */ return (0); /* @@ -81,32 +83,29 @@ ns_datetosecs(const char *cp, int *errp) { #define SECS_PER_DAY ((u_int32_t)24*60*60) #define isleap(y) ((((y) % 4) == 0 && ((y) % 100) != 0) || ((y) % 400) == 0) - result = time.tm_sec; /* Seconds */ - result += time.tm_min * 60; /* Minutes */ - result += time.tm_hour * (60*60); /* Hours */ - result += (time.tm_mday - 1) * SECS_PER_DAY; /* Days */ - + result = time.tm_sec; /*%< Seconds */ + result += time.tm_min * 60; /*%< Minutes */ + result += time.tm_hour * (60*60); /*%< Hours */ + result += (time.tm_mday - 1) * SECS_PER_DAY; /*%< Days */ /* Months are trickier. Look without leaping, then leap */ mdays = 0; for (i = 0; i < time.tm_mon; i++) mdays += days_per_month[i]; - result += mdays * SECS_PER_DAY; /* Months */ + result += mdays * SECS_PER_DAY; /*%< Months */ if (time.tm_mon > 1 && isleap(1900+time.tm_year)) - result += SECS_PER_DAY; /* Add leapday for this year */ - + result += SECS_PER_DAY; /*%< Add leapday for this year */ /* First figure years without leapdays, then add them in. */ /* The loop is slow, FIXME, but simple and accurate. */ - result += (time.tm_year - 70) * (SECS_PER_DAY*365); /* Years */ + result += (time.tm_year - 70) * (SECS_PER_DAY*365); /*%< Years */ for (i = 70; i < time.tm_year; i++) if (isleap(1900+i)) - result += SECS_PER_DAY; /* Add leapday for prev year */ - + result += SECS_PER_DAY; /*%< Add leapday for prev year */ return (result); } /* Private. */ -/* +/*% * Parse part of a date. Set error flag if any error. * Don't reset the flag if there is no error. */ @@ -126,3 +125,5 @@ datepart(const char *buf, int size, int min, int max, int *errp) { *errp = 1; return (result); } + +/*! \file */ diff --git a/lib/bind/nameser/ns_name.c b/lib/bind/nameser/ns_name.c index 73724a01f4..9d409f3d95 100644 --- a/lib/bind/nameser/ns_name.c +++ b/lib/bind/nameser/ns_name.c @@ -16,7 +16,7 @@ */ #ifndef lint -static const char rcsid[] = "$Id: ns_name.c,v 1.9 2004/05/04 03:28:31 marka Exp $"; +static const char rcsid[] = "$Id: ns_name.c,v 1.10 2005/04/27 04:56:40 sra Exp $"; #endif #include "port_before.h" @@ -41,7 +41,7 @@ static const char rcsid[] = "$Id: ns_name.c,v 1.9 2004/05/04 03:28:31 marka Exp # define SPRINTF(x) ((size_t)sprintf x) #endif -#define NS_TYPE_ELT 0x40 /* EDNS0 extended label type */ +#define NS_TYPE_ELT 0x40 /*%< EDNS0 extended label type */ #define DNS_LABELTYPE_BITSTRING 0x41 /* Data. */ @@ -83,14 +83,15 @@ static int decode_bitstring(const unsigned char **, /* Public. */ -/* - * ns_name_ntop(src, dst, dstsiz) +/*% * Convert an encoded domain name to printable ascii as per RFC1035. + * return: - * Number of bytes written to buffer, or -1 (with errno set) + *\li Number of bytes written to buffer, or -1 (with errno set) + * * notes: - * The root is returned as "." - * All other domains are returned in non absolute form + *\li The root is returned as "." + *\li All other domains are returned in non absolute form */ int ns_name_ntop(const u_char *src, char *dst, size_t dstsiz) @@ -119,7 +120,7 @@ ns_name_ntop(const u_char *src, char *dst, size_t dstsiz) *dn++ = '.'; } if ((l = labellen(cp - 1)) < 0) { - errno = EMSGSIZE; /* XXX */ + errno = EMSGSIZE; /*%< XXX */ return(-1); } if (dn + l >= eom) { @@ -184,15 +185,17 @@ ns_name_ntop(const u_char *src, char *dst, size_t dstsiz) return (dn - dst); } -/* - * ns_name_pton(src, dst, dstsiz) +/*% * Convert a ascii string into an encoded domain name as per RFC1035. + * * return: - * -1 if it fails - * 1 if string was fully qualified - * 0 is string was not fully qualified + * + *\li -1 if it fails + *\li 1 if string was fully qualified + *\li 0 is string was not fully qualified + * * notes: - * Enforces label and domain length limits. + *\li Enforces label and domain length limits. */ int @@ -209,9 +212,9 @@ ns_name_pton(const char *src, u_char *dst, size_t dstsiz) while ((c = *src++) != 0) { if (escaped) { - if (c == '[') { /* start a bit string label */ + if (c == '[') { /*%< start a bit string label */ if ((cp = strchr(src, ']')) == NULL) { - errno = EINVAL; /* ??? */ + errno = EINVAL; /*%< ??? */ return(-1); } if ((e = encode_bitsring(&src, cp + 2, @@ -256,7 +259,7 @@ ns_name_pton(const char *src, u_char *dst, size_t dstsiz) continue; } else if (c == '.') { c = (bp - label - 1); - if ((c & NS_CMPRSFLGS) != 0) { /* Label too big. */ + if ((c & NS_CMPRSFLGS) != 0) { /*%< Label too big. */ errno = EMSGSIZE; return (-1); } @@ -294,7 +297,7 @@ ns_name_pton(const char *src, u_char *dst, size_t dstsiz) *bp++ = (u_char)c; } c = (bp - label - 1); - if ((c & NS_CMPRSFLGS) != 0) { /* Label too big. */ + if ((c & NS_CMPRSFLGS) != 0) { /*%< Label too big. */ errno = EMSGSIZE; return (-1); } @@ -311,20 +314,21 @@ ns_name_pton(const char *src, u_char *dst, size_t dstsiz) } *bp++ = 0; } - if ((bp - dst) > MAXCDNAME) { /* src too big */ + if ((bp - dst) > MAXCDNAME) { /*%< src too big */ errno = EMSGSIZE; return (-1); } return (0); } -/* - * ns_name_ntol(src, dst, dstsiz) +/*% * Convert a network strings labels into all lowercase. + * * return: - * Number of bytes written to buffer, or -1 (with errno set) + *\li Number of bytes written to buffer, or -1 (with errno set) + * * notes: - * Enforces label and domain length limits. + *\li Enforces label and domain length limits. */ int @@ -371,11 +375,11 @@ ns_name_ntol(const u_char *src, u_char *dst, size_t dstsiz) return (dn - dst); } -/* - * ns_name_unpack(msg, eom, src, dst, dstsiz) +/*% * Unpack a domain name from a message, source may be compressed. + * * return: - * -1 if it fails, or consumed octets if it succeeds. + *\li -1 if it fails, or consumed octets if it succeeds. */ int ns_name_unpack(const u_char *msg, const u_char *eom, const u_char *src, @@ -424,7 +428,7 @@ ns_name_unpack(const u_char *msg, const u_char *eom, const u_char *src, if (len < 0) len = srcp - src + 1; srcp = msg + (((n & 0x3f) << 8) | (*srcp & 0xff)); - if (srcp < msg || srcp >= eom) { /* Out of range. */ + if (srcp < msg || srcp >= eom) { /*%< Out of range. */ errno = EMSGSIZE; return (-1); } @@ -442,7 +446,7 @@ ns_name_unpack(const u_char *msg, const u_char *eom, const u_char *src, default: errno = EMSGSIZE; - return (-1); /* flag error */ + return (-1); /*%< flag error */ } } *dstp = '\0'; @@ -451,19 +455,21 @@ ns_name_unpack(const u_char *msg, const u_char *eom, const u_char *src, return (len); } -/* - * ns_name_pack(src, dst, dstsiz, dnptrs, lastdnptr) +/*% * Pack domain name 'domain' into 'comp_dn'. + * * return: - * Size of the compressed name, or -1. + *\li Size of the compressed name, or -1. + * * notes: - * 'dnptrs' is an array of pointers to previous compressed names. - * dnptrs[0] is a pointer to the beginning of the message. The array + *\li 'dnptrs' is an array of pointers to previous compressed names. + *\li dnptrs[0] is a pointer to the beginning of the message. The array * ends with NULL. - * 'lastdnptr' is a pointer to the end of the array pointed to + *\li 'lastdnptr' is a pointer to the end of the array pointed to * by 'dnptrs'. + * * Side effects: - * The list of pointers in dnptrs is updated for labels inserted into + *\li The list of pointers in dnptrs is updated for labels inserted into * the message as we compress the name. If 'dnptr' is NULL, we don't * try to compress names. If 'lastdnptr' is NULL, we don't update the * list. @@ -485,7 +491,7 @@ ns_name_pack(const u_char *src, u_char *dst, int dstsiz, if ((msg = *dnptrs++) != NULL) { for (cpp = dnptrs; *cpp != NULL; cpp++) (void)NULL; - lpp = cpp; /* end of list to search */ + lpp = cpp; /*%< end of list to search */ } } else msg = NULL; @@ -560,13 +566,14 @@ cleanup: return (dstp - dst); } -/* - * ns_name_uncompress(msg, eom, src, dst, dstsiz) +/*% * Expand compressed domain name to presentation format. + * * return: - * Number of bytes read out of `src', or -1 (with errno set). + *\li Number of bytes read out of `src', or -1 (with errno set). + * * note: - * Root domain returns as "." not "". + *\li Root domain returns as "." not "". */ int ns_name_uncompress(const u_char *msg, const u_char *eom, const u_char *src, @@ -582,18 +589,19 @@ ns_name_uncompress(const u_char *msg, const u_char *eom, const u_char *src, return (n); } -/* - * ns_name_compress(src, dst, dstsiz, dnptrs, lastdnptr) +/*% * Compress a domain name into wire format, using compression pointers. + * * return: - * Number of bytes consumed in `dst' or -1 (with errno set). + *\li Number of bytes consumed in `dst' or -1 (with errno set). + * * notes: - * 'dnptrs' is an array of pointers to previous compressed names. - * dnptrs[0] is a pointer to the beginning of the message. - * The list ends with NULL. 'lastdnptr' is a pointer to the end of the + *\li 'dnptrs' is an array of pointers to previous compressed names. + *\li dnptrs[0] is a pointer to the beginning of the message. + *\li The list ends with NULL. 'lastdnptr' is a pointer to the end of the * array pointed to by 'dnptrs'. Side effect is to update the list of * pointers for labels inserted into the message as we compress the name. - * If 'dnptr' is NULL, we don't try to compress names. If 'lastdnptr' + *\li If 'dnptr' is NULL, we don't try to compress names. If 'lastdnptr' * is NULL, we don't update the list. */ int @@ -607,7 +615,7 @@ ns_name_compress(const char *src, u_char *dst, size_t dstsiz, return (ns_name_pack(tmp, dst, dstsiz, dnptrs, lastdnptr)); } -/* +/*% * Reset dnptrs so that there are no active references to pointers at or * after src. */ @@ -624,11 +632,11 @@ ns_name_rollback(const u_char *src, const u_char **dnptrs, } } -/* - * ns_name_skip(ptrptr, eom) +/*% * Advance *ptrptr to skip over the compressed name it points at. + * * return: - * 0 on success, -1 (with errno set) on failure. + *\li 0 on success, -1 (with errno set) on failure. */ int ns_name_skip(const u_char **ptrptr, const u_char *eom) @@ -641,20 +649,20 @@ ns_name_skip(const u_char **ptrptr, const u_char *eom) while (cp < eom && (n = *cp++) != 0) { /* Check for indirection. */ switch (n & NS_CMPRSFLGS) { - case 0: /* normal case, n == len */ + case 0: /*%< normal case, n == len */ cp += n; continue; - case NS_TYPE_ELT: /* EDNS0 extended label */ + case NS_TYPE_ELT: /*%< EDNS0 extended label */ if ((l = labellen(cp - 1)) < 0) { - errno = EMSGSIZE; /* XXX */ + errno = EMSGSIZE; /*%< XXX */ return(-1); } cp += l; continue; - case NS_CMPRSFLGS: /* indirection */ + case NS_CMPRSFLGS: /*%< indirection */ cp++; break; - default: /* illegal type */ + default: /*%< illegal type */ errno = EMSGSIZE; return (-1); } @@ -670,44 +678,44 @@ ns_name_skip(const u_char **ptrptr, const u_char *eom) /* Private. */ -/* - * special(ch) +/*% * Thinking in noninternationalized USASCII (per the DNS spec), * is this characted special ("in need of quoting") ? + * * return: - * boolean. + *\li boolean. */ static int special(int ch) { switch (ch) { - case 0x22: /* '"' */ - case 0x2E: /* '.' */ - case 0x3B: /* ';' */ - case 0x5C: /* '\\' */ - case 0x28: /* '(' */ - case 0x29: /* ')' */ + case 0x22: /*%< '"' */ + case 0x2E: /*%< '.' */ + case 0x3B: /*%< ';' */ + case 0x5C: /*%< '\\' */ + case 0x28: /*%< '(' */ + case 0x29: /*%< ')' */ /* Special modifiers in zone files. */ - case 0x40: /* '@' */ - case 0x24: /* '$' */ + case 0x40: /*%< '@' */ + case 0x24: /*%< '$' */ return (1); default: return (0); } } -/* - * printable(ch) +/*% * Thinking in noninternationalized USASCII (per the DNS spec), * is this character visible and not a space when printed ? + * * return: - * boolean. + *\li boolean. */ static int printable(int ch) { return (ch > 0x20 && ch < 0x7f); } -/* +/*% * Thinking in noninternationalized USASCII (per the DNS spec), * convert this character to lower case if it's upper case. */ @@ -718,14 +726,15 @@ mklower(int ch) { return (ch); } -/* - * dn_find(domain, msg, dnptrs, lastdnptr) +/*% * Search for the counted-label name in an array of compressed names. + * * return: - * offset from msg if found, or -1. + *\li offset from msg if found, or -1. + * * notes: - * dnptrs is the pointer to the first name on the list, - * not the pointer to the start of the message. + *\li dnptrs is the pointer to the first name on the list, + *\li not the pointer to the start of the message. */ static int dn_find(const u_char *domain, const u_char *msg, @@ -753,9 +762,8 @@ dn_find(const u_char *domain, const u_char *msg, * check for indirection */ switch (n & NS_CMPRSFLGS) { - case 0: /* normal case, n == len */ - n = labellen(cp - 1); /* XXX */ - + case 0: /*%< normal case, n == len */ + n = labellen(cp - 1); /*%< XXX */ if (n != *dn++) goto next; @@ -769,11 +777,11 @@ dn_find(const u_char *domain, const u_char *msg, if (*dn) continue; goto next; - case NS_CMPRSFLGS: /* indirection */ + case NS_CMPRSFLGS: /*%< indirection */ cp = msg + (((n & 0x3f) << 8) | *cp); break; - default: /* illegal type */ + default: /*%< illegal type */ errno = EMSGSIZE; return (-1); } @@ -855,12 +863,12 @@ encode_bitsring(const char **bp, const char *end, unsigned char **labelp, /* XXX: currently, only hex strings are supported */ if (*cp++ != 'x') return(EINVAL); - if (!isxdigit((*cp) & 0xff)) /* reject '\[x/BLEN]' */ + if (!isxdigit((*cp) & 0xff)) /*%< reject '\[x/BLEN]' */ return(EINVAL); for (tp = *dst + 1; cp < end && tp < eom; cp++) { switch((c = *cp)) { - case ']': /* end of the bitstring */ + case ']': /*%< end of the bitstring */ if (afterslash) { if (beg_blen == NULL) return(EINVAL); @@ -870,7 +878,7 @@ encode_bitsring(const char **bp, const char *end, unsigned char **labelp, } if (count) *tp++ = ((value << 4) & 0xff); - cp++; /* skip ']' */ + cp++; /*%< skip ']' */ goto done; case '/': afterslash = 1; @@ -914,14 +922,14 @@ encode_bitsring(const char **bp, const char *end, unsigned char **labelp, * MUST be just sufficient to contain the number of bits specified * by the . If there are insignificant bits in a final * hexadecimal or octal digit, they MUST be zero. - * RFC 2673, Section 3.2. + * RFC2673, Section 3.2. */ if (blen > 0) { int traillen; if (((blen + 3) & ~3) != tbcount) return(EINVAL); - traillen = tbcount - blen; /* between 0 and 3 */ + traillen = tbcount - blen; /*%< between 0 and 3 */ if (((value << (8 - traillen)) & 0xff) != 0) return(EINVAL); } @@ -957,7 +965,9 @@ labellen(const u_char *lp) bitlen = 256; return((bitlen + 7 ) / 8 + 1); } - return(-1); /* unknwon ELT */ + return(-1); /*%< unknwon ELT */ } return(l); } + +/*! \file */ diff --git a/lib/bind/nameser/ns_netint.c b/lib/bind/nameser/ns_netint.c index c1df837b69..559c9d5bd5 100644 --- a/lib/bind/nameser/ns_netint.c +++ b/lib/bind/nameser/ns_netint.c @@ -16,7 +16,7 @@ */ #ifndef lint -static const char rcsid[] = "$Id: ns_netint.c,v 1.2 2004/03/09 06:30:09 marka Exp $"; +static const char rcsid[] = "$Id: ns_netint.c,v 1.3 2005/04/27 04:56:40 sra Exp $"; #endif /* Import. */ @@ -54,3 +54,5 @@ void ns_put32(u_long src, u_char *dst) { NS_PUT32(src, dst); } + +/*! \file */ diff --git a/lib/bind/nameser/ns_parse.c b/lib/bind/nameser/ns_parse.c index de2df28622..7487be39a2 100644 --- a/lib/bind/nameser/ns_parse.c +++ b/lib/bind/nameser/ns_parse.c @@ -16,7 +16,7 @@ */ #ifndef lint -static const char rcsid[] = "$Id: ns_parse.c,v 1.5 2004/03/09 06:30:09 marka Exp $"; +static const char rcsid[] = "$Id: ns_parse.c,v 1.6 2005/04/27 04:56:40 sra Exp $"; #endif /* Import. */ @@ -46,22 +46,22 @@ static void setsection(ns_msg *msg, ns_sect sect); /* These need to be in the same order as the nres.h:ns_flag enum. */ struct _ns_flagdata _ns_flagdata[16] = { - { 0x8000, 15 }, /* qr. */ - { 0x7800, 11 }, /* opcode. */ - { 0x0400, 10 }, /* aa. */ - { 0x0200, 9 }, /* tc. */ - { 0x0100, 8 }, /* rd. */ - { 0x0080, 7 }, /* ra. */ - { 0x0040, 6 }, /* z. */ - { 0x0020, 5 }, /* ad. */ - { 0x0010, 4 }, /* cd. */ - { 0x000f, 0 }, /* rcode. */ - { 0x0000, 0 }, /* expansion (1/6). */ - { 0x0000, 0 }, /* expansion (2/6). */ - { 0x0000, 0 }, /* expansion (3/6). */ - { 0x0000, 0 }, /* expansion (4/6). */ - { 0x0000, 0 }, /* expansion (5/6). */ - { 0x0000, 0 }, /* expansion (6/6). */ + { 0x8000, 15 }, /*%< qr. */ + { 0x7800, 11 }, /*%< opcode. */ + { 0x0400, 10 }, /*%< aa. */ + { 0x0200, 9 }, /*%< tc. */ + { 0x0100, 8 }, /*%< rd. */ + { 0x0080, 7 }, /*%< ra. */ + { 0x0040, 6 }, /*%< z. */ + { 0x0020, 5 }, /*%< ad. */ + { 0x0010, 4 }, /*%< cd. */ + { 0x000f, 0 }, /*%< rcode. */ + { 0x0000, 0 }, /*%< expansion (1/6). */ + { 0x0000, 0 }, /*%< expansion (2/6). */ + { 0x0000, 0 }, /*%< expansion (3/6). */ + { 0x0000, 0 }, /*%< expansion (4/6). */ + { 0x0000, 0 }, /*%< expansion (5/6). */ + { 0x0000, 0 }, /*%< expansion (6/6). */ }; int ns_msg_getflag(ns_msg handle, int flag) { @@ -201,3 +201,5 @@ setsection(ns_msg *msg, ns_sect sect) { msg->_msg_ptr = msg->_sections[(int)sect]; } } + +/*! \file */ diff --git a/lib/bind/nameser/ns_print.c b/lib/bind/nameser/ns_print.c index d74e878a5a..6a23e9add6 100644 --- a/lib/bind/nameser/ns_print.c +++ b/lib/bind/nameser/ns_print.c @@ -16,7 +16,7 @@ */ #ifndef lint -static const char rcsid[] = "$Id: ns_print.c,v 1.9 2004/09/16 07:02:52 marka Exp $"; +static const char rcsid[] = "$Id: ns_print.c,v 1.10 2005/04/27 04:56:40 sra Exp $"; #endif /* Import. */ @@ -69,12 +69,11 @@ static int addtab(size_t len, size_t target, int spaced, /* Public. */ -/* - * int - * ns_sprintrr(handle, rr, name_ctx, origin, buf, buflen) +/*% * Convert an RR to presentation format. + * * return: - * Number of characters written to buf, or -1 (check errno). + *\li Number of characters written to buf, or -1 (check errno). */ int ns_sprintrr(const ns_msg *handle, const ns_rr *rr, @@ -90,13 +89,11 @@ ns_sprintrr(const ns_msg *handle, const ns_rr *rr, return (n); } -/* - * int - * ns_sprintrrf(msg, msglen, name, class, type, ttl, rdata, rdlen, - * name_ctx, origin, buf, buflen) +/*% * Convert the fields of an RR into presentation format. + * * return: - * Number of characters written to buf, or -1 (check errno). + *\li Number of characters written to buf, or -1 (check errno). */ int ns_sprintrrf(const u_char *msg, size_t msglen, @@ -645,10 +642,10 @@ ns_sprintrrf(const u_char *msg, size_t msglen, T(len = addname(msg, msglen, &rdata, origin, &buf, &buflen)); T(addstr(" ", 1, &buf, &buflen)); - rdata += 8; /* time */ + rdata += 8; /*%< time */ n = ns_get16(rdata); rdata += INT16SZ; - rdata += n; /* sig */ - n = ns_get16(rdata); rdata += INT16SZ; /* original id */ + rdata += n; /*%< sig */ + n = ns_get16(rdata); rdata += INT16SZ; /*%< original id */ sprintf(buf, "%d", ns_get16(rdata)); rdata += INT16SZ; addlen(strlen(buf), &buf, &buflen); @@ -735,7 +732,7 @@ ns_sprintrrf(const u_char *msg, size_t msglen, /* Private. */ -/* +/*% * size_t * prune_origin(name, origin) * Find out if the name is at or under the current origin. @@ -768,7 +765,7 @@ prune_origin(const char *name, const char *origin) { return (name - oname); } -/* +/*% * int * charstr(rdata, edata, buf, buflen) * Format a into the presentation buffer. @@ -824,7 +821,7 @@ addname(const u_char *msg, size_t msglen, n = dn_expand(msg, msg + msglen, *pp, *buf, *buflen); if (n < 0) - goto enospc; /* Guess. */ + goto enospc; /*%< Guess. */ newlen = prune_origin(*buf, origin); if (**buf == '\0') { goto root; @@ -896,3 +893,5 @@ addtab(size_t len, size_t target, int spaced, char **buf, size_t *buflen) { } return (spaced); } + +/*! \file */ diff --git a/lib/bind/nameser/ns_samedomain.c b/lib/bind/nameser/ns_samedomain.c index 0473a9b5af..5e9f5cab54 100644 --- a/lib/bind/nameser/ns_samedomain.c +++ b/lib/bind/nameser/ns_samedomain.c @@ -16,7 +16,7 @@ */ #ifndef lint -static const char rcsid[] = "$Id: ns_samedomain.c,v 1.5 2004/03/18 02:58:01 marka Exp $"; +static const char rcsid[] = "$Id: ns_samedomain.c,v 1.6 2005/04/27 04:56:40 sra Exp $"; #endif #include "port_before.h" @@ -28,21 +28,22 @@ static const char rcsid[] = "$Id: ns_samedomain.c,v 1.5 2004/03/18 02:58:01 mark #include "port_after.h" -/* - * int - * ns_samedomain(a, b) +/*% * Check whether a name belongs to a domain. + * * Inputs: - * a - the domain whose ancestory is being verified - * b - the potential ancestor we're checking against + *\li a - the domain whose ancestory is being verified + *\li b - the potential ancestor we're checking against + * * Return: - * boolean - is a at or below b? + *\li boolean - is a at or below b? + * * Notes: - * Trailing dots are first removed from name and domain. + *\li Trailing dots are first removed from name and domain. * Always compare complete subdomains, not only whether the * domain name is the trailing string of the given name. * - * "host.foobar.top" lies in "foobar.top" and in "top" and in "" + *\li "host.foobar.top" lies in "foobar.top" and in "top" and in "" * but NOT in "bar.top" */ @@ -140,9 +141,7 @@ ns_samedomain(const char *a, const char *b) { return (strncasecmp(cp, b, lb) == 0); } -/* - * int - * ns_subdomain(a, b) +/*% * is "a" a subdomain of "b"? */ int @@ -150,30 +149,31 @@ ns_subdomain(const char *a, const char *b) { return (ns_samename(a, b) != 1 && ns_samedomain(a, b)); } -/* - * int - * ns_makecanon(src, dst, dstsize) +/*% * make a canonical copy of domain name "src" + * * notes: + * \code * foo -> foo. * foo. -> foo. * foo.. -> foo. * foo\. -> foo\.. * foo\\. -> foo\\. + * \endcode */ int ns_makecanon(const char *src, char *dst, size_t dstsize) { size_t n = strlen(src); - if (n + sizeof "." > dstsize) { /* Note: sizeof == 2 */ + if (n + sizeof "." > dstsize) { /*%< Note: sizeof == 2 */ errno = EMSGSIZE; return (-1); } strcpy(dst, src); - while (n >= 1U && dst[n - 1] == '.') /* Ends in "." */ - if (n >= 2U && dst[n - 2] == '\\' && /* Ends in "\." */ - (n < 3U || dst[n - 3] != '\\')) /* But not "\\." */ + while (n >= 1U && dst[n - 1] == '.') /*%< Ends in "." */ + if (n >= 2U && dst[n - 2] == '\\' && /*%< Ends in "\." */ + (n < 3U || dst[n - 3] != '\\')) /*%< But not "\\." */ break; else dst[--n] = '\0'; @@ -182,14 +182,13 @@ ns_makecanon(const char *src, char *dst, size_t dstsize) { return (0); } -/* - * int - * ns_samename(a, b) +/*% * determine whether domain name "a" is the same as domain name "b" + * * return: - * -1 on error - * 0 if names differ - * 1 if names are the same + *\li -1 on error + *\li 0 if names differ + *\li 1 if names are the same */ int @@ -204,3 +203,5 @@ ns_samename(const char *a, const char *b) { else return (0); } + +/*! \file */ diff --git a/lib/bind/nameser/ns_sign.c b/lib/bind/nameser/ns_sign.c index 8b34233f48..724e17daae 100644 --- a/lib/bind/nameser/ns_sign.c +++ b/lib/bind/nameser/ns_sign.c @@ -16,7 +16,7 @@ */ #ifndef lint -static const char rcsid[] = "$Id: ns_sign.c,v 1.4 2004/03/09 06:30:10 marka Exp $"; +static const char rcsid[] = "$Id: ns_sign.c,v 1.5 2005/04/27 04:56:40 sra Exp $"; #endif /* Import. */ @@ -53,24 +53,26 @@ static const char rcsid[] = "$Id: ns_sign.c,v 1.4 2004/03/09 06:30:10 marka Exp } \ } while (0) -/* ns_sign +/*% + * ns_sign + * * Parameters: - * msg message to be sent - * msglen input - length of message + *\li msg message to be sent + *\li msglen input - length of message * output - length of signed message - * msgsize length of buffer containing message - * error value to put in the error field - * key tsig key used for signing - * querysig (response), the signature in the query - * querysiglen (response), the length of the signature in the query - * sig a buffer to hold the generated signature - * siglen input - length of signature buffer + *\li msgsize length of buffer containing message + *\li error value to put in the error field + *\li key tsig key used for signing + *\li querysig (response), the signature in the query + *\li querysiglen (response), the length of the signature in the query + *\li sig a buffer to hold the generated signature + *\li siglen input - length of signature buffer * output - length of signature * * Errors: - * - bad input data (-1) - * - bad key / sign failed (-BADKEY) - * - not enough space (NS_TSIG_ERROR_NO_SPACE) + *\li - bad input data (-1) + *\li - bad key / sign failed (-BADKEY) + *\li - not enough space (NS_TSIG_ERROR_NO_SPACE) */ int ns_sign(u_char *msg, int *msglen, int msgsize, int error, void *k, @@ -121,7 +123,7 @@ ns_sign2(u_char *msg, int *msglen, int msgsize, int error, void *k, BOUNDS_CHECK(cp, INT16SZ + INT16SZ + INT32SZ + INT16SZ); PUTSHORT(ns_t_tsig, cp); PUTSHORT(ns_c_any, cp); - PUTLONG(0, cp); /* TTL */ + PUTLONG(0, cp); /*%< TTL */ lenp = cp; cp += 2; @@ -188,18 +190,18 @@ ns_sign2(u_char *msg, int *msglen, int msgsize, int error, void *k, /* Digest the time signed, fudge, error, and other data */ cp2 = buf; - PUTSHORT(0, cp2); /* Top 16 bits of time */ + PUTSHORT(0, cp2); /*%< Top 16 bits of time */ if (error != ns_r_badtime) PUTLONG(timesigned, cp2); else PUTLONG(in_timesigned, cp2); PUTSHORT(NS_TSIG_FUDGE, cp2); - PUTSHORT(error, cp2); /* Error */ + PUTSHORT(error, cp2); /*%< Error */ if (error != ns_r_badtime) - PUTSHORT(0, cp2); /* Other data length */ + PUTSHORT(0, cp2); /*%< Other data length */ else { - PUTSHORT(INT16SZ+INT32SZ, cp2); /* Other data length */ - PUTSHORT(0, cp2); /* Top 16 bits of time */ + PUTSHORT(INT16SZ+INT32SZ, cp2); /*%< Other data length */ + PUTSHORT(0, cp2); /*%< Top 16 bits of time */ PUTLONG(timesigned, cp2); } dst_sign_data(SIG_MODE_UPDATE, key, &ctx, buf, cp2-buf, @@ -221,17 +223,17 @@ ns_sign2(u_char *msg, int *msglen, int msgsize, int error, void *k, /* The original message ID & error. */ BOUNDS_CHECK(cp, INT16SZ + INT16SZ); - PUTSHORT(ntohs(hp->id), cp); /* already in network order */ + PUTSHORT(ntohs(hp->id), cp); /*%< already in network order */ PUTSHORT(error, cp); /* Other data. */ BOUNDS_CHECK(cp, INT16SZ); if (error != ns_r_badtime) - PUTSHORT(0, cp); /* Other data length */ + PUTSHORT(0, cp); /*%< Other data length */ else { - PUTSHORT(INT16SZ+INT32SZ, cp); /* Other data length */ + PUTSHORT(INT16SZ+INT32SZ, cp); /*%< Other data length */ BOUNDS_CHECK(cp, INT32SZ+INT16SZ); - PUTSHORT(0, cp); /* Top 16 bits of time */ + PUTSHORT(0, cp); /*%< Top 16 bits of time */ PUTLONG(timesigned, cp); } @@ -320,7 +322,7 @@ ns_sign_tcp2(u_char *msg, int *msglen, int msgsize, int error, BOUNDS_CHECK(cp, INT16SZ + INT16SZ + INT32SZ + INT16SZ); PUTSHORT(ns_t_tsig, cp); PUTSHORT(ns_c_any, cp); - PUTLONG(0, cp); /* TTL */ + PUTLONG(0, cp); /*%< TTL */ lenp = cp; cp += 2; @@ -343,7 +345,7 @@ ns_sign_tcp2(u_char *msg, int *msglen, int msgsize, int error, /* Digest the time signed and fudge. */ cp2 = buf; - PUTSHORT(0, cp2); /* Top 16 bits of time */ + PUTSHORT(0, cp2); /*%< Top 16 bits of time */ PUTLONG(timesigned, cp2); PUTSHORT(NS_TSIG_FUDGE, cp2); @@ -364,7 +366,7 @@ ns_sign_tcp2(u_char *msg, int *msglen, int msgsize, int error, /* The original message ID & error. */ BOUNDS_CHECK(cp, INT16SZ + INT16SZ); - PUTSHORT(ntohs(hp->id), cp); /* already in network order */ + PUTSHORT(ntohs(hp->id), cp); /*%< already in network order */ PUTSHORT(error, cp); /* Other data. */ @@ -378,3 +380,5 @@ ns_sign_tcp2(u_char *msg, int *msglen, int msgsize, int error, *msglen = (cp - msg); return (0); } + +/*! \file */ diff --git a/lib/bind/nameser/ns_ttl.c b/lib/bind/nameser/ns_ttl.c index d5acda4dc0..4f36b596dd 100644 --- a/lib/bind/nameser/ns_ttl.c +++ b/lib/bind/nameser/ns_ttl.c @@ -16,7 +16,7 @@ */ #ifndef lint -static const char rcsid[] = "$Id: ns_ttl.c,v 1.2 2004/03/09 06:30:10 marka Exp $"; +static const char rcsid[] = "$Id: ns_ttl.c,v 1.3 2005/04/27 04:56:40 sra Exp $"; #endif /* Import. */ @@ -157,3 +157,5 @@ fmt1(int t, char s, char **buf, size_t *buflen) { *buflen -= len; return (0); } + +/*! \file */ diff --git a/lib/bind/nameser/ns_verify.c b/lib/bind/nameser/ns_verify.c index cf0edd5506..cbd2614db8 100644 --- a/lib/bind/nameser/ns_verify.c +++ b/lib/bind/nameser/ns_verify.c @@ -16,7 +16,7 @@ */ #ifndef lint -static const char rcsid[] = "$Id: ns_verify.c,v 1.2 2004/03/09 06:30:10 marka Exp $"; +static const char rcsid[] = "$Id: ns_verify.c,v 1.3 2005/04/27 04:56:41 sra Exp $"; #endif /* Import. */ @@ -107,28 +107,29 @@ ns_find_tsig(u_char *msg, u_char *eom) { } /* ns_verify + * * Parameters: - * statp res stuff - * msg received message - * msglen length of message - * key tsig key used for verifying. - * querysig (response), the signature in the query - * querysiglen (response), the length of the signature in the query - * sig (query), a buffer to hold the signature - * siglen (query), input - length of signature buffer + *\li statp res stuff + *\li msg received message + *\li msglen length of message + *\li key tsig key used for verifying. + *\li querysig (response), the signature in the query + *\li querysiglen (response), the length of the signature in the query + *\li sig (query), a buffer to hold the signature + *\li siglen (query), input - length of signature buffer * output - length of signature * * Errors: - * - bad input (-1) - * - invalid dns message (NS_TSIG_ERROR_FORMERR) - * - TSIG is not present (NS_TSIG_ERROR_NO_TSIG) - * - key doesn't match (-ns_r_badkey) - * - TSIG verification fails with BADKEY (-ns_r_badkey) - * - TSIG verification fails with BADSIG (-ns_r_badsig) - * - TSIG verification fails with BADTIME (-ns_r_badtime) - * - TSIG verification succeeds, error set to BAKEY (ns_r_badkey) - * - TSIG verification succeeds, error set to BADSIG (ns_r_badsig) - * - TSIG verification succeeds, error set to BADTIME (ns_r_badtime) + *\li - bad input (-1) + *\li - invalid dns message (NS_TSIG_ERROR_FORMERR) + *\li - TSIG is not present (NS_TSIG_ERROR_NO_TSIG) + *\li - key doesn't match (-ns_r_badkey) + *\li - TSIG verification fails with BADKEY (-ns_r_badkey) + *\li - TSIG verification fails with BADSIG (-ns_r_badsig) + *\li - TSIG verification fails with BADTIME (-ns_r_badtime) + *\li - TSIG verification succeeds, error set to BAKEY (ns_r_badkey) + *\li - TSIG verification succeeds, error set to BADSIG (ns_r_badsig) + *\li - TSIG verification succeeds, error set to BADTIME (ns_r_badtime) */ int ns_verify(u_char *msg, int *msglen, void *k, @@ -449,7 +450,7 @@ ns_verify_tcp(u_char *msg, int *msglen, ns_tcp_tsig_state *state, /* Digest the time signed and fudge. */ cp2 = buf; - PUTSHORT(0, cp2); /* Top 16 bits of time. */ + PUTSHORT(0, cp2); /*%< Top 16 bits of time. */ PUTLONG(timesigned, cp2); PUTSHORT(NS_TSIG_FUDGE, cp2); @@ -478,3 +479,5 @@ ns_verify_tcp(u_char *msg, int *msglen, ns_tcp_tsig_state *state, return (0); } + +/*! \file */ diff --git a/lib/bind/port_after.h.in b/lib/bind/port_after.h.in index c043561b16..a6608450ee 100644 --- a/lib/bind/port_after.h.in +++ b/lib/bind/port_after.h.in @@ -31,7 +31,7 @@ /* XXX sunos and cygwin needs O_NDELAY */ #define PORT_NONBLOCK O_NONBLOCK -/* +/*! \brief * We need to know the IPv6 address family number even on IPv4-only systems. * Note that this is NOT a protocol constant, and that if the system has its * own AF_INET6, different from ours below, all of BIND's libraries and @@ -69,18 +69,17 @@ struct in6_addr { /* Replace with structure from later rev of O/S if known. */ struct sockaddr_in6 { #ifdef HAVE_SA_LEN - u_int8_t sin6_len; /* length of this struct */ - u_int8_t sin6_family; /* AF_INET6 */ + u_int8_t sin6_len; /*!< \brief length of this struct */ + u_int8_t sin6_family; /*!< \brief AF_INET6 */ #else - u_int16_t sin6_family; /* AF_INET6 */ + u_int16_t sin6_family; /*!< \brief AF_INET6 */ #endif - u_int16_t sin6_port; /* transport layer port # */ - u_int32_t sin6_flowinfo; /* IPv6 flow information */ - struct in6_addr sin6_addr; /* IPv6 address */ - u_int32_t sin6_scope_id; /* set of interfaces for a scope */ + u_int16_t sin6_port; /*!< \brief transport layer port # */ + u_int32_t sin6_flowinfo; /*!< \brief IPv6 flow information */ + struct in6_addr sin6_addr; /*!< \brief IPv6 address */ + u_int32_t sin6_scope_id; /*!< \brief set of interfaces for a scope */ }; #endif /* HAS_INET6_STRUCTS */ - #ifdef BROKEN_IN6ADDR_INIT_MACROS #undef IN6ADDR_ANY_INIT #undef IN6ADDR_LOOPBACK_INIT @@ -129,13 +128,13 @@ struct sockaddr_in6 { struct sockaddr_storage { #ifdef HAVE_SA_LEN - u_int8_t ss_len; /* address length */ - u_int8_t ss_family; /* address family */ + u_int8_t ss_len; /*!< \brief address length */ + u_int8_t ss_family; /*!< \brief address family */ char __ss_pad1[__SS_ALLIGSIZE - 2 * sizeof(u_int8_t)]; long __ss_align; char __ss_pad2[__SS_MAXSIZE - 2 * __SS_ALLIGSIZE]; #else - u_int16_t ss_family; /* address family */ + u_int16_t ss_family; /*!< \brief address family */ char __ss_pad1[__SS_ALLIGSIZE - sizeof(u_int16_t)]; long __ss_align; char __ss_pad2[__SS_MAXSIZE - 2 * __SS_ALLIGSIZE]; @@ -149,7 +148,7 @@ struct sockaddr_storage { extern const struct in6_addr in6addr_any; #endif -/* +/*! \brief * IN6_ARE_ADDR_EQUAL, IN6_IS_ADDR_UNSPECIFIED, IN6_IS_ADDR_V4COMPAT and * IN6_IS_ADDR_V4MAPPED are broken in glibc 2.1. */ @@ -406,3 +405,5 @@ NGR_R_SET_RETURN setnetgrent_r(const char *netgroup); #endif #endif + +/*! \file */ diff --git a/lib/bind/port_before.h.in b/lib/bind/port_before.h.in index d6fbe86ac1..edf3542cf7 100644 --- a/lib/bind/port_before.h.in +++ b/lib/bind/port_before.h.in @@ -136,3 +136,5 @@ struct timezone; /* silence warning */ #endif #endif + +/*! \file */ diff --git a/lib/bind/resolv/herror.c b/lib/bind/resolv/herror.c index bc6948fb02..703ab8fe4d 100644 --- a/lib/bind/resolv/herror.c +++ b/lib/bind/resolv/herror.c @@ -50,7 +50,7 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)herror.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: herror.c,v 1.3 2004/03/09 06:30:16 marka Exp $"; +static const char rcsid[] = "$Id: herror.c,v 1.4 2005/04/27 04:56:41 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -72,10 +72,10 @@ static const char rcsid[] = "$Id: herror.c,v 1.3 2004/03/09 06:30:16 marka Exp $ const char *h_errlist[] = { "Resolver Error 0 (no error)", - "Unknown host", /* 1 HOST_NOT_FOUND */ - "Host name lookup failure", /* 2 TRY_AGAIN */ - "Unknown server error", /* 3 NO_RECOVERY */ - "No address associated with name", /* 4 NO_ADDRESS */ + "Unknown host", /*%< 1 HOST_NOT_FOUND */ + "Host name lookup failure", /*%< 2 TRY_AGAIN */ + "Unknown server error", /*%< 3 NO_RECOVERY */ + "No address associated with name", /*%< 4 NO_ADDRESS */ }; int h_nerr = { sizeof h_errlist / sizeof h_errlist[0] }; @@ -84,7 +84,7 @@ int h_nerr = { sizeof h_errlist / sizeof h_errlist[0] }; int h_errno; #endif -/* +/*% * herror -- * print the error indicated by the h_errno value. */ @@ -113,7 +113,7 @@ herror(const char *s) { writev(STDERR_FILENO, iov, (v - iov) + 1); } -/* +/*% * hstrerror -- * return the string associated with a given "host" errno value. */ @@ -125,3 +125,5 @@ hstrerror(int err) { return (h_errlist[err]); return ("Unknown resolver error"); } + +/*! \file */ diff --git a/lib/bind/resolv/res_comp.c b/lib/bind/resolv/res_comp.c index fcc21851d0..96a20f7c07 100644 --- a/lib/bind/resolv/res_comp.c +++ b/lib/bind/resolv/res_comp.c @@ -70,7 +70,7 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)res_comp.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: res_comp.c,v 1.3 2004/03/09 06:30:17 marka Exp $"; +static const char rcsid[] = "$Id: res_comp.c,v 1.4 2005/04/27 04:56:41 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -85,12 +85,13 @@ static const char rcsid[] = "$Id: res_comp.c,v 1.3 2004/03/09 06:30:17 marka Exp #include #include "port_after.h" -/* +/*% * Expand compressed domain name 'src' to full domain name. - * 'msg' is a pointer to the begining of the message, - * 'eom' points to the first location after the message, - * 'dst' is a pointer to a buffer of size 'dstsiz' for the result. - * Return size of compressed name or -1 if there was an error. + * + * \li 'msg' is a pointer to the begining of the message, + * \li 'eom' points to the first location after the message, + * \li 'dst' is a pointer to a buffer of size 'dstsiz' for the result. + * \li Return size of compressed name or -1 if there was an error. */ int dn_expand(const u_char *msg, const u_char *eom, const u_char *src, @@ -103,10 +104,11 @@ dn_expand(const u_char *msg, const u_char *eom, const u_char *src, return (n); } -/* +/*% * Pack domain name 'exp_dn' in presentation form into 'comp_dn'. - * Return the size of the compressed name or -1. - * 'length' is the size of the array pointed to by 'comp_dn'. + * + * \li Return the size of the compressed name or -1. + * \li 'length' is the size of the array pointed to by 'comp_dn'. */ int dn_comp(const char *src, u_char *dst, int dstsiz, @@ -117,7 +119,7 @@ dn_comp(const char *src, u_char *dst, int dstsiz, (const u_char **)lastdnptr)); } -/* +/*% * Skip over a compressed domain name. Return the size or -1. */ int @@ -129,11 +131,9 @@ dn_skipname(const u_char *ptr, const u_char *eom) { return (ptr - saveptr); } -/* +/*% * Verify that a domain name uses an acceptable character set. - */ - -/* + * * Note the conspicuous absence of ctype macros in these definitions. On * non-ASCII hosts, we can't depend on string literals or ctype macros to * tell us anything about network-format data. The rest of the BIND system @@ -176,7 +176,7 @@ res_hnok(const char *dn) { return (1); } -/* +/*% * hostname-like (A, MX, WKS) owners can have "*" as their first label * but must otherwise be as a host name. */ @@ -191,7 +191,7 @@ res_ownok(const char *dn) { return (res_hnok(dn)); } -/* +/*% * SOA RNAMEs and RP RNAMEs can have any printable character in their first * label, but the rest of the name has to look like a host name. */ @@ -219,8 +219,8 @@ res_mailok(const char *dn) { return (0); } -/* - * This function is quite liberal, since RFC 1034's character sets are only +/*% + * This function is quite liberal, since RFC1034's character sets are only * recommendations. */ int @@ -234,7 +234,7 @@ res_dnok(const char *dn) { } #ifdef BIND_4_COMPAT -/* +/*% * This module must export the following externally-visible symbols: * ___putlong * ___putshort @@ -249,3 +249,5 @@ u_int32_t _getlong(const u_char *src) { return (ns_get32(src)); } u_int16_t _getshort(const u_char *src) { return (ns_get16(src)); } #endif /*__ultrix__*/ #endif /*BIND_4_COMPAT*/ + +/*! \file */ diff --git a/lib/bind/resolv/res_data.c b/lib/bind/resolv/res_data.c index fc191fa341..ff6727c260 100644 --- a/lib/bind/resolv/res_data.c +++ b/lib/bind/resolv/res_data.c @@ -16,7 +16,7 @@ */ #if defined(LIBC_SCCS) && !defined(lint) -static const char rcsid[] = "$Id: res_data.c,v 1.3 2004/03/18 02:58:01 marka Exp $"; +static const char rcsid[] = "$Id: res_data.c,v 1.4 2005/04/27 04:56:41 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -46,8 +46,8 @@ const char *_res_opcodes[] = { "QUERY", "IQUERY", "CQUERYM", - "CQUERYU", /* experimental */ - "NOTIFY", /* experimental */ + "CQUERYU", /*%< experimental */ + "NOTIFY", /*%< experimental */ "UPDATE", "6", "7", @@ -73,7 +73,7 @@ const char *_res_sectioncodes[] = { #ifndef __BIND_NOSTATIC struct __res_state _res # if defined(__BIND_RES_TEXT) - = { RES_TIMEOUT, } /* Motorola, et al. */ + = { RES_TIMEOUT, } /*%< Motorola, et al. */ # endif ; @@ -140,14 +140,14 @@ fp_nquery(const u_char *msg, int len, FILE *file) { } int -res_mkquery(int op, /* opcode of query */ - const char *dname, /* domain name */ - int class, int type, /* class and type of query */ - const u_char *data, /* resource record data */ - int datalen, /* length of data */ - const u_char *newrr_in, /* new rr for modify or append */ - u_char *buf, /* buffer to put query */ - int buflen) /* size of buffer */ +res_mkquery(int op, /*!< opcode of query */ + const char *dname, /*!< domain name */ + int class, int type, /*!< class and type of query */ + const u_char *data, /*!< resource record data */ + int datalen, /*!< length of data */ + const u_char *newrr_in, /*!< new rr for modify or append */ + u_char *buf, /*!< buffer to put query */ + int buflen) /*!< size of buffer */ { if ((_res.options & RES_INIT) == 0U && res_init() == -1) { RES_SET_H_ERRNO(&_res, NETDB_INTERNAL); @@ -169,10 +169,10 @@ res_mkupdate(ns_updrec *rrecp_in, u_char *buf, int buflen) { } int -res_query(const char *name, /* domain name */ - int class, int type, /* class and type of query */ - u_char *answer, /* buffer to put answer */ - int anslen) /* size of answer buffer */ +res_query(const char *name, /*!< domain name */ + int class, int type, /*!< class and type of query */ + u_char *answer, /*!< buffer to put answer */ + int anslen) /*!< size of answer buffer */ { if ((_res.options & RES_INIT) == 0U && res_init() == -1) { RES_SET_H_ERRNO(&_res, NETDB_INTERNAL); @@ -234,10 +234,10 @@ res_update(ns_updrec *rrecp_in) { } int -res_search(const char *name, /* domain name */ - int class, int type, /* class and type of query */ - u_char *answer, /* buffer to put answer */ - int anslen) /* size of answer */ +res_search(const char *name, /*!< domain name */ + int class, int type, /*!< class and type of query */ + u_char *answer, /*!< buffer to put answer */ + int anslen) /*!< size of answer */ { if ((_res.options & RES_INIT) == 0U && res_init() == -1) { RES_SET_H_ERRNO(&_res, NETDB_INTERNAL); @@ -250,9 +250,9 @@ res_search(const char *name, /* domain name */ int res_querydomain(const char *name, const char *domain, - int class, int type, /* class and type of query */ - u_char *answer, /* buffer to put answer */ - int anslen) /* size of answer */ + int class, int type, /*!< class and type of query */ + u_char *answer, /*!< buffer to put answer */ + int anslen) /*!< size of answer */ { if ((_res.options & RES_INIT) == 0U && res_init() == -1) { RES_SET_H_ERRNO(&_res, NETDB_INTERNAL); @@ -289,3 +289,5 @@ local_hostname_length(const char *hostname) { #endif /*ultrix*/ #endif + +/*! \file */ diff --git a/lib/bind/resolv/res_debug.c b/lib/bind/resolv/res_debug.c index e4b8723ad6..06da2dfa39 100644 --- a/lib/bind/resolv/res_debug.c +++ b/lib/bind/resolv/res_debug.c @@ -95,7 +95,7 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)res_debug.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: res_debug.c,v 1.13 2004/07/28 20:16:50 marka Exp $"; +static const char rcsid[] = "$Id: res_debug.c,v 1.14 2005/04/27 04:56:41 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -129,7 +129,7 @@ static const char rcsid[] = "$Id: res_debug.c,v 1.13 2004/07/28 20:16:50 marka E extern const char *_res_opcodes[]; extern const char *_res_sectioncodes[]; -/* +/*% * Print the current options. */ void @@ -222,7 +222,7 @@ do_section(const res_state statp, free(buf); } -/* +/*% * Print the contents of a query. * This is intended to be primarily a debugging routine. */ @@ -317,7 +317,8 @@ p_cdname(const u_char *cp, const u_char *msg, FILE *file) { return (p_cdnname(cp, msg, PACKETSZ, file)); } -/* Return a fully-qualified domain name from a compressed name (with +/*% + * Return a fully-qualified domain name from a compressed name (with length supplied). */ const u_char * @@ -333,7 +334,7 @@ p_fqnname(cp, msg, msglen, name, namelen) return (NULL); newlen = strlen(name); if (newlen == 0 || name[newlen - 1] != '.') { - if (newlen + 1 >= namelen) /* Lack space for final dot */ + if (newlen + 1 >= namelen) /*%< Lack space for final dot */ return (NULL); else strcpy(name + newlen, "."); @@ -355,7 +356,7 @@ p_fqname(const u_char *cp, const u_char *msg, FILE *file) { return (n); } -/* +/*% * Names of RR classes and qclasses. Classes and qclasses are the same, except * that C_ANY is a qclass but not a class. (You can ask for records of class * C_ANY, but you can't have any records of that class in the database.) @@ -371,7 +372,7 @@ const struct res_sym __p_class_syms[] = { {C_IN, (char *)0, (char *)0} }; -/* +/*% * Names of message sections. */ const struct res_sym __p_default_section_syms[] = { @@ -408,7 +409,7 @@ const struct res_sym __p_cert_syms[] = { {0, NULL, NULL} }; -/* +/*% * Names of RR types and qtypes. Types and qtypes are the same, except * that T_ANY is a qtype but not a type. (You can ask for records of type * T_ANY, but you can't have any records of that type in the database.) @@ -466,7 +467,7 @@ const struct res_sym __p_type_syms[] = { {0, NULL, NULL} }; -/* +/*% * Names of DNS rcodes. */ const struct res_sym __p_rcode_syms[] = { @@ -499,7 +500,7 @@ sym_ston(const struct res_sym *syms, const char *name, int *success) { } if (success) *success = 0; - return (syms->number); /* The default value. */ + return (syms->number); /*%< The default value. */ } const char * @@ -514,7 +515,7 @@ sym_ntos(const struct res_sym *syms, int number, int *success) { } } - sprintf(unname, "%d", number); /* XXX nonreentrant */ + sprintf(unname, "%d", number); /*%< XXX nonreentrant */ if (success) *success = 0; return (unname); @@ -531,13 +532,13 @@ sym_ntop(const struct res_sym *syms, int number, int *success) { return (syms->humanname); } } - sprintf(unname, "%d", number); /* XXX nonreentrant */ + sprintf(unname, "%d", number); /*%< XXX nonreentrant */ if (success) *success = 0; return (unname); } -/* +/*% * Return a string for the type. */ const char * @@ -555,7 +556,7 @@ p_type(int type) { return (typebuf); } -/* +/*% * Return a string for the type. */ const char * @@ -573,7 +574,7 @@ p_section(int section, int opcode) { return (sym_ntos(symbols, section, (int *)0)); } -/* +/*% * Return a mnemonic for class. */ const char * @@ -591,7 +592,7 @@ p_class(int class) { return (classbuf); } -/* +/*% * Return a mnemonic for an option */ const char * @@ -613,7 +614,7 @@ p_option(u_long option) { case RES_INSECURE2: return "insecure2"; case RES_NOALIASES: return "noaliases"; case RES_USE_INET6: return "inet6"; -#ifdef RES_USE_EDNS0 /* KAME extension */ +#ifdef RES_USE_EDNS0 /*%< KAME extension */ case RES_USE_EDNS0: return "edns0"; #endif #ifdef RES_USE_DNAME @@ -634,19 +635,18 @@ p_option(u_long option) { } } -/* +/*% * Return a mnemonic for a time to live. */ const char * p_time(u_int32_t value) { - static char nbuf[40]; /* XXX nonreentrant */ - + static char nbuf[40]; /*%< XXX nonreentrant */ if (ns_format_ttl(value, nbuf, sizeof nbuf) < 0) sprintf(nbuf, "%u", value); return (nbuf); } -/* +/*% * Return a string for the rcode. */ const char * @@ -654,7 +654,7 @@ p_rcode(int rcode) { return (sym_ntos(__p_rcode_syms, rcode, (int *)0)); } -/* +/*% * Return a string for a res_sockaddr_union. */ const char * @@ -681,7 +681,7 @@ p_sockun(union res_sockaddr_union u, char *buf, size_t size) { return (buf); } -/* +/*% * routines to convert between on-the-wire RR format and zone file format. * Does not contain conversion to/from decimal degrees; divide or multiply * by 60*60*1000 for that. @@ -690,12 +690,12 @@ p_sockun(union res_sockaddr_union u, char *buf, size_t size) { static unsigned int poweroften[10] = {1, 10, 100, 1000, 10000, 100000, 1000000,10000000,100000000,1000000000}; -/* takes an XeY precision/size value, returns a string representation. */ +/*% takes an XeY precision/size value, returns a string representation. */ static const char * precsize_ntoa(prec) u_int8_t prec; { - static char retbuf[sizeof "90000000.00"]; /* XXX nonreentrant */ + static char retbuf[sizeof "90000000.00"]; /*%< XXX nonreentrant */ unsigned long val; int mantissa, exponent; @@ -708,7 +708,7 @@ precsize_ntoa(prec) return (retbuf); } -/* converts ascii size/precision X * 10**Y(cm) to 0xXY. moves pointer. */ +/*% converts ascii size/precision X * 10**Y(cm) to 0xXY. moves pointer. */ static u_int8_t precsize_aton(const char **strptr) { unsigned int mval = 0, cmval = 0; @@ -722,7 +722,7 @@ precsize_aton(const char **strptr) { while (isdigit((unsigned char)*cp)) mval = mval * 10 + (*cp++ - '0'); - if (*cp == '.') { /* centimeters */ + if (*cp == '.') { /*%< centimeters */ cp++; if (isdigit((unsigned char)*cp)) { cmval = (*cp++ - '0') * 10; @@ -748,7 +748,7 @@ precsize_aton(const char **strptr) { return (retval); } -/* converts ascii lat/lon to unsigned encoded 32-bit number. moves pointer. */ +/*% converts ascii lat/lon to unsigned encoded 32-bit number. moves pointer. */ static u_int32_t latlon2ul(const char **latlonstrptr, int *which) { const char *cp; @@ -778,7 +778,7 @@ latlon2ul(const char **latlonstrptr, int *which) { while (isdigit((unsigned char)*cp)) secs = secs * 10 + (*cp++ - '0'); - if (*cp == '.') { /* decimal seconds */ + if (*cp == '.') { /*%< decimal seconds */ cp++; if (isdigit((unsigned char)*cp)) { secsfrac = (*cp++ - '0') * 100; @@ -791,7 +791,7 @@ latlon2ul(const char **latlonstrptr, int *which) { } } - while (!isspace((unsigned char)*cp)) /* if any trailing garbage */ + while (!isspace((unsigned char)*cp)) /*%< if any trailing garbage */ cp++; while (isspace((unsigned char)*cp)) @@ -812,30 +812,29 @@ latlon2ul(const char **latlonstrptr, int *which) { - secsfrac; break; default: - retval = 0; /* invalid value -- indicates error */ + retval = 0; /*%< invalid value -- indicates error */ break; } switch (*cp) { case 'N': case 'n': case 'S': case 's': - *which = 1; /* latitude */ + *which = 1; /*%< latitude */ break; case 'E': case 'e': case 'W': case 'w': - *which = 2; /* longitude */ + *which = 2; /*%< longitude */ break; default: - *which = 0; /* error */ + *which = 0; /*%< error */ break; } - cp++; /* skip the hemisphere */ - - while (!isspace((unsigned char)*cp)) /* if any trailing garbage */ + cp++; /*%< skip the hemisphere */ + while (!isspace((unsigned char)*cp)) /*%< if any trailing garbage */ cp++; - while (isspace((unsigned char)*cp)) /* move to next field */ + while (isspace((unsigned char)*cp)) /*%< move to next field */ cp++; *latlonstrptr = cp; @@ -843,7 +842,8 @@ latlon2ul(const char **latlonstrptr, int *which) { return (retval); } -/* converts a zone file representation in a string to an RDATA on-the-wire +/*% + * converts a zone file representation in a string to an RDATA on-the-wire * representation. */ int loc_aton(ascii, binary) @@ -856,9 +856,9 @@ loc_aton(ascii, binary) u_int32_t latit = 0, longit = 0, alt = 0; u_int32_t lltemp1 = 0, lltemp2 = 0; int altmeters = 0, altfrac = 0, altsign = 1; - u_int8_t hp = 0x16; /* default = 1e6 cm = 10000.00m = 10km */ - u_int8_t vp = 0x13; /* default = 1e3 cm = 10.00m */ - u_int8_t siz = 0x12; /* default = 1e2 cm = 1.00m */ + u_int8_t hp = 0x16; /*%< default = 1e6 cm = 10000.00m = 10km */ + u_int8_t vp = 0x13; /*%< default = 1e3 cm = 10.00m */ + u_int8_t siz = 0x12; /*%< default = 1e2 cm = 1.00m */ int which1 = 0, which2 = 0; cp = ascii; @@ -869,18 +869,18 @@ loc_aton(ascii, binary) lltemp2 = latlon2ul(&cp, &which2); switch (which1 + which2) { - case 3: /* 1 + 2, the only valid combination */ - if ((which1 == 1) && (which2 == 2)) { /* normal case */ + case 3: /*%< 1 + 2, the only valid combination */ + if ((which1 == 1) && (which2 == 2)) { /*%< normal case */ latit = lltemp1; longit = lltemp2; - } else if ((which1 == 2) && (which2 == 1)) { /* reversed */ + } else if ((which1 == 2) && (which2 == 1)) { /*%< reversed */ longit = lltemp1; latit = lltemp2; - } else { /* some kind of brokenness */ + } else { /*%< some kind of brokenness */ return (0); } break; - default: /* we didn't get one of each */ + default: /*%< we didn't get one of each */ return (0); } @@ -896,7 +896,7 @@ loc_aton(ascii, binary) while (isdigit((unsigned char)*cp)) altmeters = altmeters * 10 + (*cp++ - '0'); - if (*cp == '.') { /* decimal meters */ + if (*cp == '.') { /*%< decimal meters */ cp++; if (isdigit((unsigned char)*cp)) { altfrac = (*cp++ - '0') * 10; @@ -908,7 +908,7 @@ loc_aton(ascii, binary) alt = (10000000 + (altsign * (altmeters * 100 + altfrac))); - while (!isspace((unsigned char)*cp) && (cp < maxcp)) /* if trailing garbage or m */ + while (!isspace((unsigned char)*cp) && (cp < maxcp)) /*%< if trailing garbage or m */ cp++; while (isspace((unsigned char)*cp) && (cp < maxcp)) @@ -919,7 +919,7 @@ loc_aton(ascii, binary) siz = precsize_aton(&cp); - while (!isspace((unsigned char)*cp) && (cp < maxcp)) /* if trailing garbage or m */ + while (!isspace((unsigned char)*cp) && (cp < maxcp)) /*%< if trailing garbage or m */ cp++; while (isspace((unsigned char)*cp) && (cp < maxcp)) @@ -930,7 +930,7 @@ loc_aton(ascii, binary) hp = precsize_aton(&cp); - while (!isspace((unsigned char)*cp) && (cp < maxcp)) /* if trailing garbage or m */ + while (!isspace((unsigned char)*cp) && (cp < maxcp)) /*%< if trailing garbage or m */ cp++; while (isspace((unsigned char)*cp) && (cp < maxcp)) @@ -944,7 +944,7 @@ loc_aton(ascii, binary) defaults: bcp = binary; - *bcp++ = (u_int8_t) 0; /* version byte */ + *bcp++ = (u_int8_t) 0; /*%< version byte */ *bcp++ = siz; *bcp++ = hp; *bcp++ = vp; @@ -952,10 +952,10 @@ loc_aton(ascii, binary) PUTLONG(longit,bcp); PUTLONG(alt,bcp); - return (16); /* size of RR in octets */ + return (16); /*%< size of RR in octets */ } -/* takes an on-the-wire LOC RR and formats it in a human readable format. */ +/*% takes an on-the-wire LOC RR and formats it in a human readable format. */ const char * loc_ntoa(binary, ascii) const u_char *binary; @@ -1002,7 +1002,7 @@ loc_ntoa(binary, ascii) longval = (templ - ((unsigned)1<<31)); GETLONG(templ, cp); - if (templ < referencealt) { /* below WGS 84 spheroid */ + if (templ < referencealt) { /*%< below WGS 84 spheroid */ altval = referencealt - templ; altsign = "-"; } else { @@ -1065,7 +1065,7 @@ loc_ntoa(binary, ascii) } -/* Return the number of DNS hierarchy levels in the name. */ +/*% Return the number of DNS hierarchy levels in the name. */ int dn_count_labels(const char *name) { int i, len, count; @@ -1090,15 +1090,14 @@ dn_count_labels(const char *name) { return (count); } - -/* +/*% * Make dates expressed in seconds-since-Jan-1-1970 easy to read. * SIG records are required to be printed like this, by the Secure DNS RFC. */ char * p_secstodate (u_long secs) { /* XXX nonreentrant */ - static char output[15]; /* YYYYMMDDHHMMSS and null */ + static char output[15]; /*%< YYYYMMDDHHMMSS and null */ time_t clock = secs; struct tm *time; #ifdef HAVE_TIME_R @@ -1161,3 +1160,5 @@ res_nametotype(const char *buf, int *successp) { *successp = success; return (result); } + +/*! \file */ diff --git a/lib/bind/resolv/res_debug.h b/lib/bind/resolv/res_debug.h index 2a9c0ae6f5..c28171d7c8 100644 --- a/lib/bind/resolv/res_debug.h +++ b/lib/bind/resolv/res_debug.h @@ -32,3 +32,4 @@ #endif #endif /* _RES_DEBUG_H_ */ +/*! \file */ diff --git a/lib/bind/resolv/res_findzonecut.c b/lib/bind/resolv/res_findzonecut.c index 7f053ab70d..958282d6b8 100644 --- a/lib/bind/resolv/res_findzonecut.c +++ b/lib/bind/resolv/res_findzonecut.c @@ -1,5 +1,5 @@ #if !defined(lint) && !defined(SABER) -static const char rcsid[] = "$Id: res_findzonecut.c,v 1.8 2004/09/16 07:08:43 marka Exp $"; +static const char rcsid[] = "$Id: res_findzonecut.c,v 1.9 2005/04/27 04:56:42 sra Exp $"; #endif /* not lint */ /* @@ -96,55 +96,56 @@ static void res_dprintf(const char *, ...) ISC_FORMAT_PRINTF(1, 2); /* Public. */ -/* - * int - * res_findzonecut(res, dname, class, zname, zsize, addrs, naddrs) +/*% * find enclosing zone for a , and some server addresses + * * parameters: - * res - resolver context to work within (is modified) - * dname - domain name whose enclosing zone is desired - * class - class of dname (and its enclosing zone) - * zname - found zone name - * zsize - allocated size of zname - * addrs - found server addresses - * naddrs - max number of addrs + *\li res - resolver context to work within (is modified) + *\li dname - domain name whose enclosing zone is desired + *\li class - class of dname (and its enclosing zone) + *\li zname - found zone name + *\li zsize - allocated size of zname + *\li addrs - found server addresses + *\li naddrs - max number of addrs + * * return values: - * < 0 - an error occurred (check errno) - * = 0 - zname is now valid, but addrs[] wasn't changed - * > 0 - zname is now valid, and return value is number of addrs[] found + *\li < 0 - an error occurred (check errno) + *\li = 0 - zname is now valid, but addrs[] wasn't changed + *\li > 0 - zname is now valid, and return value is number of addrs[] found + * * notes: - * this function calls res_nsend() which means it depends on correctly + *\li this function calls res_nsend() which means it depends on correctly * functioning recursive nameservers (usually defined in /etc/resolv.conf * or its local equivilent). * - * we start by asking for an SOA. if we get one as an + *\li we start by asking for an SOA. if we get one as an * answer, that just means is a zone top, which is fine. * more than likely we'll be told to go pound sand, in the form of a * negative answer. * - * note that we are not prepared to deal with referrals since that would + *\li note that we are not prepared to deal with referrals since that would * only come from authority servers and our correctly functioning local * recursive server would have followed the referral and got us something * more definite. * - * if the authority section contains an SOA, this SOA should also be the + *\li if the authority section contains an SOA, this SOA should also be the * closest enclosing zone, since any intermediary zone cuts would've been * returned as referrals and dealt with by our correctly functioning local * recursive name server. but an SOA in the authority section should NOT * match our dname (since that would have been returned in the answer * section). an authority section SOA has to be "above" our dname. * - * however, since authority section SOA's were once optional, it's + *\li however, since authority section SOA's were once optional, it's * possible that we'll have to go hunting for the enclosing SOA by * ripping labels off the front of our dname -- this is known as "doing * it the hard way." * - * ultimately we want some server addresses, which are ideally the ones + *\li ultimately we want some server addresses, which are ideally the ones * pertaining to the SOA.MNAME, but only if there is a matching NS RR. * so the second phase (after we find an SOA) is to go looking for the * NS RRset for that SOA's zone. * - * no answer section processed by this code is allowed to contain CNAME + *\li no answer section processed by this code is allowed to contain CNAME * or DNAME RR's. for the SOA query this means we strip a label and * keep going. for the NS and A queries this means we just give up. */ @@ -721,3 +722,5 @@ res_dprintf(const char *fmt, ...) { fputc('\n', stderr); va_end(ap); } + +/*! \file */ diff --git a/lib/bind/resolv/res_init.c b/lib/bind/resolv/res_init.c index d902b9f95e..22aee13050 100644 --- a/lib/bind/resolv/res_init.c +++ b/lib/bind/resolv/res_init.c @@ -70,7 +70,7 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)res_init.c 8.1 (Berkeley) 6/7/93"; -static const char rcsid[] = "$Id: res_init.c,v 1.16 2004/03/18 02:58:02 marka Exp $"; +static const char rcsid[] = "$Id: res_init.c,v 1.17 2005/04/27 04:56:42 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -98,7 +98,7 @@ static const char rcsid[] = "$Id: res_init.c,v 1.16 2004/03/18 02:58:02 marka Ex #include "res_private.h" -/* Options. Should all be left alone. */ +/*% Options. Should all be left alone. */ #define RESOLVSORT #define DEBUG @@ -110,7 +110,7 @@ static const char sort_mask[] = "/&"; static u_int32_t net_mask __P((struct in_addr)); #endif -#if !defined(isascii) /* XXX - could be a function */ +#if !defined(isascii) /*%< XXX - could be a function */ # define isascii(c) (!(c & 0200)) #endif @@ -118,7 +118,7 @@ static u_int32_t net_mask __P((struct in_addr)); * Resolver state default settings. */ -/* +/*% * Set up default settings. If the configuration file exist, the values * there will have precedence. Otherwise, the server address is set to * INADDR_ANY and the default domain name comes from the gethostname(). @@ -146,14 +146,14 @@ res_ninit(res_state statp) { return (__res_vinit(statp, 0)); } -/* This function has to be reachable by res_data.c but not publically. */ +/*% This function has to be reachable by res_data.c but not publically. */ int __res_vinit(res_state statp, int preinit) { register FILE *fp; register char *cp, **pp; register int n; char buf[BUFSIZ]; - int nserv = 0; /* number of nameserver records read from file */ + int nserv = 0; /*%< number of nameserver records read from file */ int haveenv = 0; int havesearch = 0; #ifdef RESOLVSORT @@ -235,7 +235,7 @@ __res_vinit(res_state statp, int preinit) { pp = statp->dnsrch; *pp++ = cp; for (n = 0; *cp && pp < statp->dnsrch + MAXDNSRCH; cp++) { - if (*cp == '\n') /* silly backwards compat */ + if (*cp == '\n') /*%< silly backwards compat */ break; else if (*cp == ' ' || *cp == '\t') { *cp = 0; @@ -267,7 +267,7 @@ __res_vinit(res_state statp, int preinit) { continue; /* read default domain name */ if (MATCH(buf, "domain")) { - if (haveenv) /* skip if have from environ */ + if (haveenv) /*%< skip if have from environ */ continue; cp = buf + sizeof("domain") - 1; while (*cp == ' ' || *cp == '\t') @@ -283,7 +283,7 @@ __res_vinit(res_state statp, int preinit) { } /* set search list */ if (MATCH(buf, "search")) { - if (haveenv) /* skip if have from environ */ + if (haveenv) /*%< skip if have from environ */ continue; cp = buf + sizeof("search") - 1; while (*cp == ' ' || *cp == '\t') @@ -437,7 +437,7 @@ __res_vinit(res_state statp, int preinit) { while (pp < statp->dnsrch + MAXDFLSRCH) { if (dots < LOCALDOMAINPARTS) break; - cp = strchr(cp, '.') + 1; /* we know there is one */ + cp = strchr(cp, '.') + 1; /*%< we know there is one */ *pp++ = cp; dots--; } @@ -574,7 +574,7 @@ res_setoptions(res_state statp, const char *options, const char *source) #ifdef RESOLVSORT /* XXX - should really support CIDR which means explicit masks always. */ static u_int32_t -net_mask(in) /* XXX - should really use system's version of this */ +net_mask(in) /*!< XXX - should really use system's version of this */ struct in_addr in; { register u_int32_t i = ntohl(in.s_addr); @@ -595,7 +595,7 @@ res_randomid(void) { return (0xffff & (now.tv_sec ^ now.tv_usec ^ getpid())); } -/* +/*% * This routine is for closing the socket if a virtual circuit is used and * the program wants to close it. This provides support for endhostent() * which expects to close the socket. @@ -738,3 +738,5 @@ res_getservers(res_state statp, union res_sockaddr_union *set, int cnt) { } return (statp->nscount); } + +/*! \file */ diff --git a/lib/bind/resolv/res_mkquery.c b/lib/bind/resolv/res_mkquery.c index 7b7b1daa32..09133baf42 100644 --- a/lib/bind/resolv/res_mkquery.c +++ b/lib/bind/resolv/res_mkquery.c @@ -70,7 +70,7 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)res_mkquery.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: res_mkquery.c,v 1.5 2004/03/18 02:58:02 marka Exp $"; +static const char rcsid[] = "$Id: res_mkquery.c,v 1.6 2005/04/27 04:56:42 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -89,20 +89,20 @@ static const char rcsid[] = "$Id: res_mkquery.c,v 1.5 2004/03/18 02:58:02 marka extern const char *_res_opcodes[]; -/* +/*% * Form all types of queries. * Returns the size of the result or -1. */ int res_nmkquery(res_state statp, - int op, /* opcode of query */ - const char *dname, /* domain name */ - int class, int type, /* class and type of query */ - const u_char *data, /* resource record data */ - int datalen, /* length of data */ - const u_char *newrr_in, /* new rr for modify or append */ - u_char *buf, /* buffer to put query */ - int buflen) /* size of buffer */ + int op, /*!< opcode of query */ + const char *dname, /*!< domain name */ + int class, int type, /*!< class and type of query */ + const u_char *data, /*!< resource record data */ + int datalen, /*!< length of data */ + const u_char *newrr_in, /*!< new rr for modify or append */ + u_char *buf, /*!< buffer to put query */ + int buflen) /*!< size of buffer */ { register HEADER *hp; register u_char *cp, *ep; @@ -179,7 +179,7 @@ res_nmkquery(res_state statp, */ if (ep - cp < 1 + RRFIXEDSZ + datalen) return (-1); - *cp++ = '\0'; /* no domain name */ + *cp++ = '\0'; /*%< no domain name */ ns_put16(type, cp); cp += INT16SZ; ns_put16(class, cp); @@ -209,10 +209,10 @@ res_nmkquery(res_state statp, int res_nopt(res_state statp, - int n0, /* current offset in buffer */ - u_char *buf, /* buffer to put query */ - int buflen, /* size of buffer */ - int anslen) /* UDP answer buffer size */ + int n0, /*%< current offset in buffer */ + u_char *buf, /*%< buffer to put query */ + int buflen, /*%< size of buffer */ + int anslen) /*%< UDP answer buffer size */ { register HEADER *hp; register u_char *cp, *ep; @@ -230,14 +230,13 @@ res_nopt(res_state statp, if ((ep - cp) < 1 + RRFIXEDSZ) return (-1); - *cp++ = 0; /* "." */ - - ns_put16(T_OPT, cp); /* TYPE */ + *cp++ = 0; /*%< "." */ + ns_put16(T_OPT, cp); /*%< TYPE */ cp += INT16SZ; - ns_put16(anslen & 0xffff, cp); /* CLASS = UDP payload size */ + ns_put16(anslen & 0xffff, cp); /*%< CLASS = UDP payload size */ cp += INT16SZ; - *cp++ = NOERROR; /* extended RCODE */ - *cp++ = 0; /* EDNS version */ + *cp++ = NOERROR; /*%< extended RCODE */ + *cp++ = 0; /*%< EDNS version */ if (statp->options & RES_USE_DNSSEC) { #ifdef DEBUG if (statp->options & RES_DEBUG) @@ -247,10 +246,12 @@ res_nopt(res_state statp, } ns_put16(flags, cp); cp += INT16SZ; - ns_put16(0, cp); /* RDLEN */ + ns_put16(0, cp); /*%< RDLEN */ cp += INT16SZ; hp->arcount = htons(ntohs(hp->arcount) + 1); return (cp - buf); } #endif + +/*! \file */ diff --git a/lib/bind/resolv/res_mkupdate.c b/lib/bind/resolv/res_mkupdate.c index aa3beed2ed..1775da7a02 100644 --- a/lib/bind/resolv/res_mkupdate.c +++ b/lib/bind/resolv/res_mkupdate.c @@ -15,13 +15,14 @@ * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* +/*! \file + * \brief * Based on the Dynamic DNS reference implementation by Viraj Bais - * + * <viraj_bais@ccm.fm.intel.com> */ #if !defined(lint) && !defined(SABER) -static const char rcsid[] = "$Id: res_mkupdate.c,v 1.5 2004/06/03 04:43:34 marka Exp $"; +static const char rcsid[] = "$Id: res_mkupdate.c,v 1.6 2005/04/27 04:56:42 sra Exp $"; #endif /* not lint */ #include "port_before.h" @@ -62,17 +63,19 @@ static int getstr_str(char *, int, u_char **, u_char *); int res_protocolnumber(const char *); int res_servicenumber(const char *); -/* +/*% * Form update packets. * Returns the size of the resulting packet if no error + * * On error, - * returns -1 if error in reading a word/number in rdata + * returns + *\li -1 if error in reading a word/number in rdata * portion for update packets - * -2 if length of buffer passed is insufficient - * -3 if zone section is not the first section in + *\li -2 if length of buffer passed is insufficient + *\li -3 if zone section is not the first section in * the linked list, or section order has a problem - * -4 on a number overflow - * -5 unknown operation or no records + *\li -4 on a number overflow + *\li -5 unknown operation or no records */ int res_nmkupdate(res_state statp, ns_updrec *rrecp_in, u_char *buf, int buflen) { @@ -101,7 +104,7 @@ res_nmkupdate(res_state statp, ns_updrec *rrecp_in, u_char *buf, int buflen) { hp->id = htons(++statp->id); hp->opcode = ns_o_update; hp->rcode = NOERROR; - sp1 = buf + 2*INT16SZ; /* save pointer to zocount */ + sp1 = buf + 2*INT16SZ; /*%< save pointer to zocount */ cp = buf + HFIXEDSZ; buflen -= HFIXEDSZ; dpp = dnptrs; @@ -190,7 +193,7 @@ res_nmkupdate(res_state statp, ns_updrec *rrecp_in, u_char *buf, int buflen) { } ShrinkBuffer(INT32SZ + INT16SZ); PUTLONG(rttl, cp); - sp2 = cp; /* save pointer to length byte */ + sp2 = cp; /*%< save pointer to length byte */ cp += INT16SZ; if (rrecp->r_size == 0) { if (section == S_UPDATE && rclass != C_ANY) @@ -396,7 +399,7 @@ res_nmkupdate(res_state statp, ns_updrec *rrecp_in, u_char *buf, int buflen) { } break; case T_X25: - /* RFC 1183 */ + /* RFC1183 */ if ((n = getstr_str(buf2, sizeof buf2, &startp, endp)) < 0) return (-1); @@ -408,7 +411,7 @@ res_nmkupdate(res_state statp, ns_updrec *rrecp_in, u_char *buf, int buflen) { cp += n; break; case T_ISDN: - /* RFC 1183 */ + /* RFC1183 */ if ((n = getstr_str(buf2, sizeof buf2, &startp, endp)) < 0) return (-1); @@ -709,7 +712,7 @@ res_nmkupdate(res_state statp, ns_updrec *rrecp_in, u_char *buf, int buflen) { return (cp - buf); } -/* +/*% * Get a whitespace delimited word from a string (not file) * into buf. modify the start pointer to point after the * word in the string. @@ -722,9 +725,9 @@ getword_str(char *buf, int size, u_char **startpp, u_char *endp) { for (cp = buf; *startpp <= endp; ) { c = **startpp; if (isspace(c) || c == '\0') { - if (cp != buf) /* trailing whitespace */ + if (cp != buf) /*%< trailing whitespace */ break; - else { /* leading whitespace */ + else { /*%< leading whitespace */ (*startpp)++; continue; } @@ -738,9 +741,9 @@ getword_str(char *buf, int size, u_char **startpp, u_char *endp) { return (cp != buf); } -/* +/*% * get a white spae delimited string from memory. Process quoted strings - * and \DDD escapes. Return length or -1 on error. Returned string may + * and \\DDD escapes. Return length or -1 on error. Returned string may * contain nulls. */ static char digits[] = "0123456789"; @@ -817,7 +820,8 @@ getstr_str(char *buf, int size, u_char **startpp, u_char *endp) { *cp = '\0'; return ((cp == buf)? (seen_quote? 0: -1): (cp - buf)); } -/* + +/*% * Get a whitespace delimited base 16 number from a string (not file) into buf * update the start pointer to point after the number in the string. */ @@ -833,9 +837,9 @@ gethexnum_str(u_char **startpp, u_char *endp) { for (n = 0; *startpp <= endp; ) { c = **startpp; if (isspace(c) || c == '\0') { - if (seendigit) /* trailing whitespace */ + if (seendigit) /*%< trailing whitespace */ break; - else { /* leading whitespace */ + else { /*%< leading whitespace */ (*startpp)++; continue; } @@ -865,7 +869,7 @@ gethexnum_str(u_char **startpp, u_char *endp) { return (n + m); } -/* +/*% * Get a whitespace delimited base 10 number from a string (not file) into buf * update the start pointer to point after the number in the string. */ @@ -878,9 +882,9 @@ getnum_str(u_char **startpp, u_char *endp) { for (n = 0; *startpp <= endp; ) { c = **startpp; if (isspace(c) || c == '\0') { - if (seendigit) /* trailing whitespace */ + if (seendigit) /*%< trailing whitespace */ break; - else { /* leading whitespace */ + else { /*%< leading whitespace */ (*startpp)++; continue; } @@ -907,7 +911,7 @@ getnum_str(u_char **startpp, u_char *endp) { return (n + m); } -/* +/*% * Allocate a resource record buffer & save rr info. */ ns_updrec * @@ -929,7 +933,7 @@ res_mkupdrec(int section, const char *dname, return (rrecp); } -/* +/*% * Free a resource record buffer created by res_mkupdrec. */ void @@ -971,7 +975,7 @@ res_buildservicelist() { free(slp); break; } - slp->port = ntohs((u_int16_t)sp->s_port); /* host byt order */ + slp->port = ntohs((u_int16_t)sp->s_port); /*%< host byt order */ slp->next = servicelist; slp->prev = NULL; if (servicelist) @@ -1013,7 +1017,7 @@ res_buildprotolist(void) { free(slp); break; } - slp->port = pp->p_proto; /* host byte order */ + slp->port = pp->p_proto; /*%< host byte order */ slp->next = protolist; slp->prev = NULL; if (protolist) @@ -1050,14 +1054,14 @@ findservice(const char *s, struct valuelist **list) { lp->next = *list; *list = lp; } - return (lp->port); /* host byte order */ + return (lp->port); /*%< host byte order */ } if (sscanf(s, "%d", &n) != 1 || n <= 0) n = -1; return (n); } -/* +/*% * Convert service name or (ascii) number to int. */ int @@ -1067,7 +1071,7 @@ res_servicenumber(const char *p) { return (findservice(p, &servicelist)); } -/* +/*% * Convert protocol name or (ascii) number to int. */ int @@ -1078,14 +1082,14 @@ res_protocolnumber(const char *p) { } static struct servent * -cgetservbyport(u_int16_t port, const char *proto) { /* Host byte order. */ +cgetservbyport(u_int16_t port, const char *proto) { /*%< Host byte order. */ struct valuelist **list = &servicelist; struct valuelist *lp = *list; static struct servent serv; port = ntohs(port); for (; lp != NULL; lp = lp->next) { - if (port != (u_int16_t)lp->port) /* Host byte order. */ + if (port != (u_int16_t)lp->port) /*%< Host byte order. */ continue; if (strcasecmp(lp->proto, proto) == 0) { if (lp != *list) { @@ -1106,13 +1110,13 @@ cgetservbyport(u_int16_t port, const char *proto) { /* Host byte order. */ } static struct protoent * -cgetprotobynumber(int proto) { /* Host byte order. */ +cgetprotobynumber(int proto) { /*%< Host byte order. */ struct valuelist **list = &protolist; struct valuelist *lp = *list; static struct protoent prot; for (; lp != NULL; lp = lp->next) - if (lp->port == proto) { /* Host byte order. */ + if (lp->port == proto) { /*%< Host byte order. */ if (lp != *list) { lp->prev->next = lp->next; if (lp->next) @@ -1122,7 +1126,7 @@ cgetprotobynumber(int proto) { /* Host byte order. */ *list = lp; } prot.p_name = lp->name; - prot.p_proto = lp->port; /* Host byte order. */ + prot.p_proto = lp->port; /*%< Host byte order. */ return (&prot); } return (0); @@ -1144,7 +1148,7 @@ res_protocolname(int num) { } const char * -res_servicename(u_int16_t port, const char *proto) { /* Host byte order. */ +res_servicename(u_int16_t port, const char *proto) { /*%< Host byte order. */ static char number[8]; struct servent *ss; diff --git a/lib/bind/resolv/res_mkupdate.h b/lib/bind/resolv/res_mkupdate.h index a8f1e7ce95..96c452d89e 100644 --- a/lib/bind/resolv/res_mkupdate.h +++ b/lib/bind/resolv/res_mkupdate.h @@ -22,3 +22,4 @@ __BEGIN_DECLS __END_DECLS #endif /* _RES_MKUPDATE_H_ */ +/*! \file */ diff --git a/lib/bind/resolv/res_private.h b/lib/bind/resolv/res_private.h index d7b66cd691..4e98157ced 100644 --- a/lib/bind/resolv/res_private.h +++ b/lib/bind/resolv/res_private.h @@ -18,3 +18,5 @@ extern int res_ourserver_p(const res_state statp, const struct sockaddr *sa); #endif + +/*! \file */ diff --git a/lib/bind/resolv/res_query.c b/lib/bind/resolv/res_query.c index 324a9f9af0..8dd68e8d66 100644 --- a/lib/bind/resolv/res_query.c +++ b/lib/bind/resolv/res_query.c @@ -70,7 +70,7 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)res_query.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: res_query.c,v 1.7 2004/03/18 02:58:02 marka Exp $"; +static const char rcsid[] = "$Id: res_query.c,v 1.8 2005/04/27 04:56:42 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include "port_before.h" @@ -97,7 +97,7 @@ static const char rcsid[] = "$Id: res_query.c,v 1.7 2004/03/18 02:58:02 marka Ex #define MAXPACKET 1024 #endif -/* +/*% * Formulate a normal query, send, and await answer. * Returned answer is placed in supplied buffer "answer". * Perform preliminary check of answer, returning success only @@ -109,10 +109,10 @@ static const char rcsid[] = "$Id: res_query.c,v 1.7 2004/03/18 02:58:02 marka Ex */ int res_nquery(res_state statp, - const char *name, /* domain name */ - int class, int type, /* class and type of query */ - u_char *answer, /* buffer to put answer */ - int anslen) /* size of answer buffer */ + const char *name, /*%< domain name */ + int class, int type, /*%< class and type of query */ + u_char *answer, /*%< buffer to put answer */ + int anslen) /*%< size of answer buffer */ { u_char buf[MAXPACKET]; HEADER *hp = (HEADER *) answer; @@ -122,8 +122,7 @@ res_nquery(res_state statp, oflags = statp->_flags; again: - hp->rcode = NOERROR; /* default */ - + hp->rcode = NOERROR; /*%< default */ #ifdef DEBUG if (statp->options & RES_DEBUG) printf(";; res_query(%s, %d, %d)\n", name, class, type); @@ -195,7 +194,7 @@ again: return (n); } -/* +/*% * Formulate a normal query, send, and retrieve answer in supplied buffer. * Return the size of the response on success, -1 on error. * If enabled, implement search rules until answer or unrecoverable failure @@ -203,10 +202,10 @@ again: */ int res_nsearch(res_state statp, - const char *name, /* domain name */ - int class, int type, /* class and type of query */ - u_char *answer, /* buffer to put answer */ - int anslen) /* size of answer */ + const char *name, /*%< domain name */ + int class, int type, /*%< class and type of query */ + u_char *answer, /*%< buffer to put answer */ + int anslen) /*%< size of answer */ { const char *cp, * const *domain; HEADER *hp = (HEADER *) answer; @@ -218,8 +217,7 @@ res_nsearch(res_state statp, int searched = 0; errno = 0; - RES_SET_H_ERRNO(statp, HOST_NOT_FOUND); /* True if we never query. */ - + RES_SET_H_ERRNO(statp, HOST_NOT_FOUND); /*%< True if we never query. */ dots = 0; for (cp = name; *cp != '\0'; cp++) dots += (*cp == '.'); @@ -344,7 +342,7 @@ res_nsearch(res_state statp, return (-1); } -/* +/*% * Perform a call on res_query on the concatenation of name and domain, * removing a trailing dot from name if domain is NULL. */ @@ -352,9 +350,9 @@ int res_nquerydomain(res_state statp, const char *name, const char *domain, - int class, int type, /* class and type of query */ - u_char *answer, /* buffer to put answer */ - int anslen) /* size of answer */ + int class, int type, /*%< class and type of query */ + u_char *answer, /*%< buffer to put answer */ + int anslen) /*%< size of answer */ { char nbuf[MAXDNAME]; const char *longname = nbuf; @@ -430,3 +428,5 @@ res_hostalias(const res_state statp, const char *name, char *dst, size_t siz) { fclose(fp); return (NULL); } + +/*! \file */ diff --git a/lib/bind/resolv/res_send.c b/lib/bind/resolv/res_send.c index f9a25af4c5..16a312931f 100644 --- a/lib/bind/resolv/res_send.c +++ b/lib/bind/resolv/res_send.c @@ -70,10 +70,11 @@ #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)res_send.c 8.1 (Berkeley) 6/4/93"; -static const char rcsid[] = "$Id: res_send.c,v 1.12 2004/08/09 07:47:01 marka Exp $"; +static const char rcsid[] = "$Id: res_send.c,v 1.13 2005/04/27 04:56:42 sra Exp $"; #endif /* LIBC_SCCS and not lint */ -/* +/*! \file + * \brief * Send query to name server and wait for reply. */ @@ -136,14 +137,15 @@ static const int niflags = NI_NUMERICHOST | NI_NUMERICSERV; /* Public. */ -/* int - * res_isourserver(ina) +/*% * looks up "ina" in _res.ns_addr_list[] + * * returns: - * 0 : not found - * >0 : found + *\li 0 : not found + *\li >0 : found + * * author: - * paul vixie, 29may94 + *\li paul vixie, 29may94 */ int res_ourserver_p(const res_state statp, const struct sockaddr *sa) { @@ -186,17 +188,19 @@ res_ourserver_p(const res_state statp, const struct sockaddr *sa) { return (0); } -/* int - * res_nameinquery(name, type, class, buf, eom) +/*% * look for (name,type,class) in the query section of packet (buf,eom) + * * requires: - * buf + HFIXEDSZ <= eom + *\li buf + HFIXEDSZ <= eom + * * returns: - * -1 : format error - * 0 : not found - * >0 : found + *\li -1 : format error + *\li 0 : not found + *\li >0 : found + * * author: - * paul vixie, 29may94 + *\li paul vixie, 29may94 */ int res_nameinquery(const char *name, int type, int class, @@ -224,16 +228,17 @@ res_nameinquery(const char *name, int type, int class, return (0); } -/* int - * res_queriesmatch(buf1, eom1, buf2, eom2) +/*% * is there a 1:1 mapping of (name,type,class) * in (buf1,eom1) and (buf2,eom2)? + * * returns: - * -1 : format error - * 0 : not a 1:1 mapping - * >0 : is a 1:1 mapping + *\li -1 : format error + *\li 0 : not a 1:1 mapping + *\li >0 : is a 1:1 mapping + * * author: - * paul vixie, 29may94 + *\li paul vixie, 29may94 */ int res_queriesmatch(const u_char *buf1, const u_char *eom1, @@ -508,9 +513,9 @@ res_nsend(res_state statp, res_nclose(statp); if (!v_circuit) { if (!gotsomewhere) - errno = ECONNREFUSED; /* no nameservers found */ + errno = ECONNREFUSED; /*%< no nameservers found */ else - errno = ETIMEDOUT; /* no answer obtained */ + errno = ETIMEDOUT; /*%< no answer obtained */ } else errno = terrno; return (-1); @@ -537,10 +542,10 @@ get_salen(sa) else if (sa->sa_family == AF_INET6) return (sizeof(struct sockaddr_in6)); else - return (0); /* unknown, die on connect */ + return (0); /*%< unknown, die on connect */ } -/* +/*% * pick appropriate nsaddr_list for use. see res_init() for initialization. */ static struct sockaddr * diff --git a/lib/bind/resolv/res_sendsigned.c b/lib/bind/resolv/res_sendsigned.c index 1984377ab1..fcfaae25ef 100644 --- a/lib/bind/resolv/res_sendsigned.c +++ b/lib/bind/resolv/res_sendsigned.c @@ -24,7 +24,7 @@ #include "res_debug.h" -/* res_nsendsigned */ +/*% res_nsendsigned */ int res_nsendsigned(res_state statp, const u_char *msg, int msglen, ns_tsig_key *key, u_char *answer, int anslen) @@ -157,3 +157,5 @@ retry: dst_free_key(dstkey); return (len); } + +/*! \file */ diff --git a/lib/bind/resolv/res_update.c b/lib/bind/resolv/res_update.c index 4242693735..5b2ecb1a35 100644 --- a/lib/bind/resolv/res_update.c +++ b/lib/bind/resolv/res_update.c @@ -1,5 +1,5 @@ #if !defined(lint) && !defined(SABER) -static const char rcsid[] = "$Id: res_update.c,v 1.12 2004/03/18 02:58:02 marka Exp $"; +static const char rcsid[] = "$Id: res_update.c,v 1.13 2005/04/27 04:56:43 sra Exp $"; #endif /* not lint */ /* @@ -19,9 +19,10 @@ static const char rcsid[] = "$Id: res_update.c,v 1.12 2004/03/18 02:58:02 marka * OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* +/*! \file + * \brief * Based on the Dynamic DNS reference implementation by Viraj Bais - * + * <viraj_bais@ccm.fm.intel.com> */ #include "port_before.h" @@ -49,7 +50,7 @@ static const char rcsid[] = "$Id: res_update.c,v 1.12 2004/03/18 02:58:02 marka #include "port_after.h" #include "res_private.h" -/* +/*% * Separate a linked list of records into groups so that all records * in a group will belong to a single zone on the nameserver. * Create a dynamic update packet for each zone and send it to the diff --git a/lib/bind9/check.c b/lib/bind9/check.c index 6a99fc534a..b30745787d 100644 --- a/lib/bind9/check.c +++ b/lib/bind9/check.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: check.c,v 1.56 2005/02/23 01:06:37 marka Exp $ */ +/* $Id: check.c,v 1.57 2005/04/27 04:56:43 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/bind9/getaddresses.c b/lib/bind9/getaddresses.c index dd35bcebdf..141d8c0f92 100644 --- a/lib/bind9/getaddresses.c +++ b/lib/bind9/getaddresses.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getaddresses.c,v 1.17 2004/09/16 01:01:26 marka Exp $ */ +/* $Id: getaddresses.c,v 1.18 2005/04/27 04:56:43 sra Exp $ */ + +/*! \file */ #include #include diff --git a/lib/bind9/include/bind9/check.h b/lib/bind9/include/bind9/check.h index 88e141057b..f4ebb8436b 100644 --- a/lib/bind9/include/bind9/check.h +++ b/lib/bind9/include/bind9/check.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: check.h,v 1.2 2004/03/05 05:09:10 marka Exp $ */ +/* $Id: check.h,v 1.3 2005/04/27 04:56:44 sra Exp $ */ #ifndef BIND9_CHECK_H #define BIND9_CHECK_H 1 +/*! \file */ + #include #include @@ -29,24 +31,24 @@ ISC_LANG_BEGINDECLS isc_result_t bind9_check_namedconf(cfg_obj_t *config, isc_log_t *logctx, isc_mem_t *mctx); -/* +/*%< * Check the syntactic validity of a configuration parse tree generated from * a named.conf file. * * Requires: - * config is a valid parse tree + *\li config is a valid parse tree * - * logctx is a valid logging context. + *\li logctx is a valid logging context. * * Returns: - * ISC_R_SUCCESS - * ISC_R_FAILURE + * \li #ISC_R_SUCCESS + * \li #ISC_R_FAILURE */ isc_result_t bind9_check_key(cfg_obj_t *config, isc_log_t *logctx); -/* - * As above, but for a single 'key' statement. +/*%< + * Same as bind9_check_namedconf(), but for a single 'key' statement. */ ISC_LANG_ENDDECLS diff --git a/lib/bind9/include/bind9/getaddresses.h b/lib/bind9/include/bind9/getaddresses.h index 2beb15b235..0a684867d5 100644 --- a/lib/bind9/include/bind9/getaddresses.h +++ b/lib/bind9/include/bind9/getaddresses.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getaddresses.h,v 1.3 2004/03/05 05:09:11 marka Exp $ */ +/* $Id: getaddresses.h,v 1.4 2005/04/27 04:56:44 sra Exp $ */ #ifndef BIND9_GETADDRESSES_H #define BIND9_GETADDRESSES_H 1 +/*! \file */ + #include #include @@ -30,7 +32,7 @@ ISC_LANG_BEGINDECLS isc_result_t bind9_getaddresses(const char *hostname, in_port_t port, isc_sockaddr_t *addrs, int addrsize, int *addrcount); -/* +/*%< * Use the system resolver to get the addresses associated with a hostname. * If successful, the number of addresses found is returned in 'addrcount'. * If a hostname lookup is performed and addresses of an unknown family is @@ -41,16 +43,16 @@ bind9_getaddresses(const char *hostname, in_port_t port, * framework, it should be surounded by isc_app_block()/isc_app_unblock(). * * Requires: - * 'hostname' is not NULL. - * 'addrs' is not NULL. - * 'addrsize' > 0 - * 'addrcount' is not NULL. + *\li 'hostname' is not NULL. + *\li 'addrs' is not NULL. + *\li 'addrsize' > 0 + *\li 'addrcount' is not NULL. * * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOTFOUND - * ISC_R_NOFAMILYSUPPORT - 'hostname' is an IPv6 address, and IPv6 is + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOTFOUND + *\li #ISC_R_NOFAMILYSUPPORT - 'hostname' is an IPv6 address, and IPv6 is * not supported. */ diff --git a/lib/bind9/include/bind9/version.h b/lib/bind9/include/bind9/version.h index e91dd15902..42c752caed 100644 --- a/lib/bind9/include/bind9/version.h +++ b/lib/bind9/include/bind9/version.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.h,v 1.3 2004/03/05 05:09:11 marka Exp $ */ +/* $Id: version.h,v 1.4 2005/04/27 04:56:44 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/bind9/version.c b/lib/bind9/version.c index b1d85f28e6..a0799cf203 100644 --- a/lib/bind9/version.c +++ b/lib/bind9/version.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.c,v 1.4 2004/03/05 05:09:04 marka Exp $ */ +/* $Id: version.c,v 1.5 2005/04/27 04:56:43 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/acl.c b/lib/dns/acl.c index 74d09db89a..6244aef354 100644 --- a/lib/dns/acl.c +++ b/lib/dns/acl.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: acl.c,v 1.25 2004/03/05 05:09:17 marka Exp $ */ +/* $Id: acl.c,v 1.26 2005/04/27 04:56:44 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/adb.c b/lib/dns/adb.c index 760d8adc76..103f46b0b7 100644 --- a/lib/dns/adb.c +++ b/lib/dns/adb.c @@ -15,19 +15,18 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: adb.c,v 1.220 2005/03/16 00:55:16 marka Exp $ */ +/* $Id: adb.c,v 1.221 2005/04/27 04:56:44 sra Exp $ */ -/* - * Implementation notes - * -------------------- +/*! \file * + * \note * In finds, if task == NULL, no events will be generated, and no events * have been sent. If task != NULL but taskaction == NULL, an event has been * posted but not yet freed. If neither are NULL, no event was posted. * */ -/* +/*% * After we have cleaned all buckets, dump the database contents. */ #if 0 @@ -71,37 +70,39 @@ #define DNS_ADBFETCH6_MAGIC ISC_MAGIC('a', 'd', 'F', '6') #define DNS_ADBFETCH6_VALID(x) ISC_MAGIC_VALID(x, DNS_ADBFETCH6_MAGIC) -/* +/*! * The number of buckets needs to be a prime (for good hashing). * * XXXRTH How many buckets do we need? */ -#define NBUCKETS 1009 /* how many buckets for names/addrs */ +#define NBUCKETS 1009 /*%< how many buckets for names/addrs */ -/* +/*! * For type 3 negative cache entries, we will remember that the address is * broken for this long. XXXMLG This is also used for actual addresses, too. * The intent is to keep us from constantly asking about A/AAAA records * if the zone has extremely low TTLs. */ -#define ADB_CACHE_MINIMUM 10 /* seconds */ -#define ADB_CACHE_MAXIMUM 86400 /* seconds (86400 = 24 hours) */ -#define ADB_ENTRY_WINDOW 1800 /* seconds */ +#define ADB_CACHE_MINIMUM 10 /*%< seconds */ +#define ADB_CACHE_MAXIMUM 86400 /*%< seconds (86400 = 24 hours) */ +#define ADB_ENTRY_WINDOW 1800 /*%< seconds */ -/* +/*% * Wake up every CLEAN_SECONDS and clean CLEAN_BUCKETS buckets, so that all * buckets are cleaned in CLEAN_PERIOD seconds. */ #define CLEAN_PERIOD 3600 +/*% See #CLEAN_PERIOD */ #define CLEAN_SECONDS 30 +/*% See #CLEAN_PERIOD */ #define CLEAN_BUCKETS ((NBUCKETS * CLEAN_SECONDS) / CLEAN_PERIOD) -#define FREE_ITEMS 64 /* free count for memory pools */ -#define FILL_COUNT 16 /* fill count for memory pools */ +#define FREE_ITEMS 64 /*%< free count for memory pools */ +#define FILL_COUNT 16 /*%< fill count for memory pools */ -#define DNS_ADB_INVALIDBUCKET (-1) /* invalid bucket address */ +#define DNS_ADB_INVALIDBUCKET (-1) /*%< invalid bucket address */ -#define DNS_ADB_MINADBSIZE (1024*1024) /* 1 Megabyte */ +#define DNS_ADB_MINADBSIZE (1024*1024) /*%< 1 Megabyte */ typedef ISC_LIST(dns_adbname_t) dns_adbnamelist_t; typedef struct dns_adbnamehook dns_adbnamehook_t; @@ -111,11 +112,12 @@ typedef ISC_LIST(dns_adbentry_t) dns_adbentrylist_t; typedef struct dns_adbfetch dns_adbfetch_t; typedef struct dns_adbfetch6 dns_adbfetch6_t; +/*% dns adb structure */ struct dns_adb { unsigned int magic; isc_mutex_t lock; - isc_mutex_t reflock; /* Covers irefcnt, erefcnt */ + isc_mutex_t reflock; /*%< Covers irefcnt, erefcnt */ isc_mem_t *mctx; dns_view_t *view; isc_timermgr_t *timermgr; @@ -131,32 +133,35 @@ struct dns_adb { unsigned int erefcnt; isc_mutex_t mplock; - isc_mempool_t *nmp; /* dns_adbname_t */ - isc_mempool_t *nhmp; /* dns_adbnamehook_t */ - isc_mempool_t *zimp; /* dns_adbzoneinfo_t */ - isc_mempool_t *emp; /* dns_adbentry_t */ - isc_mempool_t *ahmp; /* dns_adbfind_t */ - isc_mempool_t *aimp; /* dns_adbaddrinfo_t */ - isc_mempool_t *afmp; /* dns_adbfetch_t */ + isc_mempool_t *nmp; /*%< dns_adbname_t */ + isc_mempool_t *nhmp; /*%< dns_adbnamehook_t */ + isc_mempool_t *zimp; /*%< dns_adbzoneinfo_t */ + isc_mempool_t *emp; /*%< dns_adbentry_t */ + isc_mempool_t *ahmp; /*%< dns_adbfind_t */ + isc_mempool_t *aimp; /*%< dns_adbaddrinfo_t */ + isc_mempool_t *afmp; /*%< dns_adbfetch_t */ - /* + /*! * Bucketized locks and lists for names. * * XXXRTH Have a per-bucket structure that contains all of these? */ dns_adbnamelist_t names[NBUCKETS]; + /*% See dns_adbnamelist_t */ isc_mutex_t namelocks[NBUCKETS]; + /*% See dns_adbnamelist_t */ isc_boolean_t name_sd[NBUCKETS]; + /*% See dns_adbnamelist_t */ unsigned int name_refcnt[NBUCKETS]; - /* + /*! * Bucketized locks for entries. * * XXXRTH Have a per-bucket structure that contains all of these? */ dns_adbentrylist_t entries[NBUCKETS]; isc_mutex_t entrylocks[NBUCKETS]; - isc_boolean_t entry_sd[NBUCKETS]; /* shutting down */ + isc_boolean_t entry_sd[NBUCKETS]; /*%< shutting down */ unsigned int entry_refcnt[NBUCKETS]; isc_event_t cevent; @@ -169,6 +174,7 @@ struct dns_adb { * XXXMLG Document these structures. */ +/*% dns_adbname structure */ struct dns_adbname { unsigned int magic; dns_name_t name; @@ -191,6 +197,7 @@ struct dns_adbname { ISC_LINK(dns_adbname_t) plink; }; +/*% The adbfetch structure */ struct dns_adbfetch { unsigned int magic; dns_adbnamehook_t *namehook; @@ -199,9 +206,7 @@ struct dns_adbfetch { dns_rdataset_t rdataset; }; -/* - * dns_adbnamehook_t - * +/*% * This is a small widget that dangles off a dns_adbname_t. It contains a * pointer to the address information about this host, and a link to the next * namehook that will contain the next address this host has. @@ -212,9 +217,7 @@ struct dns_adbnamehook { ISC_LINK(dns_adbnamehook_t) plink; }; -/* - * dns_adbzoneinfo_t - * +/*% * This is a small widget that holds zone-specific information about an * address. Currently limited to lameness, but could just as easily be * extended to other types of information about zones. @@ -228,7 +231,7 @@ struct dns_adbzoneinfo { ISC_LINK(dns_adbzoneinfo_t) plink; }; -/* +/*% * An address entry. It holds quite a bit of information about addresses, * including edns state (in "flags"), rtt, and of course the address of * the host. @@ -244,7 +247,7 @@ struct dns_adbentry { isc_sockaddr_t sockaddr; isc_stdtime_t expires; - /* + /*%< * A nonzero 'expires' field indicates that the entry should * persist until that time. This allows entries found * using dns_adb_findaddrinfo() to persist for a limited time diff --git a/lib/dns/byaddr.c b/lib/dns/byaddr.c index f10e398f38..a02b0acd50 100644 --- a/lib/dns/byaddr.c +++ b/lib/dns/byaddr.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: byaddr.c,v 1.35 2004/08/28 06:16:55 marka Exp $ */ +/* $Id: byaddr.c,v 1.36 2005/04/27 04:56:44 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/cache.c b/lib/dns/cache.c index a54e78430a..e5534d9cfb 100644 --- a/lib/dns/cache.c +++ b/lib/dns/cache.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: cache.c,v 1.59 2005/03/16 00:55:17 marka Exp $ */ +/* $Id: cache.c,v 1.60 2005/04/27 04:56:44 sra Exp $ */ + +/*! \file */ #include @@ -39,13 +41,18 @@ #define CACHE_MAGIC ISC_MAGIC('$', '$', '$', '$') #define VALID_CACHE(cache) ISC_MAGIC_VALID(cache, CACHE_MAGIC) -/* - * The following two variables control incremental cleaning. - * MINSIZE is how many bytes is the floor for dns_cache_setcachesize(). - * CLEANERINCREMENT is how many nodes are examined in one pass. +/*! + * Control incremental cleaning. + * DNS_CACHE_MINSIZE is how many bytes is the floor for dns_cache_setcachesize(). + * See also DNS_CACHE_CLEANERINCREMENT */ -#define DNS_CACHE_MINSIZE 2097152 /* Bytes. 2097152 = 2 MB */ -#define DNS_CACHE_CLEANERINCREMENT 1000 /* Number of nodes. */ +#define DNS_CACHE_MINSIZE 2097152 /*%< Bytes. 2097152 = 2 MB */ +/*! + * Control incremental cleaning. + * CLEANERINCREMENT is how many nodes are examined in one pass. + * See also DNS_CACHE_MINSIZE + */ +#define DNS_CACHE_CLEANERINCREMENT 1000 /*%< Number of nodes. */ /*** *** Types @@ -59,9 +66,9 @@ typedef struct cache_cleaner cache_cleaner_t; typedef enum { - cleaner_s_idle, /* Waiting for cleaning-interval to expire. */ - cleaner_s_busy, /* Currently cleaning. */ - cleaner_s_done /* Freed enough memory after being overmem. */ + cleaner_s_idle, /*%< Waiting for cleaning-interval to expire. */ + cleaner_s_busy, /*%< Currently cleaning. */ + cleaner_s_done /*%< Freed enough memory after being overmem. */ } cleaner_state_t; /* @@ -74,13 +81,13 @@ typedef enum { (c)->iterator != NULL && \ (c)->resched_event == NULL) -/* +/*% * Accesses to a cache cleaner object are synchronized through * task/event serialization, or locked from the cache object. */ struct cache_cleaner { isc_mutex_t lock; - /* + /*%< * Locks overmem_event, overmem. Note: never allocate memory * while holding this lock - that could lead to deadlock since * the lock is take by water() which is called from the memory @@ -89,21 +96,21 @@ struct cache_cleaner { dns_cache_t *cache; isc_task_t *task; - unsigned int cleaning_interval; /* The cleaning-interval from + unsigned int cleaning_interval; /*% The cleaning-interval from named.conf, in seconds. */ isc_timer_t *cleaning_timer; - isc_event_t *resched_event; /* Sent by cleaner task to + isc_event_t *resched_event; /*% Sent by cleaner task to itself to reschedule */ isc_event_t *overmem_event; dns_dbiterator_t *iterator; - int increment; /* Number of names to + int increment; /*% Number of names to clean in one increment */ - cleaner_state_t state; /* Idle/Busy. */ - isc_boolean_t overmem; /* The cache is in an overmem state. */ + cleaner_state_t state; /*% Idle/Busy. */ + isc_boolean_t overmem; /*% The cache is in an overmem state. */ }; -/* +/*% * The actual cache object. */ diff --git a/lib/dns/callbacks.c b/lib/dns/callbacks.c index c6c83f514e..9730baf982 100644 --- a/lib/dns/callbacks.c +++ b/lib/dns/callbacks.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: callbacks.c,v 1.13 2004/03/05 05:09:18 marka Exp $ */ +/* $Id: callbacks.c,v 1.14 2005/04/27 04:56:44 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/compress.c b/lib/dns/compress.c index 8987ce2aae..8eed3fc689 100644 --- a/lib/dns/compress.c +++ b/lib/dns/compress.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: compress.c,v 1.54 2005/03/06 15:30:37 marka Exp $ */ +/* $Id: compress.c,v 1.55 2005/04/27 04:56:45 sra Exp $ */ + +/*! \file */ #define DNS_NAME_USEINLINE 1 diff --git a/lib/dns/db.c b/lib/dns/db.c index a539ebdee4..624210166c 100644 --- a/lib/dns/db.c +++ b/lib/dns/db.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: db.c,v 1.75 2004/12/21 10:45:16 jinmei Exp $ */ +/* $Id: db.c,v 1.76 2005/04/27 04:56:45 sra Exp $ */ + +/*! \file */ /*** *** Imports diff --git a/lib/dns/dbiterator.c b/lib/dns/dbiterator.c index 8996fd86c1..24244fbeaa 100644 --- a/lib/dns/dbiterator.c +++ b/lib/dns/dbiterator.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dbiterator.c,v 1.14 2004/03/05 05:09:18 marka Exp $ */ +/* $Id: dbiterator.c,v 1.15 2005/04/27 04:56:45 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/dbtable.c b/lib/dns/dbtable.c index 3183722981..8963b1621a 100644 --- a/lib/dns/dbtable.c +++ b/lib/dns/dbtable.c @@ -16,10 +16,11 @@ */ /* - * $Id: dbtable.c,v 1.28 2004/03/05 05:09:19 marka Exp $ + * $Id: dbtable.c,v 1.29 2005/04/27 04:56:45 sra Exp $ */ -/* +/*! \file + * \author * Principal Author: DCL */ diff --git a/lib/dns/diff.c b/lib/dns/diff.c index af7f8e9c04..c47b8e8c3a 100644 --- a/lib/dns/diff.c +++ b/lib/dns/diff.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: diff.c,v 1.11 2005/01/14 00:00:29 marka Exp $ */ +/* $Id: diff.c,v 1.12 2005/04/27 04:56:45 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/dispatch.c b/lib/dns/dispatch.c index c1d6c202a5..bd963d0096 100644 --- a/lib/dns/dispatch.c +++ b/lib/dns/dispatch.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dispatch.c,v 1.122 2005/02/24 00:33:33 marka Exp $ */ +/* $Id: dispatch.c,v 1.123 2005/04/27 04:56:45 sra Exp $ */ + +/*! \file */ #include @@ -43,12 +45,12 @@ typedef ISC_LIST(dns_dispentry_t) dns_displist_t; typedef struct dns_qid { unsigned int magic; - unsigned int qid_nbuckets; /* hash table size */ - unsigned int qid_increment; /* id increment on collision */ + unsigned int qid_nbuckets; /*%< hash table size */ + unsigned int qid_increment; /*%< id increment on collision */ isc_mutex_t lock; - isc_lfsr_t qid_lfsr1; /* state generator info */ - isc_lfsr_t qid_lfsr2; /* state generator info */ - dns_displist_t *qid_table; /* the table itself */ + isc_lfsr_t qid_lfsr1; /*%< state generator info */ + isc_lfsr_t qid_lfsr2; /*%< state generator info */ + dns_displist_t *qid_table; /*%< the table itself */ } dns_qid_t; struct dns_dispatchmgr { @@ -66,18 +68,18 @@ struct dns_dispatchmgr { /* locked by buffer lock */ dns_qid_t *qid; isc_mutex_t buffer_lock; - unsigned int buffers; /* allocated buffers */ - unsigned int buffersize; /* size of each buffer */ - unsigned int maxbuffers; /* max buffers */ + unsigned int buffers; /*%< allocated buffers */ + unsigned int buffersize; /*%< size of each buffer */ + unsigned int maxbuffers; /*%< max buffers */ /* Locked internally. */ isc_mutex_t pool_lock; - isc_mempool_t *epool; /* memory pool for events */ - isc_mempool_t *rpool; /* memory pool for replies */ - isc_mempool_t *dpool; /* dispatch allocations */ - isc_mempool_t *bpool; /* memory pool for buffers */ + isc_mempool_t *epool; /*%< memory pool for events */ + isc_mempool_t *rpool; /*%< memory pool for replies */ + isc_mempool_t *dpool; /*%< dispatch allocations */ + isc_mempool_t *bpool; /*%< memory pool for buffers */ - isc_entropy_t *entropy; /* entropy source */ + isc_entropy_t *entropy; /*%< entropy source */ }; #define MGR_SHUTTINGDOWN 0x00000001U @@ -103,32 +105,32 @@ struct dns_dispentry { struct dns_dispatch { /* Unlocked. */ - unsigned int magic; /* magic */ - dns_dispatchmgr_t *mgr; /* dispatch manager */ - isc_task_t *task; /* internal task */ - isc_socket_t *socket; /* isc socket attached to */ - isc_sockaddr_t local; /* local address */ - unsigned int maxrequests; /* max requests */ + unsigned int magic; /*%< magic */ + dns_dispatchmgr_t *mgr; /*%< dispatch manager */ + isc_task_t *task; /*%< internal task */ + isc_socket_t *socket; /*%< isc socket attached to */ + isc_sockaddr_t local; /*%< local address */ + unsigned int maxrequests; /*%< max requests */ isc_event_t *ctlevent; - /* Locked by mgr->lock. */ + /*% Locked by mgr->lock. */ ISC_LINK(dns_dispatch_t) link; /* Locked by "lock". */ - isc_mutex_t lock; /* locks all below */ + isc_mutex_t lock; /*%< locks all below */ isc_sockettype_t socktype; unsigned int attributes; - unsigned int refcount; /* number of users */ - dns_dispatchevent_t *failsafe_ev; /* failsafe cancel event */ + unsigned int refcount; /*%< number of users */ + dns_dispatchevent_t *failsafe_ev; /*%< failsafe cancel event */ unsigned int shutting_down : 1, shutdown_out : 1, connected : 1, tcpmsg_valid : 1, - recv_pending : 1; /* is a recv() pending? */ + recv_pending : 1; /*%< is a recv() pending? */ isc_result_t shutdown_why; - unsigned int requests; /* how many requests we have */ - unsigned int tcpbuffers; /* allocated buffers */ - dns_tcpmsg_t tcpmsg; /* for tcp streams */ + unsigned int requests; /*%< how many requests we have */ + unsigned int tcpbuffers; /*%< allocated buffers */ + dns_tcpmsg_t tcpmsg; /*%< for tcp streams */ dns_qid_t *qid; }; diff --git a/lib/dns/dnssec.c b/lib/dns/dnssec.c index 2efe8311b3..f895bfa9b5 100644 --- a/lib/dns/dnssec.c +++ b/lib/dns/dnssec.c @@ -16,9 +16,10 @@ */ /* - * $Id: dnssec.c,v 1.82 2004/06/11 00:26:59 marka Exp $ + * $Id: dnssec.c,v 1.83 2005/04/27 04:56:45 sra Exp $ */ +/*! \file */ #include diff --git a/lib/dns/ds.c b/lib/dns/ds.c index 1e2aa20f72..a952079ec0 100644 --- a/lib/dns/ds.c +++ b/lib/dns/ds.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ds.c,v 1.6 2005/03/06 15:30:37 marka Exp $ */ +/* $Id: ds.c,v 1.7 2005/04/27 04:56:45 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/dst_api.c b/lib/dns/dst_api.c index d6d13878c9..628e54f82b 100644 --- a/lib/dns/dst_api.c +++ b/lib/dns/dst_api.c @@ -18,9 +18,11 @@ /* * Principal Author: Brian Wellington - * $Id: dst_api.c,v 1.1 2004/12/09 01:41:00 marka Exp $ + * $Id: dst_api.c,v 1.2 2005/04/27 04:56:46 sra Exp $ */ +/*! \file */ + #include #include @@ -486,7 +488,7 @@ dst_key_todns(const dst_key_t *key, isc_buffer_t *target) { & 0xffff)); } - if (key->opaque == NULL) /* NULL KEY */ + if (key->opaque == NULL) /*%< NULL KEY */ return (ISC_R_SUCCESS); return (key->func->todns(key, target)); @@ -633,7 +635,7 @@ dst_key_generate(dns_name_t *name, unsigned int alg, if (key == NULL) return (ISC_R_NOMEMORY); - if (bits == 0) { /* NULL KEY */ + if (bits == 0) { /*%< NULL KEY */ key->key_flags |= DNS_KEYTYPE_NOKEY; *keyp = key; return (ISC_R_SUCCESS); @@ -758,7 +760,7 @@ dst_key_sigsize(const dst_key_t *key, unsigned int *n) { *n = 16; break; case DST_ALG_GSSAPI: - *n = 128; /* XXX */ + *n = 128; /*%< XXX */ break; case DST_ALG_DH: default: @@ -784,7 +786,7 @@ dst_key_secretsize(const dst_key_t *key, unsigned int *n) { *** Static methods ***/ -/* +/*% * Allocates a key structure and fills in some of the fields. */ static dst_key_t * @@ -826,7 +828,7 @@ get_key_struct(dns_name_t *name, unsigned int alg, return (key); } -/* +/*% * Reads a public key from disk */ isc_result_t @@ -913,7 +915,7 @@ dst_key_read_public(const char *filename, int type, if (strcasecmp(DST_AS_STR(token), "DNSKEY") == 0) keytype = dns_rdatatype_dnskey; else if (strcasecmp(DST_AS_STR(token), "KEY") == 0) - keytype = dns_rdatatype_key; /* SIG(0), TKEY */ + keytype = dns_rdatatype_key; /*%< SIG(0), TKEY */ else BADTOKEN(); @@ -960,7 +962,7 @@ issymmetric(const dst_key_t *key) { } } -/* +/*% * Writes a public key to disk in DNS format. */ static isc_result_t diff --git a/lib/dns/dst_internal.h b/lib/dns/dst_internal.h index 7b00f15d11..0e659fa405 100644 --- a/lib/dns/dst_internal.h +++ b/lib/dns/dst_internal.h @@ -16,7 +16,7 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dst_internal.h,v 1.1 2004/12/09 01:41:00 marka Exp $ */ +/* $Id: dst_internal.h,v 1.2 2005/04/27 04:56:46 sra Exp $ */ #ifndef DST_DST_INTERNAL_H #define DST_DST_INTERNAL_H 1 @@ -46,18 +46,19 @@ extern isc_mem_t *dst__memory_pool; typedef struct dst_func dst_func_t; +/*% DST Key Structure */ struct dst_key { unsigned int magic; - dns_name_t * key_name; /* name of the key */ - unsigned int key_size; /* size of the key in bits */ - unsigned int key_proto; /* protocols this key is used for */ - unsigned int key_alg; /* algorithm of the key */ - isc_uint32_t key_flags; /* flags of the public key */ - isc_uint16_t key_id; /* identifier of the key */ - dns_rdataclass_t key_class; /* class of the key record */ - isc_mem_t *mctx; /* memory context */ - void * opaque; /* pointer to key in crypto pkg fmt */ - dst_func_t * func; /* crypto package specific functions */ + dns_name_t * key_name; /*%< name of the key */ + unsigned int key_size; /*%< size of the key in bits */ + unsigned int key_proto; /*%< protocols this key is used for */ + unsigned int key_alg; /*%< algorithm of the key */ + isc_uint32_t key_flags; /*%< flags of the public key */ + isc_uint16_t key_id; /*%< identifier of the key */ + dns_rdataclass_t key_class; /*%< class of the key record */ + isc_mem_t *mctx; /*%< memory context */ + void * opaque; /*%< pointer to key in crypto pkg fmt */ + dst_func_t * func; /*%< crypto package specific functions */ }; struct dst_context { @@ -100,7 +101,7 @@ struct dst_func { void (*cleanup)(void); }; -/* +/*% * Initializers */ isc_result_t dst__openssl_init(void); @@ -111,19 +112,19 @@ isc_result_t dst__openssldsa_init(struct dst_func **funcp); isc_result_t dst__openssldh_init(struct dst_func **funcp); isc_result_t dst__gssapi_init(struct dst_func **funcp); -/* +/*% * Destructors */ void dst__openssl_destroy(void); -/* +/*% * Memory allocators using the DST memory pool. */ void * dst__mem_alloc(size_t size); void dst__mem_free(void *ptr); void * dst__mem_realloc(void *ptr, size_t size); -/* +/*% * Entropy retriever using the DST entropy pool. */ isc_result_t dst__entropy_getdata(void *buf, unsigned int len, @@ -132,3 +133,4 @@ isc_result_t dst__entropy_getdata(void *buf, unsigned int len, ISC_LANG_ENDDECLS #endif /* DST_DST_INTERNAL_H */ +/*! \file */ diff --git a/lib/dns/dst_lib.c b/lib/dns/dst_lib.c index 4935d92cb7..87bad8c38f 100644 --- a/lib/dns/dst_lib.c +++ b/lib/dns/dst_lib.c @@ -17,9 +17,11 @@ /* * Principal Author: Brian Wellington - * $Id: dst_lib.c,v 1.1 2004/12/09 01:41:01 marka Exp $ + * $Id: dst_lib.c,v 1.2 2005/04/27 04:56:46 sra Exp $ */ +/*! \file */ + #include #include diff --git a/lib/dns/dst_openssl.h b/lib/dns/dst_openssl.h index 5a29fde94e..a511e76a27 100644 --- a/lib/dns/dst_openssl.h +++ b/lib/dns/dst_openssl.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dst_openssl.h,v 1.1 2004/12/09 01:41:01 marka Exp $ */ +/* $Id: dst_openssl.h,v 1.2 2005/04/27 04:56:46 sra Exp $ */ #ifndef DST_OPENSSL_H #define DST_OPENSSL_H 1 @@ -31,3 +31,4 @@ dst__openssl_toresult(isc_result_t fallback); ISC_LANG_ENDDECLS #endif /* DST_OPENSSL_H */ +/*! \file */ diff --git a/lib/dns/dst_parse.c b/lib/dns/dst_parse.c index 9f2a93daf1..36e513d10e 100644 --- a/lib/dns/dst_parse.c +++ b/lib/dns/dst_parse.c @@ -16,9 +16,9 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* +/*% * Principal Author: Brian Wellington - * $Id: dst_parse.c,v 1.1 2004/12/09 01:41:02 marka Exp $ + * $Id: dst_parse.c,v 1.2 2005/04/27 04:56:46 sra Exp $ */ #include @@ -410,3 +410,5 @@ dst__privstruct_writefile(const dst_key_t *key, const dst_private_t *priv, fclose(fp); return (ISC_R_SUCCESS); } + +/*! \file */ diff --git a/lib/dns/dst_parse.h b/lib/dns/dst_parse.h index 6a9b133a57..5c17a66b00 100644 --- a/lib/dns/dst_parse.h +++ b/lib/dns/dst_parse.h @@ -16,8 +16,9 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dst_parse.h,v 1.1 2004/12/09 01:41:02 marka Exp $ */ +/* $Id: dst_parse.h,v 1.2 2005/04/27 04:56:46 sra Exp $ */ +/*! \file */ #ifndef DST_DST_PARSE_H #define DST_DST_PARSE_H 1 diff --git a/lib/dns/dst_result.c b/lib/dns/dst_result.c index d7e4929f38..c10ccbfeec 100644 --- a/lib/dns/dst_result.c +++ b/lib/dns/dst_result.c @@ -15,9 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* +/*% * Principal Author: Brian Wellington - * $Id: dst_result.c,v 1.1 2004/12/09 01:41:02 marka Exp $ + * $Id: dst_result.c,v 1.2 2005/04/27 04:56:46 sra Exp $ */ #include @@ -29,27 +29,27 @@ #include static const char *text[DST_R_NRESULTS] = { - "algorithm is unsupported", /* 0 */ - "openssl failure", /* 1 */ - "built with no crypto support", /* 2 */ - "illegal operation for a null key", /* 3 */ - "public key is invalid", /* 4 */ - "private key is invalid", /* 5 */ - "UNUSED6", /* 6 */ - "error occurred writing key to disk", /* 7 */ - "invalid algorithm specific parameter", /* 8 */ - "UNUSED9", /* 9 */ - "UNUSED10", /* 10 */ - "sign failure", /* 11 */ - "UNUSED12", /* 12 */ - "UNUSED13", /* 13 */ - "verify failure", /* 14 */ - "not a public key", /* 15 */ - "not a private key", /* 16 */ - "not a key that can compute a secret", /* 17 */ - "failure computing a shared secret", /* 18 */ - "no randomness available", /* 19 */ - "bad key type" /* 20 */ + "algorithm is unsupported", /*%< 0 */ + "openssl failure", /*%< 1 */ + "built with no crypto support", /*%< 2 */ + "illegal operation for a null key", /*%< 3 */ + "public key is invalid", /*%< 4 */ + "private key is invalid", /*%< 5 */ + "UNUSED6", /*%< 6 */ + "error occurred writing key to disk", /*%< 7 */ + "invalid algorithm specific parameter", /*%< 8 */ + "UNUSED9", /*%< 9 */ + "UNUSED10", /*%< 10 */ + "sign failure", /*%< 11 */ + "UNUSED12", /*%< 12 */ + "UNUSED13", /*%< 13 */ + "verify failure", /*%< 14 */ + "not a public key", /*%< 15 */ + "not a private key", /*%< 16 */ + "not a key that can compute a secret", /*%< 17 */ + "failure computing a shared secret", /*%< 18 */ + "no randomness available", /*%< 19 */ + "bad key type" /*%< 20 */ }; #define DST_RESULT_RESULTSET 2 @@ -84,3 +84,5 @@ void dst_result_register(void) { initialize(); } + +/*! \file */ diff --git a/lib/dns/forward.c b/lib/dns/forward.c index d8d3c6c521..07a4055805 100644 --- a/lib/dns/forward.c +++ b/lib/dns/forward.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: forward.c,v 1.8 2005/03/17 03:56:12 marka Exp $ */ +/* $Id: forward.c,v 1.9 2005/04/27 04:56:46 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/gen-unix.h b/lib/dns/gen-unix.h index ee51242f52..dfa52de861 100644 --- a/lib/dns/gen-unix.h +++ b/lib/dns/gen-unix.h @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gen-unix.h,v 1.14 2004/03/05 05:09:19 marka Exp $ */ +/* $Id: gen-unix.h,v 1.15 2005/04/27 04:56:46 sra Exp $ */ -/* +/*! \file + * \brief * This file is responsible for defining two operations that are not * directly portable between Unix-like systems and Windows NT, option * parsing and directory scanning. It is here because it was decided diff --git a/lib/dns/gen-win32.h b/lib/dns/gen-win32.h index fa131f50a9..02a94f0481 100644 --- a/lib/dns/gen-win32.h +++ b/lib/dns/gen-win32.h @@ -48,15 +48,15 @@ * SUCH DAMAGE. */ -/* $Id: gen-win32.h,v 1.16 2004/03/05 05:09:20 marka Exp $ */ +/* $Id: gen-win32.h,v 1.17 2005/04/27 04:56:46 sra Exp $ */ -/* - * Principal Authors: Computer Systems Research Group at UC Berkeley - * Principal ISC caretaker: DCL +/*! \file + * \author Principal Authors: Computer Systems Research Group at UC Berkeley + * \author Principal ISC caretaker: DCL */ /* - * This file was adapted from the NetBSD project's source tree, RCS ID: + * \note This file was adapted from the NetBSD project's source tree, RCS ID: * NetBSD: getopt.c,v 1.15 1999/09/20 04:39:37 lukem Exp * * The primary change has been to rename items to the ISC namespace diff --git a/lib/dns/gen.c b/lib/dns/gen.c index bc5bd645c3..9a4019630d 100644 --- a/lib/dns/gen.c +++ b/lib/dns/gen.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gen.c,v 1.73 2004/03/16 05:52:18 marka Exp $ */ +/* $Id: gen.c,v 1.74 2005/04/27 04:56:46 sra Exp $ */ + +/*! \file */ #include @@ -118,6 +120,8 @@ const char copyright[] = " *************** DO NOT EDIT!\n" " ***************\n" " ***************/\n" +"\n" +"/*! \\file */\n" "\n"; #define TYPENAMES 256 @@ -163,7 +167,7 @@ sd(int, const char *, const char *, char); void insert_into_typenames(int, const char *, const char *); -/* +/*% * If you use more than 10 of these in, say, a printf(), you'll have problems. */ char * diff --git a/lib/dns/gssapi_link.c b/lib/dns/gssapi_link.c index 0ecfb046ec..7182da9b52 100644 --- a/lib/dns/gssapi_link.c +++ b/lib/dns/gssapi_link.c @@ -16,7 +16,7 @@ */ /* - * $Id: gssapi_link.c,v 1.1 2004/12/09 01:41:02 marka Exp $ + * $Id: gssapi_link.c,v 1.2 2005/04/27 04:56:47 sra Exp $ */ #ifdef GSSAPI @@ -194,17 +194,17 @@ static dst_func_t gssapi_functions = { gssapi_adddata, gssapi_sign, gssapi_verify, - NULL, /* computesecret */ + NULL, /*%< computesecret */ gssapi_compare, - NULL, /* paramcompare */ + NULL, /*%< paramcompare */ gssapi_generate, gssapi_isprivate, gssapi_destroy, - NULL, /* todns */ - NULL, /* fromdns */ - NULL, /* tofile */ - NULL, /* parse */ - NULL, /* cleanup */ + NULL, /*%< todns */ + NULL, /*%< fromdns */ + NULL, /*%< tofile */ + NULL, /*%< parse */ + NULL, /*%< cleanup */ }; isc_result_t @@ -218,3 +218,5 @@ dst__gssapi_init(dst_func_t **funcp) { #else int gssapi_link_unneeded = 1; #endif + +/*! \file */ diff --git a/lib/dns/gssapictx.c b/lib/dns/gssapictx.c index ab8a311567..4276cdd699 100644 --- a/lib/dns/gssapictx.c +++ b/lib/dns/gssapictx.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gssapictx.c,v 1.1 2004/12/09 01:41:03 marka Exp $ */ +/* $Id: gssapictx.c,v 1.2 2005/04/27 04:56:47 sra Exp $ */ #include @@ -260,3 +260,5 @@ dst_gssapi_acceptctx(dns_name_t *name, void *cred, } #endif + +/*! \file */ diff --git a/lib/dns/hmac_link.c b/lib/dns/hmac_link.c index 38b2e30a42..282683d2a8 100644 --- a/lib/dns/hmac_link.c +++ b/lib/dns/hmac_link.c @@ -18,7 +18,7 @@ /* * Principal Author: Brian Wellington - * $Id: hmac_link.c,v 1.1 2004/12/09 01:41:03 marka Exp $ + * $Id: hmac_link.c,v 1.2 2005/04/27 04:56:47 sra Exp $ */ #include @@ -260,9 +260,9 @@ static dst_func_t hmacmd5_functions = { hmacmd5_adddata, hmacmd5_sign, hmacmd5_verify, - NULL, /* computesecret */ + NULL, /*%< computesecret */ hmacmd5_compare, - NULL, /* paramcompare */ + NULL, /*%< paramcompare */ hmacmd5_generate, hmacmd5_isprivate, hmacmd5_destroy, @@ -270,7 +270,7 @@ static dst_func_t hmacmd5_functions = { hmacmd5_fromdns, hmacmd5_tofile, hmacmd5_parse, - NULL, /* cleanup */ + NULL, /*%< cleanup */ }; isc_result_t @@ -280,3 +280,5 @@ dst__hmacmd5_init(dst_func_t **funcp) { *funcp = &hmacmd5_functions; return (ISC_R_SUCCESS); } + +/*! \file */ diff --git a/lib/dns/include/dns/acl.h b/lib/dns/include/dns/acl.h index a896b48805..38757f960e 100644 --- a/lib/dns/include/dns/acl.h +++ b/lib/dns/include/dns/acl.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: acl.h,v 1.22 2004/03/05 05:09:40 marka Exp $ */ +/* $Id: acl.h,v 1.23 2005/04/27 04:56:53 sra Exp $ */ #ifndef DNS_ACL_H #define DNS_ACL_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * Address match list handling. */ @@ -75,10 +76,10 @@ struct dns_acl { isc_mem_t *mctx; isc_refcount_t refcount; dns_aclelement_t *elements; - unsigned int alloc; /* Elements allocated */ - unsigned int length; /* Elements initialized */ - char *name; /* Temporary use only */ - ISC_LINK(dns_acl_t) nextincache; /* Ditto */ + unsigned int alloc; /*%< Elements allocated */ + unsigned int length; /*%< Elements initialized */ + char *name; /*%< Temporary use only */ + ISC_LINK(dns_acl_t) nextincache; /*%< Ditto */ }; struct dns_aclenv { @@ -98,26 +99,26 @@ ISC_LANG_BEGINDECLS isc_result_t dns_acl_create(isc_mem_t *mctx, int n, dns_acl_t **target); -/* +/*%< * Create a new ACL with room for 'n' elements. * The elements are uninitialized and the length is 0. */ isc_result_t dns_acl_appendelement(dns_acl_t *acl, dns_aclelement_t *elt); -/* +/*%< * Append an element to an existing ACL. */ isc_result_t dns_acl_any(isc_mem_t *mctx, dns_acl_t **target); -/* +/*%< * Create a new ACL that matches everything. */ isc_result_t dns_acl_none(isc_mem_t *mctx, dns_acl_t **target); -/* +/*%< * Create a new ACL that matches nothing. */ @@ -135,13 +136,13 @@ dns_acl_equal(dns_acl_t *a, dns_acl_t *b); isc_boolean_t dns_acl_isinsecure(dns_acl_t *a); -/* - * Return ISC_TRUE iff the acl 'a' is considered insecure, that is, +/*%< + * Return #ISC_TRUE iff the acl 'a' is considered insecure, that is, * if it contains IP addresses other than those of the local host. * This is intended for applications such as printing warning * messages for suspect ACLs; it is not intended for making access * control decisions. We make no guarantee that an ACL for which - * this function returns ISC_FALSE is safe. + * this function returns #ISC_FALSE is safe. */ isc_result_t @@ -160,7 +161,7 @@ dns_acl_match(isc_netaddr_t *reqaddr, dns_aclenv_t *env, int *match, dns_aclelement_t **matchelt); -/* +/*%< * General, low-level ACL matching. This is expected to * be useful even for weird stuff like the topology and sortlist statements. * @@ -181,7 +182,7 @@ dns_acl_match(isc_netaddr_t *reqaddr, * If there is no match, *match will be set to zero. * * Returns: - * ISC_R_SUCCESS Always succeeds. + *\li #ISC_R_SUCCESS Always succeeds. */ isc_boolean_t @@ -190,7 +191,7 @@ dns_aclelement_match(isc_netaddr_t *reqaddr, dns_aclelement_t *e, dns_aclenv_t *env, dns_aclelement_t **matchelt); -/* +/*%< * Like dns_acl_match, but matches against the single ACL element 'e' * rather than a complete list and returns ISC_TRUE iff it matched. * To determine whether the match was prositive or negative, the @@ -203,7 +204,7 @@ isc_result_t dns_acl_elementmatch(dns_acl_t *acl, dns_aclelement_t *elt, dns_aclelement_t **matchelt); -/* +/*%< * Search for an ACL element in 'acl' which is exactly the same as 'elt'. * If there is one, and 'matchelt' is non NULL, then '*matchelt' will point * to the entry. @@ -212,8 +213,8 @@ dns_acl_elementmatch(dns_acl_t *acl, * before adding an entry. * * Returns: - * ISC_R_SUCCESS Match succeeds. - * ISC_R_NOTFOUND Match fails. + *\li #ISC_R_SUCCESS Match succeeds. + *\li #ISC_R_NOTFOUND Match fails. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/adb.h b/lib/dns/include/dns/adb.h index 25af3e2e70..96cbf6c5af 100644 --- a/lib/dns/include/dns/adb.h +++ b/lib/dns/include/dns/adb.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: adb.h,v 1.76 2004/03/05 05:09:40 marka Exp $ */ +/* $Id: adb.h,v 1.77 2005/04/27 04:56:53 sra Exp $ */ #ifndef DNS_ADB_H #define DNS_ADB_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + *\brief * DNS Address Database * * This module implements an address database (ADB) for mapping a name @@ -56,14 +57,14 @@ * * MP: * - * The ADB takes care of all necessary locking. + *\li The ADB takes care of all necessary locking. * - * Only the task which initiated the name lookup can cancel the lookup. + *\li Only the task which initiated the name lookup can cancel the lookup. * * * Security: * - * None, since all data stored is required to be pre-filtered. + *\li None, since all data stored is required to be pre-filtered. * (Cache needs to be sane, fetches return bounds-checked and sanity- * checked data, caller passes a good dns_name_t for the zone, etc) */ @@ -98,8 +99,8 @@ ISC_LANG_BEGINDECLS typedef struct dns_adbname dns_adbname_t; -/* dns_adbfind_t - * +/*! + *\brief * Represents a lookup for a single name. * * On return, the client can safely use "list", and can reorder the list. @@ -108,14 +109,14 @@ typedef struct dns_adbname dns_adbname_t; */ struct dns_adbfind { /* Public */ - unsigned int magic; /* RO: magic */ - dns_adbaddrinfolist_t list; /* RO: list of addrs */ - unsigned int query_pending; /* RO: partial list */ - unsigned int partial_result; /* RO: addrs missing */ - unsigned int options; /* RO: options */ - isc_result_t result_v4; /* RO: v4 result */ - isc_result_t result_v6; /* RO: v6 result */ - ISC_LINK(dns_adbfind_t) publink; /* RW: client use */ + unsigned int magic; /*%< RO: magic */ + dns_adbaddrinfolist_t list; /*%< RO: list of addrs */ + unsigned int query_pending; /*%< RO: partial list */ + unsigned int partial_result; /*%< RO: addrs missing */ + unsigned int options; /*%< RO: options */ + isc_result_t result_v4; /*%< RO: v4 result */ + isc_result_t result_v6; /*%< RO: v6 result */ + ISC_LINK(dns_adbfind_t) publink; /*%< RW: client use */ /* Private */ isc_mutex_t lock; /* locks all below */ @@ -161,34 +162,65 @@ struct dns_adbfind { * At least one address was omitted from the list because it was lame. * This bit will NEVER be set if _RETURNLAME is set in the createfind(). */ +/*% Return addresses of type INET. */ #define DNS_ADBFIND_INET 0x00000001 +/*% Return addresses of type INET6. */ #define DNS_ADBFIND_INET6 0x00000002 #define DNS_ADBFIND_ADDRESSMASK 0x00000003 - +/*% + * Only schedule an event if no addresses are known. + * Must set _WANTEVENT for this to be meaningful. + */ #define DNS_ADBFIND_EMPTYEVENT 0x00000004 +/*% + * An event is desired. Check this bit in the returned find to see + * if one will actually be generated. + */ #define DNS_ADBFIND_WANTEVENT 0x00000008 +/*% + * If set, fetches will not be generated unless no addresses are + * available in any of the address families requested. + */ #define DNS_ADBFIND_AVOIDFETCHES 0x00000010 +/*% + * Fetches will start using the closest zone data or use the root servers. + * This is useful for reestablishing glue that has expired. + */ #define DNS_ADBFIND_STARTATZONE 0x00000020 +/*% + * Glue or hints are ok. These are used when matching names already + * in the adb, and when dns databases are searched. + */ #define DNS_ADBFIND_GLUEOK 0x00000040 +/*% + * Glue or hints are ok. These are used when matching names already + * in the adb, and when dns databases are searched. + */ #define DNS_ADBFIND_HINTOK 0x00000080 +/*% + * Return lame servers in a find, so that all addresses are returned. + */ #define DNS_ADBFIND_RETURNLAME 0x00000100 +/*% + * Only schedule an event if no addresses are known. + * Must set _WANTEVENT for this to be meaningful. + */ #define DNS_ADBFIND_LAMEPRUNED 0x00000200 -/* dns_adbaddrinfo_t - * +/*% * The answers to queries come back as a list of these. */ struct dns_adbaddrinfo { - unsigned int magic; /* private */ + unsigned int magic; /*%< private */ - isc_sockaddr_t sockaddr; /* [rw] */ - unsigned int srtt; /* [rw] microseconds */ - unsigned int flags; /* [rw] */ - dns_adbentry_t *entry; /* private */ + isc_sockaddr_t sockaddr; /*%< [rw] */ + unsigned int srtt; /*%< [rw] microseconds */ + unsigned int flags; /*%< [rw] */ + dns_adbentry_t *entry; /*%< private */ ISC_LINK(dns_adbaddrinfo_t) publink; }; -/* +/*!< * The event sent to the caller task is just a plain old isc_event_t. It * contains no data other than a simple status, passed in the "type" field * to indicate that another address resolved, or all partially resolved @@ -198,13 +230,13 @@ struct dns_adbaddrinfo { * * This is simply a standard event, with the "type" set to: * - * DNS_EVENT_ADBMOREADDRESSES -- another address resolved. - * DNS_EVENT_ADBNOMOREADDRESSES -- all pending addresses failed, + *\li #DNS_EVENT_ADBMOREADDRESSES -- another address resolved. + *\li #DNS_EVENT_ADBNOMOREADDRESSES -- all pending addresses failed, * were canceled, or otherwise will * not be usable. - * DNS_EVENT_ADBCANCELED -- The request was canceled by a + *\li #DNS_EVENT_ADBCANCELED -- The request was canceled by a * 3rd party. - * DNS_EVENT_ADBNAMEDELETED -- The name was deleted, so this request + *\li #DNS_EVENT_ADBNAMEDELETED -- The name was deleted, so this request * was canceled. * * In each of these cases, the addresses returned by the initial call @@ -219,81 +251,81 @@ struct dns_adbaddrinfo { isc_result_t dns_adb_create(isc_mem_t *mem, dns_view_t *view, isc_timermgr_t *tmgr, isc_taskmgr_t *taskmgr, dns_adb_t **newadb); -/* +/*%< * Create a new ADB. * * Notes: * - * Generally, applications should not create an ADB directly, but + *\li Generally, applications should not create an ADB directly, but * should instead call dns_view_createresolver(). * * Requires: * - * 'mem' must be a valid memory context. + *\li 'mem' must be a valid memory context. * - * 'view' be a pointer to a valid view. + *\li 'view' be a pointer to a valid view. * - * 'tmgr' be a pointer to a valid timer manager. + *\li 'tmgr' be a pointer to a valid timer manager. * - * 'taskmgr' be a pointer to a valid task manager. + *\li 'taskmgr' be a pointer to a valid task manager. * - * 'newadb' != NULL && '*newadb' == NULL. + *\li 'newadb' != NULL && '*newadb' == NULL. * * Returns: * - * ISC_R_SUCCESS after happiness. - * ISC_R_NOMEMORY after resource allocation failure. + *\li #ISC_R_SUCCESS after happiness. + *\li #ISC_R_NOMEMORY after resource allocation failure. */ void dns_adb_attach(dns_adb_t *adb, dns_adb_t **adbp); -/* +/*% * Attach to an 'adb' to 'adbp'. * * Requires: - * 'adb' to be a valid dns_adb_t, created via dns_adb_create(). - * 'adbp' to be a valid pointer to a *dns_adb_t which is initialized + *\li 'adb' to be a valid dns_adb_t, created via dns_adb_create(). + *\li 'adbp' to be a valid pointer to a *dns_adb_t which is initialized * to NULL. */ void dns_adb_detach(dns_adb_t **adb); -/* +/*% * Delete the ADB. Sets *ADB to NULL. Cancels any outstanding requests. * * Requires: * - * 'adb' be non-NULL and '*adb' be a valid dns_adb_t, created via + *\li 'adb' be non-NULL and '*adb' be a valid dns_adb_t, created via * dns_adb_create(). */ void dns_adb_whenshutdown(dns_adb_t *adb, isc_task_t *task, isc_event_t **eventp); -/* +/*% * Send '*eventp' to 'task' when 'adb' has shutdown. * * Requires: * - * '*adb' is a valid dns_adb_t. + *\li '*adb' is a valid dns_adb_t. * - * eventp != NULL && *eventp is a valid event. + *\li eventp != NULL && *eventp is a valid event. * * Ensures: * - * *eventp == NULL + *\li *eventp == NULL * - * The event's sender field is set to the value of adb when the event + *\li The event's sender field is set to the value of adb when the event * is sent. */ void dns_adb_shutdown(dns_adb_t *adb); -/* +/*%< * Shutdown 'adb'. * * Requires: * - * '*adb' is a valid dns_adb_t. + * \li '*adb' is a valid dns_adb_t. */ isc_result_t @@ -301,7 +333,7 @@ dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action, void *arg, dns_name_t *name, dns_name_t *zone, unsigned int options, isc_stdtime_t now, dns_name_t *target, in_port_t port, dns_adbfind_t **find); -/* +/*%< * Main interface for clients. The adb will look up the name given in * "name" and will build up a list of found addresses, and perhaps start * internal fetches to resolve names that are unknown currently. @@ -311,9 +343,9 @@ dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action, * set to a pointer to the dns_adbfind_t returned by this function. * * If no events will be generated, the *find->result_v4 and/or result_v6 - * members may be examined for address lookup status. The usual ISC_R_SUCCESS, - * ISC_R_FAILURE, and DNS_R_NX{DOMAIN,RRSET} are returned, along with - * ISC_R_NOTFOUND meaning the ADB has not _yet_ found the values. In this + * members may be examined for address lookup status. The usual #ISC_R_SUCCESS, + * #ISC_R_FAILURE, and #DNS_R_NX{DOMAIN,RRSET} are returned, along with + * #ISC_R_NOTFOUND meaning the ADB has not _yet_ found the values. In this * latter case, retrying may produce more addresses. * * If events will be returned, the result_v[46] members are only valid @@ -346,42 +378,42 @@ dns_adb_createfind(dns_adb_t *adb, isc_task_t *task, isc_taskaction_t action, * * Requires: * - * *adb be a valid isc_adb_t object. + *\li *adb be a valid isc_adb_t object. * - * If events are to be sent, *task be a valid task, + *\li If events are to be sent, *task be a valid task, * and isc_taskaction_t != NULL. * - * *name is a valid dns_name_t. + *\li *name is a valid dns_name_t. * - * zone != NULL and *zone be a valid dns_name_t. + *\li zone != NULL and *zone be a valid dns_name_t. * - * target == NULL or target is a valid name with a buffer. + *\li target == NULL or target is a valid name with a buffer. * - * find != NULL && *find == NULL. + *\li find != NULL && *find == NULL. * * Returns: * - * ISC_R_SUCCESS Addresses might have been returned, and events will be + *\li #ISC_R_SUCCESS Addresses might have been returned, and events will be * delivered for unresolved addresses. - * ISC_R_NOMORE Addresses might have been returned, but no events + *\li #ISC_R_NOMORE Addresses might have been returned, but no events * will ever be posted for this context. This is only * returned if task != NULL. - * ISC_R_NOMEMORY insufficient resources - * DNS_R_ALIAS 'name' is an alias for another name. + *\li #ISC_R_NOMEMORY insufficient resources + *\li #DNS_R_ALIAS 'name' is an alias for another name. * * Calls, and returns error codes from: * - * isc_stdtime_get() + *\li isc_stdtime_get() * * Notes: * - * No internal reference to "name" exists after this function + *\li No internal reference to "name" exists after this function * returns. */ void dns_adb_cancelfind(dns_adbfind_t *find); -/* +/*%< * Cancels the find, and sends the event off to the caller. * * It is an error to call dns_adb_cancelfind() on a find where @@ -389,7 +421,7 @@ dns_adb_cancelfind(dns_adbfind_t *find); * * Note: * - * It is possible that the real completion event was posted just + *\li It is possible that the real completion event was posted just * before the dns_adb_cancelfind() call was made. In this case, * dns_adb_cancelfind() will do nothing. The event callback needs * to be prepared to find this situation (i.e. result is valid but @@ -397,101 +429,105 @@ dns_adb_cancelfind(dns_adbfind_t *find); * * Requires: * - * 'find' be a valid dns_adbfind_t pointer. + *\li 'find' be a valid dns_adbfind_t pointer. * - * events would have been posted to the task. This can be checked + *\li events would have been posted to the task. This can be checked * with (find->options & DNS_ADBFIND_WANTEVENT). * * Ensures: * - * The event was posted to the task. + *\li The event was posted to the task. */ void dns_adb_destroyfind(dns_adbfind_t **find); -/* +/*%< * Destroys the find reference. * * Note: * - * This can only be called after the event was delivered for a + *\li This can only be called after the event was delivered for a * find. Additionally, the event MUST have been freed via * isc_event_free() BEFORE this function is called. * * Requires: * - * 'find' != NULL and *find be valid dns_adbfind_t pointer. + *\li 'find' != NULL and *find be valid dns_adbfind_t pointer. * * Ensures: * - * No "address found" events will be posted to the originating task + *\li No "address found" events will be posted to the originating task * after this function returns. */ void dns_adb_dump(dns_adb_t *adb, FILE *f); -/* +/*%< * This function is only used for debugging. It will dump as much of the * state of the running system as possible. * * Requires: * - * adb be valid. + *\li adb be valid. * - * f != NULL, and is a file open for writing. + *\li f != NULL, and is a file open for writing. */ void dns_adb_dumpfind(dns_adbfind_t *find, FILE *f); -/* +/*%< * This function is only used for debugging. Dump the data associated * with a find. * * Requires: * - * find is valid. + *\li find is valid. * - * f != NULL, and is a file open for writing. + * \li f != NULL, and is a file open for writing. */ isc_result_t dns_adb_marklame(dns_adb_t *adb, dns_adbaddrinfo_t *addr, dns_name_t *zone, isc_stdtime_t expire_time); -/* +/*%< * Mark the given address as lame for the zone "zone". expire_time should * be set to the time when the entry should expire. That is, if it is to * expire 10 minutes in the future, it should set it to (now + 10 * 60). * * Requires: * - * adb be valid. + *\li adb be valid. * - * addr be valid. + *\li addr be valid. * - * zone be the zone used in the dns_adb_createfind() call. + *\li zone be the zone used in the dns_adb_createfind() call. * * Returns: * - * ISC_R_SUCCESS -- all is well. - * ISC_R_NOMEMORY -- could not mark address as lame. + *\li #ISC_R_SUCCESS -- all is well. + *\li #ISC_R_NOMEMORY -- could not mark address as lame. */ /* * A reasonable default for RTT adjustments */ -#define DNS_ADB_RTTADJDEFAULT 7 /* default scale */ -#define DNS_ADB_RTTADJREPLACE 0 /* replace with our rtt */ -#define DNS_ADB_RTTADJAGE 10 /* age this rtt */ +#define DNS_ADB_RTTADJDEFAULT 7 /*%< default scale */ +#define DNS_ADB_RTTADJREPLACE 0 /*%< replace with our rtt */ +#define DNS_ADB_RTTADJAGE 10 /*%< age this rtt */ void dns_adb_adjustsrtt(dns_adb_t *adb, dns_adbaddrinfo_t *addr, unsigned int rtt, unsigned int factor); -/* - * Mix the round trip time into the existing smoothed rtt. The formula used +/*%< + * Mix the round trip time into the existing smoothed rtt. + + * The formula used * (where srtt is the existing rtt value, and rtt and factor are arguments to * this function): * + *\code * new_srtt = (old_srtt / 10 * factor) + (rtt / 10 * (10 - factor)); + *\endcode * * XXXRTH Do we want to publish the formula? What if we want to change how * this works later on? Recommend/require that the units are @@ -499,77 +535,79 @@ dns_adb_adjustsrtt(dns_adb_t *adb, dns_adbaddrinfo_t *addr, * * Requires: * - * adb be valid. + *\li adb be valid. * - * addr be valid. + *\li addr be valid. * - * 0 <= factor <= 10 + *\li 0 <= factor <= 10 * * Note: * - * The srtt in addr will be updated to reflect the new global + *\li The srtt in addr will be updated to reflect the new global * srtt value. This may include changes made by others. */ void dns_adb_changeflags(dns_adb_t *adb, dns_adbaddrinfo_t *addr, unsigned int bits, unsigned int mask); -/* +/*% + * Change Flags. + * * Set the flags as given by: * - * newflags = (oldflags & ~mask) | (bits & mask); + *\li newflags = (oldflags & ~mask) | (bits & mask); * * Requires: * - * adb be valid. + *\li adb be valid. * - * addr be valid. + *\li addr be valid. */ isc_result_t dns_adb_findaddrinfo(dns_adb_t *adb, isc_sockaddr_t *sa, dns_adbaddrinfo_t **addrp, isc_stdtime_t now); -/* +/*%< * Return a dns_adbaddrinfo_t that is associated with address 'sa'. * * Requires: * - * adb is valid. + *\li adb is valid. * - * sa is valid. + *\li sa is valid. * - * addrp != NULL && *addrp == NULL + *\li addrp != NULL && *addrp == NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_SHUTTINGDOWN + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_SHUTTINGDOWN */ void dns_adb_freeaddrinfo(dns_adb_t *adb, dns_adbaddrinfo_t **addrp); -/* +/*%< * Free a dns_adbaddrinfo_t allocated by dns_adb_findaddrinfo(). * * Requires: * - * adb is valid. + *\li adb is valid. * - * *addrp is a valid dns_adbaddrinfo_t *. + *\li *addrp is a valid dns_adbaddrinfo_t *. */ void dns_adb_flush(dns_adb_t *adb); -/* +/*%< * Flushes all cached data from the adb. * * Requires: - * adb is valid. + *\li adb is valid. */ void dns_adb_setadbsize(dns_adb_t *adb, isc_uint32_t size); -/* +/*%< * Set a target memory size. If memory usage exceeds the target * size entries will be removed before they would have expired on * a random basis. @@ -577,17 +615,17 @@ dns_adb_setadbsize(dns_adb_t *adb, isc_uint32_t size); * If 'size' is 0 then memory usage is unlimited. * * Requires: - * 'adb' is valid. + *\li 'adb' is valid. */ void dns_adb_flushname(dns_adb_t *adb, dns_name_t *name); -/* +/*%< * Flush 'name' from the adb cache. * * Requires: - * 'adb' is valid. - * 'name' is valid. + *\li 'adb' is valid. + *\li 'name' is valid. */ diff --git a/lib/dns/include/dns/bit.h b/lib/dns/include/dns/bit.h index 9b0ad04cc2..d0551d472a 100644 --- a/lib/dns/include/dns/bit.h +++ b/lib/dns/include/dns/bit.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: bit.h,v 1.8 2004/03/05 05:09:40 marka Exp $ */ +/* $Id: bit.h,v 1.9 2005/04/27 04:56:54 sra Exp $ */ #ifndef DNS_BIT_H #define DNS_BIT_H 1 +/*! \file */ + #include #include diff --git a/lib/dns/include/dns/byaddr.h b/lib/dns/include/dns/byaddr.h index ea2986c642..a219bc57e3 100644 --- a/lib/dns/include/dns/byaddr.h +++ b/lib/dns/include/dns/byaddr.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: byaddr.h,v 1.16 2004/03/05 05:09:40 marka Exp $ */ +/* $Id: byaddr.h,v 1.17 2005/04/27 04:56:54 sra Exp $ */ #ifndef DNS_BYADDR_H #define DNS_BYADDR_H 1 @@ -24,28 +24,27 @@ ***** Module Info *****/ -/* - * DNS ByAddr - * +/*! \file + * \brief * The byaddr module provides reverse lookup services for IPv4 and IPv6 * addresses. * * MP: - * The module ensures appropriate synchronization of data structures it + *\li The module ensures appropriate synchronization of data structures it * creates and manipulates. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * RFCs: 1034, 1035, 2181, - * Drafts: + *\li RFCs: 1034, 1035, 2181, TBS + *\li Drafts: TBS */ #include @@ -55,7 +54,7 @@ ISC_LANG_BEGINDECLS -/* +/*% * A 'dns_byaddrevent_t' is returned when a byaddr completes. * The sender field will be set to the byaddr that completed. If 'result' * is ISC_R_SUCCESS, then 'names' will contain a list of names associated @@ -72,76 +71,79 @@ typedef struct dns_byaddrevent { * This option is deprecated since we now only consider nibbles. #define DNS_BYADDROPT_IPV6NIBBLE 0x0001 */ +/*% Note DNS_BYADDROPT_IPV6NIBBLE is now deprecated. */ #define DNS_BYADDROPT_IPV6INT 0x0002 isc_result_t dns_byaddr_create(isc_mem_t *mctx, isc_netaddr_t *address, dns_view_t *view, unsigned int options, isc_task_t *task, isc_taskaction_t action, void *arg, dns_byaddr_t **byaddrp); -/* +/*%< * Find the domain name of 'address'. * * Notes: * - * There is a reverse lookup format for IPv6 addresses, 'nibble' + *\li There is a reverse lookup format for IPv6 addresses, 'nibble' * - * The 'nibble' format for that address is + *\li The 'nibble' format for that address is * + * \code * 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.e.f.ip6.arpa. + * \endcode * - * DNS_BYADDROPT_IPV6INT can be used to get nibble lookups under ip6.int. + *\li #DNS_BYADDROPT_IPV6INT can be used to get nibble lookups under ip6.int. * * Requires: * - * 'mctx' is a valid mctx. + *\li 'mctx' is a valid mctx. * - * 'address' is a valid IPv4 or IPv6 address. + *\li 'address' is a valid IPv4 or IPv6 address. * - * 'view' is a valid view which has a resolver. + *\li 'view' is a valid view which has a resolver. * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * byaddrp != NULL && *byaddrp == NULL + *\li byaddrp != NULL && *byaddrp == NULL * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY * - * Any resolver-related error (e.g. ISC_R_SHUTTINGDOWN) may also be + *\li Any resolver-related error (e.g. #ISC_R_SHUTTINGDOWN) may also be * returned. */ void dns_byaddr_cancel(dns_byaddr_t *byaddr); -/* +/*%< * Cancel 'byaddr'. * * Notes: * - * If 'byaddr' has not completed, post its BYADDRDONE event with a - * result code of ISC_R_CANCELED. + *\li If 'byaddr' has not completed, post its #BYADDRDONE event with a + * result code of #ISC_R_CANCELED. * * Requires: * - * 'byaddr' is a valid byaddr. + *\li 'byaddr' is a valid byaddr. */ void dns_byaddr_destroy(dns_byaddr_t **byaddrp); -/* +/*%< * Destroy 'byaddr'. * * Requires: * - * '*byaddrp' is a valid byaddr. + *\li '*byaddrp' is a valid byaddr. * - * The caller has received the BYADDRDONE event (either because the + *\li The caller has received the BYADDRDONE event (either because the * byaddr completed or because dns_byaddr_cancel() was called). * * Ensures: * - * *byaddrp == NULL. + *\li *byaddrp == NULL. */ isc_result_t @@ -151,7 +153,7 @@ dns_byaddr_createptrname(isc_netaddr_t *address, isc_boolean_t nibble, isc_result_t dns_byaddr_createptrname2(isc_netaddr_t *address, unsigned int options, dns_name_t *name); -/* +/*%< * Creates a name that would be used in a PTR query for this address. The * nibble flag indicates that the 'nibble' format is to be used if an IPv6 * address is provided, instead of the 'bitstring' format. Since we dropped @@ -160,8 +162,8 @@ dns_byaddr_createptrname2(isc_netaddr_t *address, unsigned int options, * * Requires: * - * 'address' is a valid address. - * 'name' is a valid name with a dedicated buffer. + * \li 'address' is a valid address. + * \li 'name' is a valid name with a dedicated buffer. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/cache.h b/lib/dns/include/dns/cache.h index 34d041b994..782d427f4f 100644 --- a/lib/dns/include/dns/cache.h +++ b/lib/dns/include/dns/cache.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: cache.h,v 1.19 2004/03/05 05:09:40 marka Exp $ */ +/* $Id: cache.h,v 1.20 2005/04/27 04:56:54 sra Exp $ */ #ifndef DNS_CACHE_H #define DNS_CACHE_H 1 @@ -24,18 +24,17 @@ ***** Module Info *****/ -/* - * cache - * +/*! \file + * \brief * Defines dns_cache_t, the cache object. * * Notes: - * A cache object contains DNS data of a single class. + *\li A cache object contains DNS data of a single class. * Multiple classes will be handled by creating multiple * views, each with a different class and its own cache. * * MP: - * See notes at the individual functions. + *\li See notes at the individual functions. * * Reliability: * @@ -66,71 +65,70 @@ dns_cache_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr, dns_rdataclass_t rdclass, const char *db_type, unsigned int db_argc, char **db_argv, dns_cache_t **cachep); -/* +/*%< * Create a new DNS cache. * * Requires: * - * 'mctx' is a valid memory context + *\li 'mctx' is a valid memory context * - * 'taskmgr' is a valid task manager and 'timermgr' is a valid timer + *\li 'taskmgr' is a valid task manager and 'timermgr' is a valid timer * manager, or both are NULL. If NULL, no periodic cleaning of the * cache will take place. * - * 'cachep' is a valid pointer, and *cachep == NULL + *\li 'cachep' is a valid pointer, and *cachep == NULL * * Ensures: * - * '*cachep' is attached to the newly created cache + *\li '*cachep' is attached to the newly created cache * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ void dns_cache_attach(dns_cache_t *cache, dns_cache_t **targetp); -/* +/*%< * Attach *targetp to cache. * * Requires: * - * 'cache' is a valid cache. + *\li 'cache' is a valid cache. * - * 'targetp' points to a NULL dns_cache_t *. + *\li 'targetp' points to a NULL dns_cache_t *. * * Ensures: * - * *targetp is attached to cache. + *\li *targetp is attached to cache. */ void dns_cache_detach(dns_cache_t **cachep); -/* +/*%< * Detach *cachep from its cache. * * Requires: * - * 'cachep' points to a valid cache. + *\li 'cachep' points to a valid cache. * * Ensures: * - * *cachep is NULL. + *\li *cachep is NULL. * - * If '*cachep' is the last reference to the cache, - * - * All resources used by the cache will be freed + *\li If '*cachep' is the last reference to the cache, + * all resources used by the cache will be freed */ void dns_cache_attachdb(dns_cache_t *cache, dns_db_t **dbp); -/* +/*%< * Attach *dbp to the cache's database. * * Notes: * - * This may be used to get a reference to the database for + *\li This may be used to get a reference to the database for * the purpose of cache lookups (XXX currently it is also * the way to add data to the cache, but having a * separate dns_cache_add() interface instead would allow @@ -140,39 +138,39 @@ dns_cache_attachdb(dns_cache_t *cache, dns_db_t **dbp); * * Requires: * - * 'cache' is a valid cache. + *\li 'cache' is a valid cache. * - * 'dbp' points to a NULL dns_db *. + *\li 'dbp' points to a NULL dns_db *. * * Ensures: * - * *dbp is attached to the database. + *\li *dbp is attached to the database. */ isc_result_t dns_cache_setfilename(dns_cache_t *cahce, char *filename); -/* +/*%< * If 'filename' is non-NULL, make the cache persistent. * The cache's data will be stored in the given file. * If 'filename' is NULL, make the cache non-persistent. * Files that are no longer used are not unlinked automatically. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * Various file-related failures + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li Various file-related failures */ isc_result_t dns_cache_load(dns_cache_t *cache); -/* +/*%< * If the cache has a file name, load the cache contents from the file. * Previous cache contents are not discarded. * If no file name has been set, do nothing and return success. * * MT: - * Multiple simultaneous attempts to load or dump the cache + *\li Multiple simultaneous attempts to load or dump the cache * will be serialized with respect to one another, but * the cache may be read and updated while the dump is * in progress. Updates performed during loading @@ -181,19 +179,19 @@ dns_cache_load(dns_cache_t *cache); * * Returns: * - * ISC_R_SUCCESS - * Various failures depending on the database implementation type + *\li #ISC_R_SUCCESS + * \li Various failures depending on the database implementation type */ isc_result_t dns_cache_dump(dns_cache_t *cache); -/* +/*%< * If the cache has a file name, write the cache contents to disk, * overwriting any preexisting file. If no file name has been set, * do nothing and return success. * * MT: - * Multiple simultaneous attempts to load or dump the cache + *\li Multiple simultaneous attempts to load or dump the cache * will be serialized with respect to one another, but * the cache may be read and updated while the dump is * in progress. Updates performed during the dump may @@ -201,13 +199,13 @@ dns_cache_dump(dns_cache_t *cache); * * Returns: * - * ISC_R_SUCCESS - * Various failures depending on the database implementation type + *\li #ISC_R_SUCCESS + * \li Various failures depending on the database implementation type */ isc_result_t dns_cache_clean(dns_cache_t *cache, isc_stdtime_t now); -/* +/*%< * Force immediate cleaning of the cache, freeing all rdatasets * whose TTL has expired as of 'now' and that have no pending * references. @@ -215,24 +213,24 @@ dns_cache_clean(dns_cache_t *cache, isc_stdtime_t now); void dns_cache_setcleaninginterval(dns_cache_t *cache, unsigned int interval); -/* +/*%< * Set the periodic cache cleaning interval to 'interval' seconds. */ void dns_cache_setcachesize(dns_cache_t *cache, isc_uint32_t size); -/* +/*%< * Set the maximum cache size. 0 means unlimited. */ isc_result_t dns_cache_flush(dns_cache_t *cache); -/* +/*%< * Flushes all data from the cache. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ isc_result_t @@ -241,13 +239,13 @@ dns_cache_flushname(dns_cache_t *cache, dns_name_t *name); * Flushes a given name from the cache. * * Requires: - * 'cache' to be valid. - * 'name' to be valid. + *\li 'cache' to be valid. + *\li 'name' to be valid. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * other error returns. + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li other error returns. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/callbacks.h b/lib/dns/include/dns/callbacks.h index 481c8fff75..8db75abc70 100644 --- a/lib/dns/include/dns/callbacks.h +++ b/lib/dns/include/dns/callbacks.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: callbacks.h,v 1.18 2004/03/05 05:09:41 marka Exp $ */ +/* $Id: callbacks.h,v 1.19 2005/04/27 04:56:54 sra Exp $ */ #ifndef DNS_CALLBACKS_H #define DNS_CALLBACKS_H 1 +/*! \file */ + /*** *** Imports ***/ @@ -35,19 +37,19 @@ ISC_LANG_BEGINDECLS ***/ struct dns_rdatacallbacks { - /* + /*% * dns_load_master calls this when it has rdatasets to commit. */ dns_addrdatasetfunc_t add; - /* + /*% * dns_load_master / dns_rdata_fromtext call this to issue a error. */ void (*error)(struct dns_rdatacallbacks *, const char *, ...); - /* + /*% * dns_load_master / dns_rdata_fromtext call this to issue a warning. */ void (*warn)(struct dns_rdatacallbacks *, const char *, ...); - /* + /*% * Private data handles for use by the above callback functions. */ void *add_private; @@ -61,20 +63,22 @@ struct dns_rdatacallbacks { void dns_rdatacallbacks_init(dns_rdatacallbacks_t *callbacks); -/* +/*%< * Initialize 'callbacks'. - * 'error' and 'warn' are set to default callbacks that print the + * + * + * \li 'error' and 'warn' are set to default callbacks that print the * error message through the DNS library log context. * - * All other elements are initialized to NULL. + *\li All other elements are initialized to NULL. * * Requires: - * 'callbacks' is a valid dns_rdatacallbacks_t, + * \li 'callbacks' is a valid dns_rdatacallbacks_t, */ void dns_rdatacallbacks_init_stdio(dns_rdatacallbacks_t *callbacks); -/* +/*%< * Like dns_rdatacallbacks_init, but logs to stdio. */ diff --git a/lib/dns/include/dns/cert.h b/lib/dns/include/dns/cert.h index 977176f2ad..30c90d7fe9 100644 --- a/lib/dns/include/dns/cert.h +++ b/lib/dns/include/dns/cert.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: cert.h,v 1.13 2004/03/05 05:09:41 marka Exp $ */ +/* $Id: cert.h,v 1.14 2005/04/27 04:56:54 sra Exp $ */ #ifndef DNS_CERT_H #define DNS_CERT_H 1 +/*! \file */ + #include #include @@ -28,38 +30,38 @@ ISC_LANG_BEGINDECLS isc_result_t dns_cert_fromtext(dns_cert_t *certp, isc_textregion_t *source); -/* +/*%< * Convert the text 'source' refers to into a certificate type. * The text may contain either a mnemonic type name or a decimal type number. * * Requires: - * 'certp' is a valid pointer. + *\li 'certp' is a valid pointer. * - * 'source' is a valid text region. + *\li 'source' is a valid text region. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_RANGE numeric type is out of range - * DNS_R_UNKNOWN mnemonic type is unknown + *\li #ISC_R_SUCCESS on success + *\li #ISC_R_RANGE numeric type is out of range + *\li #DNS_R_UNKNOWN mnemonic type is unknown */ isc_result_t dns_cert_totext(dns_cert_t cert, isc_buffer_t *target); -/* +/*%< * Put a textual representation of certificate type 'cert' into 'target'. * * Requires: - * 'cert' is a valid cert. + *\li 'cert' is a valid cert. * - * 'target' is a valid text buffer. + *\li 'target' is a valid text buffer. * * Ensures: - * If the result is success: + *\li If the result is success: * The used space in 'target' is updated. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_NOSPACE target buffer is too small + *\li #ISC_R_SUCCESS on success + *\li #ISC_R_NOSPACE target buffer is too small */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/compress.h b/lib/dns/include/dns/compress.h index c43e9dd95a..8f9ecaebe6 100644 --- a/lib/dns/include/dns/compress.h +++ b/lib/dns/include/dns/compress.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: compress.h,v 1.34 2005/03/06 15:30:37 marka Exp $ */ +/* $Id: compress.h,v 1.35 2005/04/27 04:56:54 sra Exp $ */ #ifndef DNS_COMPRESS_H #define DNS_COMPRESS_H 1 @@ -27,12 +27,12 @@ ISC_LANG_BEGINDECLS -#define DNS_COMPRESS_NONE 0x00 /* no compression */ -#define DNS_COMPRESS_GLOBAL14 0x01 /* "normal" compression. */ -#define DNS_COMPRESS_ALL 0x01 /* all compression. */ -#define DNS_COMPRESS_CASESENSITIVE 0x02 /* case sensitive compression. */ +#define DNS_COMPRESS_NONE 0x00 /*%< no compression */ +#define DNS_COMPRESS_GLOBAL14 0x01 /*%< "normal" compression. */ +#define DNS_COMPRESS_ALL 0x01 /*%< all compression. */ +#define DNS_COMPRESS_CASESENSITIVE 0x02 /*%< case sensitive compression. */ -/* +/*! \file * Direct manipulation of the structures is strongly discouraged. */ @@ -50,77 +50,77 @@ struct dns_compressnode { }; struct dns_compress { - unsigned int magic; /* Magic number. */ - unsigned int allowed; /* Allowed methods. */ - int edns; /* Edns version or -1. */ - /* Global compression table. */ + unsigned int magic; /*%< Magic number. */ + unsigned int allowed; /*%< Allowed methods. */ + int edns; /*%< Edns version or -1. */ + /*% Global compression table. */ dns_compressnode_t *table[DNS_COMPRESS_TABLESIZE]; - /* Preallocated nodes for the table. */ + /*% Preallocated nodes for the table. */ dns_compressnode_t initialnodes[DNS_COMPRESS_INITIALNODES]; - isc_uint16_t count; /* Number of nodes. */ - isc_mem_t *mctx; /* Memory context. */ + isc_uint16_t count; /*%< Number of nodes. */ + isc_mem_t *mctx; /*%< Memory context. */ }; typedef enum { - DNS_DECOMPRESS_ANY, /* Any compression */ - DNS_DECOMPRESS_STRICT, /* Allowed compression */ - DNS_DECOMPRESS_NONE /* No compression */ + DNS_DECOMPRESS_ANY, /*%< Any compression */ + DNS_DECOMPRESS_STRICT, /*%< Allowed compression */ + DNS_DECOMPRESS_NONE /*%< No compression */ } dns_decompresstype_t; struct dns_decompress { - unsigned int magic; /* Magic number. */ - unsigned int allowed; /* Allowed methods. */ - int edns; /* Edns version or -1. */ - dns_decompresstype_t type; /* Strict checking */ + unsigned int magic; /*%< Magic number. */ + unsigned int allowed; /*%< Allowed methods. */ + int edns; /*%< Edns version or -1. */ + dns_decompresstype_t type; /*%< Strict checking */ }; isc_result_t dns_compress_init(dns_compress_t *cctx, int edns, isc_mem_t *mctx); -/* +/*%< * Inialise the compression context structure pointed to by 'cctx'. * * Requires: - * 'cctx' is a valid dns_compress_t structure. - * 'mctx' is an initialized memory context. + * \li 'cctx' is a valid dns_compress_t structure. + * \li 'mctx' is an initialized memory context. * Ensures: - * cctx->global is initialized. + * \li cctx->global is initialized. * * Returns: - * ISC_R_SUCCESS - * failures from dns_rbt_create() + * \li #ISC_R_SUCCESS + * \li failures from dns_rbt_create() */ void dns_compress_invalidate(dns_compress_t *cctx); -/* +/*%< * Invalidate the compression structure pointed to by cctx. * * Requires: - * 'cctx' to be initialized. + *\li 'cctx' to be initialized. */ void dns_compress_setmethods(dns_compress_t *cctx, unsigned int allowed); -/* +/*%< * Sets allowed compression methods. * * Requires: - * 'cctx' to be initialized. + *\li 'cctx' to be initialized. */ unsigned int dns_compress_getmethods(dns_compress_t *cctx); -/* +/*%< * Gets allowed compression methods. * * Requires: - * 'cctx' to be initialized. + *\li 'cctx' to be initialized. * * Returns: - * allowed compression bitmap. + *\li allowed compression bitmap. */ void @@ -146,122 +146,122 @@ dns_compress_getsensitive(dns_compress_t *cctx); int dns_compress_getedns(dns_compress_t *cctx); -/* +/*%< * Gets edns value. * * Requires: - * 'cctx' to be initialized. + *\li 'cctx' to be initialized. * * Returns: - * -1 .. 255 + *\li -1 .. 255 */ isc_boolean_t dns_compress_findglobal(dns_compress_t *cctx, dns_name_t *name, dns_name_t *prefix, isc_uint16_t *offset); -/* +/*%< * Finds longest possible match of 'name' in the global compression table. * * Requires: - * 'cctx' to be initialized. - * 'name' to be a absolute name. - * 'prefix' to be initialized. - * 'offset' to point to an isc_uint16_t. + *\li 'cctx' to be initialized. + *\li 'name' to be a absolute name. + *\li 'prefix' to be initialized. + *\li 'offset' to point to an isc_uint16_t. * * Ensures: - * 'prefix' and 'offset' are valid if ISC_TRUE is returned. + *\li 'prefix' and 'offset' are valid if ISC_TRUE is returned. * * Returns: - * ISC_TRUE / ISC_FALSE + *\li #ISC_TRUE / #ISC_FALSE */ void dns_compress_add(dns_compress_t *cctx, dns_name_t *name, dns_name_t *prefix, isc_uint16_t offset); -/* +/*%< * Add compression pointers for 'name' to the compression table, * not replacing existing pointers. * * Requires: - * 'cctx' initialized + *\li 'cctx' initialized * - * 'name' must be initialized and absolute, and must remain + *\li 'name' must be initialized and absolute, and must remain * valid until the message compression is complete. * - * 'prefix' must be a prefix returned by + *\li 'prefix' must be a prefix returned by * dns_compress_findglobal(), or the same as 'name'. */ void dns_compress_rollback(dns_compress_t *cctx, isc_uint16_t offset); -/* +/*%< * Remove any compression pointers from global table >= offset. * * Requires: - * 'cctx' is initialized. + *\li 'cctx' is initialized. */ void dns_decompress_init(dns_decompress_t *dctx, int edns, dns_decompresstype_t type); -/* +/*%< * Initializes 'dctx'. * Records 'edns' and 'type' into the structure. * * Requires: - * 'dctx' to be a valid pointer. + *\li 'dctx' to be a valid pointer. */ void dns_decompress_invalidate(dns_decompress_t *dctx); -/* +/*%< * Invalidates 'dctx'. * * Requires: - * 'dctx' to be initialized + *\li 'dctx' to be initialized */ void dns_decompress_setmethods(dns_decompress_t *dctx, unsigned int allowed); -/* +/*%< * Sets 'dctx->allowed' to 'allowed'. * * Requires: - * 'dctx' to be initialized + *\li 'dctx' to be initialized */ unsigned int dns_decompress_getmethods(dns_decompress_t *dctx); -/* +/*%< * Returns 'dctx->allowed' * * Requires: - * 'dctx' to be initialized + *\li 'dctx' to be initialized */ int dns_decompress_edns(dns_decompress_t *dctx); -/* +/*%< * Returns 'dctx->edns' * * Requires: - * 'dctx' to be initialized + *\li 'dctx' to be initialized */ dns_decompresstype_t dns_decompress_type(dns_decompress_t *dctx); -/* +/*%< * Returns 'dctx->type' * * Requires: - * 'dctx' to be initialized + *\li 'dctx' to be initialized */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/db.h b/lib/dns/include/dns/db.h index c94dc4f930..2907ca4aef 100644 --- a/lib/dns/include/dns/db.h +++ b/lib/dns/include/dns/db.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: db.h,v 1.78 2004/12/21 10:45:18 jinmei Exp $ */ +/* $Id: db.h,v 1.79 2005/04/27 04:56:54 sra Exp $ */ #ifndef DNS_DB_H #define DNS_DB_H 1 @@ -24,31 +24,30 @@ ***** Module Info *****/ -/* - * DNS DB - * +/*! \file + * \brief * The DNS DB interface allows named rdatasets to be stored and retrieved. * * The dns_db_t type is like a "virtual class". To actually use * DBs, an implementation of the class is required. * - * XXX XXX + * XXX more XXX * * MP: - * The module ensures appropriate synchronization of data structures it + *\li The module ensures appropriate synchronization of data structures it * creates and manipulates. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * None. + *\li None. */ /***** @@ -160,10 +159,10 @@ typedef isc_result_t #define DNS_DB_MAGIC ISC_MAGIC('D','N','S','D') #define DNS_DB_VALID(db) ISC_MAGIC_VALID(db, DNS_DB_MAGIC) -/* +/*% * This structure is actually just the common prefix of a DNS db * implementation's version of a dns_db_t. - * + * \brief * Direct use of this structure by clients is forbidden. DB implementations * may change the structure. 'magic' must be DNS_DB_MAGIC for any of the * dns_db_ routines to work. DB implementations must maintain all DB @@ -183,7 +182,8 @@ struct dns_db { #define DNS_DBATTR_CACHE 0x01 #define DNS_DBATTR_STUB 0x02 -/* +/*@{*/ +/*% * Options that can be specified for dns_db_find(). */ #define DNS_DBFIND_GLUEOK 0x01 @@ -193,16 +193,19 @@ struct dns_db { #define DNS_DBFIND_NOEXACT 0x10 #define DNS_DBFIND_FORCENSEC 0x20 #define DNS_DBFIND_COVERINGNSEC 0x40 +/*@}*/ -/* +/*@{*/ +/*% * Options that can be specified for dns_db_addrdataset(). */ #define DNS_DBADD_MERGE 0x01 #define DNS_DBADD_FORCE 0x02 #define DNS_DBADD_EXACT 0x04 #define DNS_DBADD_EXACTTTL 0x08 +/*@}*/ -/* +/*% * Options that can be specified for dns_db_subtractrdataset(). */ #define DNS_DBSUB_EXACT 0x01 @@ -219,78 +222,77 @@ isc_result_t dns_db_create(isc_mem_t *mctx, const char *db_type, dns_name_t *origin, dns_dbtype_t type, dns_rdataclass_t rdclass, unsigned int argc, char *argv[], dns_db_t **dbp); -/* +/*%< * Create a new database using implementation 'db_type'. * * Notes: - * All names in the database must be subdomains of 'origin' and in class + *\li All names in the database must be subdomains of 'origin' and in class * 'rdclass'. The database makes its own copy of the origin, so the * caller may do whatever they like with 'origin' and its storage once the * call returns. * - * DB implementation-specific parameters are passed using argc and argv. + *\li DB implementation-specific parameters are passed using argc and argv. * * Requires: * - * dbp != NULL and *dbp == NULL + *\li dbp != NULL and *dbp == NULL * - * 'origin' is a valid absolute domain name. + *\li 'origin' is a valid absolute domain name. * - * mctx is a valid memory context + *\li mctx is a valid memory context * * Ensures: * - * A copy of 'origin' has been made for the databases use, and the + *\li A copy of 'origin' has been made for the databases use, and the * caller is free to do whatever they want with the name and storage * associated with 'origin'. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_NOTFOUND db_type not found + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_NOTFOUND db_type not found * - * Many other errors are possible, depending on what db_type was + *\li Many other errors are possible, depending on what db_type was * specified. */ void dns_db_attach(dns_db_t *source, dns_db_t **targetp); -/* +/*%< * Attach *targetp to source. * * Requires: * - * 'source' is a valid database. + *\li 'source' is a valid database. * - * 'targetp' points to a NULL dns_db_t *. + *\li 'targetp' points to a NULL dns_db_t *. * * Ensures: * - * *targetp is attached to source. + *\li *targetp is attached to source. */ void dns_db_detach(dns_db_t **dbp); -/* +/*%< * Detach *dbp from its database. * * Requires: * - * 'dbp' points to a valid database. + *\li 'dbp' points to a valid database. * * Ensures: * - * *dbp is NULL. + *\li *dbp is NULL. * - * If '*dbp' is the last reference to the database, - * - * All resources used by the database will be freed + *\li If '*dbp' is the last reference to the database, + * all resources used by the database will be freed */ isc_result_t dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp); -/* +/*%< * Causes 'eventp' to be sent to be sent to 'task' when the database is * destroyed. * @@ -301,189 +303,191 @@ dns_db_ondestroy(dns_db_t *db, isc_task_t *task, isc_event_t **eventp); isc_boolean_t dns_db_iscache(dns_db_t *db); -/* +/*%< * Does 'db' have cache semantics? * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * * Returns: - * ISC_TRUE 'db' has cache semantics - * ISC_FALSE otherwise + *\li #ISC_TRUE 'db' has cache semantics + *\li #ISC_FALSE otherwise */ isc_boolean_t dns_db_iszone(dns_db_t *db); -/* +/*%< * Does 'db' have zone semantics? * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * * Returns: - * ISC_TRUE 'db' has zone semantics - * ISC_FALSE otherwise + *\li #ISC_TRUE 'db' has zone semantics + *\li #ISC_FALSE otherwise */ isc_boolean_t dns_db_isstub(dns_db_t *db); -/* +/*%< * Does 'db' have stub semantics? * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * * Returns: - * ISC_TRUE 'db' has zone semantics - * ISC_FALSE otherwise + *\li #ISC_TRUE 'db' has zone semantics + *\li #ISC_FALSE otherwise */ isc_boolean_t dns_db_issecure(dns_db_t *db); -/* +/*%< * Is 'db' secure? * * Requires: * - * 'db' is a valid database with zone semantics. + *\li 'db' is a valid database with zone semantics. * * Returns: - * ISC_TRUE 'db' is secure. - * ISC_FALSE 'db' is not secure. + *\li #ISC_TRUE 'db' is secure. + *\li #ISC_FALSE 'db' is not secure. */ dns_name_t * dns_db_origin(dns_db_t *db); -/* +/*%< * The origin of the database. * * Note: caller must not try to change this name. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * * Returns: * - * The origin of the database. + *\li The origin of the database. */ dns_rdataclass_t dns_db_class(dns_db_t *db); -/* +/*%< * The class of the database. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * * Returns: * - * The class of the database. + *\li The class of the database. */ isc_result_t dns_db_beginload(dns_db_t *db, dns_addrdatasetfunc_t *addp, dns_dbload_t **dbloadp); -/* +/*%< * Begin loading 'db'. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * This is the first attempt to load 'db'. + *\li This is the first attempt to load 'db'. * - * addp != NULL && *addp == NULL + *\li addp != NULL && *addp == NULL * - * dbloadp != NULL && *dbloadp == NULL + *\li dbloadp != NULL && *dbloadp == NULL * * Ensures: * - * On success, *addp will be a valid dns_addrdatasetfunc_t suitable + *\li On success, *addp will be a valid dns_addrdatasetfunc_t suitable * for loading 'db'. *dbloadp will be a valid DB load context which * should be used as 'arg' when *addp is called. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used, syntax errors in the master file, etc. */ isc_result_t dns_db_endload(dns_db_t *db, dns_dbload_t **dbloadp); -/* +/*%< * Finish loading 'db'. * * Requires: * - * 'db' is a valid database that is being loaded. + *\li 'db' is a valid database that is being loaded. * - * dbloadp != NULL and *dbloadp is a valid database load context. + *\li dbloadp != NULL and *dbloadp is a valid database load context. * * Ensures: * - * *dbloadp == NULL + *\li *dbloadp == NULL * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used, syntax errors in the master file, etc. */ isc_result_t dns_db_load(dns_db_t *db, const char *filename); -/* +/*%< * Load master file 'filename' into 'db'. * * Notes: - * This routine is equivalent to calling + *\li This routine is equivalent to calling * + *\code * dns_db_beginload(); * dns_master_loadfile(); * dns_db_endload(); + *\endcode * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * This is the first attempt to load 'db'. + *\li This is the first attempt to load 'db'. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used, syntax errors in the master file, etc. */ isc_result_t dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename); -/* +/*%< * Dump version 'version' of 'db' to master file 'filename'. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'version' is a valid version. + *\li 'version' is a valid version. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used, OS file errors, etc. */ @@ -493,68 +497,68 @@ dns_db_dump(dns_db_t *db, dns_dbversion_t *version, const char *filename); void dns_db_currentversion(dns_db_t *db, dns_dbversion_t **versionp); -/* +/*%< * Open the current version for reading. * * Requires: * - * 'db' is a valid database with zone semantics. + *\li 'db' is a valid database with zone semantics. * - * versionp != NULL && *verisonp == NULL + *\li versionp != NULL && *verisonp == NULL * * Ensures: * - * On success, '*versionp' is attached to the current version. + *\li On success, '*versionp' is attached to the current version. * */ isc_result_t dns_db_newversion(dns_db_t *db, dns_dbversion_t **versionp); -/* +/*%< * Open a new version for reading and writing. * * Requires: * - * 'db' is a valid database with zone semantics. + *\li 'db' is a valid database with zone semantics. * - * versionp != NULL && *verisonp == NULL + *\li versionp != NULL && *verisonp == NULL * * Ensures: * - * On success, '*versionp' is attached to the current version. + *\li On success, '*versionp' is attached to the current version. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used. */ void dns_db_attachversion(dns_db_t *db, dns_dbversion_t *source, dns_dbversion_t **targetp); -/* +/*%< * Attach '*targetp' to 'source'. * * Requires: * - * 'db' is a valid database with zone semantics. + *\li 'db' is a valid database with zone semantics. * - * source is a valid open version + *\li source is a valid open version * - * targetp != NULL && *targetp == NULL + *\li targetp != NULL && *targetp == NULL * * Ensures: * - * '*targetp' is attached to source. + *\li '*targetp' is attached to source. */ void dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp, isc_boolean_t commit); -/* +/*%< * Close version '*versionp'. * * Note: if '*versionp' is a read-write version and 'commit' is ISC_TRUE, @@ -564,62 +568,62 @@ dns_db_closeversion(dns_db_t *db, dns_dbversion_t **versionp, * * Requires: * - * 'db' is a valid database with zone semantics. + *\li 'db' is a valid database with zone semantics. * - * '*versionp' refers to a valid version. + *\li '*versionp' refers to a valid version. * - * If committing a writable version, then there must be no other + *\li If committing a writable version, then there must be no other * outstanding references to the version (e.g. an active rdataset * iterator). * * Ensures: * - * *versionp == NULL + *\li *versionp == NULL * - * If *versionp is a read-write version, and commit is ISC_TRUE, then + *\li If *versionp is a read-write version, and commit is ISC_TRUE, then * the version will become the current version. If !commit, then all * changes made in the version will be undone, and the version will * not become the current version. */ -/*** +/*%<** *** Node Methods ***/ isc_result_t dns_db_findnode(dns_db_t *db, dns_name_t *name, isc_boolean_t create, dns_dbnode_t **nodep); -/* +/*%< * Find the node with name 'name'. * * Notes: - * If 'create' is ISC_TRUE and no node with name 'name' exists, then + *\li If 'create' is ISC_TRUE and no node with name 'name' exists, then * such a node will be created. * - * This routine is for finding or creating a node with the specified + *\li This routine is for finding or creating a node with the specified * name. There are no partial matches. It is not suitable for use * in building responses to ordinary DNS queries; clients which wish * to do that should use dns_db_find() instead. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'name' is a valid, non-empty, absolute name. + *\li 'name' is a valid, non-empty, absolute name. * - * nodep != NULL && *nodep == NULL + *\li nodep != NULL && *nodep == NULL * * Ensures: * - * On success, *nodep is attached to the node with name 'name'. + *\li On success, *nodep is attached to the node with name 'name'. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOTFOUND If !create and name not found. - * ISC_R_NOMEMORY Can only happen if create is ISC_TRUE. + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOTFOUND If !create and name not found. + *\li #ISC_R_NOMEMORY Can only happen if create is ISC_TRUE. * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used. */ @@ -628,44 +632,44 @@ dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version, dns_rdatatype_t type, unsigned int options, isc_stdtime_t now, dns_dbnode_t **nodep, dns_name_t *foundname, dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); -/* +/*%< * Find the best match for 'name' and 'type' in version 'version' of 'db'. * * Notes: * - * If type == dns_rdataset_any, then rdataset will not be bound. + *\li If type == dns_rdataset_any, then rdataset will not be bound. * - * If 'options' does not have DNS_DBFIND_GLUEOK set, then no glue will - * be returned. For zone databases, glue is as defined in RFC 2181. + *\li If 'options' does not have #DNS_DBFIND_GLUEOK set, then no glue will + * be returned. For zone databases, glue is as defined in RFC2181. * For cache databases, glue is any rdataset with a trust of * dns_trust_glue. * - * If 'options' does not have DNS_DBFIND_PENDINGOK set, then no + *\li If 'options' does not have #DNS_DBFIND_PENDINGOK set, then no * pending data will be returned. This option is only meaningful for * cache databases. * - * If the DNS_DBFIND_NOWILD option is set, then wildcard matching will + *\li If the #DNS_DBFIND_NOWILD option is set, then wildcard matching will * be disabled. This option is only meaningful for zone databases. * - * If the DNS_DBFIND_FORCENSEC option is set, the database is assumed to + *\li If the #DNS_DBFIND_FORCENSEC option is set, the database is assumed to * have NSEC records, and these will be returned when appropriate. This * is only necessary when querying a database that was not secure * when created. * - * If the DNS_DBFIND_COVERINGNSEC option is set, then look for a + *\li If the DNS_DBFIND_COVERINGNSEC option is set, then look for a * NSEC record that potentially covers 'name' if a answer cannot * be found. Note the returned NSEC needs to be checked to ensure * that it is correct. This only affects answers returned from the * cache. * - * To respond to a query for SIG records, the caller should create a + *\li To respond to a query for SIG records, the caller should create a * rdataset iterator and extract the signatures from each rdataset. * - * Making queries of type ANY with DNS_DBFIND_GLUEOK is not recommended, + *\li Making queries of type ANY with #DNS_DBFIND_GLUEOK is not recommended, * because the burden of determining whether a given rdataset is valid * glue or not falls upon the caller. * - * The 'now' field is ignored if 'db' is a zone database. If 'db' is a + *\li The 'now' field is ignored if 'db' is a zone database. If 'db' is a * cache database, an rdataset will not be found unless it expires after * 'now'. Any ANY query will not match unless at least one rdataset at * the node expires after 'now'. If 'now' is zero, then the current time @@ -673,43 +677,41 @@ dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version, * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT'). + *\li 'type' is not SIG, or a meta-RR type other than 'ANY' (e.g. 'OPT'). * - * 'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL. + *\li 'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL. * - * 'foundname' is a valid name with a dedicated buffer. + *\li 'foundname' is a valid name with a dedicated buffer. * - * 'rdataset' is NULL, or is a valid unassociated rdataset. + *\li 'rdataset' is NULL, or is a valid unassociated rdataset. * - * Ensures: - * On a non-error completion: + * Ensures, + * on a non-error completion: * - * If nodep != NULL, then it is bound to the found node. + * \li If nodep != NULL, then it is bound to the found node. * - * If foundname != NULL, then it contains the full name of the + * \li If foundname != NULL, then it contains the full name of the * found node. * - * If rdataset != NULL and type != dns_rdatatype_any, then + * \li If rdataset != NULL and type != dns_rdatatype_any, then * rdataset is bound to the found rdataset. * - * Returns: - * * Non-error results are: * - * ISC_R_SUCCESS The desired node and type were + *\li #ISC_R_SUCCESS The desired node and type were * found. * - * DNS_R_WILDCARD The desired node and type were + *\li #DNS_R_WILDCARD The desired node and type were * found after performing * wildcard matching. This is * only returned if the - * DNS_DBFIND_INDICATEWILD + * #DNS_DBFIND_INDICATEWILD * option is set; otherwise - * ISC_R_SUCCESS is returned. + * #ISC_R_SUCCESS is returned. * - * DNS_R_GLUE The desired node and type were + *\li #DNS_R_GLUE The desired node and type were * found, but are glue. This * result can only occur if * the DNS_DBFIND_GLUEOK option @@ -724,7 +726,7 @@ dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version, * take care not to return invalid * glue to a client. * - * DNS_R_DELEGATION The data requested is beneath + *\li #DNS_R_DELEGATION The data requested is beneath * a zone cut. node, foundname, * and rdataset reference the * NS RRset of the zone cut. @@ -732,7 +734,7 @@ dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version, * then this is the deepest known * delegation. * - * DNS_R_ZONECUT type == dns_rdatatype_any, and + *\li #DNS_R_ZONECUT type == dns_rdatatype_any, and * the desired node is a zonecut. * The caller must take care not * to return inappropriate glue @@ -741,24 +743,24 @@ dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version, * database and DNS_DBFIND_GLUEOK * is set. * - * DNS_R_DNAME The data requested is beneath + *\li #DNS_R_DNAME The data requested is beneath * a DNAME. node, foundname, * and rdataset reference the * DNAME RRset. * - * DNS_R_CNAME The rdataset requested was not + *\li #DNS_R_CNAME The rdataset requested was not * found, but there is a CNAME * at the desired name. node, * foundname, and rdataset * reference the CNAME RRset. * - * DNS_R_NXDOMAIN The desired name does not + *\li #DNS_R_NXDOMAIN The desired name does not * exist. * - * DNS_R_NXRRSET The desired name exists, but + *\li #DNS_R_NXRRSET The desired name exists, but * the desired type does not. * - * ISC_R_NOTFOUND The desired name does not + *\li #ISC_R_NOTFOUND The desired name does not * exist, and no delegation could * be found. This result can only * occur if 'db' is a cache @@ -766,19 +768,19 @@ dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version, * use its nameserver(s) of last * resort (e.g. root hints). * - * DNS_R_NCACHENXDOMAIN The desired name does not + *\li #DNS_R_NCACHENXDOMAIN The desired name does not * exist. 'node' is bound to the * cache node with the desired * name, and 'rdataset' contains * the negative caching proof. * - * DNS_R_NCACHENXRRSET The desired type does not + *\li #DNS_R_NCACHENXRRSET The desired type does not * exist. 'node' is bound to the * cache node with the desired * name, and 'rdataset' contains * the negative caching proof. * - * DNS_R_EMPTYNAME The name exists but there is + *\li #DNS_R_EMPTYNAME The name exists but there is * no data at the name. * * DNS_R_COVERINGNSEC The returned data is a NSEC @@ -786,14 +788,14 @@ dns_db_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version, * * Error results: * - * ISC_R_NOMEMORY + *\li #ISC_R_NOMEMORY * - * DNS_R_BADDB Data that is required to be + *\li #DNS_R_BADDB Data that is required to be * present in the DB, e.g. an NSEC * record in a secure zone, is not * present. * - * Other results are possible, and should all be treated as + *\li Other results are possible, and should all be treated as * errors. */ @@ -802,100 +804,97 @@ dns_db_findzonecut(dns_db_t *db, dns_name_t *name, unsigned int options, isc_stdtime_t now, dns_dbnode_t **nodep, dns_name_t *foundname, dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); -/* +/*%< * Find the deepest known zonecut which encloses 'name' in 'db'. * * Notes: * - * If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned + *\li If the #DNS_DBFIND_NOEXACT option is set, then the zonecut returned * (if any) will be the deepest known ancestor of 'name'. * - * If 'now' is zero, then the current time will be used. + *\li If 'now' is zero, then the current time will be used. * * Requires: * - * 'db' is a valid database with cache semantics. + *\li 'db' is a valid database with cache semantics. * - * 'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL. + *\li 'nodep' is NULL, or nodep is a valid pointer and *nodep == NULL. * - * 'foundname' is a valid name with a dedicated buffer. + *\li 'foundname' is a valid name with a dedicated buffer. * - * 'rdataset' is NULL, or is a valid unassociated rdataset. + *\li 'rdataset' is NULL, or is a valid unassociated rdataset. * - * Ensures: - * On a non-error completion: + * Ensures, on a non-error completion: * - * If nodep != NULL, then it is bound to the found node. + *\li If nodep != NULL, then it is bound to the found node. * - * If foundname != NULL, then it contains the full name of the + *\li If foundname != NULL, then it contains the full name of the * found node. * - * If rdataset != NULL and type != dns_rdatatype_any, then + *\li If rdataset != NULL and type != dns_rdatatype_any, then * rdataset is bound to the found rdataset. * - * Returns: - * * Non-error results are: * - * ISC_R_SUCCESS + * \li #ISC_R_SUCCESS * - * ISC_R_NOTFOUND + * \li #ISC_R_NOTFOUND * - * Other results are possible, and should all be treated as + * \li Other results are possible, and should all be treated as * errors. */ void dns_db_attachnode(dns_db_t *db, dns_dbnode_t *source, dns_dbnode_t **targetp); -/* +/*%< * Attach *targetp to source. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'source' is a valid node. + *\li 'source' is a valid node. * - * 'targetp' points to a NULL dns_node_t *. + *\li 'targetp' points to a NULL dns_node_t *. * * Ensures: * - * *targetp is attached to source. + *\li *targetp is attached to source. */ void dns_db_detachnode(dns_db_t *db, dns_dbnode_t **nodep); -/* +/*%< * Detach *nodep from its node. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'nodep' points to a valid node. + *\li 'nodep' points to a valid node. * * Ensures: * - * *nodep is NULL. + *\li *nodep is NULL. */ isc_result_t dns_db_expirenode(dns_db_t *db, dns_dbnode_t *node, isc_stdtime_t now); -/* +/*%< * Mark as stale all records at 'node' which expire at or before 'now'. * * Note: if 'now' is zero, then the current time will be used. * * Requires: * - * 'db' is a valid cache database. + *\li 'db' is a valid cache database. * - * 'node' is a valid node. + *\li 'node' is a valid node. */ void dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out); -/* +/*%< * Print a textual representation of the contents of the node to * 'out'. * @@ -903,48 +902,48 @@ dns_db_printnode(dns_db_t *db, dns_dbnode_t *node, FILE *out); * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'node' is a valid node. + *\li 'node' is a valid node. */ -/*** +/*%<** *** DB Iterator Creation ***/ isc_result_t dns_db_createiterator(dns_db_t *db, isc_boolean_t relative_names, dns_dbiterator_t **iteratorp); -/* +/*%< * Create an iterator for version 'version' of 'db'. * * Notes: * - * If 'relative_names' is ISC_TRUE, then node names returned by the + *\li If 'relative_names' is ISC_TRUE, then node names returned by the * iterator will be relative to the iterator's current origin. If - * ISC_FALSE, then the node names will be absolute. + * #ISC_FALSE, then the node names will be absolute. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * iteratorp != NULL && *iteratorp == NULL + *\li iteratorp != NULL && *iteratorp == NULL * * Ensures: * - * On success, *iteratorp will be a valid database iterator. + *\li On success, *iteratorp will be a valid database iterator. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ -/*** +/*%<** *** Rdataset Methods ***/ -/* +/*%< * XXXRTH Should we check for glue and pending data in dns_db_findrdataset()? */ @@ -953,62 +952,62 @@ dns_db_findrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version, dns_rdatatype_t type, dns_rdatatype_t covers, isc_stdtime_t now, dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); -/* +/*%< * Search for an rdataset of type 'type' at 'node' that are in version * 'version' of 'db'. If found, make 'rdataset' refer to it. * * Notes: * - * If 'version' is NULL, then the current version will be used. + *\li If 'version' is NULL, then the current version will be used. * - * Care must be used when using this routine to build a DNS response: + *\li Care must be used when using this routine to build a DNS response: * 'node' should have been found with dns_db_find(), not * dns_db_findnode(). No glue checking is done. No checking for * pending data is done. * - * The 'now' field is ignored if 'db' is a zone database. If 'db' is a + *\li The 'now' field is ignored if 'db' is a zone database. If 'db' is a * cache database, an rdataset will not be found unless it expires after * 'now'. If 'now' is zero, then the current time will be used. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'node' is a valid node. + *\li 'node' is a valid node. * - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. * - * 'sigrdataset' is a valid, disassociated rdataset, or it is NULL. + *\li 'sigrdataset' is a valid, disassociated rdataset, or it is NULL. * - * If 'covers' != 0, 'type' must be SIG. + *\li If 'covers' != 0, 'type' must be SIG. * - * 'type' is not a meta-RR type such as 'ANY' or 'OPT'. + *\li 'type' is not a meta-RR type such as 'ANY' or 'OPT'. * * Ensures: * - * On success, 'rdataset' is associated with the found rdataset. + *\li On success, 'rdataset' is associated with the found rdataset. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOTFOUND + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOTFOUND * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used. */ isc_result_t dns_db_allrdatasets(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version, isc_stdtime_t now, dns_rdatasetiter_t **iteratorp); -/* +/*%< * Make '*iteratorp' an rdataset iteratator for all rdatasets at 'node' in * version 'version' of 'db'. * * Notes: * - * If 'version' is NULL, then the current version will be used. + *\li If 'version' is NULL, then the current version will be used. * - * The 'now' field is ignored if 'db' is a zone database. If 'db' is a + *\li The 'now' field is ignored if 'db' is a zone database. If 'db' is a * cache database, an rdataset will not be found unless it expires after * 'now'. Any ANY query will not match unless at least one rdataset at * the node expires after 'now'. If 'now' is zero, then the current time @@ -1016,22 +1015,22 @@ dns_db_allrdatasets(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version, * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'node' is a valid node. + *\li 'node' is a valid node. * - * iteratorp != NULL && *iteratorp == NULL + *\li iteratorp != NULL && *iteratorp == NULL * * Ensures: * - * On success, '*iteratorp' is a valid rdataset iterator. + *\li On success, '*iteratorp' is a valid rdataset iterator. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOTFOUND + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOTFOUND * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used. */ @@ -1039,58 +1038,58 @@ isc_result_t dns_db_addrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version, isc_stdtime_t now, dns_rdataset_t *rdataset, unsigned int options, dns_rdataset_t *addedrdataset); -/* +/*%< * Add 'rdataset' to 'node' in version 'version' of 'db'. * * Notes: * - * If the database has zone semantics, the DNS_DBADD_MERGE option is set, + *\li If the database has zone semantics, the #DNS_DBADD_MERGE option is set, * and an rdataset of the same type as 'rdataset' already exists at * 'node' then the contents of 'rdataset' will be merged with the existing * rdataset. If the option is not set, then rdataset will replace any * existing rdataset of the same type. If not merging and the - * DNS_DBADD_FORCE option is set, then the data will update the database + * #DNS_DBADD_FORCE option is set, then the data will update the database * without regard to trust levels. If not forcing the data, then the * rdataset will only be added if its trust level is >= the trust level of * any existing rdataset. Forcing is only meaningful for cache databases. - * If DNS_DBADD_EXACT is set then there must be no rdata in common between - * the old and new rdata sets. If DNS_DBADD_EXACTTTL is set then both + * If #DNS_DBADD_EXACT is set then there must be no rdata in common between + * the old and new rdata sets. If #DNS_DBADD_EXACTTTL is set then both * the old and new rdata sets must have the same ttl. * - * The 'now' field is ignored if 'db' is a zone database. If 'db' is + *\li The 'now' field is ignored if 'db' is a zone database. If 'db' is * a cache database, then the added rdataset will expire no later than * now + rdataset->ttl. * - * If 'addedrdataset' is not NULL, then it will be attached to the + *\li If 'addedrdataset' is not NULL, then it will be attached to the * resulting new rdataset in the database, or to the existing data if * the existing data was better. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'node' is a valid node. + *\li 'node' is a valid node. * - * 'rdataset' is a valid, associated rdataset with the same class + *\li 'rdataset' is a valid, associated rdataset with the same class * as 'db'. * - * 'addedrdataset' is NULL, or a valid, unassociated rdataset. + *\li 'addedrdataset' is NULL, or a valid, unassociated rdataset. * - * The database has zone semantics and 'version' is a valid + *\li The database has zone semantics and 'version' is a valid * read-write version, or the database has cache semantics * and version is NULL. * - * If the database has cache semantics, the DNS_DBADD_MERGE option must + *\li If the database has cache semantics, the #DNS_DBADD_MERGE option must * not be set. * * Returns: * - * ISC_R_SUCCESS - * DNS_R_UNCHANGED The operation did not change anything. - * ISC_R_NOMEMORY - * DNS_R_NOTEXACT + *\li #ISC_R_SUCCESS + *\li #DNS_R_UNCHANGED The operation did not change anything. + *\li #ISC_R_NOMEMORY + *\li #DNS_R_NOTEXACT * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used. */ @@ -1098,41 +1097,41 @@ isc_result_t dns_db_subtractrdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version, dns_rdataset_t *rdataset, unsigned int options, dns_rdataset_t *newrdataset); -/* +/*%< * Remove any rdata in 'rdataset' from 'node' in version 'version' of * 'db'. * * Notes: * - * If 'newrdataset' is not NULL, then it will be attached to the + *\li If 'newrdataset' is not NULL, then it will be attached to the * resulting new rdataset in the database, unless the rdataset has * become nonexistent. If DNS_DBSUB_EXACT is set then all elements * of 'rdataset' must exist at 'node'. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'node' is a valid node. + *\li 'node' is a valid node. * - * 'rdataset' is a valid, associated rdataset with the same class + *\li 'rdataset' is a valid, associated rdataset with the same class * as 'db'. * - * 'newrdataset' is NULL, or a valid, unassociated rdataset. + *\li 'newrdataset' is NULL, or a valid, unassociated rdataset. * - * The database has zone semantics and 'version' is a valid + *\li The database has zone semantics and 'version' is a valid * read-write version. * * Returns: * - * ISC_R_SUCCESS - * DNS_R_UNCHANGED The operation did not change anything. - * DNS_R_NXRRSET All rdata of the same type as those + *\li #ISC_R_SUCCESS + *\li #DNS_R_UNCHANGED The operation did not change anything. + *\li #DNS_R_NXRRSET All rdata of the same type as those * in 'rdataset' have been deleted. - * DNS_R_NOTEXACT Some part of 'rdataset' did not + *\li #DNS_R_NOTEXACT Some part of 'rdataset' did not * exist and DNS_DBSUB_EXACT was set. * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used. */ @@ -1140,68 +1139,68 @@ isc_result_t dns_db_deleterdataset(dns_db_t *db, dns_dbnode_t *node, dns_dbversion_t *version, dns_rdatatype_t type, dns_rdatatype_t covers); -/* +/*%< * Make it so that no rdataset of type 'type' exists at 'node' in version * version 'version' of 'db'. * * Notes: * - * If 'type' is dns_rdatatype_any, then no rdatasets will exist in + *\li If 'type' is dns_rdatatype_any, then no rdatasets will exist in * 'version' (provided that the dns_db_deleterdataset() isn't followed * by one or more dns_db_addrdataset() calls). * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * - * 'node' is a valid node. + *\li 'node' is a valid node. * - * The database has zone semantics and 'version' is a valid + *\li The database has zone semantics and 'version' is a valid * read-write version, or the database has cache semantics * and version is NULL. * - * 'type' is not a meta-RR type, except for dns_rdatatype_any, which is + *\li 'type' is not a meta-RR type, except for dns_rdatatype_any, which is * allowed. * - * If 'covers' != 0, 'type' must be SIG. + *\li If 'covers' != 0, 'type' must be SIG. * * Returns: * - * ISC_R_SUCCESS - * DNS_R_UNCHANGED No rdatasets of 'type' existed before + *\li #ISC_R_SUCCESS + *\li #DNS_R_UNCHANGED No rdatasets of 'type' existed before * the operation was attempted. * - * Other results are possible, depending upon the database + *\li Other results are possible, depending upon the database * implementation used. */ isc_result_t dns_db_getsoaserial(dns_db_t *db, dns_dbversion_t *ver, isc_uint32_t *serialp); -/* +/*%< * Get the current SOA serial number from a zone database. * * Requires: - * 'db' is a valid database with zone semantics. - * 'ver' is a valid version. + * \li 'db' is a valid database with zone semantics. + * \li 'ver' is a valid version. */ void dns_db_overmem(dns_db_t *db, isc_boolean_t overmem); -/* +/*%< * Enable / disable agressive cache cleaning. */ unsigned int dns_db_nodecount(dns_db_t *db); -/* +/*%< * Count the number of nodes in 'db'. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * * Returns: - * The number of nodes in the database + * \li The number of nodes in the database */ void @@ -1216,58 +1215,58 @@ dns_db_settask(dns_db_t *db, isc_task_t *task); isc_boolean_t dns_db_ispersistent(dns_db_t *db); -/* +/*%< * Is 'db' persistent? A persistent database does not need to be loaded * from disk or written to disk. * * Requires: * - * 'db' is a valid database. + *\li 'db' is a valid database. * * Returns: - * ISC_TRUE 'db' is persistent. - * ISC_FALSE 'db' is not persistent. + *\li #ISC_TRUE 'db' is persistent. + *\li #ISC_FALSE 'db' is not persistent. */ isc_result_t dns_db_register(const char *name, dns_dbcreatefunc_t create, void *driverarg, isc_mem_t *mctx, dns_dbimplementation_t **dbimp); -/* +/*%< * Register a new database implementation and add it to the list of * supported implementations. * * Requires: * - * 'name' is not NULL - * 'order' is a valid function pointer - * 'mctx' is a valid memory context - * dbimp != NULL && *dbimp == NULL + *\li 'name' is not NULL + * \li 'order' is a valid function pointer + * \li 'mctx' is a valid memory context + * \li dbimp != NULL && *dbimp == NULL * * Returns: - * ISC_R_SUCCESS The registration succeeded - * ISC_R_NOMEMORY Out of memory - * ISC_R_EXISTS A database implementation with the same name exists + * \li #ISC_R_SUCCESS The registration succeeded + * \li #ISC_R_NOMEMORY Out of memory + * \li #ISC_R_EXISTS A database implementation with the same name exists * * Ensures: * - * *dbimp points to an opaque structure which must be passed to + *\li *dbimp points to an opaque structure which must be passed to * dns_db_unregister(). */ void dns_db_unregister(dns_dbimplementation_t **dbimp); -/* +/*%< * Remove a database implementation from the the list of supported * implementations. No databases of this type can be active when this * is called. * * Requires: - * dbimp != NULL && *dbimp == NULL + *\li dbimp != NULL && *dbimp == NULL * * Ensures: * - * Any memory allocated in *dbimp will be freed. + * \li Any memory allocated in *dbimp will be freed. */ isc_result_t diff --git a/lib/dns/include/dns/dbiterator.h b/lib/dns/include/dns/dbiterator.h index 87f39291ae..8782e9b81a 100644 --- a/lib/dns/include/dns/dbiterator.h +++ b/lib/dns/include/dns/dbiterator.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dbiterator.h,v 1.19 2004/03/05 05:09:41 marka Exp $ */ +/* $Id: dbiterator.h,v 1.20 2005/04/27 04:56:54 sra Exp $ */ #ifndef DNS_DBITERATOR_H #define DNS_DBITERATOR_H 1 @@ -24,9 +24,8 @@ ***** Module Info *****/ -/* - * DNS DB Iterator - * +/*! \file + * \brief * The DNS DB Iterator interface allows iteration of all of the nodes in a * database. * @@ -37,25 +36,25 @@ * It is the client's responsibility to call dns_db_detachnode() on all * nodes returned. * - * XXX XXX + * XXX <more> XXX * * MP: - * The iterator itself is not locked. The caller must ensure + *\li The iterator itself is not locked. The caller must ensure * synchronization. * - * The iterator methods ensure appropriate database locking. + *\li The iterator methods ensure appropriate database locking. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * None. + *\li None. */ /***** @@ -89,7 +88,7 @@ typedef struct dns_dbiteratormethods { #define DNS_DBITERATOR_MAGIC ISC_MAGIC('D','N','S','I') #define DNS_DBITERATOR_VALID(dbi) ISC_MAGIC_VALID(dbi, DNS_DBITERATOR_MAGIC) -/* +/*% * This structure is actually just the common prefix of a DNS db * implementation's version of a dns_dbiterator_t. * @@ -110,136 +109,136 @@ struct dns_dbiterator { void dns_dbiterator_destroy(dns_dbiterator_t **iteratorp); -/* +/*%< * Destroy '*iteratorp'. * * Requires: * - * '*iteratorp' is a valid iterator. + *\li '*iteratorp' is a valid iterator. * * Ensures: * - * All resources used by the iterator are freed. + *\li All resources used by the iterator are freed. * - * *iteratorp == NULL. + *\li *iteratorp == NULL. */ isc_result_t dns_dbiterator_first(dns_dbiterator_t *iterator); -/* +/*%< * Move the node cursor to the first node in the database (if any). * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE There are no nodes in the database. + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no nodes in the database. * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ isc_result_t dns_dbiterator_last(dns_dbiterator_t *iterator); -/* +/*%< * Move the node cursor to the last node in the database (if any). * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE There are no nodes in the database. + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no nodes in the database. * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ isc_result_t dns_dbiterator_seek(dns_dbiterator_t *iterator, dns_name_t *name); -/* +/*%< * Move the node cursor to the node with name 'name'. * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * - * 'name' is a valid name. + *\li 'name' is a valid name. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOTFOUND + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOTFOUND * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ isc_result_t dns_dbiterator_prev(dns_dbiterator_t *iterator); -/* +/*%< * Move the node cursor to the previous node in the database (if any). * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE There are no more nodes in the + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no more nodes in the * database. * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ isc_result_t dns_dbiterator_next(dns_dbiterator_t *iterator); -/* +/*%< * Move the node cursor to the next node in the database (if any). * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE There are no more nodes in the + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no more nodes in the * database. * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ isc_result_t dns_dbiterator_current(dns_dbiterator_t *iterator, dns_dbnode_t **nodep, dns_name_t *name); -/* +/*%< * Return the current node. * * Notes: - * If 'name' is not NULL, it will be set to the name of the node. + *\li If 'name' is not NULL, it will be set to the name of the node. * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * - * nodep != NULL && *nodep == NULL + *\li nodep != NULL && *nodep == NULL * - * The node cursor of 'iterator' is at a valid location (i.e. the + *\li The node cursor of 'iterator' is at a valid location (i.e. the * result of last call to a cursor movement command was ISC_R_SUCCESS). * - * 'name' is NULL, or is a valid name with a dedicated buffer. + *\li 'name' is NULL, or is a valid name with a dedicated buffer. * * Returns: * - * ISC_R_SUCCESS - * DNS_R_NEWORIGIN If this iterator was created with + *\li #ISC_R_SUCCESS + *\li #DNS_R_NEWORIGIN If this iterator was created with * 'relative_names' set to ISC_TRUE, - * then DNS_R_NEWORIGIN will be returned + * then #DNS_R_NEWORIGIN will be returned * when the origin the names are * relative to changes. This result * can occur only when 'name' is not * NULL. This is also a successful * result. * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ isc_result_t dns_dbiterator_pause(dns_dbiterator_t *iterator); -/* +/*%< * Pause iteration. * * Calling a cursor movement method or dns_dbiterator_current() may cause @@ -250,47 +249,47 @@ dns_dbiterator_pause(dns_dbiterator_t *iterator); * iterator method in the immediate future. * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * * Ensures: - * Any database locks being held for efficiency of iterator access are + *\li Any database locks being held for efficiency of iterator access are * released. * * Returns: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ isc_result_t dns_dbiterator_origin(dns_dbiterator_t *iterator, dns_name_t *name); -/* +/*%< * Return the origin to which returned node names are relative. * * Requires: * - * 'iterator' is a valid relative_names iterator. + *\li 'iterator' is a valid relative_names iterator. * - * 'name' is a valid name with a dedicated buffer. + *\li 'name' is a valid name with a dedicated buffer. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOSPACE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ void dns_dbiterator_setcleanmode(dns_dbiterator_t *iterator, isc_boolean_t mode); -/* +/*%< * Indicate that the given iterator is/is not cleaning the DB. * * Notes: - * When 'mode' is ISC_TRUE, + *\li When 'mode' is ISC_TRUE, * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/dbtable.h b/lib/dns/include/dns/dbtable.h index 727f33289e..ae0514e26c 100644 --- a/lib/dns/include/dns/dbtable.h +++ b/lib/dns/include/dns/dbtable.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dbtable.h,v 1.17 2004/03/05 05:09:41 marka Exp $ */ +/* $Id: dbtable.h,v 1.18 2005/04/27 04:56:54 sra Exp $ */ #ifndef DNS_DBTABLE_H #define DNS_DBTABLE_H 1 @@ -24,26 +24,27 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * DNS DB Tables * - * XXX XXX + * XXX TBS XXX * * MP: - * The module ensures appropriate synchronization of data structures it + *\li The module ensures appropriate synchronization of data structures it * creates and manipulates. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * None. + *\li None. * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * None. + *\li None. */ #include @@ -57,106 +58,106 @@ ISC_LANG_BEGINDECLS isc_result_t dns_dbtable_create(isc_mem_t *mctx, dns_rdataclass_t rdclass, dns_dbtable_t **dbtablep); -/* +/*%< * Make a new dbtable of class 'rdclass' * * Requires: - * mctx != NULL - * dbtablep != NULL && *dptablep == NULL - * 'rdclass' is a valid class + *\li mctx != NULL + * \li dbtablep != NULL && *dptablep == NULL + *\li 'rdclass' is a valid class * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED */ void dns_dbtable_attach(dns_dbtable_t *source, dns_dbtable_t **targetp); -/* +/*%< * Attach '*targetp' to 'source'. * * Requires: * - * 'source' is a valid dbtable. + *\li 'source' is a valid dbtable. * - * 'targetp' points to a NULL dns_dbtable_t *. + *\li 'targetp' points to a NULL dns_dbtable_t *. * * Ensures: * - * *targetp is attached to source. + *\li *targetp is attached to source. */ void dns_dbtable_detach(dns_dbtable_t **dbtablep); -/* +/*%< * Detach *dbtablep from its dbtable. * * Requires: * - * '*dbtablep' points to a valid dbtable. + *\li '*dbtablep' points to a valid dbtable. * * Ensures: * - * *dbtablep is NULL. + *\li *dbtablep is NULL. * - * If '*dbtablep' is the last reference to the dbtable, - * - * All resources used by the dbtable will be freed + *\li If '*dbtablep' is the last reference to the dbtable, + * all resources used by the dbtable will be freed */ isc_result_t dns_dbtable_add(dns_dbtable_t *dbtable, dns_db_t *db); -/* +/*%< * Add 'db' to 'dbtable'. * * Requires: - * 'dbtable' is a valid dbtable. + *\li 'dbtable' is a valid dbtable. * - * 'db' is a valid database with the same class as 'dbtable' + *\li 'db' is a valid database with the same class as 'dbtable' */ void dns_dbtable_remove(dns_dbtable_t *dbtable, dns_db_t *db); -/* +/*%< * Remove 'db' from 'dbtable'. * * Requires: - * 'db' was previously added to 'dbtable'. + *\li 'db' was previously added to 'dbtable'. */ void dns_dbtable_adddefault(dns_dbtable_t *dbtable, dns_db_t *db); -/* +/*%< * Use 'db' as the result of a dns_dbtable_find() if no better match is * available. */ void dns_dbtable_getdefault(dns_dbtable_t *dbtable, dns_db_t **db); -/* +/*%< * Get the 'db' used as the result of a dns_dbtable_find() * if no better match is available. */ void dns_dbtable_removedefault(dns_dbtable_t *dbtable); -/* +/*%< * Remove the default db from 'dbtable'. */ isc_result_t dns_dbtable_find(dns_dbtable_t *dbtable, dns_name_t *name, unsigned int options, dns_db_t **dbp); -/* +/*%< * Find the deepest match to 'name' in the dbtable, and return it * * Notes: - * If the DNS_DBTABLEFIND_NOEXACT option is set, the best partial + *\li If the DNS_DBTABLEFIND_NOEXACT option is set, the best partial * match (if any) to 'name' will be returned. * - * Returns: ISC_R_SUCCESS on success - * no default and match + * Returns: + * \li #ISC_R_SUCCESS on success + *\li something else: no default and match */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/diff.h b/lib/dns/include/dns/diff.h index 401f7b828e..278ef8acc2 100644 --- a/lib/dns/include/dns/diff.h +++ b/lib/dns/include/dns/diff.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: diff.h,v 1.6 2004/03/05 05:09:41 marka Exp $ */ +/* $Id: diff.h,v 1.7 2005/04/27 04:56:55 sra Exp $ */ #ifndef DNS_DIFF_H #define DNS_DIFF_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * A diff is a convenience type representing a list of changes to be * made to a database. */ @@ -44,7 +45,7 @@ *** Types ***/ -/* +/*% * A dns_difftuple_t represents a single RR being added or deleted. * The RR type and class are in the 'rdata' member; the class is always * the real one, not a DynDNS meta-class, so that the rdatas can be @@ -61,9 +62,9 @@ */ typedef enum { - DNS_DIFFOP_ADD, /* Add an RR. */ - DNS_DIFFOP_DEL, /* Delete an RR. */ - DNS_DIFFOP_EXISTS /* Assert RR existence. */ + DNS_DIFFOP_ADD, /*%< Add an RR. */ + DNS_DIFFOP_DEL, /*%< Delete an RR. */ + DNS_DIFFOP_EXISTS /*%< Assert RR existence. */ } dns_diffop_t; typedef struct dns_difftuple dns_difftuple_t; @@ -82,7 +83,7 @@ struct dns_difftuple { /* Variable-size name data and rdata follows. */ }; -/* +/*% * A dns_diff_t represents a set of changes being applied to * a zone. Diffs are also used to represent "RRset exists * (value dependent)" prerequisites. @@ -116,106 +117,106 @@ isc_result_t dns_difftuple_create(isc_mem_t *mctx, dns_diffop_t op, dns_name_t *name, dns_ttl_t ttl, dns_rdata_t *rdata, dns_difftuple_t **tp); -/* +/*%< * Create a tuple. Deep copies are made of the name and rdata, so * they need not remain valid after the call. * * Requires: - * *tp != NULL && *tp == NULL. + *\li *tp != NULL && *tp == NULL. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li ISC_R_SUCCESS + * \li ISC_R_NOMEMORY */ void dns_difftuple_free(dns_difftuple_t **tp); -/* +/*%< * Free a tuple. * * Requires: - * **tp is a valid tuple. + * \li **tp is a valid tuple. * * Ensures: - * *tp == NULL - * All memory used by the tuple is freed. + * \li *tp == NULL + * \li All memory used by the tuple is freed. */ isc_result_t dns_difftuple_copy(dns_difftuple_t *orig, dns_difftuple_t **copyp); -/* +/*%< * Copy a tuple. * * Requires: - * 'orig' points to a valid tuple - * copyp != NULL && *copyp == NULL + * \li 'orig' points to a valid tuple + *\li copyp != NULL && *copyp == NULL */ void dns_diff_init(isc_mem_t *mctx, dns_diff_t *diff); -/* +/*%< * Initialize a diff. * * Requires: - * 'diff' points to an uninitialized dns_diff_t - * allocated by the caller. + * \li 'diff' points to an uninitialized dns_diff_t + * \li allocated by the caller. * * Ensures: - * '*diff' is a valid, empty diff. + * \li '*diff' is a valid, empty diff. */ void dns_diff_clear(dns_diff_t *diff); -/* +/*%< * Clear a diff, destroying all its tuples. * * Requires: - * 'diff' points to a valid dns_diff_t. + * \li 'diff' points to a valid dns_diff_t. * * Ensures: - * Any tuples in the diff are destroyed. + * \li Any tuples in the diff are destroyed. * The diff now empty, but it is still valid * and may be reused without calling dns_diff_init * again. The only memory used is that of the * dns_diff_t structure itself. * * Notes: - * Managing the memory of the dns_diff_t structure itself + * \li Managing the memory of the dns_diff_t structure itself * is the caller's responsibility. */ void dns_diff_append(dns_diff_t *diff, dns_difftuple_t **tuple); -/* +/*%< * Append a single tuple to a diff. * - * 'diff' is a valid diff. - * '*tuple' is a valid tuple. + *\li 'diff' is a valid diff. + * \li '*tuple' is a valid tuple. * * Ensures: - * *tuple is NULL. - * The tuple has been freed, or will be freed when the diff is cleared. + *\li *tuple is NULL. + *\li The tuple has been freed, or will be freed when the diff is cleared. */ void dns_diff_appendminimal(dns_diff_t *diff, dns_difftuple_t **tuple); -/* +/*%< * Append 'tuple' to 'diff', removing any duplicate * or conflicting updates as needed to create a minimal diff. * * Requires: - * 'diff' is a minimal diff. + *\li 'diff' is a minimal diff. * * Ensures: - * 'diff' is still a minimal diff. - * *tuple is NULL. - * The tuple has been freed, or will be freed when the diff is cleared. + *\li 'diff' is still a minimal diff. + * \li *tuple is NULL. + * \li The tuple has been freed, or will be freed when the diff is cleared. * */ isc_result_t dns_diff_sort(dns_diff_t *diff, dns_diff_compare_func *compare); -/* +/*%< * Sort 'diff' in-place according to the comparison function 'compare'. */ @@ -223,7 +224,7 @@ isc_result_t dns_diff_apply(dns_diff_t *diff, dns_db_t *db, dns_dbversion_t *ver); isc_result_t dns_diff_applysilently(dns_diff_t *diff, dns_db_t *db, dns_dbversion_t *ver); -/* +/*%< * Apply 'diff' to the database 'db'. * * dns_diff_apply() logs warnings about updates with no effect or @@ -234,44 +235,44 @@ dns_diff_applysilently(dns_diff_t *diff, dns_db_t *db, dns_dbversion_t *ver); * but less efficient. * * Requires: - * *diff is a valid diff (possibly empty), containing - * tuples of type DNS_DIFFOP_ADD and/or - * For DNS_DIFFOP_DEL tuples, the TTL is ignored. + *\li *diff is a valid diff (possibly empty), containing + * tuples of type #DNS_DIFFOP_ADD and/or + * For #DNS_DIFFOP_DEL tuples, the TTL is ignored. * */ isc_result_t dns_diff_load(dns_diff_t *diff, dns_addrdatasetfunc_t addfunc, void *add_private); -/* +/*%< * Like dns_diff_apply, but for use when loading a new database * instead of modifying an existing one. This bypasses the * database transaction mechanisms. * * Requires: - * 'addfunc' is a valid dns_addradatasetfunc_t obtained from + *\li 'addfunc' is a valid dns_addradatasetfunc_t obtained from * dns_db_beginload() * - * 'add_private' points to a corresponding dns_dbload_t * + *\li 'add_private' points to a corresponding dns_dbload_t * * (XXX why is it a void pointer, then?) */ isc_result_t dns_diff_print(dns_diff_t *diff, FILE *file); -/* +/*%< * Print the differences to 'file' or if 'file' is NULL via the * logging system. * * Require: - * 'diff' to be valid. - * 'file' to refer to a open file or NULL. + *\li 'diff' to be valid. + *\li 'file' to refer to a open file or NULL. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED - * any error from dns_rdataset_totext() + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED + *\li any error from dns_rdataset_totext() */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/dispatch.h b/lib/dns/include/dns/dispatch.h index 92a3c46e25..95ea7d97fa 100644 --- a/lib/dns/include/dns/dispatch.h +++ b/lib/dns/include/dns/dispatch.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dispatch.h,v 1.48 2004/03/05 05:09:41 marka Exp $ */ +/* $Id: dispatch.h,v 1.49 2005/04/27 04:56:55 sra Exp $ */ #ifndef DNS_DISPATCH_H #define DNS_DISPATCH_H 1 @@ -24,14 +24,14 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * DNS Dispatch Management - * * Shared UDP and single-use TCP dispatches for queries and responses. * * MP: * - * All locking is performed internally to each dispatch. + *\li All locking is performed internally to each dispatch. * Restrictions apply to dns_dispatch_removeresponse(). * * Reliability: @@ -40,12 +40,12 @@ * * Security: * - * Depends on the isc_socket_t and dns_message_t for prevention of + *\li Depends on the isc_socket_t and dns_message_t for prevention of * buffer overruns. * * Standards: * - * None. + *\li None. */ /*** @@ -61,7 +61,7 @@ ISC_LANG_BEGINDECLS -/* +/*% * This event is sent to a task when a response comes in. * No part of this structure should ever be modified by the caller, * other than parts of the buffer. The holy parts of the buffer are @@ -79,16 +79,17 @@ ISC_LANG_BEGINDECLS */ struct dns_dispatchevent { - ISC_EVENT_COMMON(dns_dispatchevent_t); /* standard event common */ - isc_result_t result; /* result code */ - isc_int32_t id; /* message id */ - isc_sockaddr_t addr; /* address recv'd from */ - struct in6_pktinfo pktinfo; /* reply info for v6 */ - isc_buffer_t buffer; /* data buffer */ - isc_uint32_t attributes; /* mirrored from socket.h */ + ISC_EVENT_COMMON(dns_dispatchevent_t); /*%< standard event common */ + isc_result_t result; /*%< result code */ + isc_int32_t id; /*%< message id */ + isc_sockaddr_t addr; /*%< address recv'd from */ + struct in6_pktinfo pktinfo; /*%< reply info for v6 */ + isc_buffer_t buffer; /*%< data buffer */ + isc_uint32_t attributes; /*%< mirrored from socket.h */ }; -/* +/*@{*/ +/*% * Attributes for added dispatchers. * * Values with the mask 0xffff0000 are application defined. @@ -121,83 +122,84 @@ struct dns_dispatchevent { #define DNS_DISPATCHATTR_NOLISTEN 0x00000020U #define DNS_DISPATCHATTR_MAKEQUERY 0x00000040U #define DNS_DISPATCHATTR_CONNECTED 0x00000080U +/*@}*/ isc_result_t dns_dispatchmgr_create(isc_mem_t *mctx, isc_entropy_t *entropy, dns_dispatchmgr_t **mgrp); -/* +/*%< * Creates a new dispatchmgr object. * * Requires: - * "mctx" be a valid memory context. + *\li "mctx" be a valid memory context. * - * mgrp != NULL && *mgrp == NULL + *\li mgrp != NULL && *mgrp == NULL * - * "entropy" may be NULL, in which case an insecure random generator + *\li "entropy" may be NULL, in which case an insecure random generator * will be used. If it is non-NULL, it must be a valid entropy * source. * * Returns: - * ISC_R_SUCCESS -- all ok + *\li ISC_R_SUCCESS -- all ok * - * anything else -- failure + *\li anything else -- failure */ void dns_dispatchmgr_destroy(dns_dispatchmgr_t **mgrp); -/* +/*%< * Destroys the dispatchmgr when it becomes empty. This could be * immediately. * * Requires: - * mgrp != NULL && *mgrp is a valid dispatchmgr. + *\li mgrp != NULL && *mgrp is a valid dispatchmgr. */ void dns_dispatchmgr_setblackhole(dns_dispatchmgr_t *mgr, dns_acl_t *blackhole); -/* +/*%< * Sets the dispatcher's "blackhole list," a list of addresses that will * be ignored by all dispatchers created by the dispatchmgr. * * Requires: - * mgrp is a valid dispatchmgr - * blackhole is a valid acl + * \li mgrp is a valid dispatchmgr + * \li blackhole is a valid acl */ dns_acl_t * dns_dispatchmgr_getblackhole(dns_dispatchmgr_t *mgr); -/* +/*%< * Gets a pointer to the dispatcher's current blackhole list, * without incrementing its reference count. * * Requires: - * mgr is a valid dispatchmgr + *\li mgr is a valid dispatchmgr * Returns: - * A pointer to the current blackhole list, or NULL. + *\li A pointer to the current blackhole list, or NULL. */ void dns_dispatchmgr_setblackportlist(dns_dispatchmgr_t *mgr, dns_portlist_t *portlist); -/* +/*%< * Sets a list of UDP ports that won't be used when creating a udp * dispatch with a wildcard port. * * Requires: - * mgr is a valid dispatchmgr - * portlist to be NULL or a valid port list. + *\li mgr is a valid dispatchmgr + *\li portlist to be NULL or a valid port list. */ dns_portlist_t * dns_dispatchmgr_getblackportlist(dns_dispatchmgr_t *mgr); -/* +/*%< * Return the current port list. * * Requires: - * mgr is a valid dispatchmgr + *\li mgr is a valid dispatchmgr */ @@ -210,29 +212,29 @@ dns_dispatch_getudp(dns_dispatchmgr_t *mgr, isc_socketmgr_t *sockmgr, unsigned int buckets, unsigned int increment, unsigned int attributes, unsigned int mask, dns_dispatch_t **dispp); -/* +/*%< * Attach to existing dns_dispatch_t if one is found with dns_dispatchmgr_find, * otherwise create a new UDP dispatch. * * Requires: - * All pointer parameters be valid for their respective types. + *\li All pointer parameters be valid for their respective types. * - * dispp != NULL && *disp == NULL + *\li dispp != NULL && *disp == NULL * - * 512 <= buffersize <= 64k + *\li 512 <= buffersize <= 64k * - * maxbuffers > 0 + *\li maxbuffers > 0 * - * buckets < 2097169 + *\li buckets < 2097169 * - * increment > buckets + *\li increment > buckets * - * (attributes & DNS_DISPATCHATTR_TCP) == 0 + *\li (attributes & DNS_DISPATCHATTR_TCP) == 0 * * Returns: - * ISC_R_SUCCESS -- success. + *\li ISC_R_SUCCESS -- success. * - * Anything else -- failure. + *\li Anything else -- failure. */ isc_result_t @@ -241,7 +243,7 @@ dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock, unsigned int maxbuffers, unsigned int maxrequests, unsigned int buckets, unsigned int increment, unsigned int attributes, dns_dispatch_t **dispp); -/* +/*%< * Create a new dns_dispatch and attach it to the provided isc_socket_t. * * For all dispatches, "buffersize" is the maximum packet size we will @@ -258,65 +260,65 @@ dns_dispatch_createtcp(dns_dispatchmgr_t *mgr, isc_socket_t *sock, * * Requires: * - * mgr is a valid dispatch manager. + *\li mgr is a valid dispatch manager. * - * sock is a valid. + *\li sock is a valid. * - * task is a valid task that can be used internally to this dispatcher. + *\li task is a valid task that can be used internally to this dispatcher. * - * 512 <= buffersize <= 64k + * \li 512 <= buffersize <= 64k * - * maxbuffers > 0. + *\li maxbuffers > 0. * - * maxrequests <= maxbuffers. + *\li maxrequests <= maxbuffers. * - * buckets < 2097169 (the next prime after 65536 * 32) + *\li buckets < 2097169 (the next prime after 65536 * 32) * - * increment > buckets (and prime). + *\li increment > buckets (and prime). * - * attributes includes DNS_DISPATCHATTR_TCP and does not include - * DNS_DISPATCHATTR_UDP. + *\li attributes includes #DNS_DISPATCHATTR_TCP and does not include + * #DNS_DISPATCHATTR_UDP. * * Returns: - * ISC_R_SUCCESS -- success. + *\li ISC_R_SUCCESS -- success. * - * Anything else -- failure. + *\li Anything else -- failure. */ void dns_dispatch_attach(dns_dispatch_t *disp, dns_dispatch_t **dispp); -/* +/*%< * Attach to a dispatch handle. * * Requires: - * disp is valid. + *\li disp is valid. * - * dispp != NULL && *dispp == NULL + *\li dispp != NULL && *dispp == NULL */ void dns_dispatch_detach(dns_dispatch_t **dispp); -/* +/*%< * Detaches from the dispatch. * * Requires: - * dispp != NULL and *dispp be a valid dispatch. + *\li dispp != NULL and *dispp be a valid dispatch. */ void dns_dispatch_starttcp(dns_dispatch_t *disp); -/* +/*%< * Start processing of a TCP dispatch once the socket connects. * * Requires: - * 'disp' is valid. + *\li 'disp' is valid. */ isc_result_t dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest, isc_task_t *task, isc_taskaction_t action, void *arg, isc_uint16_t *idp, dns_dispentry_t **resp); -/* +/*%< * Add a response entry for this dispatch. * * "*idp" is filled in with the assigned message ID, and *resp is filled in @@ -327,24 +329,24 @@ dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest, * or through dns_dispatch_removeresponse() for another to be delivered. * * Requires: - * "idp" be non-NULL. + *\li "idp" be non-NULL. * - * "task" "action" and "arg" be set as appropriate. + *\li "task" "action" and "arg" be set as appropriate. * - * "dest" be non-NULL and valid. + *\li "dest" be non-NULL and valid. * - * "resp" be non-NULL and *resp be NULL + *\li "resp" be non-NULL and *resp be NULL * * Ensures: * - * is a unique tuple. That means incoming messages + *\li <id, dest> is a unique tuple. That means incoming messages * are identifiable. * * Returns: * - * ISC_R_SUCCESS -- all is well. - * ISC_R_NOMEMORY -- memory could not be allocated. - * ISC_R_NOMORE -- no more message ids can be allocated + *\li ISC_R_SUCCESS -- all is well. + *\li ISC_R_NOMEMORY -- memory could not be allocated. + *\li ISC_R_NOMORE -- no more message ids can be allocated * for this destination. */ @@ -352,88 +354,90 @@ dns_dispatch_addresponse(dns_dispatch_t *disp, isc_sockaddr_t *dest, void dns_dispatch_removeresponse(dns_dispentry_t **resp, dns_dispatchevent_t **sockevent); -/* +/*%< * Stops the flow of responses for the provided id and destination. * If "sockevent" is non-NULL, the dispatch event and associated buffer is * also returned to the system. * * Requires: - * "resp" != NULL and "*resp" contain a value previously allocated + *\li "resp" != NULL and "*resp" contain a value previously allocated * by dns_dispatch_addresponse(); * - * May only be called from within the task given as the 'task' + *\li May only be called from within the task given as the 'task' * argument to dns_dispatch_addresponse() when allocating '*resp'. */ isc_socket_t * dns_dispatch_getsocket(dns_dispatch_t *disp); -/* +/*%< * Return the socket associated with this dispatcher. * * Requires: - * disp is valid. + *\li disp is valid. * * Returns: - * The socket the dispatcher is using. + *\li The socket the dispatcher is using. */ isc_result_t dns_dispatch_getlocaladdress(dns_dispatch_t *disp, isc_sockaddr_t *addrp); -/* +/*%< * Return the local address for this dispatch. * This currently only works for dispatches using UDP sockets. * * Requires: - * disp is valid. - * addrp to be non null. + *\li disp is valid. + *\li addrp to be non null. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOTIMPLEMENTED + *\li ISC_R_SUCCESS + *\li ISC_R_NOTIMPLEMENTED */ void dns_dispatch_cancel(dns_dispatch_t *disp); -/* +/*%< * cancel outstanding clients * * Requires: - * disp is valid. + *\li disp is valid. */ void dns_dispatch_changeattributes(dns_dispatch_t *disp, unsigned int attributes, unsigned int mask); -/* +/*%< * Set the bits described by "mask" to the corresponding values in * "attributes". * * That is: * + * \code * new = (old & ~mask) | (attributes & mask) + * \endcode * - * This function has a side effect when DNS_DISPATCHATTR_NOLISTEN changes. + * This function has a side effect when #DNS_DISPATCHATTR_NOLISTEN changes. * When the flag becomes off, the dispatch will start receiving on the * corresponding socket. When the flag becomes on, receive events on the * corresponding socket will be canceled. * * Requires: - * disp is valid. + *\li disp is valid. * - * attributes are reasonable for the dispatch. That is, setting the UDP + *\li attributes are reasonable for the dispatch. That is, setting the UDP * attribute on a TCP socket isn't reasonable. */ void dns_dispatch_importrecv(dns_dispatch_t *disp, isc_event_t *event); -/* +/*%< * Inform the dispatcher of a socket receive. This is used for sockets * shared between dispatchers and clients. If the dispatcher fails to copy * or send the event, nothing happens. * * Requires: - * disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set. + *\li disp is valid, and the attribute DNS_DISPATCHATTR_NOLISTEN is set. * event != NULL */ diff --git a/lib/dns/include/dns/dnssec.h b/lib/dns/include/dns/dnssec.h index 4bfd2c844f..c490de7d3f 100644 --- a/lib/dns/include/dns/dnssec.h +++ b/lib/dns/include/dns/dnssec.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dnssec.h,v 1.26 2004/03/05 05:09:42 marka Exp $ */ +/* $Id: dnssec.h,v 1.27 2005/04/27 04:56:55 sra Exp $ */ #ifndef DNS_DNSSEC_H #define DNS_DNSSEC_H 1 +/*! \file */ + #include #include @@ -32,51 +34,51 @@ ISC_LANG_BEGINDECLS isc_result_t dns_dnssec_keyfromrdata(dns_name_t *name, dns_rdata_t *rdata, isc_mem_t *mctx, dst_key_t **key); -/* +/*%< * Creates a DST key from a DNS record. Basically a wrapper around * dst_key_fromdns(). * * Requires: - * 'name' is not NULL - * 'rdata' is not NULL - * 'mctx' is not NULL - * 'key' is not NULL - * '*key' is NULL + *\li 'name' is not NULL + *\li 'rdata' is not NULL + *\li 'mctx' is not NULL + *\li 'key' is not NULL + *\li '*key' is NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * DST_R_INVALIDPUBLICKEY - * various errors from dns_name_totext + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li DST_R_INVALIDPUBLICKEY + *\li various errors from dns_name_totext */ isc_result_t dns_dnssec_sign(dns_name_t *name, dns_rdataset_t *set, dst_key_t *key, isc_stdtime_t *inception, isc_stdtime_t *expire, isc_mem_t *mctx, isc_buffer_t *buffer, dns_rdata_t *sigrdata); -/* +/*%< * Generates a SIG record covering this rdataset. This has no effect * on existing SIG records. * * Requires: - * 'name' (the owner name of the record) is a valid name - * 'set' is a valid rdataset - * 'key' is a valid key - * 'inception' is not NULL - * 'expire' is not NULL - * 'mctx' is not NULL - * 'buffer' is not NULL - * 'sigrdata' is not NULL + *\li 'name' (the owner name of the record) is a valid name + *\li 'set' is a valid rdataset + *\li 'key' is a valid key + *\li 'inception' is not NULL + *\li 'expire' is not NULL + *\li 'mctx' is not NULL + *\li 'buffer' is not NULL + *\li 'sigrdata' is not NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_NOSPACE - * DNS_R_INVALIDTIME - the expiration is before the inception - * DNS_R_KEYUNAUTHORIZED - the key cannot sign this data (either + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_NOSPACE + *\li #DNS_R_INVALIDTIME - the expiration is before the inception + *\li #DNS_R_KEYUNAUTHORIZED - the key cannot sign this data (either * it is not a zone key or its flags prevent * authentication) - * DST_R_* + *\li DST_R_* */ isc_result_t @@ -88,35 +90,36 @@ isc_result_t dns_dnssec_verify2(dns_name_t *name, dns_rdataset_t *set, dst_key_t *key, isc_boolean_t ignoretime, isc_mem_t *mctx, dns_rdata_t *sigrdata, dns_name_t *wild); -/* +/*%< * Verifies the SIG record covering this rdataset signed by a specific * key. This does not determine if the key's owner is authorized to * sign this record, as this requires a resolver or database. * If 'ignoretime' is ISC_TRUE, temporal validity will not be checked. * * Requires: - * 'name' (the owner name of the record) is a valid name - * 'set' is a valid rdataset - * 'key' is a valid key - * 'mctx' is not NULL - * 'sigrdata' is a valid rdata containing a SIG record - * 'wild' if non-NULL then is a valid and has a buffer. + *\li 'name' (the owner name of the record) is a valid name + *\li 'set' is a valid rdataset + *\li 'key' is a valid key + *\li 'mctx' is not NULL + *\li 'sigrdata' is a valid rdata containing a SIG record + *\li 'wild' if non-NULL then is a valid and has a buffer. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * DNS_R_FROMWILDCARD - the signature is valid and is from + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #DNS_R_FROMWILDCARD - the signature is valid and is from * a wildcard expansion. dns_dnssec_verify2() only. * 'wild' contains the name of the wildcard if non-NULL. - * DNS_R_SIGINVALID - the signature fails to verify - * DNS_R_SIGEXPIRED - the signature has expired - * DNS_R_SIGFUTURE - the signature's validity period has not begun - * DNS_R_KEYUNAUTHORIZED - the key cannot sign this data (either + *\li #DNS_R_SIGINVALID - the signature fails to verify + *\li #DNS_R_SIGEXPIRED - the signature has expired + *\li #DNS_R_SIGFUTURE - the signature's validity period has not begun + *\li #DNS_R_KEYUNAUTHORIZED - the key cannot sign this data (either * it is not a zone key or its flags prevent * authentication) - * DST_R_* + *\li DST_R_* */ +/*@{*/ isc_result_t dns_dnssec_findzonekeys(dns_db_t *db, dns_dbversion_t *ver, dns_dbnode_t *node, dns_name_t *name, isc_mem_t *mctx, @@ -128,50 +131,51 @@ dns_dnssec_findzonekeys2(dns_db_t *db, dns_dbversion_t *ver, const char *directory, isc_mem_t *mctx, unsigned int maxkeys, dst_key_t **keys, unsigned int *nkeys); -/* +/*%< * Finds a set of zone keys. * XXX temporary - this should be handled in dns_zone_t. */ +/*@}*/ isc_result_t dns_dnssec_signmessage(dns_message_t *msg, dst_key_t *key); -/* +/*%< * Signs a message with a SIG(0) record. This is implicitly called by * dns_message_renderend() if msg->sig0key is not NULL. * * Requires: - * 'msg' is a valid message - * 'key' is a valid key that can be used for signing + *\li 'msg' is a valid message + *\li 'key' is a valid key that can be used for signing * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * DST_R_* + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li DST_R_* */ isc_result_t dns_dnssec_verifymessage(isc_buffer_t *source, dns_message_t *msg, dst_key_t *key); -/* +/*%< * Verifies a message signed by a SIG(0) record. This is not * called implicitly by dns_message_parse(). If dns_message_signer() * is called before dns_dnssec_verifymessage(), it will return - * DNS_R_NOTVERIFIEDYET. dns_dnssec_verifymessage() will set + * #DNS_R_NOTVERIFIEDYET. dns_dnssec_verifymessage() will set * the verified_sig0 flag in msg if the verify succeeds, and * the sig0status field otherwise. * * Requires: - * 'source' is a valid buffer containing the unparsed message - * 'msg' is a valid message - * 'key' is a valid key + *\li 'source' is a valid buffer containing the unparsed message + *\li 'msg' is a valid message + *\li 'key' is a valid key * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_NOTFOUND - no SIG(0) was found - * DNS_R_SIGINVALID - the SIG record is not well-formed or + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_NOTFOUND - no SIG(0) was found + *\li #DNS_R_SIGINVALID - the SIG record is not well-formed or * was not generated by the key. - * DST_R_* + *\li DST_R_* */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/ds.h b/lib/dns/include/dns/ds.h index 54a4c2f948..809c5cf6e4 100644 --- a/lib/dns/include/dns/ds.h +++ b/lib/dns/include/dns/ds.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ds.h,v 1.5 2005/03/06 15:30:37 marka Exp $ */ +/* $Id: ds.h,v 1.6 2005/04/27 04:56:55 sra Exp $ */ #ifndef DNS_DS_H #define DNS_DS_H 1 @@ -37,17 +37,17 @@ isc_result_t dns_ds_buildrdata(dns_name_t *owner, dns_rdata_t *key, unsigned int digest_type, unsigned char *buffer, dns_rdata_t *rdata); -/* +/*%< * Build the rdata of a DS record. * * Requires: - * key Points to a valid DNS KEY record. - * buffer Points to a temporary buffer of at least - * DNS_DS_BUFFERSIZE bytes. - * rdata Points to an initialized dns_rdata_t. + *\li key Points to a valid DNS KEY record. + *\li buffer Points to a temporary buffer of at least + * #DNS_DS_BUFFERSIZE bytes. + *\li rdata Points to an initialized dns_rdata_t. * * Ensures: - * *rdata Contains a valid DS rdata. The 'data' member refers + * \li *rdata Contains a valid DS rdata. The 'data' member refers * to 'buffer'. */ diff --git a/lib/dns/include/dns/events.h b/lib/dns/include/dns/events.h index 9f8ffd13cc..bdf9cd4438 100644 --- a/lib/dns/include/dns/events.h +++ b/lib/dns/include/dns/events.h @@ -15,14 +15,15 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: events.h,v 1.43 2004/12/21 10:45:19 jinmei Exp $ */ +/* $Id: events.h,v 1.44 2005/04/27 04:56:55 sra Exp $ */ #ifndef DNS_EVENTS_H #define DNS_EVENTS_H 1 #include -/* +/*! \file + * \brief * Registry of DNS event numbers. */ diff --git a/lib/dns/include/dns/fixedname.h b/lib/dns/include/dns/fixedname.h index 83f7825e02..d0accbc2d5 100644 --- a/lib/dns/include/dns/fixedname.h +++ b/lib/dns/include/dns/fixedname.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: fixedname.h,v 1.13 2004/03/05 05:09:42 marka Exp $ */ +/* $Id: fixedname.h,v 1.14 2005/04/27 04:56:55 sra Exp $ */ #ifndef DNS_FIXEDNAME_H #define DNS_FIXEDNAME_H 1 @@ -24,28 +24,31 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * Fixed-size Names * * dns_fixedname_t is a convenience type containing a name, an offsets table, * and a dedicated buffer big enough for the longest possible name. * * MP: - * The caller must ensure any required synchronization. + *\li The caller must ensure any required synchronization. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * Per dns_fixedname_t: + *\li Per dns_fixedname_t: + *\code * sizeof(dns_name_t) + sizeof(dns_offsets_t) + * sizeof(isc_buffer_t) + 255 bytes + structure padding + *\endcode * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * None. + *\li None. */ /***** diff --git a/lib/dns/include/dns/forward.h b/lib/dns/include/dns/forward.h index 13724ba3ad..bdbffe4452 100644 --- a/lib/dns/include/dns/forward.h +++ b/lib/dns/include/dns/forward.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: forward.h,v 1.5 2005/03/17 03:56:12 marka Exp $ */ +/* $Id: forward.h,v 1.6 2005/04/27 04:56:55 sra Exp $ */ #ifndef DNS_FORWARD_H #define DNS_FORWARD_H 1 +/*! \file */ + #include #include @@ -34,68 +36,81 @@ struct dns_forwarders { isc_result_t dns_fwdtable_create(isc_mem_t *mctx, dns_fwdtable_t **fwdtablep); -/* +/*%< * Creates a new forwarding table. * * Requires: - * mctx is a valid memory context. - * fwdtablep != NULL && *fwdtablep == NULL + * \li mctx is a valid memory context. + * \li fwdtablep != NULL && *fwdtablep == NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ isc_result_t dns_fwdtable_add(dns_fwdtable_t *fwdtable, dns_name_t *name, isc_sockaddrlist_t *addrs, dns_fwdpolicy_t policy); -/* +/*%< * Adds an entry to the forwarding table. The entry associates * a domain with a list of forwarders and a forwarding policy. The * addrs list is copied if not empty, so the caller should free its copy. * * Requires: - * fwdtable is a valid forwarding table. - * name is a valid name - * addrs is a valid list of sockaddrs, which may be empty. + * \li fwdtable is a valid forwarding table. + * \li name is a valid name + * \li addrs is a valid list of sockaddrs, which may be empty. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + * \li #ISC_R_SUCCESS + * \li #ISC_R_NOMEMORY */ isc_result_t dns_fwdtable_find(dns_fwdtable_t *fwdtable, dns_name_t *name, dns_forwarders_t **forwardersp); - -isc_result_t -dns_fwdtable_find2(dns_fwdtable_t *fwdtable, dns_name_t *name, - dns_name_t *foundname, dns_forwarders_t **forwardersp); -/* +/*%< * Finds a domain in the forwarding table. The closest matching parent * domain is returned. * * Requires: - * fwdtable is a valid forwarding table. - * name is a valid name - * forwardersp != NULL && *forwardersp == NULL - * foundname to be NULL or a valid name with buffer. + * \li fwdtable is a valid forwarding table. + * \li name is a valid name + * \li forwardersp != NULL && *forwardersp == NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOTFOUND + * \li #ISC_R_SUCCESS + * \li #ISC_R_NOTFOUND + */ + +isc_result_t +dns_fwdtable_find2(dns_fwdtable_t *fwdtable, dns_name_t *name, + dns_name_t *foundname, dns_forwarders_t **forwardersp); +/*%< + * Finds a domain in the forwarding table. The closest matching parent + * domain is returned. + * + * Requires: + * \li fwdtable is a valid forwarding table. + * \li name is a valid name + * \li forwardersp != NULL && *forwardersp == NULL + * \li foundname to be NULL or a valid name with buffer. + * + * Returns: + * \li #ISC_R_SUCCESS + * \li #ISC_R_NOTFOUND */ void dns_fwdtable_destroy(dns_fwdtable_t **fwdtablep); -/* +/*%< * Destroys a forwarding table. * * Requires: - * fwtablep != NULL && *fwtablep != NULL + * \li fwtablep != NULL && *fwtablep != NULL * * Ensures: - * all memory associated with the forwarding table is freed. + * \li all memory associated with the forwarding table is freed. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/journal.h b/lib/dns/include/dns/journal.h index b4a6d21087..361cebe6ba 100644 --- a/lib/dns/include/dns/journal.h +++ b/lib/dns/include/dns/journal.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: journal.h,v 1.25 2004/03/05 05:09:42 marka Exp $ */ +/* $Id: journal.h,v 1.26 2005/04/27 04:56:55 sra Exp $ */ #ifndef DNS_JOURNAL_H #define DNS_JOURNAL_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * Database journalling. */ @@ -44,7 +45,7 @@ *** Types ***/ -/* +/*% * A dns_journal_t represents an open journal file. This is an opaque type. * * A particular dns_journal_t object may be opened for writing, in which case @@ -67,19 +68,21 @@ ISC_LANG_BEGINDECLS isc_result_t dns_db_createsoatuple(dns_db_t *db, dns_dbversion_t *ver, isc_mem_t *mctx, dns_diffop_t op, dns_difftuple_t **tp); -/* +/*!< brief * Create a diff tuple for the current database SOA. * XXX this probably belongs somewhere else. */ +/*@{*/ #define DNS_SERIAL_GT(a, b) ((int)(((a) - (b)) & 0xFFFFFFFF) > 0) #define DNS_SERIAL_GE(a, b) ((int)(((a) - (b)) & 0xFFFFFFFF) >= 0) -/* +/*!< brief * Compare SOA serial numbers. DNS_SERIAL_GT(a, b) returns true iff * a is "greater than" b where "greater than" is as defined in RFC1982. * DNS_SERIAL_GE(a, b) returns true iff a is "greater than or equal to" b. */ +/*@}*/ /**************************************************************************/ /* @@ -89,7 +92,7 @@ dns_db_createsoatuple(dns_db_t *db, dns_dbversion_t *ver, isc_mem_t *mctx, isc_result_t dns_journal_open(isc_mem_t *mctx, const char *filename, isc_boolean_t write, dns_journal_t **journalp); -/* +/*%< * Open the journal file 'filename' and create a dns_journal_t object for it. * * If 'write' is ISC_TRUE, the journal is open for writing. If it does @@ -101,7 +104,7 @@ dns_journal_open(isc_mem_t *mctx, const char *filename, isc_boolean_t write, void dns_journal_destroy(dns_journal_t **journalp); -/* +/*%< * Destroy a dns_journal_t, closing any open files and freeing its memory. */ @@ -112,52 +115,52 @@ dns_journal_destroy(dns_journal_t **journalp); isc_result_t dns_journal_begin_transaction(dns_journal_t *j); -/* +/*%< * Prepare to write a new transaction to the open journal file 'j'. * * Requires: - * 'j' is open for writing. + * \li 'j' is open for writing. */ isc_result_t dns_journal_writediff(dns_journal_t *j, dns_diff_t *diff); -/* +/*%< * Write 'diff' to the current transaction of journal file 'j'. * * Requires: - * 'j' is open for writing and dns_journal_begin_transaction() + * \li 'j' is open for writing and dns_journal_begin_transaction() * has been called. * - * 'diff' is a full or partial, correctly ordered IXFR + *\li 'diff' is a full or partial, correctly ordered IXFR * difference sequence. */ isc_result_t dns_journal_commit(dns_journal_t *j); -/* +/*%< * Commit the current transaction of journal file 'j'. * * Requires: - * 'j' is open for writing and dns_journal_begin_transaction() + * \li 'j' is open for writing and dns_journal_begin_transaction() * has been called. * - * dns_journal_writediff() has been called one or more times + * \li dns_journal_writediff() has been called one or more times * to form a complete, correctly ordered IXFR difference * sequence. */ isc_result_t dns_journal_write_transaction(dns_journal_t *j, dns_diff_t *diff); -/* +/*% * Write a complete transaction at once to a journal file, * sorting it if necessary, and commit it. Equivalent to calling * dns_diff_sort(), dns_journal_begin_transaction(), * dns_journal_writediff(), and dns_journal_commit(). * * Requires: - * 'j' is open for writing. + *\li 'j' is open for writing. * - * 'diff' contains exactly one SOA deletion, one SOA addition + * \li 'diff' contains exactly one SOA deletion, one SOA addition * with a greater serial number, and possibly other changes, * in arbitrary order. */ @@ -171,46 +174,48 @@ isc_uint32_t dns_journal_first_serial(dns_journal_t *j); isc_uint32_t dns_journal_last_serial(dns_journal_t *j); -/* +/*%< * Get the first and last addressable serial number in the journal. */ isc_result_t dns_journal_iter_init(dns_journal_t *j, isc_uint32_t begin_serial, isc_uint32_t end_serial); -/* +/*%< * Prepare to iterate over the transactions that will bring the database * from SOA serial number 'begin_serial' to 'end_serial'. * * Returns: - * ISC_R_SUCCESS - * ISC_R_RANGE begin_serial is outside the addressable range. - * ISC_R_NOTFOUND begin_serial is within the range of adressable + *\li ISC_R_SUCCESS + *\li ISC_R_RANGE begin_serial is outside the addressable range. + *\li ISC_R_NOTFOUND begin_serial is within the range of adressable * serial numbers covered by the journal, but * this particular serial number does not exist. */ +/*@{*/ isc_result_t dns_journal_first_rr(dns_journal_t *j); isc_result_t dns_journal_next_rr(dns_journal_t *j); -/* +/*%< * Position the iterator at the first/next RR in a journal * transaction sequence established using dns_journal_iter_init(). * * Requires: - * dns_journal_iter_init() has been called. + * \li dns_journal_iter_init() has been called. * */ +/*@}*/ void dns_journal_current_rr(dns_journal_t *j, dns_name_t **name, isc_uint32_t *ttl, dns_rdata_t **rdata); -/* +/*%< * Get the name, ttl, and rdata of the current journal RR. * * Requires: - * The last call to dns_journal_first_rr() or dns_journal_next_rr() + * \li The last call to dns_journal_first_rr() or dns_journal_next_rr() * returned ISC_R_SUCCESS. */ @@ -221,22 +226,22 @@ dns_journal_current_rr(dns_journal_t *j, dns_name_t **name, isc_uint32_t *ttl, isc_result_t dns_journal_rollforward(isc_mem_t *mctx, dns_db_t *db, const char *filename); -/* +/*%< * Roll forward (play back) the journal file "filename" into the * database "db". This should be called when the server starts * after a shutdown or crash. * * Requires: - * 'mctx' is a valid memory context. - * 'db' is a valid database which does not have a version + *\li 'mctx' is a valid memory context. + *\li 'db' is a valid database which does not have a version * open for writing. - * 'filename' is the name of the journal file belonging to 'db'. + * \li 'filename' is the name of the journal file belonging to 'db'. * * Returns: - * DNS_R_NOJOURNAL when journal does not exist. - * ISC_R_NOTFOUND when current serial in not in journal. - * ISC_R_RANGE when current serial in not in journals range. - * ISC_R_SUCCESS journal has been applied successfully to database. + *\li DNS_R_NOJOURNAL when journal does not exist. + *\li ISC_R_NOTFOUND when current serial in not in journal. + *\li ISC_R_RANGE when current serial in not in journals range. + *\li ISC_R_SUCCESS journal has been applied successfully to database. * others */ @@ -249,7 +254,7 @@ dns_db_diff(isc_mem_t *mctx, dns_db_t *dba, dns_dbversion_t *dbvera, dns_db_t *dbb, dns_dbversion_t *dbverb, const char *journal_filename); -/* +/*%< * Compare the databases 'dba' and 'dbb' and generate a journal * entry containing the changes to make 'dba' from 'dbb' (note * the order). This journal entry will consist of a single, @@ -260,7 +265,7 @@ dns_db_diff(isc_mem_t *mctx, isc_result_t dns_journal_compact(isc_mem_t *mctx, char *filename, isc_uint32_t serial, isc_uint32_t target_size); -/* +/*%< * Attempt to compact the journal if it is greater that 'target_size'. * Changes from 'serial' onwards will be preserved. If the journal * exists and is non-empty 'serial' must exist in the journal. diff --git a/lib/dns/include/dns/keyflags.h b/lib/dns/include/dns/keyflags.h index 372e43c9e2..b22271cc4b 100644 --- a/lib/dns/include/dns/keyflags.h +++ b/lib/dns/include/dns/keyflags.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: keyflags.h,v 1.10 2004/03/05 05:09:42 marka Exp $ */ +/* $Id: keyflags.h,v 1.11 2005/04/27 04:56:55 sra Exp $ */ #ifndef DNS_KEYFLAGS_H #define DNS_KEYFLAGS_H 1 +/*! \file */ + #include #include @@ -28,7 +30,7 @@ ISC_LANG_BEGINDECLS isc_result_t dns_keyflags_fromtext(dns_keyflags_t *flagsp, isc_textregion_t *source); -/* +/*%< * Convert the text 'source' refers to into a DNSSEC KEY flags value. * The text may contain either a set of flag mnemonics separated by * vertical bars or a decimal flags value. For compatibility with @@ -37,14 +39,14 @@ dns_keyflags_fromtext(dns_keyflags_t *flagsp, isc_textregion_t *source); * are also accepted. * * Requires: - * 'flagsp' is a valid pointer. + *\li 'flagsp' is a valid pointer. * - * 'source' is a valid text region. + *\li 'source' is a valid text region. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_RANGE numeric flag value is out of range - * DNS_R_UNKNOWN mnemonic flag is unknown + *\li ISC_R_SUCCESS on success + *\li ISC_R_RANGE numeric flag value is out of range + *\li DNS_R_UNKNOWN mnemonic flag is unknown */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/keytable.h b/lib/dns/include/dns/keytable.h index 63ab71d9e6..85f76b98be 100644 --- a/lib/dns/include/dns/keytable.h +++ b/lib/dns/include/dns/keytable.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: keytable.h,v 1.11 2004/03/05 05:09:43 marka Exp $ */ +/* $Id: keytable.h,v 1.12 2005/04/27 04:56:56 sra Exp $ */ #ifndef DNS_KEYTABLE_H #define DNS_KEYTABLE_H 1 @@ -24,22 +24,21 @@ ***** Module Info *****/ -/* - * Key Tables - * +/*! \file + * \brief * The keytable module provides services for storing and retrieving DNSSEC * trusted keys, as well as the ability to find the deepest matching key * for a given domain name. * * MP: - * The module ensures appropriate synchronization of data structures it + *\li The module ensures appropriate synchronization of data structures it * creates and manipulates. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. */ #include @@ -52,201 +51,200 @@ ISC_LANG_BEGINDECLS isc_result_t dns_keytable_create(isc_mem_t *mctx, dns_keytable_t **keytablep); -/* +/*%< * Create a keytable. * * Requires: * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. * - * keytablep != NULL && *keytablep == NULL + *\li keytablep != NULL && *keytablep == NULL * * Ensures: * - * On success, *keytablep is a valid, empty key table. + *\li On success, *keytablep is a valid, empty key table. * * Returns: * - * ISC_R_SUCCESS + *\li ISC_R_SUCCESS * - * Any other result indicates failure. + *\li Any other result indicates failure. */ void dns_keytable_attach(dns_keytable_t *source, dns_keytable_t **targetp); -/* +/*%< * Attach *targetp to source. * * Requires: * - * 'source' is a valid keytable. + *\li 'source' is a valid keytable. * - * 'targetp' points to a NULL dns_keytable_t *. + *\li 'targetp' points to a NULL dns_keytable_t *. * * Ensures: * - * *targetp is attached to source. + *\li *targetp is attached to source. */ void dns_keytable_detach(dns_keytable_t **keytablep); -/* +/*%< * Detach *keytablep from its keytable. * * Requires: * - * 'keytablep' points to a valid keytable. + *\li 'keytablep' points to a valid keytable. * * Ensures: * - * *keytablep is NULL. + *\li *keytablep is NULL. * - * If '*keytablep' is the last reference to the keytable, - * - * All resources used by the keytable will be freed + *\li If '*keytablep' is the last reference to the keytable, + * all resources used by the keytable will be freed */ isc_result_t dns_keytable_add(dns_keytable_t *keytable, dst_key_t **keyp); -/* +/*%< * Add '*keyp' to 'keytable'. * * Notes: * - * Ownership of *keyp is transferred to the keytable. + *\li Ownership of *keyp is transferred to the keytable. * * Requires: * - * keyp != NULL && *keyp is a valid dst_key_t *. + *\li keyp != NULL && *keyp is a valid dst_key_t *. * * Ensures: * - * On success, *keyp == NULL + *\li On success, *keyp == NULL * * Returns: * - * ISC_R_SUCCESS + *\li ISC_R_SUCCESS * - * Any other result indicates failure. + *\li Any other result indicates failure. */ isc_result_t dns_keytable_findkeynode(dns_keytable_t *keytable, dns_name_t *name, dns_secalg_t algorithm, dns_keytag_t tag, dns_keynode_t **keynodep); -/* +/*%< * Search for a key named 'name', matching 'algorithm' and 'tag' in * 'keytable'. * * Requires: * - * 'keytable' is a valid keytable. + *\li 'keytable' is a valid keytable. * - * 'name' is a valid absolute name. + *\li 'name' is a valid absolute name. * - * keynodep != NULL && *keynodep == NULL + *\li keynodep != NULL && *keynodep == NULL * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOTFOUND + *\li ISC_R_SUCCESS + *\li ISC_R_NOTFOUND * - * Any other result indicates an error. + *\li Any other result indicates an error. */ isc_result_t dns_keytable_findnextkeynode(dns_keytable_t *keytable, dns_keynode_t *keynode, dns_keynode_t **nextnodep); -/* +/*%< * Search for the next key with the same properties as 'keynode' in * 'keytable'. * * Requires: * - * 'keytable' is a valid keytable. + *\li 'keytable' is a valid keytable. * - * 'keynode' is a valid keynode. + *\li 'keynode' is a valid keynode. * - * nextnodep != NULL && *nextnodep == NULL + *\li nextnodep != NULL && *nextnodep == NULL * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOTFOUND + *\li ISC_R_SUCCESS + *\li ISC_R_NOTFOUND * - * Any other result indicates an error. + *\li Any other result indicates an error. */ isc_result_t dns_keytable_finddeepestmatch(dns_keytable_t *keytable, dns_name_t *name, dns_name_t *foundname); -/* +/*%< * Search for the deepest match of 'name' in 'keytable'. * * Requires: * - * 'keytable' is a valid keytable. + *\li 'keytable' is a valid keytable. * - * 'name' is a valid absolute name. + *\li 'name' is a valid absolute name. * - * 'foundname' is a name with a dedicated buffer. + *\li 'foundname' is a name with a dedicated buffer. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOTFOUND + *\li ISC_R_SUCCESS + *\li ISC_R_NOTFOUND * - * Any other result indicates an error. + *\li Any other result indicates an error. */ void dns_keytable_detachkeynode(dns_keytable_t *keytable, dns_keynode_t **keynodep); -/* +/*%< * Give back a keynode found via dns_keytable_findkeynode(). * * Requires: * - * 'keytable' is a valid keytable. + *\li 'keytable' is a valid keytable. * - * *keynodep is a valid keynode returned by a call to + *\li *keynodep is a valid keynode returned by a call to * dns_keytable_findkeynode(). * * Ensures: * - * *keynodep == NULL + *\li *keynodep == NULL */ isc_result_t dns_keytable_issecuredomain(dns_keytable_t *keytable, dns_name_t *name, isc_boolean_t *wantdnssecp); -/* +/*%< * Is 'name' at or beneath a trusted key? * * Requires: * - * 'keytable' is a valid keytable. + *\li 'keytable' is a valid keytable. * - * 'name' is a valid absolute name. + *\li 'name' is a valid absolute name. * - * '*wantsdnssecp' is a valid isc_boolean_t. + *\li '*wantsdnssecp' is a valid isc_boolean_t. * * Ensures: * - * On success, *wantsdnssecp will be ISC_TRUE if and only if 'name' + *\li On success, *wantsdnssecp will be ISC_TRUE if and only if 'name' * is at or beneath a trusted key. * * Returns: * - * ISC_R_SUCCESS + *\li ISC_R_SUCCESS * - * Any other result is an error. + *\li Any other result is an error. */ dst_key_t * dns_keynode_key(dns_keynode_t *keynode); -/* +/*%< * Get the DST key associated with keynode. */ diff --git a/lib/dns/include/dns/keyvalues.h b/lib/dns/include/dns/keyvalues.h index 6e94459901..fd9e51ff2d 100644 --- a/lib/dns/include/dns/keyvalues.h +++ b/lib/dns/include/dns/keyvalues.h @@ -15,36 +15,38 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: keyvalues.h,v 1.15 2004/03/05 05:09:43 marka Exp $ */ +/* $Id: keyvalues.h,v 1.16 2005/04/27 04:56:56 sra Exp $ */ #ifndef DNS_KEYVALUES_H #define DNS_KEYVALUES_H 1 +/*! \file */ + /* * Flags field of the KEY RR rdata */ -#define DNS_KEYFLAG_TYPEMASK 0xC000 /* Mask for "type" bits */ -#define DNS_KEYTYPE_AUTHCONF 0x0000 /* Key usable for both */ -#define DNS_KEYTYPE_CONFONLY 0x8000 /* Key usable for confidentiality */ -#define DNS_KEYTYPE_AUTHONLY 0x4000 /* Key usable for authentication */ -#define DNS_KEYTYPE_NOKEY 0xC000 /* No key usable for either; no key */ +#define DNS_KEYFLAG_TYPEMASK 0xC000 /*%< Mask for "type" bits */ +#define DNS_KEYTYPE_AUTHCONF 0x0000 /*%< Key usable for both */ +#define DNS_KEYTYPE_CONFONLY 0x8000 /*%< Key usable for confidentiality */ +#define DNS_KEYTYPE_AUTHONLY 0x4000 /*%< Key usable for authentication */ +#define DNS_KEYTYPE_NOKEY 0xC000 /*%< No key usable for either; no key */ #define DNS_KEYTYPE_NOAUTH DNS_KEYTYPE_CONFONLY #define DNS_KEYTYPE_NOCONF DNS_KEYTYPE_AUTHONLY -#define DNS_KEYFLAG_RESERVED2 0x2000 /* reserved - must be zero */ -#define DNS_KEYFLAG_EXTENDED 0x1000 /* key has extended flags */ -#define DNS_KEYFLAG_RESERVED4 0x0800 /* reserved - must be zero */ -#define DNS_KEYFLAG_RESERVED5 0x0400 /* reserved - must be zero */ -#define DNS_KEYFLAG_OWNERMASK 0x0300 /* these bits determine the type */ -#define DNS_KEYOWNER_USER 0x0000 /* key is assoc. with user */ -#define DNS_KEYOWNER_ENTITY 0x0200 /* key is assoc. with entity eg host */ -#define DNS_KEYOWNER_ZONE 0x0100 /* key is zone key */ -#define DNS_KEYOWNER_RESERVED 0x0300 /* reserved meaning */ -#define DNS_KEYFLAG_RESERVED8 0x0080 /* reserved - must be zero */ -#define DNS_KEYFLAG_RESERVED9 0x0040 /* reserved - must be zero */ -#define DNS_KEYFLAG_RESERVED10 0x0020 /* reserved - must be zero */ -#define DNS_KEYFLAG_RESERVED11 0x0010 /* reserved - must be zero */ -#define DNS_KEYFLAG_SIGNATORYMASK 0x000F /* key can sign RR's of same name */ +#define DNS_KEYFLAG_RESERVED2 0x2000 /*%< reserved - must be zero */ +#define DNS_KEYFLAG_EXTENDED 0x1000 /*%< key has extended flags */ +#define DNS_KEYFLAG_RESERVED4 0x0800 /*%< reserved - must be zero */ +#define DNS_KEYFLAG_RESERVED5 0x0400 /*%< reserved - must be zero */ +#define DNS_KEYFLAG_OWNERMASK 0x0300 /*%< these bits determine the type */ +#define DNS_KEYOWNER_USER 0x0000 /*%< key is assoc. with user */ +#define DNS_KEYOWNER_ENTITY 0x0200 /*%< key is assoc. with entity eg host */ +#define DNS_KEYOWNER_ZONE 0x0100 /*%< key is zone key */ +#define DNS_KEYOWNER_RESERVED 0x0300 /*%< reserved meaning */ +#define DNS_KEYFLAG_RESERVED8 0x0080 /*%< reserved - must be zero */ +#define DNS_KEYFLAG_RESERVED9 0x0040 /*%< reserved - must be zero */ +#define DNS_KEYFLAG_RESERVED10 0x0020 /*%< reserved - must be zero */ +#define DNS_KEYFLAG_RESERVED11 0x0010 /*%< reserved - must be zero */ +#define DNS_KEYFLAG_SIGNATORYMASK 0x000F /*%< key can sign RR's of same name */ #define DNS_KEYFLAG_RESERVEDMASK (DNS_KEYFLAG_RESERVED2 | \ DNS_KEYFLAG_RESERVED4 | \ @@ -53,21 +55,21 @@ DNS_KEYFLAG_RESERVED9 | \ DNS_KEYFLAG_RESERVED10 | \ DNS_KEYFLAG_RESERVED11 ) -#define DNS_KEYFLAG_KSK 0x0001 /* key signing key */ +#define DNS_KEYFLAG_KSK 0x0001 /*%< key signing key */ -#define DNS_KEYFLAG_RESERVEDMASK2 0xFFFF /* no bits defined here */ +#define DNS_KEYFLAG_RESERVEDMASK2 0xFFFF /*%< no bits defined here */ /* The Algorithm field of the KEY and SIG RR's is an integer, {1..254} */ -#define DNS_KEYALG_RSAMD5 1 /* RSA with MD5 */ +#define DNS_KEYALG_RSAMD5 1 /*%< RSA with MD5 */ #define DNS_KEYALG_RSA DNS_KEYALG_RSAMD5 -#define DNS_KEYALG_DH 2 /* Diffie Hellman KEY */ -#define DNS_KEYALG_DSA 3 /* DSA KEY */ +#define DNS_KEYALG_DH 2 /*%< Diffie Hellman KEY */ +#define DNS_KEYALG_DSA 3 /*%< DSA KEY */ #define DNS_KEYALG_DSS NS_ALG_DSA #define DNS_KEYALG_ECC 4 #define DNS_KEYALG_RSASHA1 5 #define DNS_KEYALG_INDIRECT 252 #define DNS_KEYALG_PRIVATEDNS 253 -#define DNS_KEYALG_PRIVATEOID 254 /* Key begins with OID giving alg */ +#define DNS_KEYALG_PRIVATEOID 254 /*%< Key begins with OID giving alg */ /* Protocol values */ #define DNS_KEYPROTO_RESERVED 0 @@ -78,11 +80,11 @@ #define DNS_KEYPROTO_ANY 255 /* Signatures */ -#define DNS_SIG_RSAMINBITS 512 /* Size of a mod or exp in bits */ +#define DNS_SIG_RSAMINBITS 512 /*%< Size of a mod or exp in bits */ #define DNS_SIG_RSAMAXBITS 2552 /* Total of binary mod and exp */ #define DNS_SIG_RSAMAXBYTES ((DNS_SIG_RSAMAXBITS+7/8)*2+3) - /* Max length of text sig block */ + /*%< Max length of text sig block */ #define DNS_SIG_RSAMAXBASE64 (((DNS_SIG_RSAMAXBYTES+2)/3)*4) #define DNS_SIG_RSAMINSIZE ((DNS_SIG_RSAMINBITS+7)/8) #define DNS_SIG_RSAMAXSIZE ((DNS_SIG_RSAMAXBITS+7)/8) diff --git a/lib/dns/include/dns/lib.h b/lib/dns/include/dns/lib.h index 131090c6ab..696503dc17 100644 --- a/lib/dns/include/dns/lib.h +++ b/lib/dns/include/dns/lib.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lib.h,v 1.8 2004/03/05 05:09:43 marka Exp $ */ +/* $Id: lib.h,v 1.9 2005/04/27 04:56:56 sra Exp $ */ #ifndef DNS_LIB_H #define DNS_LIB_H 1 +/*! \file */ + #include #include @@ -29,7 +31,7 @@ LIBDNS_EXTERNAL_DATA extern isc_msgcat_t *dns_msgcat; void dns_lib_initmsgcat(void); -/* +/*%< * Initialize the DNS library's message catalog, dns_msgcat, if it * has not already been initialized. */ diff --git a/lib/dns/include/dns/log.h b/lib/dns/include/dns/log.h index 514d31aa1e..c7984d2053 100644 --- a/lib/dns/include/dns/log.h +++ b/lib/dns/include/dns/log.h @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: log.h,v 1.34 2004/12/21 10:45:19 jinmei Exp $ */ +/* $Id: log.h,v 1.35 2005/04/27 04:56:56 sra Exp $ */ -/* Principal Authors: DCL */ +/*! \file + * \author Principal Authors: DCL */ #ifndef DNS_LOG_H #define DNS_LOG_H 1 @@ -75,28 +76,28 @@ ISC_LANG_BEGINDECLS void dns_log_init(isc_log_t *lctx); -/* +/*% * Make the libdns categories and modules available for use with the * ISC logging library. * * Requires: - * lctx is a valid logging context. + *\li lctx is a valid logging context. * - * dns_log_init() is called only once. + *\li dns_log_init() is called only once. * * Ensures: - * The catgories and modules defined above are available for + * \li The catgories and modules defined above are available for * use by isc_log_usechannnel() and isc_log_write(). */ void dns_log_setcontext(isc_log_t *lctx); -/* +/*% * Make the libdns library use the provided context for logging internal * messages. * * Requires: - * lctx is a valid logging context. + *\li lctx is a valid logging context. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/lookup.h b/lib/dns/include/dns/lookup.h index ca6dfbce40..0e692fee66 100644 --- a/lib/dns/include/dns/lookup.h +++ b/lib/dns/include/dns/lookup.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lookup.h,v 1.6 2004/03/05 05:09:43 marka Exp $ */ +/* $Id: lookup.h,v 1.7 2005/04/27 04:56:56 sra Exp $ */ #ifndef DNS_LOOKUP_H #define DNS_LOOKUP_H 1 @@ -24,29 +24,28 @@ ***** Module Info *****/ -/* - * DNS Lookup - * +/*! \file + * \brief * The lookup module performs simple DNS lookups. It implements * the full resolver algorithm, both looking for local data and * resoving external names as necessary. * * MP: - * The module ensures appropriate synchronization of data structures it + *\li The module ensures appropriate synchronization of data structures it * creates and manipulates. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * RFCs: 1034, 1035, 2181, - * Drafts: + *\li RFCs: 1034, 1035, 2181, TBS + *\li Drafts: TBS */ #include @@ -56,7 +55,7 @@ ISC_LANG_BEGINDECLS -/* +/*% * A 'dns_lookupevent_t' is returned when a lookup completes. * The sender field will be set to the lookup that completed. If 'result' * is ISC_R_SUCCESS, then 'names' will contain a list of names associated @@ -77,60 +76,60 @@ isc_result_t dns_lookup_create(isc_mem_t *mctx, dns_name_t *name, dns_rdatatype_t type, dns_view_t *view, unsigned int options, isc_task_t *task, isc_taskaction_t action, void *arg, dns_lookup_t **lookupp); -/* +/*%< * Finds the rrsets matching 'name' and 'type'. * * Requires: * - * 'mctx' is a valid mctx. + *\li 'mctx' is a valid mctx. * - * 'name' is a valid name. + *\li 'name' is a valid name. * - * 'view' is a valid view which has a resolver. + *\li 'view' is a valid view which has a resolver. * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * lookupp != NULL && *lookupp == NULL + *\li lookupp != NULL && *lookupp == NULL * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li ISC_R_SUCCESS + *\li ISC_R_NOMEMORY * - * Any resolver-related error (e.g. ISC_R_SHUTTINGDOWN) may also be + *\li Any resolver-related error (e.g. ISC_R_SHUTTINGDOWN) may also be * returned. */ void dns_lookup_cancel(dns_lookup_t *lookup); -/* +/*%< * Cancel 'lookup'. * * Notes: * - * If 'lookup' has not completed, post its LOOKUPDONE event with a + *\li If 'lookup' has not completed, post its LOOKUPDONE event with a * result code of ISC_R_CANCELED. * * Requires: * - * 'lookup' is a valid lookup. + *\li 'lookup' is a valid lookup. */ void dns_lookup_destroy(dns_lookup_t **lookupp); -/* +/*%< * Destroy 'lookup'. * * Requires: * - * '*lookupp' is a valid lookup. + *\li '*lookupp' is a valid lookup. * - * The caller has received the LOOKUPDONE event (either because the + *\li The caller has received the LOOKUPDONE event (either because the * lookup completed or because dns_lookup_cancel() was called). * * Ensures: * - * *lookupp == NULL. + *\li *lookupp == NULL. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/master.h b/lib/dns/include/dns/master.h index a60aa947aa..2ce21ed756 100644 --- a/lib/dns/include/dns/master.h +++ b/lib/dns/include/dns/master.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: master.h,v 1.41 2005/02/17 05:49:01 marka Exp $ */ +/* $Id: master.h,v 1.42 2005/04/27 04:56:56 sra Exp $ */ #ifndef DNS_MASTER_H #define DNS_MASTER_H 1 +/*! \file */ + /*** *** Imports ***/ @@ -33,16 +35,20 @@ /* * Flags to be passed in the 'options' argument in the functions below. */ -#define DNS_MASTER_AGETTL 0x00000001 /* Age the ttl based on $DATE. */ -#define DNS_MASTER_MANYERRORS 0x00000002 /* Continue processing on errors. */ -#define DNS_MASTER_NOINCLUDE 0x00000004 /* Disallow $INCLUDE directives. */ -#define DNS_MASTER_ZONE 0x00000008 /* Loading a zone master file. */ -#define DNS_MASTER_HINT 0x00000010 /* Loading a hint master file. */ -#define DNS_MASTER_SLAVE 0x00000020 /* Loading a slave master file. */ -#define DNS_MASTER_CHECKNS 0x00000040 /* Check NS records to see if - * they are an address */ -#define DNS_MASTER_FATALNS 0x00000080 /* Treat DNS_MASTER_CHECKNS - * matches as fatal */ +#define DNS_MASTER_AGETTL 0x00000001 /*%< Age the ttl based on $DATE. */ +#define DNS_MASTER_MANYERRORS 0x00000002 /*%< Continue processing on errors. */ +#define DNS_MASTER_NOINCLUDE 0x00000004 /*%< Disallow $INCLUDE directives. */ +#define DNS_MASTER_ZONE 0x00000008 /*%< Loading a zone master file. */ +#define DNS_MASTER_HINT 0x00000010 /*%< Loading a hint master file. */ +#define DNS_MASTER_SLAVE 0x00000020 /*%< Loading a slave master file. */ +#define DNS_MASTER_CHECKNS 0x00000040 /*%< + * Check NS records to see + * if they are an address + */ +#define DNS_MASTER_FATALNS 0x00000080 /*%< + * Treat DNS_MASTER_CHECKNS + * matches as fatal + */ #define DNS_MASTER_CHECKNAMES 0x00000100 #define DNS_MASTER_CHECKNAMESFAIL 0x00000200 #define DNS_MASTER_CHECKWILDCARD 0x00000400 /* Check for internal wildcards. */ @@ -133,8 +139,8 @@ dns_master_loadlexerinc(isc_lex_t *lex, dns_loaddonefunc_t done, void *done_arg, dns_loadctx_t **ctxp, isc_mem_t *mctx); -/* - * Loads a RFC 1305 master file from a file, stream, buffer, or existing +/*%< + * Loads a RFC1305 master file from a file, stream, buffer, or existing * lexer into rdatasets and then calls 'callbacks->commit' to commit the * rdatasets. Rdata memory belongs to dns_master_load and will be * reused / released when the callback completes. dns_load_master will @@ -151,63 +157,63 @@ dns_master_loadlexerinc(isc_lex_t *lex, * not called. * * Requires: - * 'master_file' points to a valid string. - * 'lexer' points to a valid lexer. - * 'top' points to a valid name. - * 'origin' points to a valid name. - * 'callbacks->commit' points to a valid function. - * 'callbacks->error' points to a valid function. - * 'callbacks->warn' points to a valid function. - * 'mctx' points to a valid memory context. - * 'task' and 'done' to be valid. - * 'lmgr' to be valid. - * 'ctxp != NULL && ctxp == NULL'. + *\li 'master_file' points to a valid string. + *\li 'lexer' points to a valid lexer. + *\li 'top' points to a valid name. + *\li 'origin' points to a valid name. + *\li 'callbacks->commit' points to a valid function. + *\li 'callbacks->error' points to a valid function. + *\li 'callbacks->warn' points to a valid function. + *\li 'mctx' points to a valid memory context. + *\li 'task' and 'done' to be valid. + *\li 'lmgr' to be valid. + *\li 'ctxp != NULL && ctxp == NULL'. * * Returns: - * ISC_R_SUCCESS upon successfully loading the master file. - * ISC_R_SEENINCLUDE upon successfully loading the master file with + *\li ISC_R_SUCCESS upon successfully loading the master file. + *\li ISC_R_SEENINCLUDE upon successfully loading the master file with * a $INCLUDE statement. - * ISC_R_NOMEMORY out of memory. - * ISC_R_UNEXPECTEDEND expected to be able to read a input token and + *\li ISC_R_NOMEMORY out of memory. + *\li ISC_R_UNEXPECTEDEND expected to be able to read a input token and * there was not one. - * ISC_R_UNEXPECTED - * DNS_R_NOOWNER failed to specify a ownername. - * DNS_R_NOTTL failed to specify a ttl. - * DNS_R_BADCLASS record class did not match zone class. - * DNS_R_CONTINUE load still in progress (dns_master_load*inc() only). - * Any dns_rdata_fromtext() error code. - * Any error code from callbacks->commit(). + *\li ISC_R_UNEXPECTED + *\li DNS_R_NOOWNER failed to specify a ownername. + *\li DNS_R_NOTTL failed to specify a ttl. + *\li DNS_R_BADCLASS record class did not match zone class. + *\li DNS_R_CONTINUE load still in progress (dns_master_load*inc() only). + *\li Any dns_rdata_fromtext() error code. + *\li Any error code from callbacks->commit(). */ void dns_loadctx_detach(dns_loadctx_t **ctxp); -/* +/*%< * Detach from the load context. * * Requires: - * '*ctxp' to be valid. + *\li '*ctxp' to be valid. * * Ensures: - * '*ctxp == NULL' + *\li '*ctxp == NULL' */ void dns_loadctx_attach(dns_loadctx_t *source, dns_loadctx_t **target); -/* +/*%< * Attach to the load context. * * Requires: - * 'source' to be valid. - * 'target != NULL && *target == NULL'. + *\li 'source' to be valid. + *\li 'target != NULL && *target == NULL'. */ void dns_loadctx_cancel(dns_loadctx_t *ctx); -/* +/*%< * Cancel loading the zone file associated with this load context. * * Requires: - * 'ctx' to be valid + *\li 'ctx' to be valid */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/masterdump.h b/lib/dns/include/dns/masterdump.h index 07f6beb829..20e2f51c55 100644 --- a/lib/dns/include/dns/masterdump.h +++ b/lib/dns/include/dns/masterdump.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: masterdump.h,v 1.31 2004/03/19 04:50:20 marka Exp $ */ +/* $Id: masterdump.h,v 1.32 2005/04/27 04:56:56 sra Exp $ */ #ifndef DNS_MASTERDUMP_H #define DNS_MASTERDUMP_H 1 +/*! \file */ + /*** *** Imports ***/ @@ -46,10 +48,10 @@ typedef struct dns_master_style dns_master_style_t; * rdata.h. */ -/* Omit the owner name when possible. */ +/*% Omit the owner name when possible. */ #define DNS_STYLEFLAG_OMIT_OWNER 0x00010000U -/* +/*% * Omit the TTL when possible. If DNS_STYLEFLAG_TTL is * also set, this means no TTLs are ever printed * because $TTL directives are generated before every @@ -67,32 +69,32 @@ typedef struct dns_master_style dns_master_style_t; */ #define DNS_STYLEFLAG_OMIT_TTL 0x00020000U -/* Omit the class when possible. */ +/*% Omit the class when possible. */ #define DNS_STYLEFLAG_OMIT_CLASS 0x00040000U -/* Output $TTL directives. */ +/*% Output $TTL directives. */ #define DNS_STYLEFLAG_TTL 0x00080000U -/* +/*% * Output $ORIGIN directives and print owner names relative to * the origin when possible. */ #define DNS_STYLEFLAG_REL_OWNER 0x00100000U -/* Print domain names in RR data in relative form when possible. +/*% Print domain names in RR data in relative form when possible. For this to take effect, DNS_STYLEFLAG_REL_OWNER must also be set. */ #define DNS_STYLEFLAG_REL_DATA 0x00200000U -/* Print the trust level of each rdataset. */ +/*% Print the trust level of each rdataset. */ #define DNS_STYLEFLAG_TRUST 0x00400000U -/* Print negative caching entries. */ +/*% Print negative caching entries. */ #define DNS_STYLEFLAG_NCACHE 0x00800000U -/* Never print the TTL */ +/*% Never print the TTL */ #define DNS_STYLEFLAG_NO_TTL 0x01000000U -/* Never print the CLASS */ +/*% Never print the CLASS */ #define DNS_STYLEFLAG_NO_CLASS 0x02000000U ISC_LANG_BEGINDECLS @@ -101,7 +103,7 @@ ISC_LANG_BEGINDECLS *** Constants ***/ -/* +/*% * The default master file style. * * This uses $TTL directives to avoid the need to dedicate a @@ -110,13 +112,13 @@ ISC_LANG_BEGINDECLS */ LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_default; -/* +/*% * A master file style that dumps zones to a very generic format easily * imported/checked with external tools. */ LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_full; -/* +/*% * A master file style that prints explicit TTL values on each * record line, never using $TTL statements. The TTL has a tab * stop of its own, but the class and type share one. @@ -124,13 +126,13 @@ LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_full; LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_explicitttl; -/* +/*% * A master style format designed for cache files. It prints explicit TTL * values on each record line and never uses $ORIGIN or relative names. */ LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_cache; -/* +/*% * A master style that prints name, ttl, class, type, and value on * every line. Similar to explicitttl above, but more verbose. * Intended for generating master files which can be easily parsed @@ -138,7 +140,7 @@ LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_cache; */ LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_simple; -/* +/*% * The style used for debugging, "dig" output, etc. */ LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_debug; @@ -149,54 +151,55 @@ LIBDNS_EXTERNAL_DATA extern const dns_master_style_t dns_master_style_debug; void dns_dumpctx_attach(dns_dumpctx_t *source, dns_dumpctx_t **target); -/* +/*%< * Attach to a dump context. * * Require: - * 'source' to be valid. - * 'target' to be non NULL and '*target' to be NULL. + *\li 'source' to be valid. + *\li 'target' to be non NULL and '*target' to be NULL. */ void dns_dumpctx_detach(dns_dumpctx_t **dctxp); -/* +/*%< * Detach from a dump context. * * Require: - * 'dctxp' to point to a valid dump context. + *\li 'dctxp' to point to a valid dump context. * * Ensures: - * '*dctxp' is NULL. + *\li '*dctxp' is NULL. */ void dns_dumpctx_cancel(dns_dumpctx_t *dctx); -/* +/*%< * Cancel a in progress dump. * * Require: - * 'dctx' to be valid. + *\li 'dctx' to be valid. */ dns_dbversion_t * dns_dumpctx_version(dns_dumpctx_t *dctx); -/* +/*%< * Return the version handle (if any) of the database being dumped. * * Require: - * 'dctx' to be valid. + *\li 'dctx' to be valid. */ dns_db_t * dns_dumpctx_db(dns_dumpctx_t *dctx); -/* +/*%< * Return the database being dumped. * * Require: - * 'dctx' to be valid. + *\li 'dctx' to be valid. */ +/*@{*/ isc_result_t dns_master_dumptostreaminc(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version, @@ -208,7 +211,7 @@ isc_result_t dns_master_dumptostream(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version, const dns_master_style_t *style, FILE *f); -/* +/*%< * Dump the database 'db' to the steam 'f' in RFC1035 master * file format, in the style defined by 'style' * (e.g., &dns_default_master_style_default) @@ -216,18 +219,20 @@ dns_master_dumptostream(isc_mem_t *mctx, dns_db_t *db, * Temporary dynamic memory may be allocated from 'mctx'. * * Require: - * 'task' to be valid. - * 'done' to be non NULL. - * 'dctxp' to be non NULL && '*dctxp' to be NULL. + *\li 'task' to be valid. + *\li 'done' to be non NULL. + *\li 'dctxp' to be non NULL && '*dctxp' to be NULL. * * Returns: - * ISC_R_SUCCESS - * DNS_R_CONTINUE dns_master_dumptostreaminc() only. - * ISC_R_NOMEMORY - * Any database or rrset iterator error. - * Any dns_rdata_totext() error code. + *\li ISC_R_SUCCESS + *\li ISC_R_CONTINUE dns_master_dumptostreaminc() only. + *\li ISC_R_NOMEMORY + *\li Any database or rrset iterator error. + *\li Any dns_rdata_totext() error code. */ +/*@}*/ +/*@{*/ isc_result_t dns_master_dumpinc(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version, const dns_master_style_t *style, const char *filename, @@ -238,7 +243,7 @@ isc_result_t dns_master_dump(isc_mem_t *mctx, dns_db_t *db, dns_dbversion_t *version, const dns_master_style_t *style, const char *filename); -/* +/*%< * Dump the database 'db' to the file 'filename' in RFC1035 master * file format, in the style defined by 'style' * (e.g., &dns_default_master_style_default) @@ -246,28 +251,29 @@ dns_master_dump(isc_mem_t *mctx, dns_db_t *db, * Temporary dynamic memory may be allocated from 'mctx'. * * Returns: - * ISC_R_SUCCESS - * DNS_R_CONTINUE dns_master_dumpinc() only. - * ISC_R_NOMEMORY - * Any database or rrset iterator error. - * Any dns_rdata_totext() error code. + *\li ISC_R_SUCCESS + *\li ISC_R_CONTINUE dns_master_dumpinc() only. + *\li ISC_R_NOMEMORY + *\li Any database or rrset iterator error. + *\li Any dns_rdata_totext() error code. */ +/*@}*/ isc_result_t dns_master_rdatasettotext(dns_name_t *owner_name, dns_rdataset_t *rdataset, const dns_master_style_t *style, isc_buffer_t *target); -/* +/*%< * Convert 'rdataset' to text format, storing the result in 'target'. * * Notes: - * The rdata cursor position will be changed. + *\li The rdata cursor position will be changed. * * Requires: - * 'rdataset' is a valid non-question rdataset. + *\li 'rdataset' is a valid non-question rdataset. * - * 'rdataset' is not empty. + *\li 'rdataset' is not empty. */ isc_result_t diff --git a/lib/dns/include/dns/message.h b/lib/dns/include/dns/message.h index d4ff210a5c..0d8f7fdb23 100644 --- a/lib/dns/include/dns/message.h +++ b/lib/dns/include/dns/message.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: message.h,v 1.114 2004/03/05 05:09:44 marka Exp $ */ +/* $Id: message.h,v 1.115 2005/04/27 04:56:56 sra Exp $ */ #ifndef DNS_MESSAGE_H #define DNS_MESSAGE_H 1 @@ -33,7 +33,9 @@ #include -/* +/*! \file + * \brief Message Handling Module + * * How this beast works: * * When a dns message is received in a buffer, dns_message_fromwire() is called @@ -54,9 +56,9 @@ * one of two ways. Assume a name was allocated via * dns_message_gettempname(): * - * (1) insert it into a section, using dns_message_addname(). + *\li (1) insert it into a section, using dns_message_addname(). * - * (2) return it to the message using dns_message_puttempname(). + *\li (2) return it to the message using dns_message_puttempname(). * * The same applies to rdatasets. * @@ -74,6 +76,7 @@ * Since the buffer itself exists until the message is destroyed, this sort * of code can be written: * + * \code * buffer = isc_buffer_allocate(mctx, 512); * name = NULL; * name = dns_message_gettempname(message, &name); @@ -81,6 +84,7 @@ * result = dns_name_fromtext(name, &source, dns_rootname, ISC_FALSE, * buffer); * dns_message_takebuffer(message, &buffer); + * \endcode * * * TODO: @@ -102,7 +106,7 @@ #define DNS_MESSAGE_REPLYPRESERVE (DNS_MESSAGEFLAG_RD|DNS_MESSAGEFLAG_CD) #define DNS_MESSAGEEXTFLAG_REPLYPRESERVE (DNS_MESSAGEEXTFLAG_DO) -#define DNS_MESSAGE_HEADERLEN 12 /* 6 isc_uint16_t's */ +#define DNS_MESSAGE_HEADERLEN 12 /*%< 6 isc_uint16_t's */ #define DNS_MESSAGE_MAGIC ISC_MAGIC('M','S','G','@') #define DNS_MESSAGE_VALID(msg) ISC_MAGIC_VALID(msg, DNS_MESSAGE_MAGIC) @@ -140,32 +144,32 @@ typedef int dns_messagetextflag_t; /* * These tell the message library how the created dns_message_t will be used. */ -#define DNS_MESSAGE_INTENTUNKNOWN 0 /* internal use only */ -#define DNS_MESSAGE_INTENTPARSE 1 /* parsing messages */ -#define DNS_MESSAGE_INTENTRENDER 2 /* rendering */ +#define DNS_MESSAGE_INTENTUNKNOWN 0 /*%< internal use only */ +#define DNS_MESSAGE_INTENTPARSE 1 /*%< parsing messages */ +#define DNS_MESSAGE_INTENTRENDER 2 /*%< rendering */ /* * Control behavior of parsing */ -#define DNS_MESSAGEPARSE_PRESERVEORDER 0x0001 /* preserve rdata order */ -#define DNS_MESSAGEPARSE_BESTEFFORT 0x0002 /* return a message if a +#define DNS_MESSAGEPARSE_PRESERVEORDER 0x0001 /*%< preserve rdata order */ +#define DNS_MESSAGEPARSE_BESTEFFORT 0x0002 /*%< return a message if a recoverable parse error occurs */ -#define DNS_MESSAGEPARSE_CLONEBUFFER 0x0004 /* save a copy of the +#define DNS_MESSAGEPARSE_CLONEBUFFER 0x0004 /*%< save a copy of the source buffer */ -#define DNS_MESSAGEPARSE_IGNORETRUNCATION 0x0008 /* trucation errors are +#define DNS_MESSAGEPARSE_IGNORETRUNCATION 0x0008 /*%< trucation errors are * not fatal. */ /* * Control behavior of rendering */ -#define DNS_MESSAGERENDER_ORDERED 0x0001 /* don't change order */ -#define DNS_MESSAGERENDER_PARTIAL 0x0002 /* allow a partial rdataset */ -#define DNS_MESSAGERENDER_OMITDNSSEC 0x0004 /* omit DNSSEC records */ -#define DNS_MESSAGERENDER_PREFER_A 0x0008 /* prefer A records in - * additional section. */ -#define DNS_MESSAGERENDER_PREFER_AAAA 0x0010 /* prefer AAAA records in - * additional section. */ +#define DNS_MESSAGERENDER_ORDERED 0x0001 /*%< don't change order */ +#define DNS_MESSAGERENDER_PARTIAL 0x0002 /*%< allow a partial rdataset */ +#define DNS_MESSAGERENDER_OMITDNSSEC 0x0004 /*%< omit DNSSEC records */ +#define DNS_MESSAGERENDER_PREFER_A 0x0008 /*%< prefer A records in + additional section. */ +#define DNS_MESSAGERENDER_PREFER_AAAA 0x0010 /*%< prefer AAAA records in + additional section. */ typedef struct dns_msgblock dns_msgblock_t; @@ -248,32 +252,32 @@ ISC_LANG_BEGINDECLS isc_result_t dns_message_create(isc_mem_t *mctx, unsigned int intent, dns_message_t **msgp); -/* +/*%< * Create msg structure. * * This function will allocate some internal blocks of memory that are * expected to be needed for parsing or rendering nearly any type of message. * * Requires: - * 'mctx' be a valid memory context. + *\li 'mctx' be a valid memory context. * - * 'msgp' be non-null and '*msg' be NULL. + *\li 'msgp' be non-null and '*msg' be NULL. * - * 'intent' must be one of DNS_MESSAGE_INTENTPARSE or - * DNS_MESSAGE_INTENTRENDER. + *\li 'intent' must be one of DNS_MESSAGE_INTENTPARSE or + * #DNS_MESSAGE_INTENTRENDER. * * Ensures: - * The data in "*msg" is set to indicate an unused and empty msg + *\li The data in "*msg" is set to indicate an unused and empty msg * structure. * * Returns: - * ISC_R_NOMEMORY -- out of memory - * ISC_R_SUCCESS -- success + *\li #ISC_R_NOMEMORY -- out of memory + *\li #ISC_R_SUCCESS -- success */ void dns_message_reset(dns_message_t *msg, unsigned int intent); -/* +/*%< * Reset a message structure to default state. All internal lists are freed * or reset to a default state as well. This is simply a more efficient * way to call dns_message_destroy() followed by dns_message_allocate(), @@ -286,22 +290,22 @@ dns_message_reset(dns_message_t *msg, unsigned int intent); * * Requires: * - * 'msg' be valid. + *\li 'msg' be valid. * - * 'intent' is DNS_MESSAGE_INTENTPARSE or DNS_MESSAGE_INTENTRENDER + *\li 'intent' is DNS_MESSAGE_INTENTPARSE or DNS_MESSAGE_INTENTRENDER */ void dns_message_destroy(dns_message_t **msgp); -/* +/*%< * Destroy all state in the message. * * Requires: * - * 'msgp' be valid. + *\li 'msgp' be valid. * * Ensures: - * '*msgp' == NULL + *\li '*msgp' == NULL */ isc_result_t @@ -316,85 +320,83 @@ dns_message_pseudosectiontotext(dns_message_t *msg, const dns_master_style_t *style, dns_messagetextflag_t flags, isc_buffer_t *target); -/* +/*%< * Convert section 'section' or 'pseudosection' of message 'msg' to * a cleartext representation * * Notes: - * See dns_message_totext for meanings of flags. + * \li See dns_message_totext for meanings of flags. * * Requires: * - * 'msg' is a valid message. + *\li 'msg' is a valid message. * - * 'style' is a valid master dump style. + *\li 'style' is a valid master dump style. * - * 'target' is a valid buffer. + *\li 'target' is a valid buffer. * - * 'section' is a valid section label. + *\li 'section' is a valid section label. * * Ensures: * - * If the result is success: - * + *\li If the result is success: * The used space in 'target' is updated. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOSPACE - * ISC_R_NOMORE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE + *\li #ISC_R_NOMORE * - * Note: On error return, *target may be partially filled with data. + *\li Note: On error return, *target may be partially filled with data. */ isc_result_t dns_message_totext(dns_message_t *msg, const dns_master_style_t *style, dns_messagetextflag_t flags, isc_buffer_t *target); -/* +/*%< * Convert all sections of message 'msg' to a cleartext representation * * Notes: - * In flags, If DNS_MESSAGETEXTFLAG_OMITDOT is set, then the + * \li In flags, If #DNS_MESSAGETEXTFLAG_OMITDOT is set, then the * final '.' in absolute names will not be emitted. If - * DNS_MESSAGETEXTFLAG_NOCOMMENTS is cleared, lines beginning + * #DNS_MESSAGETEXTFLAG_NOCOMMENTS is cleared, lines beginning * with ";;" will be emitted indicating section name. If - * DNS_MESSAGETEXTFLAG_NOHEADERS is cleared, header lines will + * #DNS_MESSAGETEXTFLAG_NOHEADERS is cleared, header lines will * be emitted. * * Requires: * - * 'msg' is a valid message. + *\li 'msg' is a valid message. * - * 'style' is a valid master dump style. + *\li 'style' is a valid master dump style. * - * 'target' is a valid buffer. + *\li 'target' is a valid buffer. * * Ensures: * - * If the result is success: - * + *\li If the result is success: * The used space in 'target' is updated. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOSPACE - * ISC_R_NOMORE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE + *\li #ISC_R_NOMORE * - * Note: On error return, *target may be partially filled with data. + *\li Note: On error return, *target may be partially filled with data. */ isc_result_t dns_message_parse(dns_message_t *msg, isc_buffer_t *source, unsigned int options); -/* +/*%< * Parse raw wire data in 'source' as a DNS message. * * OPT records are detected and stored in the pseudo-section "opt". * TSIGs are detected and stored in the pseudo-section "tsig". * - * If DNS_MESSAGEPARSE_PRESERVEORDER is set, or if the opcode of the message + * If #DNS_MESSAGEPARSE_PRESERVEORDER is set, or if the opcode of the message * is UPDATE, a separate dns_name_t object will be created for each RR in the * message. Each such dns_name_t will have a single rdataset containing the * single RR, and the order of the RRs in the message is preserved. @@ -403,39 +405,39 @@ dns_message_parse(dns_message_t *msg, isc_buffer_t *source, * of rdatasets. To access the names and their data, use * dns_message_firstname() and dns_message_nextname(). * - * If DNS_MESSAGEPARSE_BESTEFFORT is set, errors in message content will + * If #DNS_MESSAGEPARSE_BESTEFFORT is set, errors in message content will * not be considered FORMERRs. If the entire message can be parsed, it * will be returned and DNS_R_RECOVERABLE will be returned. * - * If DNS_MESSAGEPARSE_IGNORETRUNCATION is set then return as many complete + * If #DNS_MESSAGEPARSE_IGNORETRUNCATION is set then return as many complete * RR's as possible, DNS_R_RECOVERABLE will be returned. * * OPT and TSIG records are always handled specially, regardless of the * 'preserve_order' setting. * * Requires: - * "msg" be valid. + *\li "msg" be valid. * - * "buffer" be a wire format buffer. + *\li "buffer" be a wire format buffer. * * Ensures: - * The buffer's data format is correct. + *\li The buffer's data format is correct. * - * The buffer's contents verify as correct regarding header bits, buffer + *\li The buffer's contents verify as correct regarding header bits, buffer * and rdata sizes, etc. * * Returns: - * ISC_R_SUCCESS -- all is well - * ISC_R_NOMEMORY -- no memory - * DNS_R_RECOVERABLE -- the message parsed properly, but contained + *\li #ISC_R_SUCCESS -- all is well + *\li #ISC_R_NOMEMORY -- no memory + *\li #DNS_R_RECOVERABLE -- the message parsed properly, but contained * errors. - * Many other errors possible XXXMLG + *\li Many other errors possible XXXMLG */ isc_result_t dns_message_renderbegin(dns_message_t *msg, dns_compress_t *cctx, isc_buffer_t *buffer); -/* +/*%< * Begin rendering on a message. Only one call can be made to this function * per message. * @@ -447,24 +449,24 @@ dns_message_renderbegin(dns_message_t *msg, dns_compress_t *cctx, * * Requires: * - * 'msg' be valid. + *\li 'msg' be valid. * - * 'cctx' be valid. + *\li 'cctx' be valid. * - * 'buffer' is a valid buffer. + *\li 'buffer' is a valid buffer. * * Side Effects: * - * The buffer is cleared before it is used. + *\li The buffer is cleared before it is used. * * Returns: - * ISC_R_SUCCESS -- all is well - * ISC_R_NOSPACE -- output buffer is too small + *\li #ISC_R_SUCCESS -- all is well + *\li #ISC_R_NOSPACE -- output buffer is too small */ isc_result_t dns_message_renderchangebuffer(dns_message_t *msg, isc_buffer_t *buffer); -/* +/*%< * Reset the buffer. This can be used after growing the old buffer * on a ISC_R_NOSPACE return from most of the render functions. * @@ -474,20 +476,20 @@ dns_message_renderchangebuffer(dns_message_t *msg, isc_buffer_t *buffer); * * Requires: * - * 'msg' be valid. + *\li 'msg' be valid. * - * dns_message_renderbegin() was called. + *\li dns_message_renderbegin() was called. * - * buffer != NULL. + *\li buffer != NULL. * * Returns: - * ISC_R_NOSPACE -- new buffer is too small - * ISC_R_SUCCESS -- all is well. + *\li #ISC_R_NOSPACE -- new buffer is too small + *\li #ISC_R_SUCCESS -- all is well. */ isc_result_t dns_message_renderreserve(dns_message_t *msg, unsigned int space); -/* +/*%< * XXXMLG should use size_t rather than unsigned int once the buffer * API is cleaned up * @@ -495,18 +497,18 @@ dns_message_renderreserve(dns_message_t *msg, unsigned int space); * * Requires: * - * 'msg' be valid. + *\li 'msg' be valid. * - * dns_message_renderbegin() was called. + *\li dns_message_renderbegin() was called. * * Returns: - * ISC_R_SUCCESS -- all is well. - * ISC_R_NOSPACE -- not enough free space in the buffer. + *\li #ISC_R_SUCCESS -- all is well. + *\li #ISC_R_NOSPACE -- not enough free space in the buffer. */ void dns_message_renderrelease(dns_message_t *msg, unsigned int space); -/* +/*%< * XXXMLG should use size_t rather than unsigned int once the buffer * API is cleaned up * @@ -514,87 +516,87 @@ dns_message_renderrelease(dns_message_t *msg, unsigned int space); * * Requires: * - * 'msg' be valid. + *\li 'msg' be valid. * - * 'space' is less than or equal to the total amount of space reserved + *\li 'space' is less than or equal to the total amount of space reserved * via prior calls to dns_message_renderreserve(). * - * dns_message_renderbegin() was called. + *\li dns_message_renderbegin() was called. */ isc_result_t dns_message_rendersection(dns_message_t *msg, dns_section_t section, unsigned int options); -/* +/*%< * Render all names, rdatalists, etc from the given section at the * specified priority or higher. * * Requires: - * 'msg' be valid. + *\li 'msg' be valid. * - * 'section' be a valid section. + *\li 'section' be a valid section. * - * dns_message_renderbegin() was called. + *\li dns_message_renderbegin() was called. * * Returns: - * ISC_R_SUCCESS -- all records were written, and there are + *\li #ISC_R_SUCCESS -- all records were written, and there are * no more records for this section. - * ISC_R_NOSPACE -- Not enough room in the buffer to write + *\li #ISC_R_NOSPACE -- Not enough room in the buffer to write * all records requested. - * DNS_R_MOREDATA -- All requested records written, and there + *\li #DNS_R_MOREDATA -- All requested records written, and there * are records remaining for this section. */ void dns_message_renderheader(dns_message_t *msg, isc_buffer_t *target); -/* +/*%< * Render the message header. This is implicitly called by * dns_message_renderend(). * * Requires: * - * 'msg' be a valid message. + *\li 'msg' be a valid message. * - * dns_message_renderbegin() was called. + *\li dns_message_renderbegin() was called. * - * 'target' is a valid buffer with enough space to hold a message header + *\li 'target' is a valid buffer with enough space to hold a message header */ isc_result_t dns_message_renderend(dns_message_t *msg); -/* +/*%< * Finish rendering to the buffer. Note that more data can be in the * 'msg' structure. Destroying the structure will free this, or in a multi- * part EDNS1 message this data can be rendered to another buffer later. * * Requires: * - * 'msg' be a valid message. + *\li 'msg' be a valid message. * - * dns_message_renderbegin() was called. + *\li dns_message_renderbegin() was called. * * Returns: - * ISC_R_SUCCESS -- all is well. + *\li #ISC_R_SUCCESS -- all is well. */ void dns_message_renderreset(dns_message_t *msg); -/* +/*%< * Reset the message so that it may be rendered again. * * Notes: * - * If dns_message_renderbegin() has been called, dns_message_renderend() + *\li If dns_message_renderbegin() has been called, dns_message_renderend() * must be called before calling this function. * * Requires: * - * 'msg' be a valid message with rendering intent. + *\li 'msg' be a valid message with rendering intent. */ isc_result_t dns_message_firstname(dns_message_t *msg, dns_section_t section); -/* +/*%< * Set internal per-section name pointer to the beginning of the section. * * The functions dns_message_firstname() and dns_message_nextname() may @@ -602,39 +604,39 @@ dns_message_firstname(dns_message_t *msg, dns_section_t section); * * Requires: * - * 'msg' be valid. + *\li 'msg' be valid. * - * 'section' be a valid section. + *\li 'section' be a valid section. * * Returns: - * ISC_R_SUCCESS -- All is well. - * ISC_R_NOMORE -- No names on given section. + *\li #ISC_R_SUCCESS -- All is well. + *\li #ISC_R_NOMORE -- No names on given section. */ isc_result_t dns_message_nextname(dns_message_t *msg, dns_section_t section); -/* +/*%< * Sets the internal per-section name pointer to point to the next name * in that section. * * Requires: * - * 'msg' be valid. + * \li 'msg' be valid. * - * 'section' be a valid section. + *\li 'section' be a valid section. * - * dns_message_firstname() must have been called on this section, + *\li dns_message_firstname() must have been called on this section, * and the result was ISC_R_SUCCESS. * * Returns: - * ISC_R_SUCCESS -- All is well. - * ISC_R_NOMORE -- No more names in given section. + *\li #ISC_R_SUCCESS -- All is well. + *\li #ISC_R_NOMORE -- No more names in given section. */ void dns_message_currentname(dns_message_t *msg, dns_section_t section, dns_name_t **name); -/* +/*%< * Sets 'name' to point to the name where the per-section internal name * pointer is currently set. * @@ -643,15 +645,15 @@ dns_message_currentname(dns_message_t *msg, dns_section_t section, * * Requires: * - * 'msg' be valid. + *\li 'msg' be valid. * - * 'name' be non-NULL, and *name be NULL. + *\li 'name' be non-NULL, and *name be NULL. * - * 'section' be a valid section. + *\li 'section' be a valid section. * - * dns_message_firstname() must have been called on this section, + *\li dns_message_firstname() must have been called on this section, * and the result of it and any dns_message_nextname() calls was - * ISC_R_SUCCESS. + * #ISC_R_SUCCESS. */ isc_result_t @@ -659,79 +661,79 @@ dns_message_findname(dns_message_t *msg, dns_section_t section, dns_name_t *target, dns_rdatatype_t type, dns_rdatatype_t covers, dns_name_t **foundname, dns_rdataset_t **rdataset); -/* +/*%< * Search for a name in the specified section. If it is found, *name is * set to point to the name, and *rdataset is set to point to the found * rdataset (if type is specified as other than dns_rdatatype_any). * * Requires: - * 'msg' be valid. + *\li 'msg' be valid. * - * 'section' be a valid section. + *\li 'section' be a valid section. * - * If a pointer to the name is desired, 'foundname' should be non-NULL. + *\li If a pointer to the name is desired, 'foundname' should be non-NULL. * If it is non-NULL, '*foundname' MUST be NULL. * - * If a type other than dns_datatype_any is searched for, 'rdataset' + *\li If a type other than dns_datatype_any is searched for, 'rdataset' * may be non-NULL, '*rdataset' be NULL, and will point at the found * rdataset. If the type is dns_datatype_any, 'rdataset' must be NULL. * - * 'target' be a valid name. + *\li 'target' be a valid name. * - * 'type' be a valid type. + *\li 'type' be a valid type. * - * If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type. + *\li If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type. * Otherwise it should be 0. * * Returns: - * ISC_R_SUCCESS -- all is well. - * DNS_R_NXDOMAIN -- name does not exist in that section. - * DNS_R_NXRRSET -- The name does exist, but the desired + *\li #ISC_R_SUCCESS -- all is well. + *\li #DNS_R_NXDOMAIN -- name does not exist in that section. + *\li #DNS_R_NXRRSET -- The name does exist, but the desired * type does not. */ isc_result_t dns_message_findtype(dns_name_t *name, dns_rdatatype_t type, dns_rdatatype_t covers, dns_rdataset_t **rdataset); -/* +/*%< * Search the name for the specified type. If it is found, *rdataset is * filled in with a pointer to that rdataset. * * Requires: - * if '**rdataset' is non-NULL, *rdataset needs to be NULL. + *\li if '**rdataset' is non-NULL, *rdataset needs to be NULL. * - * 'type' be a valid type, and NOT dns_rdatatype_any. + *\li 'type' be a valid type, and NOT dns_rdatatype_any. * - * If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type. + *\li If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type. * Otherwise it should be 0. * * Returns: - * ISC_R_SUCCESS -- all is well. - * ISC_R_NOTFOUND -- the desired type does not exist. + *\li #ISC_R_SUCCESS -- all is well. + *\li #ISC_R_NOTFOUND -- the desired type does not exist. */ void dns_message_movename(dns_message_t *msg, dns_name_t *name, dns_section_t fromsection, dns_section_t tosection); -/* +/*%< * Move a name from one section to another. * * Requires: * - * 'msg' be valid. + *\li 'msg' be valid. * - * 'name' must be a name already in 'fromsection'. + *\li 'name' must be a name already in 'fromsection'. * - * 'fromsection' must be a valid section. + *\li 'fromsection' must be a valid section. * - * 'tosection' must be a valid section. + *\li 'tosection' must be a valid section. */ void dns_message_addname(dns_message_t *msg, dns_name_t *name, dns_section_t section); -/* +/*%< * Adds the name to the given section. * * It is the caller's responsibility to enforce any unique name requirements @@ -739,11 +741,11 @@ dns_message_addname(dns_message_t *msg, dns_name_t *name, * * Requires: * - * 'msg' be valid, and be a renderable message. + *\li 'msg' be valid, and be a renderable message. * - * 'name' be a valid absolute name. + *\li 'name' be a valid absolute name. * - * 'section' be a named section. + *\li 'section' be a named section. */ /* @@ -756,7 +758,7 @@ dns_message_addname(dns_message_t *msg, dns_name_t *name, isc_result_t dns_message_gettempname(dns_message_t *msg, dns_name_t **item); -/* +/*%< * Return a name that can be used for any temporary purpose, including * inserting into the message's linked lists. The name must be returned * to the message code using dns_message_puttempname() or inserted into @@ -765,180 +767,180 @@ dns_message_gettempname(dns_message_t *msg, dns_name_t **item); * It is the caller's responsibility to initialize this name. * * Requires: - * msg be a valid message + *\li msg be a valid message * - * item != NULL && *item == NULL + *\li item != NULL && *item == NULL * * Returns: - * ISC_R_SUCCESS -- All is well. - * ISC_R_NOMEMORY -- No item can be allocated. + *\li #ISC_R_SUCCESS -- All is well. + *\li #ISC_R_NOMEMORY -- No item can be allocated. */ isc_result_t dns_message_gettempoffsets(dns_message_t *msg, dns_offsets_t **item); -/* +/*%< * Return an offsets array that can be used for any temporary purpose, * such as attaching to a temporary name. The offsets will be freed * when the message is destroyed or reset. * * Requires: - * msg be a valid message + *\li msg be a valid message * - * item != NULL && *item == NULL + *\li item != NULL && *item == NULL * * Returns: - * ISC_R_SUCCESS -- All is well. - * ISC_R_NOMEMORY -- No item can be allocated. + *\li #ISC_R_SUCCESS -- All is well. + *\li #ISC_R_NOMEMORY -- No item can be allocated. */ isc_result_t dns_message_gettemprdata(dns_message_t *msg, dns_rdata_t **item); -/* +/*%< * Return a rdata that can be used for any temporary purpose, including * inserting into the message's linked lists. The rdata will be freed * when the message is destroyed or reset. * * Requires: - * msg be a valid message + *\li msg be a valid message * - * item != NULL && *item == NULL + *\li item != NULL && *item == NULL * * Returns: - * ISC_R_SUCCESS -- All is well. - * ISC_R_NOMEMORY -- No item can be allocated. + *\li #ISC_R_SUCCESS -- All is well. + *\li #ISC_R_NOMEMORY -- No item can be allocated. */ isc_result_t dns_message_gettemprdataset(dns_message_t *msg, dns_rdataset_t **item); -/* +/*%< * Return a rdataset that can be used for any temporary purpose, including * inserting into the message's linked lists. The name must be returned * to the message code using dns_message_puttempname() or inserted into * one of the message's sections before the message is destroyed. * * Requires: - * msg be a valid message + *\li msg be a valid message * - * item != NULL && *item == NULL + *\li item != NULL && *item == NULL * * Returns: - * ISC_R_SUCCESS -- All is well. - * ISC_R_NOMEMORY -- No item can be allocated. + *\li #ISC_R_SUCCESS -- All is well. + *\li #ISC_R_NOMEMORY -- No item can be allocated. */ isc_result_t dns_message_gettemprdatalist(dns_message_t *msg, dns_rdatalist_t **item); -/* +/*%< * Return a rdatalist that can be used for any temporary purpose, including * inserting into the message's linked lists. The rdatalist will be * destroyed when the message is destroyed or reset. * * Requires: - * msg be a valid message + *\li msg be a valid message * - * item != NULL && *item == NULL + *\li item != NULL && *item == NULL * * Returns: - * ISC_R_SUCCESS -- All is well. - * ISC_R_NOMEMORY -- No item can be allocated. + *\li #ISC_R_SUCCESS -- All is well. + *\li #ISC_R_NOMEMORY -- No item can be allocated. */ void dns_message_puttempname(dns_message_t *msg, dns_name_t **item); -/* +/*%< * Return a borrowed name to the message's name free list. * * Requires: - * msg be a valid message + *\li msg be a valid message * - * item != NULL && *item point to a name returned by + *\li item != NULL && *item point to a name returned by * dns_message_gettempname() * * Ensures: - * *item == NULL + *\li *item == NULL */ void dns_message_puttemprdata(dns_message_t *msg, dns_rdata_t **item); -/* +/*%< * Return a borrowed rdata to the message's rdata free list. * * Requires: - * msg be a valid message + *\li msg be a valid message * - * item != NULL && *item point to a rdata returned by + *\li item != NULL && *item point to a rdata returned by * dns_message_gettemprdata() * * Ensures: - * *item == NULL + *\li *item == NULL */ void dns_message_puttemprdataset(dns_message_t *msg, dns_rdataset_t **item); -/* +/*%< * Return a borrowed rdataset to the message's rdataset free list. * * Requires: - * msg be a valid message + *\li msg be a valid message * - * item != NULL && *item point to a rdataset returned by + *\li item != NULL && *item point to a rdataset returned by * dns_message_gettemprdataset() * * Ensures: - * *item == NULL + *\li *item == NULL */ void dns_message_puttemprdatalist(dns_message_t *msg, dns_rdatalist_t **item); -/* +/*%< * Return a borrowed rdatalist to the message's rdatalist free list. * * Requires: - * msg be a valid message + *\li msg be a valid message * - * item != NULL && *item point to a rdatalist returned by + *\li item != NULL && *item point to a rdatalist returned by * dns_message_gettemprdatalist() * * Ensures: - * *item == NULL + *\li *item == NULL */ isc_result_t dns_message_peekheader(isc_buffer_t *source, dns_messageid_t *idp, unsigned int *flagsp); -/* +/*%< * Assume the remaining region of "source" is a DNS message. Peek into * it and fill in "*idp" with the message id, and "*flagsp" with the flags. * * Requires: * - * source != NULL + *\li source != NULL * * Ensures: * - * if (idp != NULL) *idp == message id. + *\li if (idp != NULL) *idp == message id. * - * if (flagsp != NULL) *flagsp == message flags. + *\li if (flagsp != NULL) *flagsp == message flags. * * Returns: * - * ISC_R_SUCCESS -- all is well. + *\li #ISC_R_SUCCESS -- all is well. * - * ISC_R_UNEXPECTEDEND -- buffer doesn't contain enough for a header. + *\li #ISC_R_UNEXPECTEDEND -- buffer doesn't contain enough for a header. */ isc_result_t dns_message_reply(dns_message_t *msg, isc_boolean_t want_question_section); -/* +/*%< * Start formatting a reply to the query in 'msg'. * * Requires: * - * 'msg' is a valid message with parsing intent, and contains a query. + *\li 'msg' is a valid message with parsing intent, and contains a query. * * Ensures: * - * The message will have a rendering intent. If 'want_question_section' + *\li The message will have a rendering intent. If 'want_question_section' * is true, the message opcode is query or notify, and the question * section is present and properly formatted, then the question section * will be included in the reply. All other sections will be cleared. @@ -947,9 +949,9 @@ dns_message_reply(dns_message_t *msg, isc_boolean_t want_question_section); * * Returns: * - * ISC_R_SUCCESS -- all is well. + *\li #ISC_R_SUCCESS -- all is well. * - * DNS_R_FORMERR -- the header or question section of the + *\li #DNS_R_FORMERR -- the header or question section of the * message is invalid, replying is impossible. * If DNS_R_FORMERR is returned when * want_question_section is ISC_FALSE, then @@ -960,308 +962,308 @@ dns_message_reply(dns_message_t *msg, isc_boolean_t want_question_section); dns_rdataset_t * dns_message_getopt(dns_message_t *msg); -/* +/*%< * Get the OPT record for 'msg'. * * Requires: * - * 'msg' is a valid message. + *\li 'msg' is a valid message. * * Returns: * - * The OPT rdataset of 'msg', or NULL if there isn't one. + *\li The OPT rdataset of 'msg', or NULL if there isn't one. */ isc_result_t dns_message_setopt(dns_message_t *msg, dns_rdataset_t *opt); -/* +/*%< * Set the OPT record for 'msg'. * * Requires: * - * 'msg' is a valid message with rendering intent + *\li 'msg' is a valid message with rendering intent * and no sections have been rendered. * - * 'opt' is a valid OPT record. + *\li 'opt' is a valid OPT record. * * Ensures: * - * The OPT record has either been freed or ownership of it has + *\li The OPT record has either been freed or ownership of it has * been transferred to the message. * - * If ISC_R_SUCCESS was returned, the OPT record will be rendered + *\li If ISC_R_SUCCESS was returned, the OPT record will be rendered * when dns_message_renderend() is called. * * Returns: * - * ISC_R_SUCCESS -- all is well. + *\li #ISC_R_SUCCESS -- all is well. * - * ISC_R_NOSPACE -- there is no space for the OPT record. + *\li #ISC_R_NOSPACE -- there is no space for the OPT record. */ dns_rdataset_t * dns_message_gettsig(dns_message_t *msg, dns_name_t **owner); -/* +/*%< * Get the TSIG record and owner for 'msg'. * * Requires: * - * 'msg' is a valid message. - * 'owner' is NULL or *owner is NULL. + *\li 'msg' is a valid message. + *\li 'owner' is NULL or *owner is NULL. * * Returns: * - * The TSIG rdataset of 'msg', or NULL if there isn't one. + *\li The TSIG rdataset of 'msg', or NULL if there isn't one. * * Ensures: * - * If 'owner' is not NULL, it will point to the owner name. + * \li If 'owner' is not NULL, it will point to the owner name. */ isc_result_t dns_message_settsigkey(dns_message_t *msg, dns_tsigkey_t *key); -/* +/*%< * Set the tsig key for 'msg'. This is only necessary for when rendering a * query or parsing a response. The key (if non-NULL) is attached to, and * will be detached when the message is destroyed. * * Requires: * - * 'msg' is a valid message with rendering intent, + *\li 'msg' is a valid message with rendering intent, * dns_message_renderbegin() has been called, and no sections have been * rendered. - * 'key' is a valid tsig key or NULL. + *\li 'key' is a valid tsig key or NULL. * * Returns: * - * ISC_R_SUCCESS -- all is well. + *\li #ISC_R_SUCCESS -- all is well. * - * ISC_R_NOSPACE -- there is no space for the TSIG record. + *\li #ISC_R_NOSPACE -- there is no space for the TSIG record. */ dns_tsigkey_t * dns_message_gettsigkey(dns_message_t *msg); -/* +/*%< * Gets the tsig key for 'msg'. * * Requires: * - * 'msg' is a valid message + *\li 'msg' is a valid message */ isc_result_t dns_message_setquerytsig(dns_message_t *msg, isc_buffer_t *querytsig); -/* +/*%< * Indicates that 'querytsig' is the TSIG from the signed query for which * 'msg' is the response. This is also used for chained TSIGs in TCP * responses. * * Requires: * - * 'querytsig' is a valid buffer as returned by dns_message_getquerytsig() + *\li 'querytsig' is a valid buffer as returned by dns_message_getquerytsig() * or NULL * - * 'msg' is a valid message + *\li 'msg' is a valid message * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ isc_result_t dns_message_getquerytsig(dns_message_t *msg, isc_mem_t *mctx, isc_buffer_t **querytsig); -/* +/*%< * Gets the tsig from the TSIG from the signed query 'msg'. This is also used * for chained TSIGs in TCP responses. Unlike dns_message_gettsig, this makes * a copy of the data, so can be used if the message is destroyed. * * Requires: * - * 'msg' is a valid signed message - * 'mctx' is a valid memory context - * querytsig != NULL && *querytsig == NULL + *\li 'msg' is a valid signed message + *\li 'mctx' is a valid memory context + *\li querytsig != NULL && *querytsig == NULL * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY * * Ensures: - * 'tsig' points to NULL or an allocated buffer which must be freed + *\li 'tsig' points to NULL or an allocated buffer which must be freed * by the caller. */ dns_rdataset_t * dns_message_getsig0(dns_message_t *msg, dns_name_t **owner); -/* +/*%< * Get the SIG(0) record and owner for 'msg'. * * Requires: * - * 'msg' is a valid message. - * 'owner' is NULL or *owner is NULL. + *\li 'msg' is a valid message. + *\li 'owner' is NULL or *owner is NULL. * * Returns: * - * The SIG(0) rdataset of 'msg', or NULL if there isn't one. + *\li The SIG(0) rdataset of 'msg', or NULL if there isn't one. * * Ensures: * - * If 'owner' is not NULL, it will point to the owner name. + * \li If 'owner' is not NULL, it will point to the owner name. */ isc_result_t dns_message_setsig0key(dns_message_t *msg, dst_key_t *key); -/* +/*%< * Set the SIG(0) key for 'msg'. * * Requires: * - * 'msg' is a valid message with rendering intent, + *\li 'msg' is a valid message with rendering intent, * dns_message_renderbegin() has been called, and no sections have been * rendered. - * 'key' is a valid sig key or NULL. + *\li 'key' is a valid sig key or NULL. * * Returns: * - * ISC_R_SUCCESS -- all is well. + *\li #ISC_R_SUCCESS -- all is well. * - * ISC_R_NOSPACE -- there is no space for the SIG(0) record. + *\li #ISC_R_NOSPACE -- there is no space for the SIG(0) record. */ dst_key_t * dns_message_getsig0key(dns_message_t *msg); -/* +/*%< * Gets the SIG(0) key for 'msg'. * * Requires: * - * 'msg' is a valid message + *\li 'msg' is a valid message */ void dns_message_takebuffer(dns_message_t *msg, isc_buffer_t **buffer); -/* +/*%< * Give the *buffer to the message code to clean up when it is no * longer needed. This is usually when the message is reset or * destroyed. * * Requires: * - * msg be a valid message. + *\li msg be a valid message. * - * buffer != NULL && *buffer is a valid isc_buffer_t, which was + *\li buffer != NULL && *buffer is a valid isc_buffer_t, which was * dynamincally allocated via isc_buffer_allocate(). */ isc_result_t dns_message_signer(dns_message_t *msg, dns_name_t *signer); -/* +/*%< * If this message was signed, return the identity of the signer. * Unless ISC_R_NOTFOUND is returned, signer will reflect the name of the * key that signed the message. * * Requires: * - * msg is a valid parsed message. - * signer is a valid name + *\li msg is a valid parsed message. + *\li signer is a valid name * * Returns: * - * ISC_R_SUCCESS - the message was signed, and *signer + *\li #ISC_R_SUCCESS - the message was signed, and *signer * contains the signing identity * - * ISC_R_NOTFOUND - no TSIG or SIG(0) record is present in the + *\li #ISC_R_NOTFOUND - no TSIG or SIG(0) record is present in the * message * - * DNS_R_TSIGVERIFYFAILURE - the message was signed by a TSIG, but the + *\li #DNS_R_TSIGVERIFYFAILURE - the message was signed by a TSIG, but the * signature failed to verify * - * DNS_R_TSIGERRORSET - the message was signed by a TSIG and + *\li #DNS_R_TSIGERRORSET - the message was signed by a TSIG and * verified, but the query was rejected by * the server * - * DNS_R_NOIDENTITY - the message was signed by a TSIG and + *\li #DNS_R_NOIDENTITY - the message was signed by a TSIG and * verified, but the key has no identity since * it was generated by an unsigned TKEY process * - * DNS_R_SIGINVALID - the message was signed by a SIG(0), but + *\li #DNS_R_SIGINVALID - the message was signed by a SIG(0), but * the signature failed to verify * - * DNS_R_NOTVERIFIEDYET - the message was signed by a TSIG or SIG(0), + *\li #DNS_R_NOTVERIFIEDYET - the message was signed by a TSIG or SIG(0), * but the signature has not been verified yet */ isc_result_t dns_message_checksig(dns_message_t *msg, dns_view_t *view); -/* +/*%< * If this message was signed, verify the signature. * * Requires: * - * msg is a valid parsed message. - * view is a valid view or NULL + *\li msg is a valid parsed message. + *\li view is a valid view or NULL * * Returns: * - * ISC_R_SUCCESS - the message was unsigned, or the message + *\li #ISC_R_SUCCESS - the message was unsigned, or the message * was signed correctly. * - * DNS_R_EXPECTEDTSIG - A TSIG was expected, but not seen - * DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected - * DNS_R_TSIGVERIFYFAILURE - The TSIG failed to verify + *\li #DNS_R_EXPECTEDTSIG - A TSIG was expected, but not seen + *\li #DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected + *\li #DNS_R_TSIGVERIFYFAILURE - The TSIG failed to verify */ isc_result_t dns_message_rechecksig(dns_message_t *msg, dns_view_t *view); -/* +/*%< * Reset the signature state and then if the message was signed, * verify the message. * * Requires: * - * msg is a valid parsed message. - * view is a valid view or NULL + *\li msg is a valid parsed message. + *\li view is a valid view or NULL * * Returns: * - * ISC_R_SUCCESS - the message was unsigned, or the message + *\li #ISC_R_SUCCESS - the message was unsigned, or the message * was signed correctly. * - * DNS_R_EXPECTEDTSIG - A TSIG was expected, but not seen - * DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected - * DNS_R_TSIGVERIFYFAILURE - The TSIG failed to verify + *\li #DNS_R_EXPECTEDTSIG - A TSIG was expected, but not seen + *\li #DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected + *\li #DNS_R_TSIGVERIFYFAILURE - The TSIG failed to verify */ void dns_message_resetsig(dns_message_t *msg); -/* +/*%< * Reset the signature state. * * Requires: - * 'msg' is a valid parsed message. + *\li 'msg' is a valid parsed message. */ isc_region_t * dns_message_getrawmessage(dns_message_t *msg); -/* +/*%< * Retrieve the raw message in compressed wire format. The message must * have been successfully parsed for it to have been saved. * * Requires: - * msg is a valid parsed message. + *\li msg is a valid parsed message. * * Returns: - * NULL if there is no saved message. + *\li NULL if there is no saved message. * a pointer to a region which refers the dns message. */ void dns_message_setsortorder(dns_message_t *msg, dns_rdatasetorderfunc_t order, void *order_arg); -/* +/*%< * Define the order in which RR sets get rendered by * dns_message_rendersection() to be the ascending order * defined by the integer value returned by 'order' when @@ -1269,27 +1271,27 @@ dns_message_setsortorder(dns_message_t *msg, dns_rdatasetorderfunc_t order, * 'order_arg' are NULL, a default order is used. * * Requires: - * msg be a valid message. - * order_arg is NULL if and only if order is NULL. + *\li msg be a valid message. + *\li order_arg is NULL if and only if order is NULL. */ void dns_message_settimeadjust(dns_message_t *msg, int timeadjust); -/* +/*%< * Adjust the time used to sign/verify a message by timeadjust. * Currently only TSIG. * * Requires: - * msg be a valid message. + *\li msg be a valid message. */ int dns_message_gettimeadjust(dns_message_t *msg); -/* +/*%< * Return the current time adjustment. * * Requires: - * msg be a valid message. + *\li msg be a valid message. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/name.h b/lib/dns/include/dns/name.h index 8528495ede..d8237f6dcc 100644 --- a/lib/dns/include/dns/name.h +++ b/lib/dns/include/dns/name.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: name.h,v 1.114 2005/03/04 02:56:21 marka Exp $ */ +/* $Id: name.h,v 1.115 2005/04/27 04:56:57 sra Exp $ */ #ifndef DNS_NAME_H #define DNS_NAME_H 1 @@ -24,9 +24,8 @@ ***** Module Info *****/ -/* - * DNS Names and Labels - * +/*! \file + * \brief * Provides facilities for manipulating DNS names and labels, including * conversions to and from wire format and text format. * @@ -45,26 +44,26 @@ * handles. * * MP: - * Clients of this module must impose any required synchronization. + *\li Clients of this module must impose any required synchronization. * * Reliability: - * This module deals with low-level byte streams. Errors in any of + *\li This module deals with low-level byte streams. Errors in any of * the functions are likely to crash the server or corrupt memory. * * Resources: - * None. + *\li None. * * Security: * - * *** WARNING *** + *\li *** WARNING *** * - * dns_name_fromwire() deals with raw network data. An error in + *\li dns_name_fromwire() deals with raw network data. An error in * this routine could result in the failure or hijacking of the server. * * Standards: - * RFC 1035 - * Draft EDNS0 (0) - * Draft Binary Labels (2) + *\li RFC1035 + *\li Draft EDNS0 (0) + *\li Draft Binary Labels (2) * */ @@ -109,7 +108,7 @@ ISC_LANG_BEGINDECLS *** Types ***/ -/* +/*% * Clients are strongly discouraged from using this type directly, with * the exception of the 'link' and 'list' fields which may be used directly * for whatever purpose the client desires. @@ -135,22 +134,22 @@ struct dns_name { /* * Attributes below 0x0100 reserved for name.c usage. */ -#define DNS_NAMEATTR_CACHE 0x0100 /* Used by resolver. */ -#define DNS_NAMEATTR_ANSWER 0x0200 /* Used by resolver. */ -#define DNS_NAMEATTR_NCACHE 0x0400 /* Used by resolver. */ -#define DNS_NAMEATTR_CHAINING 0x0800 /* Used by resolver. */ -#define DNS_NAMEATTR_CHASE 0x1000 /* Used by resolver. */ -#define DNS_NAMEATTR_WILDCARD 0x2000 /* Used by server. */ +#define DNS_NAMEATTR_CACHE 0x0100 /*%< Used by resolver. */ +#define DNS_NAMEATTR_ANSWER 0x0200 /*%< Used by resolver. */ +#define DNS_NAMEATTR_NCACHE 0x0400 /*%< Used by resolver. */ +#define DNS_NAMEATTR_CHAINING 0x0800 /*%< Used by resolver. */ +#define DNS_NAMEATTR_CHASE 0x1000 /*%< Used by resolver. */ +#define DNS_NAMEATTR_WILDCARD 0x2000 /*%< Used by server. */ #define DNS_NAME_DOWNCASE 0x0001 -#define DNS_NAME_CHECKNAMES 0x0002 /* Used by rdata. */ -#define DNS_NAME_CHECKNAMESFAIL 0x0004 /* Used by rdata. */ -#define DNS_NAME_CHECKREVERSE 0x0008 /* Used by rdata. */ +#define DNS_NAME_CHECKNAMES 0x0002 /*%< Used by rdata. */ +#define DNS_NAME_CHECKNAMESFAIL 0x0004 /*%< Used by rdata. */ +#define DNS_NAME_CHECKREVERSE 0x0008 /*%< Used by rdata. */ LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_rootname; LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_wildcardname; -/* +/*% * Standard size of a wire format name */ #define DNS_NAME_MAXWIRE 255 @@ -161,63 +160,63 @@ LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_wildcardname; void dns_name_init(dns_name_t *name, unsigned char *offsets); -/* +/*%< * Initialize 'name'. * * Notes: - * 'offsets' is never required to be non-NULL, but specifying a + * \li 'offsets' is never required to be non-NULL, but specifying a * dns_offsets_t for 'offsets' will improve the performance of most * name operations if the name is used more than once. * * Requires: - * 'name' is not NULL and points to a struct dns_name. + * \li 'name' is not NULL and points to a struct dns_name. * - * offsets == NULL or offsets is a dns_offsets_t. + * \li offsets == NULL or offsets is a dns_offsets_t. * * Ensures: - * 'name' is a valid name. - * dns_name_countlabels(name) == 0 - * dns_name_isabsolute(name) == ISC_FALSE + * \li 'name' is a valid name. + * \li dns_name_countlabels(name) == 0 + * \li dns_name_isabsolute(name) == ISC_FALSE */ void dns_name_reset(dns_name_t *name); -/* +/*%< * Reinitialize 'name'. * * Notes: - * This function distinguishes itself from dns_name_init() in two + * \li This function distinguishes itself from dns_name_init() in two * key ways: * - * + If any buffer is associated with 'name' (via dns_name_setbuffer() + * \li + If any buffer is associated with 'name' (via dns_name_setbuffer() * or by being part of a dns_fixedname_t) the link to the buffer * is retained but the buffer itself is cleared. * - * + Of the attributes associated with 'name', all are retained except + * \li + Of the attributes associated with 'name', all are retained except * DNS_NAMEATTR_ABSOLUTE. * * Requires: - * 'name' is a valid name. + * \li 'name' is a valid name. * * Ensures: - * 'name' is a valid name. - * dns_name_countlabels(name) == 0 - * dns_name_isabsolute(name) == ISC_FALSE + * \li 'name' is a valid name. + * \li dns_name_countlabels(name) == 0 + * \li dns_name_isabsolute(name) == ISC_FALSE */ void dns_name_invalidate(dns_name_t *name); -/* +/*%< * Make 'name' invalid. * * Requires: - * 'name' is a valid name. + * \li 'name' is a valid name. * * Ensures: - * If assertion checking is enabled, future attempts to use 'name' + * \li If assertion checking is enabled, future attempts to use 'name' * without initializing it will cause an assertion failure. * - * If the name had a dedicated buffer, that association is ended. + * \li If the name had a dedicated buffer, that association is ended. */ @@ -227,40 +226,40 @@ dns_name_invalidate(dns_name_t *name); void dns_name_setbuffer(dns_name_t *name, isc_buffer_t *buffer); -/* +/*%< * Dedicate a buffer for use with 'name'. * * Notes: - * Specification of a target buffer in dns_name_fromwire(), + * \li Specification of a target buffer in dns_name_fromwire(), * dns_name_fromtext(), and dns_name_concatentate() is optional if * 'name' has a dedicated buffer. * - * The caller must not write to buffer until the name has been + * \li The caller must not write to buffer until the name has been * invalidated or is otherwise known not to be in use. * - * If buffer is NULL and the name previously had a dedicated buffer, + * \li If buffer is NULL and the name previously had a dedicated buffer, * than that buffer is no longer dedicated to use with this name. * The caller is responsible for ensuring that the storage used by * the name remains valid. * * Requires: - * 'name' is a valid name. + * \li 'name' is a valid name. * - * 'buffer' is a valid binary buffer and 'name' doesn't have a + * \li 'buffer' is a valid binary buffer and 'name' doesn't have a * dedicated buffer already, or 'buffer' is NULL. */ isc_boolean_t dns_name_hasbuffer(const dns_name_t *name); -/* +/*%< * Does 'name' have a dedicated buffer? * * Requires: - * 'name' is a valid name. + * \li 'name' is a valid name. * * Returns: - * ISC_TRUE 'name' has a dedicated buffer. - * ISC_FALSE 'name' does not have a dedicated buffer. + * \li ISC_TRUE 'name' has a dedicated buffer. + * \li ISC_FALSE 'name' does not have a dedicated buffer. */ @@ -270,50 +269,50 @@ dns_name_hasbuffer(const dns_name_t *name); isc_boolean_t dns_name_isabsolute(const dns_name_t *name); -/* +/*%< * Does 'name' end in the root label? * * Requires: - * 'name' is a valid name + * \li 'name' is a valid name * * Returns: - * TRUE The last label in 'name' is the root label. - * FALSE The last label in 'name' is not the root label. + * \li TRUE The last label in 'name' is the root label. + * \li FALSE The last label in 'name' is not the root label. */ isc_boolean_t dns_name_iswildcard(const dns_name_t *name); -/* +/*%< * Is 'name' a wildcard name? * * Requires: - * 'name' is a valid name + * \li 'name' is a valid name * - * dns_name_countlabels(name) > 0 + * \li dns_name_countlabels(name) > 0 * * Returns: - * TRUE The least significant label of 'name' is '*'. - * FALSE The least significant label of 'name' is not '*'. + * \li TRUE The least significant label of 'name' is '*'. + * \li FALSE The least significant label of 'name' is not '*'. */ unsigned int dns_name_hash(dns_name_t *name, isc_boolean_t case_sensitive); -/* +/*%< * Provide a hash value for 'name'. * * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in * case will have the same hash value. * * Requires: - * 'name' is a valid name + * \li 'name' is a valid name * * Returns: - * A hash value + * \li A hash value */ unsigned int dns_name_fullhash(dns_name_t *name, isc_boolean_t case_sensitive); -/* +/*%< * Provide a hash value for 'name'. Unlike dns_name_hash(), this function * always takes into account of the entire name to calculate the hash value. * @@ -321,15 +320,15 @@ dns_name_fullhash(dns_name_t *name, isc_boolean_t case_sensitive); * case will have the same hash value. * * Requires: - * 'name' is a valid name + *\li 'name' is a valid name * * Returns: - * A hash value + *\li A hash value */ unsigned int dns_name_hashbylabel(dns_name_t *name, isc_boolean_t case_sensitive); -/* +/*%< * Provide a hash value for 'name', where the hash value is the sum * of the hash values of each label. * @@ -337,20 +336,20 @@ dns_name_hashbylabel(dns_name_t *name, isc_boolean_t case_sensitive); * case will have the same hash value. * * Requires: - * 'name' is a valid name + *\li 'name' is a valid name * * Returns: - * A hash value + *\li A hash value */ -/*** +/* *** Comparisons ***/ dns_namereln_t dns_name_fullcompare(const dns_name_t *name1, const dns_name_t *name2, int *orderp, unsigned int *nlabelsp); -/* +/*%< * Determine the relative ordering under the DNSSEC order relation of * 'name1' and 'name2', and also determine the hierarchical * relationship of the names. @@ -361,39 +360,39 @@ dns_name_fullcompare(const dns_name_t *name1, const dns_name_t *name2, * same domain. * * Requires: - * 'name1' is a valid name + *\li 'name1' is a valid name * - * dns_name_countlabels(name1) > 0 + *\li dns_name_countlabels(name1) > 0 * - * 'name2' is a valid name + *\li 'name2' is a valid name * - * dns_name_countlabels(name2) > 0 + *\li dns_name_countlabels(name2) > 0 * - * orderp and nlabelsp are valid pointers. + *\li orderp and nlabelsp are valid pointers. * - * Either name1 is absolute and name2 is absolute, or neither is. + *\li Either name1 is absolute and name2 is absolute, or neither is. * * Ensures: * - * *orderp is < 0 if name1 < name2, 0 if name1 = name2, > 0 if + *\li *orderp is < 0 if name1 < name2, 0 if name1 = name2, > 0 if * name1 > name2. * - * *nlabelsp is the number of common significant labels. + *\li *nlabelsp is the number of common significant labels. * * Returns: - * dns_namereln_none There's no hierarchical relationship + *\li dns_namereln_none There's no hierarchical relationship * between name1 and name2. - * dns_namereln_contains name1 properly contains name2; i.e. + *\li dns_namereln_contains name1 properly contains name2; i.e. * name2 is a proper subdomain of name1. - * dns_namereln_subdomain name1 is a proper subdomain of name2. - * dns_namereln_equal name1 and name2 are equal. - * dns_namereln_commonancestor name1 and name2 share a common + *\li dns_namereln_subdomain name1 is a proper subdomain of name2. + *\li dns_namereln_equal name1 and name2 are equal. + *\li dns_namereln_commonancestor name1 and name2 share a common * ancestor. */ int dns_name_compare(const dns_name_t *name1, const dns_name_t *name2); -/* +/*%< * Determine the relative ordering under the DNSSEC order relation of * 'name1' and 'name2'. * @@ -403,126 +402,130 @@ dns_name_compare(const dns_name_t *name1, const dns_name_t *name2); * same domain. * * Requires: - * 'name1' is a valid name + * \li 'name1' is a valid name * - * 'name2' is a valid name + * \li 'name2' is a valid name * - * Either name1 is absolute and name2 is absolute, or neither is. + * \li Either name1 is absolute and name2 is absolute, or neither is. * * Returns: - * < 0 'name1' is less than 'name2' - * 0 'name1' is equal to 'name2' - * > 0 'name1' is greater than 'name2' + * \li < 0 'name1' is less than 'name2' + * \li 0 'name1' is equal to 'name2' + * \li > 0 'name1' is greater than 'name2' */ isc_boolean_t dns_name_equal(const dns_name_t *name1, const dns_name_t *name2); -isc_boolean_t -dns_name_caseequal(const dns_name_t *name1, const dns_name_t *name2); -/* +/*%< * Are 'name1' and 'name2' equal? * * Notes: - * Because it only needs to test for equality, dns_name_equal() can be + * \li Because it only needs to test for equality, dns_name_equal() can be * significantly faster than dns_name_fullcompare() or dns_name_compare(). * - * Offsets tables are not used in the comparision. + * \li Offsets tables are not used in the comparision. * - * It makes no sense for one of the names to be relative and the + * \li It makes no sense for one of the names to be relative and the * other absolute. If both names are relative, then to be meaningfully * compared the caller must ensure that they are both relative to the * same domain. * * Requires: - * 'name1' is a valid name + * \li 'name1' is a valid name * - * 'name2' is a valid name + * \li 'name2' is a valid name * - * Either name1 is absolute and name2 is absolute, or neither is. + * \li Either name1 is absolute and name2 is absolute, or neither is. * * Returns: - * ISC_TRUE 'name1' and 'name2' are equal - * ISC_FALSE 'name1' and 'name2' are not equal + * \li ISC_TRUE 'name1' and 'name2' are equal + * \li ISC_FALSE 'name1' and 'name2' are not equal + */ + +isc_boolean_t +dns_name_caseequal(const dns_name_t *name1, const dns_name_t *name2); +/*%< + * Case sensitive version of dns_name_equal(). */ int dns_name_rdatacompare(const dns_name_t *name1, const dns_name_t *name2); -/* +/*%< * Compare two names as if they are part of rdata in DNSSEC canonical * form. * * Requires: - * 'name1' is a valid absolute name + * \li 'name1' is a valid absolute name * - * dns_name_countlabels(name1) > 0 + * \li dns_name_countlabels(name1) > 0 * - * 'name2' is a valid absolute name + * \li 'name2' is a valid absolute name * - * dns_name_countlabels(name2) > 0 + * \li dns_name_countlabels(name2) > 0 * * Returns: - * < 0 'name1' is less than 'name2' - * 0 'name1' is equal to 'name2' - * > 0 'name1' is greater than 'name2' + * \li < 0 'name1' is less than 'name2' + * \li 0 'name1' is equal to 'name2' + * \li > 0 'name1' is greater than 'name2' */ isc_boolean_t dns_name_issubdomain(const dns_name_t *name1, const dns_name_t *name2); -/* +/*%< * Is 'name1' a subdomain of 'name2'? * * Notes: - * name1 is a subdomain of name2 if name1 is contained in name2, or + * \li name1 is a subdomain of name2 if name1 is contained in name2, or * name1 equals name2. * - * It makes no sense for one of the names to be relative and the + * \li It makes no sense for one of the names to be relative and the * other absolute. If both names are relative, then to be meaningfully * compared the caller must ensure that they are both relative to the * same domain. * * Requires: - * 'name1' is a valid name + * \li 'name1' is a valid name * - * 'name2' is a valid name + * \li 'name2' is a valid name * - * Either name1 is absolute and name2 is absolute, or neither is. + * \li Either name1 is absolute and name2 is absolute, or neither is. * * Returns: - * TRUE 'name1' is a subdomain of 'name2' - * FALSE 'name1' is not a subdomain of 'name2' + * \li TRUE 'name1' is a subdomain of 'name2' + * \li FALSE 'name1' is not a subdomain of 'name2' */ isc_boolean_t dns_name_matcheswildcard(const dns_name_t *name, const dns_name_t *wname); -/* +/*%< * Does 'name' match the wildcard specified in 'wname'? * * Notes: - * name matches the wildcard specified in wname if all labels + * \li name matches the wildcard specified in wname if all labels * following the wildcard in wname are identical to the same number * of labels at the end of name. * - * It makes no sense for one of the names to be relative and the + * \li It makes no sense for one of the names to be relative and the * other absolute. If both names are relative, then to be meaningfully * compared the caller must ensure that they are both relative to the * same domain. * * Requires: - * 'name' is a valid name + * \li 'name' is a valid name * - * dns_name_countlabels(name) > 0 + * \li dns_name_countlabels(name) > 0 * - * 'wname' is a valid name + * \li 'wname' is a valid name * - * dns_name_countlabels(wname) > 0 + * \li dns_name_countlabels(wname) > 0 * - * dns_name_iswildcard(wname) is true + * \li dns_name_iswildcard(wname) is true * - * Either name is absolute and wname is absolute, or neither is. + * \li Either name is absolute and wname is absolute, or neither is. * * Returns: - * TRUE 'name' matches the wildcard specified in 'wname' - * FALSE 'name' does not match the wildcard specified in 'wname' + * \li TRUE 'name' matches the wildcard specified in 'wname' + * \li FALSE 'name' does not match the wildcard specified in 'wname' */ /*** @@ -531,89 +534,91 @@ dns_name_matcheswildcard(const dns_name_t *name, const dns_name_t *wname); unsigned int dns_name_countlabels(const dns_name_t *name); -/* +/*%< * How many labels does 'name' have? * * Notes: - * In this case, as in other places, a 'label' is an ordinary label. + * \li In this case, as in other places, a 'label' is an ordinary label. * * Requires: - * 'name' is a valid name + * \li 'name' is a valid name * * Ensures: - * The result is <= 128. + * \li The result is <= 128. * * Returns: - * The number of labels in 'name'. + * \li The number of labels in 'name'. */ void dns_name_getlabel(const dns_name_t *name, unsigned int n, dns_label_t *label); -/* +/*%< * Make 'label' refer to the 'n'th least significant label of 'name'. * * Notes: - * Numbering starts at 0. + * \li Numbering starts at 0. * - * Given "rc.vix.com.", the label 0 is "rc", and label 3 is the + * \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the * root label. * - * 'label' refers to the same memory as 'name', so 'name' must not + * \li 'label' refers to the same memory as 'name', so 'name' must not * be changed while 'label' is still in use. * * Requires: - * n < dns_name_countlabels(name) + * \li n < dns_name_countlabels(name) */ void dns_name_getlabelsequence(const dns_name_t *source, unsigned int first, unsigned int n, dns_name_t *target); -/* +/*%< * Make 'target' refer to the 'n' labels including and following 'first' * in 'source'. * * Notes: - * Numbering starts at 0. + * \li Numbering starts at 0. * - * Given "rc.vix.com.", the label 0 is "rc", and label 3 is the + * \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the * root label. * - * 'target' refers to the same memory as 'source', so 'source' + * \li 'target' refers to the same memory as 'source', so 'source' * must not be changed while 'target' is still in use. * * Requires: - * 'source' and 'target' are valid names. + * \li 'source' and 'target' are valid names. * - * first < dns_name_countlabels(name) + * \li first < dns_name_countlabels(name) * - * first + n <= dns_name_countlabels(name) + * \li first + n <= dns_name_countlabels(name) */ void dns_name_clone(dns_name_t *source, dns_name_t *target); -/* +/*%< * Make 'target' refer to the same name as 'source'. * * Notes: * - * 'target' refers to the same memory as 'source', so 'source' + * \li 'target' refers to the same memory as 'source', so 'source' * must not be changed while 'target' is still in use. * - * This call is functionally equivalent to: + * \li This call is functionally equivalent to: * + * \code * dns_name_getlabelsequence(source, 0, * dns_name_countlabels(source), * target); + * \endcode * * but is more efficient. Also, dns_name_clone() works even if 'source' * is empty. * * Requires: * - * 'source' is a valid name. + * \li 'source' is a valid name. * - * 'target' is a valid name that is not read-only. + * \li 'target' is a valid name that is not read-only. */ /*** @@ -622,205 +627,204 @@ dns_name_clone(dns_name_t *source, dns_name_t *target); void dns_name_fromregion(dns_name_t *name, const isc_region_t *r); -/* +/*%< * Make 'name' refer to region 'r'. * * Note: - * If the conversion encounters a root label before the end of the + * \li If the conversion encounters a root label before the end of the * region the conversion stops and the length is set to the length * so far converted. A maximum of 255 bytes is converted. * * Requires: - * The data in 'r' is a sequence of one or more type 00 or type 01000001 + * \li The data in 'r' is a sequence of one or more type 00 or type 01000001 * labels. */ void dns_name_toregion(dns_name_t *name, isc_region_t *r); -/* +/*%< * Make 'r' refer to 'name'. * * Requires: * - * 'name' is a valid name. + * \li 'name' is a valid name. * - * 'r' is a valid region. + * \li 'r' is a valid region. */ isc_result_t dns_name_fromwire(dns_name_t *name, isc_buffer_t *source, dns_decompress_t *dctx, unsigned int options, isc_buffer_t *target); -/* +/*%< * Copy the possibly-compressed name at source (active region) into target, * decompressing it. * * Notes: - * Decompression policy is controlled by 'dctx'. + * \li Decompression policy is controlled by 'dctx'. * - * If DNS_NAME_DOWNCASE is set, any uppercase letters in 'source' will be + * \li If DNS_NAME_DOWNCASE is set, any uppercase letters in 'source' will be * downcased when they are copied into 'target'. * * Security: * - * *** WARNING *** + * \li *** WARNING *** * - * This routine will often be used when 'source' contains raw network + * \li This routine will often be used when 'source' contains raw network * data. A programming error in this routine could result in a denial * of service, or in the hijacking of the server. * * Requires: * - * 'name' is a valid name. + * \li 'name' is a valid name. * - * 'source' is a valid buffer and the first byte of the active + * \li 'source' is a valid buffer and the first byte of the active * region should be the first byte of a DNS wire format domain name. * - * 'target' is a valid buffer or 'target' is NULL and 'name' has + * \li 'target' is a valid buffer or 'target' is NULL and 'name' has * a dedicated buffer. * - * 'dctx' is a valid decompression context. + * \li 'dctx' is a valid decompression context. * * Ensures: * * If result is success: - * If 'target' is not NULL, 'name' is attached to it. + * \li If 'target' is not NULL, 'name' is attached to it. * - * Uppercase letters are downcased in the copy iff + * \li Uppercase letters are downcased in the copy iff * DNS_NAME_DOWNCASE is set in options. * - * The current location in source is advanced, and the used space + * \li The current location in source is advanced, and the used space * in target is updated. * * Result: - * Success - * Bad Form: Label Length - * Bad Form: Unknown Label Type - * Bad Form: Name Length - * Bad Form: Compression type not allowed - * Bad Form: Bad compression pointer - * Bad Form: Input too short - * Resource Limit: Too many compression pointers - * Resource Limit: Not enough space in buffer + * \li Success + * \li Bad Form: Label Length + * \li Bad Form: Unknown Label Type + * \li Bad Form: Name Length + * \li Bad Form: Compression type not allowed + * \li Bad Form: Bad compression pointer + * \li Bad Form: Input too short + * \li Resource Limit: Too many compression pointers + * \li Resource Limit: Not enough space in buffer */ isc_result_t dns_name_towire(dns_name_t *name, dns_compress_t *cctx, isc_buffer_t *target); -/* +/*%< * Convert 'name' into wire format, compressing it as specified by the * compression context 'cctx', and storing the result in 'target'. * * Notes: - * If the compression context allows global compression, then the + * \li If the compression context allows global compression, then the * global compression table may be updated. * * Requires: - * 'name' is a valid name + * \li 'name' is a valid name * - * dns_name_countlabels(name) > 0 + * \li dns_name_countlabels(name) > 0 * - * dns_name_isabsolute(name) == TRUE + * \li dns_name_isabsolute(name) == TRUE * - * target is a valid buffer. + * \li target is a valid buffer. * - * Any offsets specified in a global compression table are valid + * \li Any offsets specified in a global compression table are valid * for buffer. * * Ensures: * * If the result is success: * - * The used space in target is updated. + * \li The used space in target is updated. * * Returns: - * Success - * Resource Limit: Not enough space in buffer + * \li Success + * \li Resource Limit: Not enough space in buffer */ isc_result_t dns_name_fromtext(dns_name_t *name, isc_buffer_t *source, dns_name_t *origin, unsigned int options, isc_buffer_t *target); -/* +/*%< * Convert the textual representation of a DNS name at source * into uncompressed wire form stored in target. * * Notes: - * Relative domain names will have 'origin' appended to them + * \li Relative domain names will have 'origin' appended to them * unless 'origin' is NULL, in which case relative domain names * will remain relative. * - * If DNS_NAME_DOWNCASE is set in 'options', any uppercase letters + * \li If DNS_NAME_DOWNCASE is set in 'options', any uppercase letters * in 'source' will be downcased when they are copied into 'target'. * * Requires: * - * 'name' is a valid name. + * \li 'name' is a valid name. * - * 'source' is a valid buffer. + * \li 'source' is a valid buffer. * - * 'target' is a valid buffer or 'target' is NULL and 'name' has + * \li 'target' is a valid buffer or 'target' is NULL and 'name' has * a dedicated buffer. * * Ensures: * * If result is success: - * If 'target' is not NULL, 'name' is attached to it. + * \li If 'target' is not NULL, 'name' is attached to it. * - * Uppercase letters are downcased in the copy iff + * \li Uppercase letters are downcased in the copy iff * DNS_NAME_DOWNCASE is set in 'options'. * - * The current location in source is advanced, and the used space + * \li The current location in source is advanced, and the used space * in target is updated. * * Result: - * ISC_R_SUCCESS - * DNS_R_EMPTYLABEL - * DNS_R_LABELTOOLONG - * DNS_R_BADESCAPE - * (DNS_R_BADBITSTRING: should not be returned) - * (DNS_R_BITSTRINGTOOLONG: should not be returned) - * DNS_R_BADDOTTEDQUAD - * ISC_R_NOSPACE - * ISC_R_UNEXPECTEDEND + *\li #ISC_R_SUCCESS + *\li #DNS_R_EMPTYLABEL + *\li #DNS_R_LABELTOOLONG + *\li #DNS_R_BADESCAPE + *\li (#DNS_R_BADBITSTRING: should not be returned) + *\li (#DNS_R_BITSTRINGTOOLONG: should not be returned) + *\li #DNS_R_BADDOTTEDQUAD + *\li #ISC_R_NOSPACE + *\li #ISC_R_UNEXPECTEDEND */ isc_result_t dns_name_totext(dns_name_t *name, isc_boolean_t omit_final_dot, isc_buffer_t *target); -/* +/*%< * Convert 'name' into text format, storing the result in 'target'. * * Notes: - * If 'omit_final_dot' is true, then the final '.' in absolute + *\li If 'omit_final_dot' is true, then the final '.' in absolute * names other than the root name will be omitted. * - * If dns_name_countlabels == 0, the name will be "@", representing the - * current origin as described by RFC 1035. + *\li If dns_name_countlabels == 0, the name will be "@", representing the + * current origin as described by RFC1035. * - * The name is not NUL terminated. + *\li The name is not NUL terminated. * * Requires: * - * 'name' is a valid name + *\li 'name' is a valid name * - * 'target' is a valid buffer. + *\li 'target' is a valid buffer. * - * if dns_name_isabsolute == FALSE, then omit_final_dot == FALSE + *\li if dns_name_isabsolute == FALSE, then omit_final_dot == FALSE * * Ensures: * - * If the result is success: - * - * The used space in target is updated. + *\li If the result is success: + * the used space in target is updated. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE */ #define DNS_NAME_MAXTEXT 1023 -/* +/*%< * The maximum length of the text representation of a domain * name as generated by dns_name_totext(). This does not * include space for a terminating NULL. @@ -845,56 +849,53 @@ dns_name_totext(dns_name_t *name, isc_boolean_t omit_final_dot, isc_result_t dns_name_tofilenametext(dns_name_t *name, isc_boolean_t omit_final_dot, isc_buffer_t *target); -/* +/*%< * Convert 'name' into an alternate text format appropriate for filenames, * storing the result in 'target'. The name data is downcased, guaranteeing * that the filename does not depend on the case of the converted name. * * Notes: - * If 'omit_final_dot' is true, then the final '.' in absolute + *\li If 'omit_final_dot' is true, then the final '.' in absolute * names other than the root name will be omitted. * - * The name is not NUL terminated. + *\li The name is not NUL terminated. * * Requires: * - * 'name' is a valid absolute name + *\li 'name' is a valid absolute name * - * 'target' is a valid buffer. + *\li 'target' is a valid buffer. * * Ensures: * - * If the result is success: - * - * The used space in target is updated. + *\li If the result is success: + * the used space in target is updated. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE */ isc_result_t dns_name_downcase(dns_name_t *source, dns_name_t *name, isc_buffer_t *target); -/* +/*%< * Downcase 'source'. * * Requires: * - * 'source' and 'name' are valid names. - * - * If source == name, then + *\li 'source' and 'name' are valid names. * + *\li If source == name, then * 'source' must not be read-only * - * Otherwise, - * + *\li Otherwise, * 'target' is a valid buffer or 'target' is NULL and * 'name' has a dedicated buffer. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE * * Note: if source == name, then the result will always be ISC_R_SUCCESS. */ @@ -902,199 +903,197 @@ dns_name_downcase(dns_name_t *source, dns_name_t *name, isc_result_t dns_name_concatenate(dns_name_t *prefix, dns_name_t *suffix, dns_name_t *name, isc_buffer_t *target); -/* +/*%< * Concatenate 'prefix' and 'suffix'. * * Requires: * - * 'prefix' is a valid name or NULL. + *\li 'prefix' is a valid name or NULL. * - * 'suffix' is a valid name or NULL. + *\li 'suffix' is a valid name or NULL. * - * 'name' is a valid name or NULL. + *\li 'name' is a valid name or NULL. * - * 'target' is a valid buffer or 'target' is NULL and 'name' has + *\li 'target' is a valid buffer or 'target' is NULL and 'name' has * a dedicated buffer. * - * If 'prefix' is absolute, 'suffix' must be NULL or the empty name. + *\li If 'prefix' is absolute, 'suffix' must be NULL or the empty name. * * Ensures: * - * On success, + *\li On success, * If 'target' is not NULL and 'name' is not NULL, then 'name' * is attached to it. - * * The used space in target is updated. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE - * DNS_R_NAMETOOLONG + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE + *\li #DNS_R_NAMETOOLONG */ void dns_name_split(dns_name_t *name, unsigned int suffixlabels, dns_name_t *prefix, dns_name_t *suffix); -/* +/*%< * * Split 'name' into two pieces on a label boundary. * * Notes: - * 'name' is split such that 'suffix' holds the most significant + * \li 'name' is split such that 'suffix' holds the most significant * 'suffixlabels' labels. All other labels are stored in 'prefix'. * - * Copying name data is avoided as much as possible, so 'prefix' + *\li Copying name data is avoided as much as possible, so 'prefix' * and 'suffix' will end up pointing at the data for 'name'. * - * It is legitimate to pass a 'prefix' or 'suffix' that has + *\li It is legitimate to pass a 'prefix' or 'suffix' that has * its name data stored someplace other than the dedicated buffer. * This is useful to avoid name copying in the calling function. * - * It is also legitimate to pass a 'prefix' or 'suffix' that is + *\li It is also legitimate to pass a 'prefix' or 'suffix' that is * the same dns_name_t as 'name'. * * Requires: - * 'name' is a valid name. + *\li 'name' is a valid name. * - * 'suffixlabels' cannot exceed the number of labels in 'name'. + * \li 'suffixlabels' cannot exceed the number of labels in 'name'. * - * 'prefix' is a valid name or NULL, and cannot be read-only. + *\li 'prefix' is a valid name or NULL, and cannot be read-only. * - * 'suffix' is a valid name or NULL, and cannot be read-only. + *\li 'suffix' is a valid name or NULL, and cannot be read-only. * - * If non-NULL, 'prefix' and 'suffix' must have dedicated buffers. + *\li If non-NULL, 'prefix' and 'suffix' must have dedicated buffers. * - * 'prefix' and 'suffix' cannot point to the same buffer. + *\li 'prefix' and 'suffix' cannot point to the same buffer. * * Ensures: * - * On success: + *\li On success: * If 'prefix' is not NULL it will contain the least significant * labels. - * * If 'suffix' is not NULL it will contain the most significant * labels. dns_name_countlabels(suffix) will be equal to * suffixlabels. * - * On failure: + *\li On failure: * Either 'prefix' or 'suffix' is invalidated (depending * on which one the problem was encountered with). * * Returns: - * ISC_R_SUCCESS No worries. (This function should always success). + *\li #ISC_R_SUCCESS No worries. (This function should always success). */ isc_result_t dns_name_dup(dns_name_t *source, isc_mem_t *mctx, dns_name_t *target); -/* +/*%< * Make 'target' a dynamically allocated copy of 'source'. * * Requires: * - * 'source' is a valid non-empty name. + *\li 'source' is a valid non-empty name. * - * 'target' is a valid name that is not read-only. + *\li 'target' is a valid name that is not read-only. * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. */ isc_result_t dns_name_dupwithoffsets(dns_name_t *source, isc_mem_t *mctx, dns_name_t *target); -/* +/*%< * Make 'target' a read-only dynamically allocated copy of 'source'. * 'target' will also have a dynamically allocated offsets table. * * Requires: * - * 'source' is a valid non-empty name. + *\li 'source' is a valid non-empty name. * - * 'target' is a valid name that is not read-only. + *\li 'target' is a valid name that is not read-only. * - * 'target' has no offsets table. + *\li 'target' has no offsets table. * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. */ void dns_name_free(dns_name_t *name, isc_mem_t *mctx); -/* +/*%< * Free 'name'. * * Requires: * - * 'name' is a valid name created previously in 'mctx' by dns_name_dup(). + *\li 'name' is a valid name created previously in 'mctx' by dns_name_dup(). * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. * * Ensures: * - * All dynamic resources used by 'name' are freed and the name is + *\li All dynamic resources used by 'name' are freed and the name is * invalidated. */ isc_result_t dns_name_digest(dns_name_t *name, dns_digestfunc_t digest, void *arg); -/* +/*%< * Send 'name' in DNSSEC canonical form to 'digest'. * * Requires: * - * 'name' is a valid name. + *\li 'name' is a valid name. * - * 'digest' is a valid dns_digestfunc_t. + *\li 'digest' is a valid dns_digestfunc_t. * * Ensures: * - * If successful, the DNSSEC canonical form of 'name' will have been + *\li If successful, the DNSSEC canonical form of 'name' will have been * sent to 'digest'. * - * If digest() returns something other than ISC_R_SUCCESS, that result + *\li If digest() returns something other than ISC_R_SUCCESS, that result * will be returned as the result of dns_name_digest(). * * Returns: * - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * - * Many other results are possible if not successful. + *\li Many other results are possible if not successful. * */ isc_boolean_t dns_name_dynamic(dns_name_t *name); -/* +/*%< * Returns whether there is dynamic memory associated with this name. * * Requires: * - * 'name' is a valid name. + *\li 'name' is a valid name. * * Returns: * - * 'ISC_TRUE' if the name is dynamic othewise 'ISC_FALSE'. + *\li 'ISC_TRUE' if the name is dynamic othewise 'ISC_FALSE'. */ isc_result_t dns_name_print(dns_name_t *name, FILE *stream); -/* +/*%< * Print 'name' on 'stream'. * * Requires: * - * 'name' is a valid name. + *\li 'name' is a valid name. * - * 'stream' is a valid stream. + *\li 'stream' is a valid stream. * * Returns: * - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * - * Any error that dns_name_totext() can return. + *\li Any error that dns_name_totext() can return. */ void dns_name_format(dns_name_t *name, char *cp, unsigned int size); -/* +/*%< * Format 'name' as text appropriate for use in log messages. * * Store the formatted name at 'cp', writing no more than @@ -1109,42 +1108,42 @@ dns_name_format(dns_name_t *name, char *cp, unsigned int size); * * Requires: * - * 'name' is a valid name. + *\li 'name' is a valid name. * - * 'cp' points a valid character array of size 'size'. + *\li 'cp' points a valid character array of size 'size'. * - * 'size' > 0. + *\li 'size' > 0. * */ #define DNS_NAME_FORMATSIZE (DNS_NAME_MAXTEXT + 1) -/* +/*%< * Suggested size of buffer passed to dns_name_format(). * Includes space for the terminating NULL. */ isc_result_t dns_name_copy(dns_name_t *source, dns_name_t *dest, isc_buffer_t *target); -/* +/*%< * Makes 'dest' refer to a copy of the name in 'source'. The data are * either copied to 'target' or the dedicated buffer in 'dest'. * * Requires: - * 'source' is a valid name. + * \li 'source' is a valid name. * - * 'dest' is an initialized name with a dedicated buffer. + * \li 'dest' is an initialized name with a dedicated buffer. * - * 'target' is NULL or an initialized buffer. + * \li 'target' is NULL or an initialized buffer. * - * Either dest has a dedicated buffer or target != NULL. + * \li Either dest has a dedicated buffer or target != NULL. * * Ensures: * - * On success, the used space in target is updated. + *\li On success, the used space in target is updated. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE */ isc_boolean_t @@ -1180,7 +1179,7 @@ dns_name_internalwildcard(const dns_name_t *name); ISC_LANG_ENDDECLS -/*** +/* *** High Peformance Macros ***/ diff --git a/lib/dns/include/dns/ncache.h b/lib/dns/include/dns/ncache.h index 321733fed3..aa3fa2bbc8 100644 --- a/lib/dns/include/dns/ncache.h +++ b/lib/dns/include/dns/ncache.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ncache.h,v 1.17 2004/03/05 05:09:44 marka Exp $ */ +/* $Id: ncache.h,v 1.18 2005/04/27 04:56:57 sra Exp $ */ #ifndef DNS_NCACHE_H #define DNS_NCACHE_H 1 @@ -24,25 +24,26 @@ ***** Module Info *****/ -/* +/*! \file + *\brief * DNS Ncache * - * XXX XXX + * XXX TBS XXX * * MP: - * The caller must ensure any required synchronization. + *\li The caller must ensure any required synchronization. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * RFC 2308 + *\li RFC2308 */ #include @@ -52,7 +53,7 @@ ISC_LANG_BEGINDECLS -/* +/*% * _OMITDNSSEC: * Omit DNSSEC records when rendering. */ @@ -62,7 +63,7 @@ isc_result_t dns_ncache_add(dns_message_t *message, dns_db_t *cache, dns_dbnode_t *node, dns_rdatatype_t covers, isc_stdtime_t now, dns_ttl_t maxttl, dns_rdataset_t *addedrdataset); -/* +/*%< * Convert the authority data from 'message' into a negative cache * rdataset, and store it in 'cache' at 'node' with a TTL limited to * 'maxttl'. @@ -71,21 +72,21 @@ dns_ncache_add(dns_message_t *message, dns_db_t *cache, dns_dbnode_t *node, * or dns_rdatatype_any when caching a NXDOMAIN response. * * Note: - * If 'addedrdataset' is not NULL, then it will be attached to the added + *\li If 'addedrdataset' is not NULL, then it will be attached to the added * rdataset. See dns_db_addrdataset() for more details. * * Requires: - * 'message' is a valid message with a properly formatting negative cache + *\li 'message' is a valid message with a properly formatting negative cache * authority section. * - * The requirements of dns_db_addrdataset() apply to 'cache', 'node', + *\li The requirements of dns_db_addrdataset() apply to 'cache', 'node', * 'now', and 'addedrdataset'. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE * - * Any result code of dns_db_addrdataset() is a possible result code + *\li Any result code of dns_db_addrdataset() is a possible result code * of dns_ncache_add(). */ @@ -93,63 +94,63 @@ isc_result_t dns_ncache_towire(dns_rdataset_t *rdataset, dns_compress_t *cctx, isc_buffer_t *target, unsigned int options, unsigned int *countp); -/* +/*%< * Convert the negative caching rdataset 'rdataset' to wire format, * compressing names as specified in 'cctx', and storing the result in * 'target'. If 'omit_dnssec' is set, DNSSEC records will not * be added to 'target'. * * Notes: - * The number of RRs added to target will be added to *countp. + *\li The number of RRs added to target will be added to *countp. * * Requires: - * 'rdataset' is a valid negative caching rdataset. + *\li 'rdataset' is a valid negative caching rdataset. * - * 'rdataset' is not empty. + *\li 'rdataset' is not empty. * - * 'countp' is a valid pointer. + *\li 'countp' is a valid pointer. * * Ensures: - * On a return of ISC_R_SUCCESS, 'target' contains a wire format + *\li On a return of ISC_R_SUCCESS, 'target' contains a wire format * for the data contained in 'rdataset'. Any error return leaves * the buffer unchanged. * - * *countp has been incremented by the number of RRs added to + *\li *countp has been incremented by the number of RRs added to * target. * * Returns: - * ISC_R_SUCCESS - all ok - * ISC_R_NOSPACE - 'target' doesn't have enough room + *\li #ISC_R_SUCCESS - all ok + *\li #ISC_R_NOSPACE - 'target' doesn't have enough room * - * Any error returned by dns_rdata_towire(), dns_rdataset_next(), + *\li Any error returned by dns_rdata_towire(), dns_rdataset_next(), * dns_name_towire(). */ isc_result_t dns_ncache_getrdataset(dns_rdataset_t *ncacherdataset, dns_name_t *name, dns_rdatatype_t type, dns_rdataset_t *rdataset); -/* +/*%< * Search the negative caching rdataset for an rdataset with the * specified name and type. * * Requires: - * 'ncacherdataset' is a valid negative caching rdataset. + *\li 'ncacherdataset' is a valid negative caching rdataset. * - * 'ncacherdataset' is not empty. + *\li 'ncacherdataset' is not empty. * - * 'name' is a valid name. + *\li 'name' is a valid name. * - * 'type' is not SIG, or a meta-RR type. + *\li 'type' is not SIG, or a meta-RR type. * - * 'rdataset' is a valid disassociated rdataset. + *\li 'rdataset' is a valid disassociated rdataset. * * Ensures: - * On a return of ISC_R_SUCCESS, 'rdataset' is bound to the found + *\li On a return of ISC_R_SUCCESS, 'rdataset' is bound to the found * rdataset. * * Returns: - * ISC_R_SUCCESS - the rdataset was found. - * ISC_R_NOTFOUND - the rdataset was not found. + *\li #ISC_R_SUCCESS - the rdataset was found. + *\li #ISC_R_NOTFOUND - the rdataset was not found. * */ diff --git a/lib/dns/include/dns/nsec.h b/lib/dns/include/dns/nsec.h index de00f26568..564b9177d0 100644 --- a/lib/dns/include/dns/nsec.h +++ b/lib/dns/include/dns/nsec.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: nsec.h,v 1.4 2004/03/05 05:09:44 marka Exp $ */ +/* $Id: nsec.h,v 1.5 2005/04/27 04:56:57 sra Exp $ */ #ifndef DNS_NSEC_H #define DNS_NSEC_H 1 +/*! \file */ + #include #include @@ -33,33 +35,33 @@ isc_result_t dns_nsec_buildrdata(dns_db_t *db, dns_dbversion_t *version, dns_dbnode_t *node, dns_name_t *target, unsigned char *buffer, dns_rdata_t *rdata); -/* +/*%< * Build the rdata of a NSEC record. * * Requires: - * buffer Points to a temporary buffer of at least + *\li buffer Points to a temporary buffer of at least * DNS_NSEC_BUFFERSIZE bytes. - * rdata Points to an initialized dns_rdata_t. + *\li rdata Points to an initialized dns_rdata_t. * * Ensures: - * *rdata Contains a valid NSEC rdata. The 'data' member refers + * \li *rdata Contains a valid NSEC rdata. The 'data' member refers * to 'buffer'. */ isc_result_t dns_nsec_build(dns_db_t *db, dns_dbversion_t *version, dns_dbnode_t *node, dns_name_t *target, dns_ttl_t ttl); -/* +/*%< * Build a NSEC record and add it to a database. */ isc_boolean_t dns_nsec_typepresent(dns_rdata_t *nsec, dns_rdatatype_t type); -/* +/*%< * Determine if a type is marked as present in an NSEC record. * * Requires: - * 'nsec' points to a valid rdataset of type NSEC + *\li 'nsec' points to a valid rdataset of type NSEC */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/opcode.h b/lib/dns/include/dns/opcode.h index 8789391a4c..15c04880f2 100644 --- a/lib/dns/include/dns/opcode.h +++ b/lib/dns/include/dns/opcode.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: opcode.h,v 1.2 2004/03/05 05:09:44 marka Exp $ */ +/* $Id: opcode.h,v 1.3 2005/04/27 04:56:57 sra Exp $ */ #ifndef DNS_OPCODE_H #define DNS_OPCODE_H 1 +/*! \file */ + #include #include @@ -27,21 +29,21 @@ ISC_LANG_BEGINDECLS isc_result_t dns_opcode_totext(dns_opcode_t opcode, isc_buffer_t *target); -/* +/*%< * Put a textual representation of error 'opcode' into 'target'. * * Requires: - * 'opcode' is a valid opcode. + *\li 'opcode' is a valid opcode. * - * 'target' is a valid text buffer. + *\li 'target' is a valid text buffer. * * Ensures: - * If the result is success: + *\li If the result is success: * The used space in 'target' is updated. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_NOSPACE target buffer is too small + *\li #ISC_R_SUCCESS on success + *\li #ISC_R_NOSPACE target buffer is too small */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/order.h b/lib/dns/include/dns/order.h index ad18439da5..cb9a2988cb 100644 --- a/lib/dns/include/dns/order.h +++ b/lib/dns/include/dns/order.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: order.h,v 1.3 2004/03/05 05:09:44 marka Exp $ */ +/* $Id: order.h,v 1.4 2005/04/27 04:56:57 sra Exp $ */ #ifndef DNS_ORDER_H #define DNS_ORDER_H 1 +/*! \file */ + #include #include @@ -29,67 +31,67 @@ ISC_LANG_BEGINDECLS isc_result_t dns_order_create(isc_mem_t *mctx, dns_order_t **orderp); -/* +/*%< * Create a order object. * * Requires: - * 'orderp' to be non NULL and '*orderp == NULL'. - * 'mctx' to be valid. + * \li 'orderp' to be non NULL and '*orderp == NULL'. + *\li 'mctx' to be valid. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li ISC_R_SUCCESS + *\li ISC_R_NOMEMORY */ isc_result_t dns_order_add(dns_order_t *order, dns_name_t *name, dns_rdatatype_t rdtype, dns_rdataclass_t rdclass, unsigned int mode); -/* +/*%< * Add a entry to the end of the order list. * * Requires: - * 'order' to be valid. - * 'name' to be valid. - * 'mode' to be one of DNS_RDATASERATTR_RANDOMIZE, - * DNS_RDATASERATTR_RANDOMIZE or zero (DNS_RDATASERATTR_CYCLIC). + * \li 'order' to be valid. + *\li 'name' to be valid. + *\li 'mode' to be one of #DNS_RDATASERATTR_RANDOMIZE, + * #DNS_RDATASERATTR_RANDOMIZE or zero (#DNS_RDATASERATTR_CYCLIC). * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ unsigned int dns_order_find(dns_order_t *order, dns_name_t *name, dns_rdatatype_t rdtype, dns_rdataclass_t rdclass); -/* +/*%< * Find the first matching entry on the list. * * Requires: - * 'order' to be valid. - * 'name' to be valid. + *\li 'order' to be valid. + *\li 'name' to be valid. * * Returns the mode set by dns_order_add() or zero. */ void dns_order_attach(dns_order_t *source, dns_order_t **target); -/* +/*%< * Attach to the 'source' object. * * Requires: - * 'source' to be valid. - * 'target' to be non NULL and '*target == NULL'. + * \li 'source' to be valid. + *\li 'target' to be non NULL and '*target == NULL'. */ void dns_order_detach(dns_order_t **orderp); -/* +/*%< * Detach from the object. Clean up if last this was the last * reference. * * Requires: - * '*orderp' to be valid. + *\li '*orderp' to be valid. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/peer.h b/lib/dns/include/dns/peer.h index 31501f5fdd..e8de6e3b9c 100644 --- a/lib/dns/include/dns/peer.h +++ b/lib/dns/include/dns/peer.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: peer.h,v 1.22 2005/01/17 23:58:32 marka Exp $ */ +/* $Id: peer.h,v 1.23 2005/04/27 04:56:57 sra Exp $ */ #ifndef DNS_PEER_H #define DNS_PEER_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * Data structures for peers (e.g. a 'server' config file statement) */ diff --git a/lib/dns/include/dns/portlist.h b/lib/dns/include/dns/portlist.h index 86ff186930..cf7a2ec69a 100644 --- a/lib/dns/include/dns/portlist.h +++ b/lib/dns/include/dns/portlist.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: portlist.h,v 1.3 2004/03/05 05:09:45 marka Exp $ */ +/* $Id: portlist.h,v 1.4 2005/04/27 04:56:58 sra Exp $ */ + +/*! \file */ #include #include @@ -27,73 +29,73 @@ ISC_LANG_BEGINDECLS isc_result_t dns_portlist_create(isc_mem_t *mctx, dns_portlist_t **portlistp); -/* +/*%< * Create a port list. * * Requires: - * 'mctx' to be valid. - * 'portlistp' to be non NULL and '*portlistp' to be NULL; + *\li 'mctx' to be valid. + *\li 'portlistp' to be non NULL and '*portlistp' to be NULL; * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED */ isc_result_t dns_portlist_add(dns_portlist_t *portlist, int af, in_port_t port); -/* +/*%< * Add the given tuple to the portlist. * * Requires: - * 'portlist' to be valid. - * 'af' to be AF_INET or AF_INET6 + *\li 'portlist' to be valid. + *\li 'af' to be AF_INET or AF_INET6 * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ void dns_portlist_remove(dns_portlist_t *portlist, int af, in_port_t port); -/* +/*%< * Remove the given tuple to the portlist. * * Requires: - * 'portlist' to be valid. - * 'af' to be AF_INET or AF_INET6 + *\li 'portlist' to be valid. + *\li 'af' to be AF_INET or AF_INET6 */ isc_boolean_t dns_portlist_match(dns_portlist_t *portlist, int af, in_port_t port); -/* +/*%< * Find the given tuple to the portlist. * * Requires: - * 'portlist' to be valid. - * 'af' to be AF_INET or AF_INET6 + *\li 'portlist' to be valid. + *\li 'af' to be AF_INET or AF_INET6 * * Returns - * ISC_TRUE if the tuple is found, ISC_FALSE otherwise. + * \li #ISC_TRUE if the tuple is found, ISC_FALSE otherwise. */ void dns_portlist_attach(dns_portlist_t *portlist, dns_portlist_t **portlistp); -/* +/*%< * Attach to a port list. * * Requires: - * 'portlist' to be valid. - * 'portlistp' to be non NULL and '*portlistp' to be NULL; + *\li 'portlist' to be valid. + *\li 'portlistp' to be non NULL and '*portlistp' to be NULL; */ void dns_portlist_detach(dns_portlist_t **portlistp); -/* +/*%< * Detach from a port list. * * Requires: - * '*portlistp' to be valid. + *\li '*portlistp' to be valid. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/rbt.h b/lib/dns/include/dns/rbt.h index d3461aa3fb..dd76bb25ea 100644 --- a/lib/dns/include/dns/rbt.h +++ b/lib/dns/include/dns/rbt.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rbt.h,v 1.60 2004/10/11 05:49:29 marka Exp $ */ +/* $Id: rbt.h,v 1.61 2005/04/27 04:56:58 sra Exp $ */ #ifndef DNS_RBT_H #define DNS_RBT_H 1 +/*! \file */ + #include #include @@ -29,7 +31,8 @@ ISC_LANG_BEGINDECLS #define DNS_RBT_USEHASH 1 -/* +/*@{*/ +/*% * Option values for dns_rbt_findnode() and dns_rbt_findname(). * These are used to form a bitmask. */ @@ -37,6 +40,7 @@ ISC_LANG_BEGINDECLS #define DNS_RBTFIND_EMPTYDATA 0x01 #define DNS_RBTFIND_NOEXACT 0x02 #define DNS_RBTFIND_NOPREDECESSOR 0x04 +/*@}*/ /* * These should add up to 30. @@ -51,7 +55,7 @@ ISC_LANG_BEGINDECLS #define DNS_RBTNODE_VALID(n) ISC_TRUE #endif -/* +/*% * This is the structure that is used for each node in the red/black * tree of trees. NOTE WELL: the implementation manages this as a variable * length structure, with the actual wire-format name and other data @@ -69,7 +73,8 @@ typedef struct dns_rbtnode { #ifdef DNS_RBT_USEHASH struct dns_rbtnode *hashnext; #endif - /* + /*@{*/ + /*! * The following bitfields add up to a total bitwidth of 32. * The range of values necessary for each item is indicated, * but in the case of "attributes" the field is wider to accomodate @@ -81,19 +86,21 @@ typedef struct dns_rbtnode { * In each case below the "range" indicated is what's _necessary_ for * the bitfield to hold, not what it actually _can_ hold. */ - unsigned int is_root : 1; /* range is 0..1 */ - unsigned int color : 1; /* range is 0..1 */ - unsigned int find_callback : 1; /* range is 0..1 */ - unsigned int attributes : 4; /* range is 0..2 */ - unsigned int namelen : 8; /* range is 1..255 */ - unsigned int offsetlen : 8; /* range is 1..128 */ - unsigned int padbytes : 9; /* range is 0..380 */ + unsigned int is_root : 1; /*%< range is 0..1 */ + unsigned int color : 1; /*%< range is 0..1 */ + unsigned int find_callback : 1; /*%< range is 0..1 */ + unsigned int attributes : 4; /*%< range is 0..2 */ + unsigned int namelen : 8; /*%< range is 1..255 */ + unsigned int offsetlen : 8; /*%< range is 1..128 */ + unsigned int padbytes : 9; /*%< range is 0..380 */ + /*@}*/ #ifdef DNS_RBT_USEHASH unsigned int hashval; #endif - /* + /*@{*/ + /*! * These values are used in the RBT DB implementation. The appropriate * node lock must be held before accessing them. */ @@ -102,6 +109,7 @@ typedef struct dns_rbtnode { unsigned int wild:1; unsigned int locknum:DNS_RBT_LOCKLENGTH; unsigned int references:DNS_RBT_REFLENGTH; + /*@}*/ } dns_rbtnode_t; typedef isc_result_t (*dns_rbtfindcallback_t)(dns_rbtnode_t *node, @@ -112,7 +120,7 @@ typedef isc_result_t (*dns_rbtfindcallback_t)(dns_rbtnode_t *node, ***** Chain Info *****/ -/* +/*! * A chain is used to keep track of the sequence of nodes to reach any given * node from the root of the tree. Originally nodes did not have parent * pointers in them (for memory usage reasons) so there was no way to find @@ -151,7 +159,7 @@ typedef isc_result_t (*dns_rbtfindcallback_t)(dns_rbtnode_t *node, * functions but additionally can provide the node to which the chain points. */ -/* +/*% * The number of level blocks to allocate at a time. Currently the maximum * number of levels is allocated directly in the structure, but future * revisions of this code might have a static initial block with dynamic @@ -165,14 +173,14 @@ typedef isc_result_t (*dns_rbtfindcallback_t)(dns_rbtnode_t *node, typedef struct dns_rbtnodechain { unsigned int magic; isc_mem_t * mctx; - /* + /*% * The terminal node of the chain. It is not in levels[]. * This is ostensibly private ... but in a pinch it could be * used tell that the chain points nowhere without needing to * call dns_rbtnodechain_current(). */ dns_rbtnode_t * end; - /* + /*% * The maximum number of labels in a name is 128; bitstrings mean * a conceptually very large number (which I have not bothered to * compute) of logical levels because splitting can potentially occur @@ -181,7 +189,7 @@ typedef struct dns_rbtnodechain { * in the worst case. */ dns_rbtnode_t * levels[DNS_RBT_LEVELBLOCK]; - /* + /*% * level_count indicates how deep the chain points into the * tree of trees, and is the index into the levels[] array. * Thus, levels[level_count - 1] is the last level node stored. @@ -190,7 +198,7 @@ typedef struct dns_rbtnodechain { * so on. */ unsigned int level_count; - /* + /*% * level_matches tells how many levels matched above the node * returned by dns_rbt_findnode(). A match (partial or exact) found * in the first level thus results in level_matches being set to 1. @@ -207,40 +215,40 @@ typedef struct dns_rbtnodechain { isc_result_t dns_rbt_create(isc_mem_t *mctx, void (*deleter)(void *, void *), void *deleter_arg, dns_rbt_t **rbtp); -/* +/*%< * Initialize a red-black tree of trees. * * Notes: - * The deleter argument, if non-null, points to a function that is + *\li The deleter argument, if non-null, points to a function that is * responsible for cleaning up any memory associated with the data * pointer of a node when the node is deleted. It is passed the * deleted node's data pointer as its first argument and deleter_arg * as its second argument. * * Requires: - * mctx is a pointer to a valid memory context. - * rbtp != NULL && *rbtp == NULL - * arg == NULL iff deleter == NULL + * \li mctx is a pointer to a valid memory context. + *\li rbtp != NULL && *rbtp == NULL + *\li arg == NULL iff deleter == NULL * * Ensures: - * If result is ISC_R_SUCCESS: + *\li If result is ISC_R_SUCCESS: * *rbtp points to a valid red-black tree manager * - * If result is failure: + *\li If result is failure: * *rbtp does not point to a valid red-black tree manager. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_NOMEMORY Resource limit: Out of Memory + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_NOMEMORY Resource limit: Out of Memory */ isc_result_t dns_rbt_addname(dns_rbt_t *rbt, dns_name_t *name, void *data); -/* +/*%< * Add 'name' to the tree of trees, associated with 'data'. * * Notes: - * 'data' is never required to be non-NULL, but specifying it + *\li 'data' is never required to be non-NULL, but specifying it * when the name is added is faster than searching for 'name' * again and then setting the data pointer. The lack of a data pointer * for a node also has other ramifications regarding whether @@ -248,106 +256,103 @@ dns_rbt_addname(dns_rbt_t *rbt, dns_name_t *name, void *data); * joins nodes. * * Requires: - * rbt is a valid rbt manager. - * dns_name_isabsolute(name) == TRUE + *\li rbt is a valid rbt manager. + *\li dns_name_isabsolute(name) == TRUE * * Ensures: - * 'name' is not altered in any way. + *\li 'name' is not altered in any way. * - * Any external references to nodes in the tree are unaffected by + *\li Any external references to nodes in the tree are unaffected by * node splits that are necessary to insert the new name. * - * If result is ISC_R_SUCCESS: + *\li If result is #ISC_R_SUCCESS: * 'name' is findable in the red/black tree of trees in O(log N). - * * The data pointer of the node for 'name' is set to 'data'. * - * If result is ISC_R_EXISTS or ISC_R_NOSPACE: + *\li If result is #ISC_R_EXISTS or #ISC_R_NOSPACE: * The tree of trees is unaltered. * - * If result is ISC_R_NOMEMORY: + *\li If result is #ISC_R_NOMEMORY: * No guarantees. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_EXISTS The name already exists with associated data. - * ISC_R_NOSPACE The name had more logical labels than are allowed. - * ISC_R_NOMEMORY Resource Limit: Out of Memory + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_EXISTS The name already exists with associated data. + *\li #ISC_R_NOSPACE The name had more logical labels than are allowed. + *\li #ISC_R_NOMEMORY Resource Limit: Out of Memory */ isc_result_t dns_rbt_addnode(dns_rbt_t *rbt, dns_name_t *name, dns_rbtnode_t **nodep); -/* +/*%< * Just like dns_rbt_addname, but returns the address of the node. * * Requires: - * rbt is a valid rbt structure. - * dns_name_isabsolute(name) == TRUE - * nodep != NULL && *nodep == NULL + *\li rbt is a valid rbt structure. + *\li dns_name_isabsolute(name) == TRUE + *\li nodep != NULL && *nodep == NULL * * Ensures: - * 'name' is not altered in any way. + *\li 'name' is not altered in any way. * - * Any external references to nodes in the tree are unaffected by + *\li Any external references to nodes in the tree are unaffected by * node splits that are necessary to insert the new name. * - * If result is ISC_R_SUCCESS: + *\li If result is ISC_R_SUCCESS: * 'name' is findable in the red/black tree of trees in O(log N). - * * *nodep is the node that was added for 'name'. * - * If result is ISC_R_EXISTS: + *\li If result is ISC_R_EXISTS: * The tree of trees is unaltered. - * * *nodep is the existing node for 'name'. * - * If result is ISC_R_NOMEMORY: + *\li If result is ISC_R_NOMEMORY: * No guarantees. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_EXISTS The name already exists, possibly without data. - * ISC_R_NOMEMORY Resource Limit: Out of Memory + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_EXISTS The name already exists, possibly without data. + *\li #ISC_R_NOMEMORY Resource Limit: Out of Memory */ isc_result_t dns_rbt_findname(dns_rbt_t *rbt, dns_name_t *name, unsigned int options, dns_name_t *foundname, void **data); -/* +/*%< * Get the data pointer associated with 'name'. * * Notes: - * When DNS_RBTFIND_NOEXACT is set, the closest matching superdomain is - * returned (also subject to DNS_RBTFIND_EMPTYDATA), even when there is + *\li When #DNS_RBTFIND_NOEXACT is set, the closest matching superdomain is + * returned (also subject to #DNS_RBTFIND_EMPTYDATA), even when there is * an exact match in the tree. * - * A node that has no data is considered not to exist for this function, - * unless the DNS_RBTFIND_EMPTYDATA option is set. + *\li A node that has no data is considered not to exist for this function, + * unless the #DNS_RBTFIND_EMPTYDATA option is set. * * Requires: - * rbt is a valid rbt manager. - * dns_name_isabsolute(name) == TRUE - * data != NULL && *data == NULL + *\li rbt is a valid rbt manager. + *\li dns_name_isabsolute(name) == TRUE + *\li data != NULL && *data == NULL * * Ensures: - * 'name' and the tree are not altered in any way. + *\li 'name' and the tree are not altered in any way. * - * If result is ISC_R_SUCCESS: + *\li If result is ISC_R_SUCCESS: * *data is the data associated with 'name'. * - * If result is DNS_R_PARTIALMATCH: + *\li If result is DNS_R_PARTIALMATCH: * *data is the data associated with the deepest superdomain * of 'name' which has data. * - * If result is ISC_R_NOTFOUND: + *\li If result is ISC_R_NOTFOUND: * Neither the name nor a superdomain was found with data. * * Returns: - * ISC_R_SUCCESS Success - * DNS_R_PARTIALMATCH Superdomain found with data - * ISC_R_NOTFOUND No match - * ISC_R_NOSPACE Concatenating nodes to form foundname failed + *\li #ISC_R_SUCCESS Success + *\li #DNS_R_PARTIALMATCH Superdomain found with data + *\li #ISC_R_NOTFOUND No match + *\li #ISC_R_NOSPACE Concatenating nodes to form foundname failed */ isc_result_t @@ -355,20 +360,20 @@ dns_rbt_findnode(dns_rbt_t *rbt, dns_name_t *name, dns_name_t *foundname, dns_rbtnode_t **node, dns_rbtnodechain_t *chain, unsigned int options, dns_rbtfindcallback_t callback, void *callback_arg); -/* +/*%< * Find the node for 'name'. * * Notes: - * A node that has no data is considered not to exist for this function, + *\li A node that has no data is considered not to exist for this function, * unless the DNS_RBTFIND_EMPTYDATA option is set. This applies to both * exact matches and partial matches. * - * If the chain parameter is non-NULL, then the path through the tree + *\li If the chain parameter is non-NULL, then the path through the tree * to the DNSSEC predecessor of the searched for name is maintained, * unless the DNS_RBTFIND_NOPREDECESSOR or DNS_RBTFIND_NOEXACT option * is used. (For more details on those options, see below.) * - * If there is no predecessor, then the chain will point to nowhere, as + *\li If there is no predecessor, then the chain will point to nowhere, as * indicated by chain->end being NULL or dns_rbtnodechain_current * returning ISC_R_NOTFOUND. Note that in a normal Internet DNS RBT * there will always be a predecessor for all names except the root @@ -376,23 +381,23 @@ dns_rbt_findnode(dns_rbt_t *rbt, dns_name_t *name, dns_name_t *foundname, * everything. But you can certainly construct a trivial tree and a * search for it that has no predecessor. * - * Within the chain structure, the 'levels' member of the structure holds + *\li Within the chain structure, the 'levels' member of the structure holds * the root node of each level except the first. * - * The 'level_count' of the chain indicates how deep the chain to the + *\li The 'level_count' of the chain indicates how deep the chain to the * predecessor name is, as an index into the 'levels[]' array. It does * not count name elements, per se, but only levels of the tree of trees, * the distinction arrising because multiple labels from a name can be * stored on only one level. It is also does not include the level * that has the node, since that level is not stored in levels[]. * - * The chain's 'level_matches' is not directly related to the predecessor. + *\li The chain's 'level_matches' is not directly related to the predecessor. * It is the number of levels above the level of the found 'node', * regardless of whether it was a partial match or exact match. When * the node is found in the top level tree, or no node is found at all, * level_matches is 0. * - * When DNS_RBTFIND_NOEXACT is set, the closest matching superdomain is + *\li When DNS_RBTFIND_NOEXACT is set, the closest matching superdomain is * returned (also subject to DNS_RBTFIND_EMPTYDATA), even when * there is an exact match in the tree. In this case, the chain * will not point to the DNSSEC predecessor, but will instead point @@ -407,26 +412,29 @@ dns_rbt_findnode(dns_rbt_t *rbt, dns_name_t *name, dns_name_t *foundname, * where you want the chain pointed, so this can be made more firm. * * Requires: - * rbt is a valid rbt manager. - * dns_name_isabsolute(name) == TRUE. - * node != NULL && *node == NULL. - * DNS_RBTFIND_NOEXACT and DNS_RBTFIND_NOPREDECESSOR are mutally + *\li rbt is a valid rbt manager. + *\li dns_name_isabsolute(name) == TRUE. + *\li node != NULL && *node == NULL. + *\li #DNS_RBTFIND_NOEXACT and DNS_RBTFIND_NOPREDECESSOR are mutally * exclusive. * * Ensures: - * 'name' and the tree are not altered in any way. + *\li 'name' and the tree are not altered in any way. * - * If result is ISC_R_SUCCESS: + *\li If result is ISC_R_SUCCESS: + *\verbatim * *node is the terminal node for 'name'. - * + * 'foundname' and 'name' represent the same name (though not * the same memory). - * + * 'chain' points to the DNSSEC predecessor, if any, of 'name'. * * chain->level_matches and chain->level_count are equal. + *\endverbatim * * If result is DNS_R_PARTIALMATCH: + *\verbatim * *node is the data associated with the deepest superdomain * of 'name' which has data. * @@ -434,59 +442,62 @@ dns_rbt_findnode(dns_rbt_t *rbt, dns_name_t *name, dns_name_t *foundname, * data, unless the DNS_RBTFIND_EMPTYDATA option is set). * * 'chain' points to the DNSSEC predecessor, if any, of 'name'. + *\endverbatim * - * If result is ISC_R_NOTFOUND: + *\li If result is ISC_R_NOTFOUND: + *\verbatim * Neither the name nor a superdomain was found. *node is NULL. * * 'chain' points to the DNSSEC predecessor, if any, of 'name'. * * chain->level_matches is 0. + *\endverbatim * * Returns: - * ISC_R_SUCCESS Success - * DNS_R_PARTIALMATCH Superdomain found with data - * ISC_R_NOTFOUND No match, or superdomain with no data - * ISC_R_NOSPACE Concatenating nodes to form foundname failed + *\li #ISC_R_SUCCESS Success + *\li #DNS_R_PARTIALMATCH Superdomain found with data + *\li #ISC_R_NOTFOUND No match, or superdomain with no data + *\li #ISC_R_NOSPACE Concatenating nodes to form foundname failed */ isc_result_t dns_rbt_deletename(dns_rbt_t *rbt, dns_name_t *name, isc_boolean_t recurse); -/* +/*%< * Delete 'name' from the tree of trees. * * Notes: - * When 'name' is removed, if recurse is ISC_TRUE then all of its + *\li When 'name' is removed, if recurse is ISC_TRUE then all of its * subnames are removed too. * * Requires: - * rbt is a valid rbt manager. - * dns_name_isabsolute(name) == TRUE + *\li rbt is a valid rbt manager. + *\li dns_name_isabsolute(name) == TRUE * * Ensures: - * 'name' is not altered in any way. + *\li 'name' is not altered in any way. * - * Does NOT ensure that any external references to nodes in the tree + *\li Does NOT ensure that any external references to nodes in the tree * are unaffected by node joins. * - * If result is ISC_R_SUCCESS: + *\li If result is ISC_R_SUCCESS: * 'name' does not appear in the tree with data; however, * the node for the name might still exist which can be * found with dns_rbt_findnode (but not dns_rbt_findname). * - * If result is ISC_R_NOTFOUND: + *\li If result is ISC_R_NOTFOUND: * 'name' does not appear in the tree with data, because * it did not appear in the tree before the function was called. * - * If result is something else: + *\li If result is something else: * See result codes for dns_rbt_findnode (if it fails, the * node is not deleted) or dns_rbt_deletenode (if it fails, * the node is deleted, but the tree is not optimized when * it could have been). * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_NOTFOUND No match - * something_else Any return code from dns_rbt_findnode except + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_NOTFOUND No match + *\li something_else Any return code from dns_rbt_findnode except * DNS_R_PARTIALMATCH (which causes ISC_R_NOTFOUND * to be returned instead), and any code from * dns_rbt_deletenode. @@ -494,115 +505,115 @@ dns_rbt_deletename(dns_rbt_t *rbt, dns_name_t *name, isc_boolean_t recurse); isc_result_t dns_rbt_deletenode(dns_rbt_t *rbt, dns_rbtnode_t *node, isc_boolean_t recurse); -/* +/*%< * Delete 'node' from the tree of trees. * * Notes: - * When 'node' is removed, if recurse is ISC_TRUE then all nodes + *\li When 'node' is removed, if recurse is ISC_TRUE then all nodes * in levels down from it are removed too. * * Requires: - * rbt is a valid rbt manager. - * node != NULL. + *\li rbt is a valid rbt manager. + *\li node != NULL. * * Ensures: - * Does NOT ensure that any external references to nodes in the tree + *\li Does NOT ensure that any external references to nodes in the tree * are unaffected by node joins. * - * If result is ISC_R_SUCCESS: + *\li If result is ISC_R_SUCCESS: * 'node' does not appear in the tree with data; however, * the node might still exist if it serves as a pointer to * a lower tree level as long as 'recurse' was false, hence * the node could can be found with dns_rbt_findnode whem * that function's empty_data_ok parameter is true. * - * If result is ISC_R_NOMEMORY or ISC_R_NOSPACE: + *\li If result is ISC_R_NOMEMORY or ISC_R_NOSPACE: * The node was deleted, but the tree structure was not * optimized. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_NOMEMORY Resource Limit: Out of Memory when joining nodes. - * ISC_R_NOSPACE dns_name_concatenate failed when joining nodes. + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_NOMEMORY Resource Limit: Out of Memory when joining nodes. + *\li #ISC_R_NOSPACE dns_name_concatenate failed when joining nodes. */ void dns_rbt_namefromnode(dns_rbtnode_t *node, dns_name_t *name); -/* +/*%< * Convert the sequence of labels stored at 'node' into a 'name'. * * Notes: - * This function does not return the full name, from the root, but + *\li This function does not return the full name, from the root, but * just the labels at the indicated node. * - * The name data pointed to by 'name' is the information stored + *\li The name data pointed to by 'name' is the information stored * in the node, not a copy. Altering the data at this pointer * will likely cause grief. * * Requires: - * name->offsets == NULL + * \li name->offsets == NULL * * Ensures: - * 'name' is DNS_NAMEATTR_READONLY. + * \li 'name' is DNS_NAMEATTR_READONLY. * - * 'name' will point directly to the labels stored after the + * \li 'name' will point directly to the labels stored after the * dns_rbtnode_t struct. * - * 'name' will have offsets that also point to the information stored + * \li 'name' will have offsets that also point to the information stored * as part of the node. */ isc_result_t dns_rbt_fullnamefromnode(dns_rbtnode_t *node, dns_name_t *name); -/* +/*%< * Like dns_rbt_namefromnode, but returns the full name from the root. * * Notes: - * Unlike dns_rbt_namefromnode, the name will not point directly + * \li Unlike dns_rbt_namefromnode, the name will not point directly * to node data. Rather, dns_name_concatenate will be used to copy * the name data from each node into the 'name' argument. * * Requires: - * name != NULL - * name has a dedicated buffer. + * \li name != NULL + * \li name has a dedicated buffer. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE (possible via dns_name_concatenate) - * DNS_R_NAMETOOLONG (possible via dns_name_concatenate) + * \li ISC_R_SUCCESS + * \li ISC_R_NOSPACE (possible via dns_name_concatenate) + * \li DNS_R_NAMETOOLONG (possible via dns_name_concatenate) */ char * dns_rbt_formatnodename(dns_rbtnode_t *node, char *printname, unsigned int size); -/* +/*%< * Format the full name of a node for printing, using dns_name_format(). * * Notes: - * 'size' is the length of the printname buffer. This should be + * \li 'size' is the length of the printname buffer. This should be * DNS_NAME_FORMATSIZE or larger. * * Requires: - * node and printname are not NULL. + * \li node and printname are not NULL. * * Returns: - * The 'printname' pointer. + * \li The 'printname' pointer. */ unsigned int dns_rbt_nodecount(dns_rbt_t *rbt); -/* +/*%< * Obtain the number of nodes in the tree of trees. * * Requires: - * rbt is a valid rbt manager. + * \li rbt is a valid rbt manager. */ void dns_rbt_destroy(dns_rbt_t **rbtp); isc_result_t dns_rbt_destroy2(dns_rbt_t **rbtp, unsigned int quantum); -/* +/*%< * Stop working with a red-black tree of trees. * If 'quantum' is zero then the entire tree will be destroyed. * If 'quantum' is non zero then up to 'quantum' nodes will be destroyed @@ -612,26 +623,26 @@ dns_rbt_destroy2(dns_rbt_t **rbtp, unsigned int quantum); * performed on the tree of trees. * * Requires: - * *rbt is a valid rbt manager. + * \li *rbt is a valid rbt manager. * * Ensures on ISC_R_SUCCESS: - * All space allocated by the RBT library has been returned. + * \li All space allocated by the RBT library has been returned. * - * *rbt is invalidated as an rbt manager. + * \li *rbt is invalidated as an rbt manager. * * Returns: - * ISC_R_SUCCESS - * ISC_R_QUOTA if 'quantum' nodes have been destroyed. + * \li ISC_R_SUCCESS + * \li ISC_R_QUOTA if 'quantum' nodes have been destroyed. */ void dns_rbt_printall(dns_rbt_t *rbt); -/* +/*%< * Print an ASCII representation of the internal structure of the red-black * tree of trees. * * Notes: - * The name stored at each node, along with the node's color, is printed. + * \li The name stored at each node, along with the node's color, is printed. * Then the down pointer, left and right pointers are displayed * recursively in turn. NULL down pointers are silently omitted; * NULL left and right pointers are printed. @@ -643,70 +654,70 @@ dns_rbt_printall(dns_rbt_t *rbt); void dns_rbtnodechain_init(dns_rbtnodechain_t *chain, isc_mem_t *mctx); -/* +/*%< * Initialize 'chain'. * * Requires: - * 'chain' is a valid pointer. + *\li 'chain' is a valid pointer. * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. * * Ensures: - * 'chain' is suitable for use. + *\li 'chain' is suitable for use. */ void dns_rbtnodechain_reset(dns_rbtnodechain_t *chain); -/* +/*%< * Free any dynamic storage associated with 'chain', and then reinitialize * 'chain'. * * Requires: - * 'chain' is a valid pointer. + *\li 'chain' is a valid pointer. * * Ensures: - * 'chain' is suitable for use, and uses no dynamic storage. + *\li 'chain' is suitable for use, and uses no dynamic storage. */ void dns_rbtnodechain_invalidate(dns_rbtnodechain_t *chain); -/* +/*%< * Free any dynamic storage associated with 'chain', and then invalidates it. * * Notes: - * Future calls to any dns_rbtnodechain_ function will need to call + *\li Future calls to any dns_rbtnodechain_ function will need to call * dns_rbtnodechain_init on the chain first (except, of course, * dns_rbtnodechain_init itself). * * Requires: - * 'chain' is a valid chain. + *\li 'chain' is a valid chain. * * Ensures: - * 'chain' is no longer suitable for use, and uses no dynamic storage. + *\li 'chain' is no longer suitable for use, and uses no dynamic storage. */ isc_result_t dns_rbtnodechain_current(dns_rbtnodechain_t *chain, dns_name_t *name, dns_name_t *origin, dns_rbtnode_t **node); -/* +/*%< * Provide the name, origin and node to which the chain is currently pointed. * * Notes: - * The tree need not have be locked against additions for the chain + *\li The tree need not have be locked against additions for the chain * to remain valid, however there are no guarantees if any deletion * has been made since the chain was established. * * Requires: - * 'chain' is a valid chain. + *\li 'chain' is a valid chain. * * Ensures: - * 'node', if non-NULL, is the node to which the chain was pointed + *\li 'node', if non-NULL, is the node to which the chain was pointed * by dns_rbt_findnode, dns_rbtnodechain_first or dns_rbtnodechain_last. * If none were called for the chain since it was initialized or reset, * or if the was no predecessor to the name searched for with * dns_rbt_findnode, then '*node' is NULL and ISC_R_NOTFOUND is returned. * - * 'name', if non-NULL, is the name stored at the terminal level of + *\li 'name', if non-NULL, is the name stored at the terminal level of * the chain. This is typically a single label, like the "www" of * "www.isc.org", but need not be so. At the root of the tree of trees, * if the node is "." then 'name' is ".", otherwise it is relative to ".". @@ -714,123 +725,123 @@ dns_rbtnodechain_current(dns_rbtnodechain_t *chain, dns_name_t *name, * "isc.org." then the root node's stored name is "isc.org." but 'name' * will be "isc.org".) * - * 'origin', if non-NULL, is the sequence of labels in the levels + *\li 'origin', if non-NULL, is the sequence of labels in the levels * above the terminal level, such as "isc.org." in the above example. * 'origin' is always "." for the root node. * * * Returns: - * ISC_R_SUCCESS name, origin & node were successfully set. - * ISC_R_NOTFOUND The chain does not point to any node. - * Any error return from dns_name_concatenate. + *\li #ISC_R_SUCCESS name, origin & node were successfully set. + *\li #ISC_R_NOTFOUND The chain does not point to any node. + *\li <something_else> Any error return from dns_name_concatenate. */ isc_result_t dns_rbtnodechain_first(dns_rbtnodechain_t *chain, dns_rbt_t *rbt, dns_name_t *name, dns_name_t *origin); -/* +/*%< * Set the chain to the lexically first node in the tree of trees. * * Notes: - * By the definition of ordering for DNS names, the root of the tree of + *\li By the definition of ordering for DNS names, the root of the tree of * trees is the very first node, since everything else in the megatree * uses it as a common suffix. * * Requires: - * 'chain' is a valid chain. - * 'rbt' is a valid rbt manager. + *\li 'chain' is a valid chain. + *\li 'rbt' is a valid rbt manager. * * Ensures: - * The chain points to the very first node of the tree. + *\li The chain points to the very first node of the tree. * - * 'name' and 'origin', if non-NULL, are set as described for + *\li 'name' and 'origin', if non-NULL, are set as described for * dns_rbtnodechain_current. Thus 'origin' will always be ".". * * Returns: - * DNS_R_NEWORIGIN The name & origin were successfully set. - * Any error result from dns_rbtnodechain_current. + *\li #DNS_R_NEWORIGIN The name & origin were successfully set. + *\li <something_else> Any error result from dns_rbtnodechain_current. */ isc_result_t dns_rbtnodechain_last(dns_rbtnodechain_t *chain, dns_rbt_t *rbt, dns_name_t *name, dns_name_t *origin); -/* +/*%< * Set the chain to the lexically last node in the tree of trees. * * Requires: - * 'chain' is a valid chain. - * 'rbt' is a valid rbt manager. + *\li 'chain' is a valid chain. + *\li 'rbt' is a valid rbt manager. * * Ensures: - * The chain points to the very last node of the tree. + *\li The chain points to the very last node of the tree. * - * 'name' and 'origin', if non-NULL, are set as described for + *\li 'name' and 'origin', if non-NULL, are set as described for * dns_rbtnodechain_current. * * Returns: - * DNS_R_NEWORIGIN The name & origin were successfully set. - * ISC_R_NOMEMORY Resource Limit: Out of Memory building chain. - * Any error result from dns_name_concatenate. + *\li #DNS_R_NEWORIGIN The name & origin were successfully set. + *\li #ISC_R_NOMEMORY Resource Limit: Out of Memory building chain. + *\li <something_else> Any error result from dns_name_concatenate. */ isc_result_t dns_rbtnodechain_prev(dns_rbtnodechain_t *chain, dns_name_t *name, dns_name_t *origin); -/* +/*%< * Adjusts chain to point the DNSSEC predecessor of the name to which it * is currently pointed. * * Requires: - * 'chain' is a valid chain. - * 'chain' has been pointed somewhere in the tree with dns_rbt_findnode, + *\li 'chain' is a valid chain. + *\li 'chain' has been pointed somewhere in the tree with dns_rbt_findnode, * dns_rbtnodechain_first or dns_rbtnodechain_last -- and remember that * dns_rbt_findnode is not guaranteed to point the chain somewhere, * since there may have been no predecessor to the searched for name. * * Ensures: - * The chain is pointed to the predecessor of its current target. + *\li The chain is pointed to the predecessor of its current target. * - * 'name' and 'origin', if non-NULL, are set as described for + *\li 'name' and 'origin', if non-NULL, are set as described for * dns_rbtnodechain_current. * - * 'origin' is only if a new origin was found. + *\li 'origin' is only if a new origin was found. * * Returns: - * ISC_R_SUCCESS The predecessor was found and 'name' was set. - * DNS_R_NEWORIGIN The predecessor was found with a different + *\li #ISC_R_SUCCESS The predecessor was found and 'name' was set. + *\li #DNS_R_NEWORIGIN The predecessor was found with a different * origin and 'name' and 'origin' were set. - * ISC_R_NOMORE There was no predecessor. - * Any error result from dns_rbtnodechain_current. + *\li #ISC_R_NOMORE There was no predecessor. + *\li <something_else> Any error result from dns_rbtnodechain_current. */ isc_result_t dns_rbtnodechain_next(dns_rbtnodechain_t *chain, dns_name_t *name, dns_name_t *origin); -/* +/*%< * Adjusts chain to point the DNSSEC successor of the name to which it * is currently pointed. * * Requires: - * 'chain' is a valid chain. - * 'chain' has been pointed somewhere in the tree with dns_rbt_findnode, + *\li 'chain' is a valid chain. + *\li 'chain' has been pointed somewhere in the tree with dns_rbt_findnode, * dns_rbtnodechain_first or dns_rbtnodechain_last -- and remember that * dns_rbt_findnode is not guaranteed to point the chain somewhere, * since there may have been no predecessor to the searched for name. * * Ensures: - * The chain is pointed to the successor of its current target. + *\li The chain is pointed to the successor of its current target. * - * 'name' and 'origin', if non-NULL, are set as described for + *\li 'name' and 'origin', if non-NULL, are set as described for * dns_rbtnodechain_current. * - * 'origin' is only if a new origin was found. + *\li 'origin' is only if a new origin was found. * * Returns: - * ISC_R_SUCCESS The successor was found and 'name' was set. - * DNS_R_NEWORIGIN The successor was found with a different + *\li #ISC_R_SUCCESS The successor was found and 'name' was set. + *\li #DNS_R_NEWORIGIN The successor was found with a different * origin and 'name' and 'origin' were set. - * ISC_R_NOMORE There was no successor. - * Any error result from dns_name_concatenate. + *\li #ISC_R_NOMORE There was no successor. + *\li <something_else> Any error result from dns_name_concatenate. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/rcode.h b/lib/dns/include/dns/rcode.h index d714933d12..4c02a7574b 100644 --- a/lib/dns/include/dns/rcode.h +++ b/lib/dns/include/dns/rcode.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rcode.h,v 1.13 2004/03/05 05:09:45 marka Exp $ */ +/* $Id: rcode.h,v 1.14 2005/04/27 04:56:58 sra Exp $ */ #ifndef DNS_RCODE_H #define DNS_RCODE_H 1 +/*! \file */ + #include #include @@ -27,68 +29,68 @@ ISC_LANG_BEGINDECLS isc_result_t dns_rcode_fromtext(dns_rcode_t *rcodep, isc_textregion_t *source); -/* +/*%< * Convert the text 'source' refers to into a DNS error value. * * Requires: - * 'rcodep' is a valid pointer. + *\li 'rcodep' is a valid pointer. * - * 'source' is a valid text region. + *\li 'source' is a valid text region. * * Returns: - * ISC_R_SUCCESS on success - * DNS_R_UNKNOWN type is unknown + *\li #ISC_R_SUCCESS on success + *\li #DNS_R_UNKNOWN type is unknown */ isc_result_t dns_rcode_totext(dns_rcode_t rcode, isc_buffer_t *target); -/* +/*%< * Put a textual representation of error 'rcode' into 'target'. * * Requires: - * 'rcode' is a valid rcode. + *\li 'rcode' is a valid rcode. * - * 'target' is a valid text buffer. + *\li 'target' is a valid text buffer. * * Ensures: - * If the result is success: + *\li If the result is success: * The used space in 'target' is updated. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_NOSPACE target buffer is too small + *\li #ISC_R_SUCCESS on success + *\li #ISC_R_NOSPACE target buffer is too small */ isc_result_t dns_tsigrcode_fromtext(dns_rcode_t *rcodep, isc_textregion_t *source); -/* +/*%< * Convert the text 'source' refers to into a TSIG/TKEY error value. * * Requires: - * 'rcodep' is a valid pointer. + *\li 'rcodep' is a valid pointer. * - * 'source' is a valid text region. + *\li 'source' is a valid text region. * * Returns: - * ISC_R_SUCCESS on success - * DNS_R_UNKNOWN type is unknown + *\li #ISC_R_SUCCESS on success + *\li #DNS_R_UNKNOWN type is unknown */ isc_result_t dns_tsigrcode_totext(dns_rcode_t rcode, isc_buffer_t *target); -/* +/*%< * Put a textual representation of TSIG/TKEY error 'rcode' into 'target'. * * Requires: - * 'rcode' is a valid TSIG/TKEY error code. + *\li 'rcode' is a valid TSIG/TKEY error code. * - * 'target' is a valid text buffer. + *\li 'target' is a valid text buffer. * * Ensures: - * If the result is success: + *\li If the result is success: * The used space in 'target' is updated. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_NOSPACE target buffer is too small + *\li #ISC_R_SUCCESS on success + *\li #ISC_R_NOSPACE target buffer is too small */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/rdata.h b/lib/dns/include/dns/rdata.h index 0fd2e484ff..6faf9b9aa5 100644 --- a/lib/dns/include/dns/rdata.h +++ b/lib/dns/include/dns/rdata.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdata.h,v 1.60 2004/03/05 05:09:45 marka Exp $ */ +/* $Id: rdata.h,v 1.61 2005/04/27 04:56:58 sra Exp $ */ #ifndef DNS_RDATA_H #define DNS_RDATA_H 1 @@ -24,9 +24,8 @@ ***** Module Info *****/ -/* - * DNS Rdata - * +/*! \file + * \brief * Provides facilities for manipulating DNS rdata, including conversions to * and from wire format and text format. * @@ -46,7 +45,7 @@ * * Implementation Notes: * - * The routines in this module are expected to be synthesized by the + *\li The routines in this module are expected to be synthesized by the * build process from a set of source files, one per rdata type. For * portability, it's probably best that the building be done by a C * program. Adding a new rdata type will be a simple matter of adding @@ -54,38 +53,37 @@ * the format of a particular rdata type is in this file. * * MP: - * Clients of this module must impose any required synchronization. + *\li Clients of this module must impose any required synchronization. * * Reliability: - * This module deals with low-level byte streams. Errors in any of + *\li This module deals with low-level byte streams. Errors in any of * the functions are likely to crash the server or corrupt memory. * - * Rdata is typed, and the caller must know what type of rdata it has. + *\li Rdata is typed, and the caller must know what type of rdata it has. * A caller that gets this wrong could crash the server. * - * The fromstruct() and tostruct() routines use a void * pointer to + *\li The fromstruct() and tostruct() routines use a void * pointer to * represent the structure. The caller must ensure that it passes a * pointer to the appropriate type, or the server could crash or memory * could be corrupted. * * Resources: - * None. + *\li None. * * Security: * - * *** WARNING *** - * + *\li *** WARNING *** * dns_rdata_fromwire() deals with raw network data. An error in * this routine could result in the failure or hijacking of the server. * * Standards: - * RFC 1035 - * Draft EDNS0 (0) - * Draft EDNS1 (0) - * Draft Binary Labels (2) - * Draft Local Compression (1) - * + *\li RFC1035 + *\li Draft EDNS0 (0) + *\li Draft EDNS1 (0) + *\li Draft Binary Labels (2) + *\li Draft Local Compression (1) + *\li Various RFCs for particular types; these will be documented in the + * sources files of the types. * */ @@ -100,19 +98,17 @@ ISC_LANG_BEGINDECLS -/***** - ***** RData - ***** - ***** An 'rdata' is a handle to a binary region. The handle has an RR - ***** class and type, and the data in the binary region is in the format - ***** of the given class and type. - *****/ /*** *** Types ***/ -/* +/*% + ***** An 'rdata' is a handle to a binary region. The handle has an RR + ***** class and type, and the data in the binary region is in the format + ***** of the given class and type. + *****/ +/*% * Clients are strongly discouraged from using this type directly, with * the exception of the 'link' field which may be used directly for whatever * purpose the client desires. @@ -128,7 +124,7 @@ struct dns_rdata { #define DNS_RDATA_INIT { NULL, 0, 0, 0, 0, {(void*)(-1), (void *)(-1)}} -#define DNS_RDATA_UPDATE 0x0001 /* update pseudo record */ +#define DNS_RDATA_UPDATE 0x0001 /*%< update pseudo record */ /* * Flags affecting rdata formatting style. Flags 0xFFFF0000 @@ -136,11 +132,11 @@ struct dns_rdata { * See additional comments at dns_rdata_tofmttext(). */ -/* Split the rdata into multiple lines to try to keep it +/*% Split the rdata into multiple lines to try to keep it within the "width". */ #define DNS_STYLEFLAG_MULTILINE 0x00000001U -/* Output explanatory comments. */ +/*% Output explanatory comments. */ #define DNS_STYLEFLAG_COMMENT 0x00000002U #define DNS_RDATA_DOWNCASE DNS_NAME_DOWNCASE @@ -154,7 +150,7 @@ struct dns_rdata { void dns_rdata_init(dns_rdata_t *rdata); -/* +/*%< * Make 'rdata' empty. * * Requires: @@ -163,21 +159,21 @@ dns_rdata_init(dns_rdata_t *rdata); void dns_rdata_reset(dns_rdata_t *rdata); -/* +/*%< * Make 'rdata' empty. * * Requires: - * 'rdata' is a previously initialized rdata and is not linked. + *\li 'rdata' is a previously initialized rdata and is not linked. */ void dns_rdata_clone(const dns_rdata_t *src, dns_rdata_t *target); -/* +/*%< * Clone 'target' from 'src'. * * Requires: - * 'src' to be initialized. - * 'target' to be initialized. + *\li 'src' to be initialized. + *\li 'target' to be initialized. */ /*** @@ -186,20 +182,20 @@ dns_rdata_clone(const dns_rdata_t *src, dns_rdata_t *target); int dns_rdata_compare(const dns_rdata_t *rdata1, const dns_rdata_t *rdata2); -/* +/*%< * Determine the relative ordering under the DNSSEC order relation of * 'rdata1' and 'rdata2'. * * Requires: * - * 'rdata1' is a valid, non-empty rdata + *\li 'rdata1' is a valid, non-empty rdata * - * 'rdata2' is a valid, non-empty rdata + *\li 'rdata2' is a valid, non-empty rdata * * Returns: - * < 0 'rdata1' is less than 'rdata2' - * 0 'rdata1' is equal to 'rdata2' - * > 0 'rdata1' is greater than 'rdata2' + *\li < 0 'rdata1' is less than 'rdata2' + *\li 0 'rdata1' is equal to 'rdata2' + *\li > 0 'rdata1' is greater than 'rdata2' */ /*** @@ -209,17 +205,17 @@ dns_rdata_compare(const dns_rdata_t *rdata1, const dns_rdata_t *rdata2); void dns_rdata_fromregion(dns_rdata_t *rdata, dns_rdataclass_t rdclass, dns_rdatatype_t type, isc_region_t *r); -/* +/*%< * Make 'rdata' refer to region 'r'. * * Requires: * - * The data in 'r' is properly formatted for whatever type it is. + *\li The data in 'r' is properly formatted for whatever type it is. */ void dns_rdata_toregion(const dns_rdata_t *rdata, isc_region_t *r); -/* +/*%< * Make 'r' refer to 'rdata'. */ @@ -228,73 +224,70 @@ dns_rdata_fromwire(dns_rdata_t *rdata, dns_rdataclass_t rdclass, dns_rdatatype_t type, isc_buffer_t *source, dns_decompress_t *dctx, unsigned int options, isc_buffer_t *target); -/* +/*%< * Copy the possibly-compressed rdata at source into the target region. * * Notes: - * Name decompression policy is controlled by 'dctx'. + *\li Name decompression policy is controlled by 'dctx'. * * 'options' - * DNS_RDATA_DOWNCASE downcase domain names when they are copied + *\li DNS_RDATA_DOWNCASE downcase domain names when they are copied * into target. * * Requires: * - * 'rdclass' and 'type' are valid. + *\li 'rdclass' and 'type' are valid. * - * 'source' is a valid buffer, and the active region of 'source' + *\li 'source' is a valid buffer, and the active region of 'source' * references the rdata to be processed. * - * 'target' is a valid buffer. + *\li 'target' is a valid buffer. * - * 'dctx' is a valid decompression context. + *\li 'dctx' is a valid decompression context. * - * Ensures: - * - * If result is success: - * If 'rdata' is not NULL, it is attached to the target. - * - * The conditions dns_name_fromwire() ensures for names hold + * Ensures, + * if result is success: + * \li If 'rdata' is not NULL, it is attached to the target. + * \li The conditions dns_name_fromwire() ensures for names hold * for all names in the rdata. - * - * The current location in source is advanced, and the used space + * \li The current location in source is advanced, and the used space * in target is updated. * * Result: - * Success - * - * - * Bad Form: Input too short - * Resource Limit: Not enough space + *\li Success + *\li Any non-success status from dns_name_fromwire() + *\li Various 'Bad Form' class failures depending on class and type + *\li Bad Form: Input too short + *\li Resource Limit: Not enough space */ isc_result_t dns_rdata_towire(dns_rdata_t *rdata, dns_compress_t *cctx, isc_buffer_t *target); -/* +/*%< * Convert 'rdata' into wire format, compressing it as specified by the * compression context 'cctx', and storing the result in 'target'. * * Notes: - * If the compression context allows global compression, then the + *\li If the compression context allows global compression, then the * global compression table may be updated. * * Requires: - * 'rdata' is a valid, non-empty rdata + *\li 'rdata' is a valid, non-empty rdata * - * target is a valid buffer + *\li target is a valid buffer * - * Any offsets specified in a global compression table are valid + *\li Any offsets specified in a global compression table are valid * for target. * - * Ensures: - * If the result is success: - * The used space in target is updated. + * Ensures, + * if the result is success: + * \li The used space in target is updated. * * Returns: - * Success - * - * Resource Limit: Not enough space + *\li Success + *\li Any non-success status from dns_name_towire() + *\li Resource Limit: Not enough space */ isc_result_t @@ -302,100 +295,100 @@ dns_rdata_fromtext(dns_rdata_t *rdata, dns_rdataclass_t rdclass, dns_rdatatype_t type, isc_lex_t *lexer, dns_name_t *origin, unsigned int options, isc_mem_t *mctx, isc_buffer_t *target, dns_rdatacallbacks_t *callbacks); -/* +/*%< * Convert the textual representation of a DNS rdata into uncompressed wire * form stored in the target region. Tokens constituting the text of the rdata * are taken from 'lexer'. * * Notes: - * Relative domain names in the rdata will have 'origin' appended to them. + *\li Relative domain names in the rdata will have 'origin' appended to them. * A NULL origin implies "origin == dns_rootname". * * * 'options' - * DNS_RDATA_DOWNCASE downcase domain names when they are copied + *\li DNS_RDATA_DOWNCASE downcase domain names when they are copied * into target. - * DNS_RDATA_CHECKNAMES perform checknames checks. - * DNS_RDATA_CHECKNAMESFAIL fail if the checknames check fail. If + *\li DNS_RDATA_CHECKNAMES perform checknames checks. + *\li DNS_RDATA_CHECKNAMESFAIL fail if the checknames check fail. If * not set a warning will be issued. - * DNS_RDATA_CHECKREVERSE this should set if the owner name ends + *\li DNS_RDATA_CHECKREVERSE this should set if the owner name ends * in IP6.ARPA, IP6.INT or IN-ADDR.ARPA. * * Requires: * - * 'rdclass' and 'type' are valid. + *\li 'rdclass' and 'type' are valid. * - * 'lexer' is a valid isc_lex_t. + *\li 'lexer' is a valid isc_lex_t. * - * 'mctx' is a valid isc_mem_t. + *\li 'mctx' is a valid isc_mem_t. * - * 'target' is a valid region. + *\li 'target' is a valid region. * - * 'origin' if non NULL it must be absolute. + *\li 'origin' if non NULL it must be absolute. * - * 'callbacks' to be NULL or callbacks->warn and callbacks->error be + *\li 'callbacks' to be NULL or callbacks->warn and callbacks->error be * initialized. * - * Ensures: - * If result is success: - * If 'rdata' is not NULL, it is attached to the target. - * - * The conditions dns_name_fromtext() ensures for names hold + * Ensures, + * if result is success: + *\li If 'rdata' is not NULL, it is attached to the target. + + *\li The conditions dns_name_fromtext() ensures for names hold * for all names in the rdata. - * - * The used space in target is updated. + + *\li The used space in target is updated. * * Result: - * Success - * - * - * Bad Form: Input too short - * Resource Limit: Not enough space - * Resource Limit: Not enough memory + *\li Success + *\li Translated result codes from isc_lex_gettoken + *\li Various 'Bad Form' class failures depending on class and type + *\li Bad Form: Input too short + *\li Resource Limit: Not enough space + *\li Resource Limit: Not enough memory */ isc_result_t dns_rdata_totext(dns_rdata_t *rdata, dns_name_t *origin, isc_buffer_t *target); -/* +/*%< * Convert 'rdata' into text format, storing the result in 'target'. * The text will consist of a single line, with fields separated by * single spaces. * * Notes: - * If 'origin' is not NULL, then any names in the rdata that are + *\li If 'origin' is not NULL, then any names in the rdata that are * subdomains of 'origin' will be made relative it. * - * XXX Do we *really* want to support 'origin'? I'm inclined towards "no" + *\li XXX Do we *really* want to support 'origin'? I'm inclined towards "no" * at the moment. * * Requires: * - * 'rdata' is a valid, non-empty rdata + *\li 'rdata' is a valid, non-empty rdata * - * 'origin' is NULL, or is a valid name + *\li 'origin' is NULL, or is a valid name * - * 'target' is a valid text buffer + *\li 'target' is a valid text buffer * - * Ensures: - * If the result is success: + * Ensures, + * if the result is success: * - * The used space in target is updated. + * \li The used space in target is updated. * * Returns: - * Success - * - * Resource Limit: Not enough space + *\li Success + *\li Any non-success status from dns_name_totext() + *\li Resource Limit: Not enough space */ isc_result_t dns_rdata_tofmttext(dns_rdata_t *rdata, dns_name_t *origin, unsigned int flags, unsigned int width, char *linebreak, isc_buffer_t *target); -/* +/*%< * Like dns_rdata_totext, but do formatted output suitable for * database dumps. This is intended for use by dns_db_dump(); * library users are discouraged from calling it directly. * - * If (flags & DNS_STYLEFLAG_MULTILINE) != 0, attempt to stay + * If (flags & #DNS_STYLEFLAG_MULTILINE) != 0, attempt to stay * within 'width' by breaking the text into multiple lines. * The string 'linebreak' is inserted between lines, and parentheses * are added when necessary. Because RRs contain unbreakable elements @@ -403,11 +396,11 @@ dns_rdata_tofmttext(dns_rdata_t *rdata, dns_name_t *origin, unsigned int flags, * potentially large, there is no guarantee that the lines will * not exceed 'width' anyway. * - * If (flags & DNS_STYLEFLAG_MULTILINE) == 0, the rdata is always + * If (flags & #DNS_STYLEFLAG_MULTILINE) == 0, the rdata is always * printed as a single line, and no parentheses are used. * The 'width' and 'linebreak' arguments are ignored. * - * If (flags & DNS_STYLEFLAG_COMMENT) != 0, output explanatory + * If (flags & #DNS_STYLEFLAG_COMMENT) != 0, output explanatory * comments next to things like the SOA timer fields. Some * comments (e.g., the SOA ones) are only printed when multiline * output is selected. @@ -416,7 +409,7 @@ dns_rdata_tofmttext(dns_rdata_t *rdata, dns_name_t *origin, unsigned int flags, isc_result_t dns_rdata_fromstruct(dns_rdata_t *rdata, dns_rdataclass_t rdclass, dns_rdatatype_t type, void *source, isc_buffer_t *target); -/* +/*%< * Convert the C structure representation of an rdata into uncompressed wire * format in 'target'. * @@ -424,30 +417,30 @@ dns_rdata_fromstruct(dns_rdata_t *rdata, dns_rdataclass_t rdclass, * * Requires: * - * 'rdclass' and 'type' are valid. + *\li 'rdclass' and 'type' are valid. * - * 'source' points to a valid C struct for the class and type. + *\li 'source' points to a valid C struct for the class and type. * - * 'target' is a valid buffer. + *\li 'target' is a valid buffer. * - * All structure pointers to memory blocks should be NULL if their + *\li All structure pointers to memory blocks should be NULL if their * corresponding length values are zero. * - * Ensures: - * If result is success: - * If 'rdata' is not NULL, it is attached to the target. + * Ensures, + * if result is success: + * \li If 'rdata' is not NULL, it is attached to the target. * - * The used space in 'target' is updated. + * \li The used space in 'target' is updated. * * Result: - * Success - * - * Resource Limit: Not enough space + *\li Success + *\li Various 'Bad Form' class failures depending on class and type + *\li Resource Limit: Not enough space */ isc_result_t dns_rdata_tostruct(dns_rdata_t *rdata, void *target, isc_mem_t *mctx); -/* +/*%< * Convert an rdata into its C structure representation. * * If 'mctx' is NULL then 'rdata' must persist while 'target' is being used. @@ -456,80 +449,80 @@ dns_rdata_tostruct(dns_rdata_t *rdata, void *target, isc_mem_t *mctx); * * Requires: * - * 'rdata' is a valid, non-empty rdata. + *\li 'rdata' is a valid, non-empty rdata. * - * 'target' to point to a valid pointer for the type and class. + *\li 'target' to point to a valid pointer for the type and class. * * Result: - * Success - * Resource Limit: Not enough memory + *\li Success + *\li Resource Limit: Not enough memory */ void dns_rdata_freestruct(void *source); -/* +/*%< * Free dynamic memory attached to 'source' (if any). * * Requires: * - * 'source' to point to the structure previously filled in by + *\li 'source' to point to the structure previously filled in by * dns_rdata_tostruct(). */ isc_boolean_t dns_rdatatype_ismeta(dns_rdatatype_t type); -/* +/*%< * Return true iff the rdata type 'type' is a meta-type * like ANY or AXFR. */ isc_boolean_t dns_rdatatype_issingleton(dns_rdatatype_t type); -/* +/*%< * Return true iff the rdata type 'type' is a singleton type, * like CNAME or SOA. * * Requires: - * 'type' is a valid rdata type. + * \li 'type' is a valid rdata type. * */ isc_boolean_t dns_rdataclass_ismeta(dns_rdataclass_t rdclass); -/* +/*%< * Return true iff the rdata class 'rdclass' is a meta-class * like ANY or NONE. */ isc_boolean_t dns_rdatatype_isdnssec(dns_rdatatype_t type); -/* +/*%< * Return true iff 'type' is one of the DNSSEC * rdata types that may exist alongside a CNAME record. * * Requires: - * 'type' is a valid rdata type. + * \li 'type' is a valid rdata type. */ isc_boolean_t dns_rdatatype_iszonecutauth(dns_rdatatype_t type); -/* +/*%< * Return true iff rdata of type 'type' is considered authoritative * data (not glue) in the NSEC chain when it occurs in the parent zone * at a zone cut. * * Requires: - * 'type' is a valid rdata type. + * \li 'type' is a valid rdata type. * */ isc_boolean_t dns_rdatatype_isknown(dns_rdatatype_t type); -/* +/*%< * Return true iff the rdata type 'type' is known. * * Requires: - * 'type' is a valid rdata type. + * \li 'type' is a valid rdata type. * */ @@ -537,140 +530,140 @@ dns_rdatatype_isknown(dns_rdatatype_t type); isc_result_t dns_rdata_additionaldata(dns_rdata_t *rdata, dns_additionaldatafunc_t add, void *arg); -/* +/*%< * Call 'add' for each name and type from 'rdata' which is subject to * additional section processing. * * Requires: * - * 'rdata' is a valid, non-empty rdata. + *\li 'rdata' is a valid, non-empty rdata. * - * 'add' is a valid dns_additionalfunc_t. + *\li 'add' is a valid dns_additionalfunc_t. * * Ensures: * - * If successful, then add() will have been called for each name + *\li If successful, then add() will have been called for each name * and type subject to additional section processing. * - * If add() returns something other than ISC_R_SUCCESS, that result + *\li If add() returns something other than #ISC_R_SUCCESS, that result * will be returned as the result of dns_rdata_additionaldata(). * * Returns: * - * ISC_R_SUCCESS + *\li ISC_R_SUCCESS * - * Many other results are possible if not successful. + *\li Many other results are possible if not successful. */ isc_result_t dns_rdata_digest(dns_rdata_t *rdata, dns_digestfunc_t digest, void *arg); -/* +/*%< * Send 'rdata' in DNSSEC canonical form to 'digest'. * * Note: - * 'digest' may be called more than once by dns_rdata_digest(). The + *\li 'digest' may be called more than once by dns_rdata_digest(). The * concatenation of all the regions, in the order they were given * to 'digest', will be the DNSSEC canonical form of 'rdata'. * * Requires: * - * 'rdata' is a valid, non-empty rdata. + *\li 'rdata' is a valid, non-empty rdata. * - * 'digest' is a valid dns_digestfunc_t. + *\li 'digest' is a valid dns_digestfunc_t. * * Ensures: * - * If successful, then all of the rdata's data has been sent, in + *\li If successful, then all of the rdata's data has been sent, in * DNSSEC canonical form, to 'digest'. * - * If digest() returns something other than ISC_R_SUCCESS, that result + *\li If digest() returns something other than ISC_R_SUCCESS, that result * will be returned as the result of dns_rdata_digest(). * * Returns: * - * ISC_R_SUCCESS + *\li ISC_R_SUCCESS * - * Many other results are possible if not successful. + *\li Many other results are possible if not successful. */ isc_boolean_t dns_rdatatype_questiononly(dns_rdatatype_t type); -/* +/*%< * Return true iff rdata of type 'type' can only appear in the question * section of a properly formatted message. * * Requires: - * 'type' is a valid rdata type. + * \li 'type' is a valid rdata type. * */ isc_boolean_t dns_rdatatype_notquestion(dns_rdatatype_t type); -/* +/*%< * Return true iff rdata of type 'type' can not appear in the question * section of a properly formatted message. * * Requires: - * 'type' is a valid rdata type. + * \li 'type' is a valid rdata type. * */ isc_boolean_t dns_rdatatype_atparent(dns_rdatatype_t type); -/* +/*%< * Return true iff rdata of type 'type' should appear at the parent of * a zone cut. * * Requires: - * 'type' is a valid rdata type. + * \li 'type' is a valid rdata type. * */ unsigned int dns_rdatatype_attributes(dns_rdatatype_t rdtype); -/* +/*%< * Return attributes for the given type. * * Requires: - * 'rdtype' are known. + *\li 'rdtype' are known. * * Returns: - * a bitmask consisting of the following flags. + *\li a bitmask consisting of the following flags. */ -/* only one may exist for a name */ +/*% only one may exist for a name */ #define DNS_RDATATYPEATTR_SINGLETON 0x00000001U -/* requires no other data be present */ +/*% requires no other data be present */ #define DNS_RDATATYPEATTR_EXCLUSIVE 0x00000002U -/* Is a meta type */ +/*% Is a meta type */ #define DNS_RDATATYPEATTR_META 0x00000004U -/* Is a DNSSEC type, like RRSIG or NSEC */ +/*% Is a DNSSEC type, like RRSIG or NSEC */ #define DNS_RDATATYPEATTR_DNSSEC 0x00000008U -/* Is a zone cut authority type */ +/*% Is a zone cut authority type */ #define DNS_RDATATYPEATTR_ZONECUTAUTH 0x00000010U -/* Is reserved (unusable) */ +/*% Is reserved (unusable) */ #define DNS_RDATATYPEATTR_RESERVED 0x00000020U -/* Is an unknown type */ +/*% Is an unknown type */ #define DNS_RDATATYPEATTR_UNKNOWN 0x00000040U -/* Is META, and can only be in a question section */ +/*% Is META, and can only be in a question section */ #define DNS_RDATATYPEATTR_QUESTIONONLY 0x00000080U -/* is META, and can NOT be in a question section */ +/*% is META, and can NOT be in a question section */ #define DNS_RDATATYPEATTR_NOTQUESTION 0x00000100U -/* Is present at zone cuts in the parent, not the child */ +/*% Is present at zone cuts in the parent, not the child */ #define DNS_RDATATYPEATTR_ATPARENT 0x00000200U dns_rdatatype_t dns_rdata_covers(dns_rdata_t *rdata); -/* +/*%< * Return the rdatatype that this type covers. * * Requires: - * 'rdata' is a valid, non-empty rdata. + *\li 'rdata' is a valid, non-empty rdata. * - * 'rdata' is a type that covers other rdata types. + *\li 'rdata' is a type that covers other rdata types. * * Returns: - * The type covered. + *\li The type covered. */ isc_boolean_t diff --git a/lib/dns/include/dns/rdataclass.h b/lib/dns/include/dns/rdataclass.h index 6688211698..e36b980e10 100644 --- a/lib/dns/include/dns/rdataclass.h +++ b/lib/dns/include/dns/rdataclass.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdataclass.h,v 1.18 2004/03/05 05:09:45 marka Exp $ */ +/* $Id: rdataclass.h,v 1.19 2005/04/27 04:56:58 sra Exp $ */ #ifndef DNS_RDATACLASS_H #define DNS_RDATACLASS_H 1 +/*! \file */ + #include #include @@ -28,49 +30,49 @@ ISC_LANG_BEGINDECLS isc_result_t dns_rdataclass_fromtext(dns_rdataclass_t *classp, isc_textregion_t *source); -/* +/*%< * Convert the text 'source' refers to into a DNS class. * * Requires: - * 'classp' is a valid pointer. + *\li 'classp' is a valid pointer. * - * 'source' is a valid text region. + *\li 'source' is a valid text region. * * Returns: - * ISC_R_SUCCESS on success - * DNS_R_UNKNOWN class is unknown + *\li #ISC_R_SUCCESS on success + *\li #DNS_R_UNKNOWN class is unknown */ isc_result_t dns_rdataclass_totext(dns_rdataclass_t rdclass, isc_buffer_t *target); -/* +/*%< * Put a textual representation of class 'rdclass' into 'target'. * * Requires: - * 'rdclass' is a valid class. + *\li 'rdclass' is a valid class. * - * 'target' is a valid text buffer. + *\li 'target' is a valid text buffer. * - * Ensures: - * If the result is success: - * The used space in 'target' is updated. + * Ensures, + * if the result is success: + *\li The used space in 'target' is updated. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_NOSPACE target buffer is too small + *\li #ISC_R_SUCCESS on success + *\li #ISC_R_NOSPACE target buffer is too small */ void dns_rdataclass_format(dns_rdataclass_t rdclass, char *array, unsigned int size); -/* +/*%< * Format a human-readable representation of the class 'rdclass' * into the character array 'array', which is of size 'size'. * The resulting string is guaranteed to be null-terminated. */ #define DNS_RDATACLASS_FORMATSIZE sizeof("CLASS65535") -/* +/*%< * Minimum size of array to pass to dns_rdataclass_format(). */ diff --git a/lib/dns/include/dns/rdatalist.h b/lib/dns/include/dns/rdatalist.h index 8386299d96..3edc600630 100644 --- a/lib/dns/include/dns/rdatalist.h +++ b/lib/dns/include/dns/rdatalist.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdatalist.h,v 1.14 2004/03/05 05:09:45 marka Exp $ */ +/* $Id: rdatalist.h,v 1.15 2005/04/27 04:56:58 sra Exp $ */ #ifndef DNS_RDATALIST_H #define DNS_RDATALIST_H 1 @@ -24,32 +24,31 @@ ***** Module Info *****/ -/* - * DNS Rdatalist - * +/*! \file + * \brief * A DNS rdatalist is a list of rdata of a common type and class. * * MP: - * Clients of this module must impose any required synchronization. + *\li Clients of this module must impose any required synchronization. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * None. + *\li None. */ #include #include -/* +/*% * Clients may use this type directly. */ struct dns_rdatalist { @@ -65,38 +64,38 @@ ISC_LANG_BEGINDECLS void dns_rdatalist_init(dns_rdatalist_t *rdatalist); -/* +/*%< * Initialize rdatalist. * * Ensures: - * All fields of rdatalist have been initialized to their default + *\li All fields of rdatalist have been initialized to their default * values. */ isc_result_t dns_rdatalist_tordataset(dns_rdatalist_t *rdatalist, dns_rdataset_t *rdataset); -/* +/*%< * Make 'rdataset' refer to the rdata in 'rdatalist'. * * Note: - * The caller must ensure that 'rdatalist' remains valid and unchanged + *\li The caller must ensure that 'rdatalist' remains valid and unchanged * while 'rdataset' is associated with it. * * Requires: * - * 'rdatalist' is a valid rdatalist. + *\li 'rdatalist' is a valid rdatalist. * - * 'rdataset' is a valid rdataset that is not currently associated with + *\li 'rdataset' is a valid rdataset that is not currently associated with * any rdata. * - * Ensures: - * On success, + * Ensures, + * on success, * - * 'rdataset' is associated with the rdata in rdatalist. + *\li 'rdataset' is associated with the rdata in rdatalist. * * Returns: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/rdataset.h b/lib/dns/include/dns/rdataset.h index c83db86384..f63658c038 100644 --- a/lib/dns/include/dns/rdataset.h +++ b/lib/dns/include/dns/rdataset.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdataset.h,v 1.54 2005/03/16 00:55:18 marka Exp $ */ +/* $Id: rdataset.h,v 1.55 2005/04/27 04:56:58 sra Exp $ */ #ifndef DNS_RDATASET_H #define DNS_RDATASET_H 1 @@ -24,9 +24,8 @@ ***** Module Info *****/ -/* - * DNS Rdataset - * +/*! \file + * \brief * A DNS rdataset is a handle that can be associated with a collection of * rdata all having a common owner name, class, and type. * @@ -34,22 +33,22 @@ * rdatasets, an implementation of the method suite (e.g. "slabbed rdata") is * required. * - * XXX XXX + * XXX <more> XXX * * MP: - * Clients of this module must impose any required synchronization. + *\li Clients of this module must impose any required synchronization. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * None. + *\li None. */ #include @@ -110,7 +109,7 @@ typedef struct dns_rdatasetmethods { #define DNS_RDATASET_MAGIC ISC_MAGIC('D','N','S','R') #define DNS_RDATASET_VALID(set) ISC_MAGIC_VALID(set, DNS_RDATASET_MAGIC) -/* +/*% * Direct use of this structure by clients is strongly discouraged, except * for the 'link' field which may be used however the client wishes. The * 'private', 'current', and 'index' fields MUST NOT be changed by clients. @@ -134,14 +133,15 @@ struct dns_rdataset { * attributes */ unsigned int attributes; - /* + /*% * the counter provides the starting point in the "cyclic" order. * The value ISC_UINT32_MAX has a special meaning of "picking up a * random value." in order to take care of databases that do not * increment the counter. */ isc_uint32_t count; - /* + /*@{*/ + /*% * These are for use by the rdataset implementation, and MUST NOT * be changed by clients. */ @@ -151,35 +151,36 @@ struct dns_rdataset { unsigned int privateuint4; void * private5; void * private6; + /*@}*/ }; -/* - * _RENDERED: +/*! + * \def DNS_RDATASETATTR_RENDERED * Used by message.c to indicate that the rdataset was rendered. * - * _TTLADJUSTED: + * \def DNS_RDATASETATTR_TTLADJUSTED * Used by message.c to indicate that the rdataset's rdata had differing * TTL values, and the rdataset->ttl holds the smallest. */ #define DNS_RDATASETATTR_QUESTION 0x00000001 -#define DNS_RDATASETATTR_RENDERED 0x00000002 /* Used by message.c */ -#define DNS_RDATASETATTR_ANSWERED 0x00000004 /* Used by server. */ -#define DNS_RDATASETATTR_CACHE 0x00000008 /* Used by resolver. */ -#define DNS_RDATASETATTR_ANSWER 0x00000010 /* Used by resolver. */ -#define DNS_RDATASETATTR_ANSWERSIG 0x00000020 /* Used by resolver. */ -#define DNS_RDATASETATTR_EXTERNAL 0x00000040 /* Used by resolver. */ -#define DNS_RDATASETATTR_NCACHE 0x00000080 /* Used by resolver. */ -#define DNS_RDATASETATTR_CHAINING 0x00000100 /* Used by resolver. */ -#define DNS_RDATASETATTR_TTLADJUSTED 0x00000200 /* Used by message.c */ +#define DNS_RDATASETATTR_RENDERED 0x00000002 /*%< Used by message.c */ +#define DNS_RDATASETATTR_ANSWERED 0x00000004 /*%< Used by server. */ +#define DNS_RDATASETATTR_CACHE 0x00000008 /*%< Used by resolver. */ +#define DNS_RDATASETATTR_ANSWER 0x00000010 /*%< Used by resolver. */ +#define DNS_RDATASETATTR_ANSWERSIG 0x00000020 /*%< Used by resolver. */ +#define DNS_RDATASETATTR_EXTERNAL 0x00000040 /*%< Used by resolver. */ +#define DNS_RDATASETATTR_NCACHE 0x00000080 /*%< Used by resolver. */ +#define DNS_RDATASETATTR_CHAINING 0x00000100 /*%< Used by resolver. */ +#define DNS_RDATASETATTR_TTLADJUSTED 0x00000200 /*%< Used by message.c */ #define DNS_RDATASETATTR_FIXEDORDER 0x00000400 #define DNS_RDATASETATTR_RANDOMIZE 0x00000800 -#define DNS_RDATASETATTR_CHASE 0x00001000 /* Used by resolver. */ +#define DNS_RDATASETATTR_CHASE 0x00001000 /*%< Used by resolver. */ #define DNS_RDATASETATTR_NXDOMAIN 0x00002000 #define DNS_RDATASETATTR_NOQNAME 0x00004000 -#define DNS_RDATASETATTR_CHECKNAMES 0x00008000 /* Used by resolver. */ +#define DNS_RDATASETATTR_CHECKNAMES 0x00008000 /*%< Used by resolver. */ #define DNS_RDATASETATTR_REQUIREDGLUE 0x00010000 -/* +/*% * _OMITDNSSEC: * Omit DNSSEC records when rendering ncache records. */ @@ -187,147 +188,147 @@ struct dns_rdataset { void dns_rdataset_init(dns_rdataset_t *rdataset); -/* +/*%< * Make 'rdataset' a valid, disassociated rdataset. * * Requires: - * 'rdataset' is not NULL. + *\li 'rdataset' is not NULL. * * Ensures: - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. */ void dns_rdataset_invalidate(dns_rdataset_t *rdataset); -/* +/*%< * Invalidate 'rdataset'. * * Requires: - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. * * Ensures: - * If assertion checking is enabled, future attempts to use 'rdataset' + *\li If assertion checking is enabled, future attempts to use 'rdataset' * without initializing it will cause an assertion failure. */ void dns_rdataset_disassociate(dns_rdataset_t *rdataset); -/* +/*%< * Disassociate 'rdataset' from its rdata, allowing it to be reused. * * Notes: - * The client must ensure it has no references to rdata in the rdataset + *\li The client must ensure it has no references to rdata in the rdataset * before disassociating. * * Requires: - * 'rdataset' is a valid, associated rdataset. + *\li 'rdataset' is a valid, associated rdataset. * * Ensures: - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. */ isc_boolean_t dns_rdataset_isassociated(dns_rdataset_t *rdataset); -/* +/*%< * Is 'rdataset' associated? * * Requires: - * 'rdataset' is a valid rdataset. + *\li 'rdataset' is a valid rdataset. * * Returns: - * ISC_TRUE 'rdataset' is associated. - * ISC_FALSE 'rdataset' is not associated. + *\li #ISC_TRUE 'rdataset' is associated. + *\li #ISC_FALSE 'rdataset' is not associated. */ void dns_rdataset_makequestion(dns_rdataset_t *rdataset, dns_rdataclass_t rdclass, dns_rdatatype_t type); -/* +/*%< * Make 'rdataset' a valid, associated, question rdataset, with a * question class of 'rdclass' and type 'type'. * * Notes: - * Question rdatasets have a class and type, but no rdata. + *\li Question rdatasets have a class and type, but no rdata. * * Requires: - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. * * Ensures: - * 'rdataset' is a valid, associated, question rdataset. + *\li 'rdataset' is a valid, associated, question rdataset. */ void dns_rdataset_clone(dns_rdataset_t *source, dns_rdataset_t *target); -/* +/*%< * Make 'target' refer to the same rdataset as 'source'. * * Requires: - * 'source' is a valid, associated rdataset. + *\li 'source' is a valid, associated rdataset. * - * 'target' is a valid, dissociated rdataset. + *\li 'target' is a valid, dissociated rdataset. * * Ensures: - * 'target' references the same rdataset as 'source'. + *\li 'target' references the same rdataset as 'source'. */ unsigned int dns_rdataset_count(dns_rdataset_t *rdataset); -/* +/*%< * Return the number of records in 'rdataset'. * * Requires: - * 'rdataset' is a valid, associated rdataset. + *\li 'rdataset' is a valid, associated rdataset. * * Returns: - * The number of records in 'rdataset'. + *\li The number of records in 'rdataset'. */ isc_result_t dns_rdataset_first(dns_rdataset_t *rdataset); -/* +/*%< * Move the rdata cursor to the first rdata in the rdataset (if any). * * Requires: - * 'rdataset' is a valid, associated rdataset. + *\li 'rdataset' is a valid, associated rdataset. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE There are no rdata in the set. + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no rdata in the set. */ isc_result_t dns_rdataset_next(dns_rdataset_t *rdataset); -/* +/*%< * Move the rdata cursor to the next rdata in the rdataset (if any). * * Requires: - * 'rdataset' is a valid, associated rdataset. + *\li 'rdataset' is a valid, associated rdataset. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE There are no more rdata in the set. + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE There are no more rdata in the set. */ void dns_rdataset_current(dns_rdataset_t *rdataset, dns_rdata_t *rdata); -/* +/*%< * Make 'rdata' refer to the current rdata. * * Notes: * - * The data returned in 'rdata' is valid for the life of the + *\li The data returned in 'rdata' is valid for the life of the * rdataset; in particular, subsequent changes in the cursor position * do not invalidate 'rdata'. * * Requires: - * 'rdataset' is a valid, associated rdataset. + *\li 'rdataset' is a valid, associated rdataset. * - * The rdata cursor of 'rdataset' is at a valid location (i.e. the + *\li The rdata cursor of 'rdataset' is at a valid location (i.e. the * result of last call to a cursor movement command was ISC_R_SUCCESS). * * Ensures: - * 'rdata' refers to the rdata at the rdata cursor location of - * 'rdataset'. + *\li 'rdata' refers to the rdata at the rdata cursor location of + *\li 'rdataset'. */ isc_result_t @@ -336,23 +337,23 @@ dns_rdataset_totext(dns_rdataset_t *rdataset, isc_boolean_t omit_final_dot, isc_boolean_t question, isc_buffer_t *target); -/* +/*%< * Convert 'rdataset' to text format, storing the result in 'target'. * * Notes: - * The rdata cursor position will be changed. + *\li The rdata cursor position will be changed. * - * The 'question' flag should normally be ISC_FALSE. If it is - * ISC_TRUE, the TTL and rdata fields are not printed. This is + *\li The 'question' flag should normally be #ISC_FALSE. If it is + * #ISC_TRUE, the TTL and rdata fields are not printed. This is * for use when printing an rdata representing a question section. * - * This interface is deprecated; use dns_master_rdatasettottext() + *\li This interface is deprecated; use dns_master_rdatasettottext() * and/or dns_master_questiontotext() instead. * * Requires: - * 'rdataset' is a valid rdataset. + *\li 'rdataset' is a valid rdataset. * - * 'rdataset' is not empty. + *\li 'rdataset' is not empty. */ isc_result_t @@ -362,35 +363,35 @@ dns_rdataset_towire(dns_rdataset_t *rdataset, isc_buffer_t *target, unsigned int options, unsigned int *countp); -/* +/*%< * Convert 'rdataset' to wire format, compressing names as specified * in 'cctx', and storing the result in 'target'. * * Notes: - * The rdata cursor position will be changed. + *\li The rdata cursor position will be changed. * - * The number of RRs added to target will be added to *countp. + *\li The number of RRs added to target will be added to *countp. * * Requires: - * 'rdataset' is a valid rdataset. + *\li 'rdataset' is a valid rdataset. * - * 'rdataset' is not empty. + *\li 'rdataset' is not empty. * - * 'countp' is a valid pointer. + *\li 'countp' is a valid pointer. * * Ensures: - * On a return of ISC_R_SUCCESS, 'target' contains a wire format + *\li On a return of ISC_R_SUCCESS, 'target' contains a wire format * for the data contained in 'rdataset'. Any error return leaves * the buffer unchanged. * - * *countp has been incremented by the number of RRs added to + *\li *countp has been incremented by the number of RRs added to * target. * * Returns: - * ISC_R_SUCCESS - all ok - * ISC_R_NOSPACE - 'target' doesn't have enough room + *\li #ISC_R_SUCCESS - all ok + *\li #ISC_R_NOSPACE - 'target' doesn't have enough room * - * Any error returned by dns_rdata_towire(), dns_rdataset_next(), + *\li Any error returned by dns_rdata_towire(), dns_rdataset_next(), * dns_name_towire(). */ @@ -403,13 +404,13 @@ dns_rdataset_towiresorted(dns_rdataset_t *rdataset, void *order_arg, unsigned int options, unsigned int *countp); -/* +/*%< * Like dns_rdataset_towire(), but sorting the rdatasets according to * the integer value returned by 'order' when called witih the rdataset * and 'order_arg' as arguments. * * Requires: - * All the requirements of dns_rdataset_towire(), and + *\li All the requirements of dns_rdataset_towire(), and * that order_arg is NULL if and only if order is NULL. */ @@ -423,20 +424,20 @@ dns_rdataset_towirepartial(dns_rdataset_t *rdataset, unsigned int options, unsigned int *countp, void **state); -/* +/*%< * Like dns_rdataset_towiresorted() except that a partial rdataset * may be written. * * Requires: - * All the requirements of dns_rdataset_towiresorted(). + *\li All the requirements of dns_rdataset_towiresorted(). * If 'state' is non NULL then the current position in the * rdataset will be remembered if the rdataset in not * completely written and should be passed on on subsequent * calls (NOT CURRENTLY IMPLEMENTED). * * Returns: - * ISC_R_SUCCESS if all of the records were written. - * ISC_R_NOSPACE if unable to fit in all of the records. *countp + *\li #ISC_R_SUCCESS if all of the records were written. + *\li #ISC_R_NOSPACE if unable to fit in all of the records. *countp * will be updated to reflect the number of records * written. */ @@ -444,54 +445,54 @@ dns_rdataset_towirepartial(dns_rdataset_t *rdataset, isc_result_t dns_rdataset_additionaldata(dns_rdataset_t *rdataset, dns_additionaldatafunc_t add, void *arg); -/* +/*%< * For each rdata in rdataset, call 'add' for each name and type in the * rdata which is subject to additional section processing. * * Requires: * - * 'rdataset' is a valid, non-question rdataset. + *\li 'rdataset' is a valid, non-question rdataset. * - * 'add' is a valid dns_additionaldatafunc_t + *\li 'add' is a valid dns_additionaldatafunc_t * * Ensures: * - * If successful, dns_rdata_additionaldata() will have been called for + *\li If successful, dns_rdata_additionaldata() will have been called for * each rdata in 'rdataset'. * - * If a call to dns_rdata_additionaldata() is not successful, the + *\li If a call to dns_rdata_additionaldata() is not successful, the * result returned will be the result of dns_rdataset_additionaldata(). * * Returns: * - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * - * Any error that dns_rdata_additionaldata() can return. + *\li Any error that dns_rdata_additionaldata() can return. */ isc_result_t dns_rdataset_getnoqname(dns_rdataset_t *rdataset, dns_name_t *name, dns_rdataset_t *nsec, dns_rdataset_t *nsecsig); -/* +/*%< * Return the noqname proof for this record. * * Requires: - * 'rdataset' to be valid and DNS_RDATASETATTR_NOQNAME to be set. - * 'name' to be valid. - * 'nsec' and 'nsecsig' to be valid and not associated. + *\li 'rdataset' to be valid and #DNS_RDATASETATTR_NOQNAME to be set. + *\li 'name' to be valid. + *\li 'nsec' and 'nsecsig' to be valid and not associated. */ isc_result_t dns_rdataset_addnoqname(dns_rdataset_t *rdataset, dns_name_t *name); -/* +/*%< * Associate a noqname proof with this record. - * Sets DNS_RDATASETATTR_NOQNAME if successful. + * Sets #DNS_RDATASETATTR_NOQNAME if successful. * Adjusts the 'rdataset->ttl' to minimum of the 'rdataset->ttl' and * the 'nsec' and 'rrsig(nsec)' ttl. * * Requires: - * 'rdataset' to be valid and DNS_RDATASETATTR_NOQNAME to be set. - * 'name' to be valid and have NSEC and RRSIG(NSEC) rdatasets. + *\li 'rdataset' to be valid and #DNS_RDATASETATTR_NOQNAME to be set. + *\li 'name' to be valid and have NSEC and RRSIG(NSEC) rdatasets. */ isc_result_t diff --git a/lib/dns/include/dns/rdatasetiter.h b/lib/dns/include/dns/rdatasetiter.h index 7de734ca35..c2d2e7e6d2 100644 --- a/lib/dns/include/dns/rdatasetiter.h +++ b/lib/dns/include/dns/rdatasetiter.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdatasetiter.h,v 1.15 2004/03/05 05:09:45 marka Exp $ */ +/* $Id: rdatasetiter.h,v 1.16 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_RDATASETITER_H #define DNS_RDATASETITER_H 1 @@ -24,9 +24,8 @@ ***** Module Info *****/ -/* - * DNS Rdataset Iterator - * +/*! \file + * \brief * The DNS Rdataset Iterator interface allows iteration of all of the * rdatasets at a node. * @@ -37,25 +36,25 @@ * It is the client's responsibility to call dns_rdataset_disassociate() * on all rdatasets returned. * - * XXX XXX + * XXX more XXX * * MP: - * The iterator itself is not locked. The caller must ensure + *\li The iterator itself is not locked. The caller must ensure * synchronization. * - * The iterator methods ensure appropriate database locking. + *\li The iterator methods ensure appropriate database locking. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * None. + *\li None. */ /***** @@ -85,12 +84,12 @@ typedef struct dns_rdatasetitermethods { #define DNS_RDATASETITER_MAGIC ISC_MAGIC('D','N','S','i') #define DNS_RDATASETITER_VALID(i) ISC_MAGIC_VALID(i, DNS_RDATASETITER_MAGIC) -/* +/*% * This structure is actually just the common prefix of a DNS db * implementation's version of a dns_rdatasetiter_t. - * + * \brief * Direct use of this structure by clients is forbidden. DB implementations - * may change the structure. 'magic' must be DNS_RDATASETITER_MAGIC for + * may change the structure. 'magic' must be #DNS_RDATASETITER_MAGIC for * any of the dns_rdatasetiter routines to work. DB implementations must * maintain all DB rdataset iterator invariants. */ @@ -106,64 +105,64 @@ struct dns_rdatasetiter { void dns_rdatasetiter_destroy(dns_rdatasetiter_t **iteratorp); -/* +/*%< * Destroy '*iteratorp'. * * Requires: * - * '*iteratorp' is a valid iterator. + *\li '*iteratorp' is a valid iterator. * * Ensures: * - * All resources used by the iterator are freed. + *\li All resources used by the iterator are freed. * - * *iteratorp == NULL. + *\li *iteratorp == NULL. */ isc_result_t dns_rdatasetiter_first(dns_rdatasetiter_t *iterator); -/* +/*%< * Move the rdataset cursor to the first rdataset at the node (if any). * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE There are no rdatasets at the node. + *\li ISC_R_SUCCESS + *\li ISC_R_NOMORE There are no rdatasets at the node. * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ isc_result_t dns_rdatasetiter_next(dns_rdatasetiter_t *iterator); -/* +/*%< * Move the rdataset cursor to the next rdataset at the node (if any). * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE There are no more rdatasets at the + *\li ISC_R_SUCCESS + *\li ISC_R_NOMORE There are no more rdatasets at the * node. * - * Other results are possible, depending on the DB implementation. + *\li Other results are possible, depending on the DB implementation. */ void dns_rdatasetiter_current(dns_rdatasetiter_t *iterator, dns_rdataset_t *rdataset); -/* +/*%< * Return the current rdataset. * * Requires: - * 'iterator' is a valid iterator. + *\li 'iterator' is a valid iterator. * - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. * - * The rdataset cursor of 'iterator' is at a valid location (i.e. the - * result of last call to a cursor movement command was ISC_R_SUCCESS). + *\li The rdataset cursor of 'iterator' is at a valid location (i.e. the + * result of last call to a cursor movement command was #ISC_R_SUCCESS). */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/rdataslab.h b/lib/dns/include/dns/rdataslab.h index 500a87385b..01b34ca030 100644 --- a/lib/dns/include/dns/rdataslab.h +++ b/lib/dns/include/dns/rdataslab.h @@ -15,34 +15,33 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdataslab.h,v 1.25 2004/03/05 05:09:46 marka Exp $ */ +/* $Id: rdataslab.h,v 1.26 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_RDATASLAB_H #define DNS_RDATASLAB_H 1 -/* - * DNS Rdata Slab - * +/*! \file + * \brief * Implements storage of rdatasets into slabs of memory. * * MP: - * Clients of this module must impose any required synchronization. + *\li Clients of this module must impose any required synchronization. * * Reliability: - * This module deals with low-level byte streams. Errors in any of + *\li This module deals with low-level byte streams. Errors in any of * the functions are likely to crash the server or corrupt memory. * - * If the caller passes invalid memory references, these functions are + *\li If the caller passes invalid memory references, these functions are * likely to crash the server or corrupt memory. * * Resources: - * None. + *\li None. * * Security: - * None. + *\li None. * * Standards: - * None. + *\li None. */ /*** @@ -65,22 +64,22 @@ ISC_LANG_BEGINDECLS isc_result_t dns_rdataslab_fromrdataset(dns_rdataset_t *rdataset, isc_mem_t *mctx, isc_region_t *region, unsigned int reservelen); -/* +/*%< * Slabify a rdataset. The slab area will be allocated and returned * in 'region'. * * Requires: - * 'rdataset' is valid. + *\li 'rdataset' is valid. * * Ensures: - * 'region' will have base pointing to the start of allocated memory, + *\li 'region' will have base pointing to the start of allocated memory, * with the slabified region beginning at region->base + reservelen. * region->length contains the total length allocated. * * Returns: - * ISC_R_SUCCESS - successful completion - * ISC_R_NOMEMORY - no memory. - * + *\li ISC_R_SUCCESS - successful completion + *\li ISC_R_NOMEMORY - no memory. + *\li XXX others */ void @@ -88,27 +87,26 @@ dns_rdataslab_tordataset(unsigned char *slab, unsigned int reservelen, dns_rdataclass_t rdclass, dns_rdatatype_t rdtype, dns_rdatatype_t covers, dns_ttl_t ttl, dns_rdataset_t *rdataset); -/* +/*%< * Construct an rdataset from a slab. * * Requires: - * 'slab' points to a slab. - * 'rdataset' is disassociated. + *\li 'slab' points to a slab. + *\li 'rdataset' is disassociated. * * Ensures: - * 'rdataset' is associated and points to a valid rdataest. + *\li 'rdataset' is associated and points to a valid rdataest. */ - unsigned int dns_rdataslab_size(unsigned char *slab, unsigned int reservelen); -/* +/*%< * Return the total size of an rdataslab. * * Requires: - * 'slab' points to a slab. + *\li 'slab' points to a slab. * * Returns: - * The number of bytes in the slab, including the reservelen. + *\li The number of bytes in the slab, including the reservelen. */ isc_result_t @@ -116,7 +114,7 @@ dns_rdataslab_merge(unsigned char *oslab, unsigned char *nslab, unsigned int reservelen, isc_mem_t *mctx, dns_rdataclass_t rdclass, dns_rdatatype_t type, unsigned int flags, unsigned char **tslabp); -/* +/*%< * Merge 'oslab' and 'nslab'. */ @@ -125,7 +123,7 @@ dns_rdataslab_subtract(unsigned char *mslab, unsigned char *sslab, unsigned int reservelen, isc_mem_t *mctx, dns_rdataclass_t rdclass, dns_rdatatype_t type, unsigned int flags, unsigned char **tslabp); -/* +/*%< * Subtract 'sslab' from 'mslab'. If 'exact' is true then all elements * of 'sslab' must exist in 'mslab'. * @@ -136,30 +134,28 @@ dns_rdataslab_subtract(unsigned char *mslab, unsigned char *sslab, isc_boolean_t dns_rdataslab_equal(unsigned char *slab1, unsigned char *slab2, unsigned int reservelen); - -/* +/*%< * Compare two rdataslabs for equality. This does _not_ do a full * DNSSEC comparison. * * Requires: - * 'slab1' and 'slab2' point to slabs. + *\li 'slab1' and 'slab2' point to slabs. * * Returns: - * ISC_TRUE if the slabs are equal, ISC_FALSE otherwise. + *\li ISC_TRUE if the slabs are equal, ISC_FALSE otherwise. */ - isc_boolean_t dns_rdataslab_equalx(unsigned char *slab1, unsigned char *slab2, unsigned int reservelen, dns_rdataclass_t rdclass, dns_rdatatype_t type); -/* +/*%< * Compare two rdataslabs for DNSSEC equality. * * Requires: - * 'slab1' and 'slab2' point to slabs. + *\li 'slab1' and 'slab2' point to slabs. * * Returns: - * ISC_TRUE if the slabs are equal, ISC_FALSE otherwise. + *\li ISC_TRUE if the slabs are equal, #ISC_FALSE otherwise. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/rdatatype.h b/lib/dns/include/dns/rdatatype.h index d4c94e5ca3..13d1416f6f 100644 --- a/lib/dns/include/dns/rdatatype.h +++ b/lib/dns/include/dns/rdatatype.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdatatype.h,v 1.18 2004/03/05 05:09:46 marka Exp $ */ +/* $Id: rdatatype.h,v 1.19 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_RDATATYPE_H #define DNS_RDATATYPE_H 1 +/*! \file */ + #include #include @@ -28,49 +30,49 @@ ISC_LANG_BEGINDECLS isc_result_t dns_rdatatype_fromtext(dns_rdatatype_t *typep, isc_textregion_t *source); -/* +/*%< * Convert the text 'source' refers to into a DNS rdata type. * * Requires: - * 'typep' is a valid pointer. + *\li 'typep' is a valid pointer. * - * 'source' is a valid text region. + *\li 'source' is a valid text region. * * Returns: - * ISC_R_SUCCESS on success - * DNS_R_UNKNOWN type is unknown + *\li ISC_R_SUCCESS on success + *\li DNS_R_UNKNOWN type is unknown */ isc_result_t dns_rdatatype_totext(dns_rdatatype_t type, isc_buffer_t *target); -/* +/*%< * Put a textual representation of type 'type' into 'target'. * * Requires: - * 'type' is a valid type. + *\li 'type' is a valid type. * - * 'target' is a valid text buffer. + *\li 'target' is a valid text buffer. * - * Ensures: - * If the result is success: - * The used space in 'target' is updated. + * Ensures, + * if the result is success: + *\li The used space in 'target' is updated. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_NOSPACE target buffer is too small + *\li #ISC_R_SUCCESS on success + *\li #ISC_R_NOSPACE target buffer is too small */ void dns_rdatatype_format(dns_rdatatype_t rdtype, char *array, unsigned int size); -/* +/*%< * Format a human-readable representation of the type 'rdtype' * into the character array 'array', which is of size 'size'. * The resulting string is guaranteed to be null-terminated. */ #define DNS_RDATATYPE_FORMATSIZE sizeof("TYPE65535") -/* +/*%< * Minimum size of array to pass to dns_rdatatype_format(). * May need to be adjusted if a new RR type with a very long * name is defined. diff --git a/lib/dns/include/dns/request.h b/lib/dns/include/dns/request.h index 7579f5920a..f7cad946c9 100644 --- a/lib/dns/include/dns/request.h +++ b/lib/dns/include/dns/request.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: request.h,v 1.21 2004/03/05 05:09:46 marka Exp $ */ +/* $Id: request.h,v 1.22 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_REQUEST_H #define DNS_REQUEST_H 1 @@ -24,21 +24,21 @@ ***** Module Info *****/ -/* - * DNS Request +/*! \file * + * \brief * The request module provides simple request/response services useful for * sending SOA queries, DNS Notify messages, and dynamic update requests. * * MP: - * The module ensures appropriate synchronization of data structures it + *\li The module ensures appropriate synchronization of data structures it * creates and manipulates. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. */ #include @@ -62,102 +62,101 @@ dns_requestmgr_create(isc_mem_t *mctx, isc_timermgr_t *timermgr, dns_dispatchmgr_t *dispatchmgr, dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6, dns_requestmgr_t **requestmgrp); -/* +/*%< * Create a request manager. * * Requires: * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. * - * 'timermgr' is a valid timer manager. + *\li 'timermgr' is a valid timer manager. * - * 'socketmgr' is a valid socket manager. + *\li 'socketmgr' is a valid socket manager. * - * 'taskmgr' is a valid task manager. + *\li 'taskmgr' is a valid task manager. * - * 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL. + *\li 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL. * - * 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL. + *\li 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL. * - * requestmgrp != NULL && *requestmgrp == NULL + *\li requestmgrp != NULL && *requestmgrp == NULL * * Ensures: * - * On success, *requestmgrp is a valid request manager. + *\li On success, *requestmgrp is a valid request manager. * * Returns: * - * ISC_R_SUCCESS + *\li ISC_R_SUCCESS * - * Any other result indicates failure. + *\li Any other result indicates failure. */ void dns_requestmgr_whenshutdown(dns_requestmgr_t *requestmgr, isc_task_t *task, isc_event_t **eventp); -/* +/*%< * Send '*eventp' to 'task' when 'requestmgr' has completed shutdown. * * Notes: * - * It is not safe to detach the last reference to 'requestmgr' until + *\li It is not safe to detach the last reference to 'requestmgr' until * shutdown is complete. * * Requires: * - * 'requestmgr' is a valid request manager. + *\li 'requestmgr' is a valid request manager. * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * *eventp is a valid event. + *\li *eventp is a valid event. * * Ensures: * - * *eventp == NULL. + *\li *eventp == NULL. */ void dns_requestmgr_shutdown(dns_requestmgr_t *requestmgr); -/* +/*%< * Start the shutdown process for 'requestmgr'. * * Notes: * - * This call has no effect if the request manager is already shutting + *\li This call has no effect if the request manager is already shutting * down. * * Requires: * - * 'requestmgr' is a valid requestmgr. + *\li 'requestmgr' is a valid requestmgr. */ void dns_requestmgr_attach(dns_requestmgr_t *source, dns_requestmgr_t **targetp); -/* +/*%< * Attach to the request manager. dns_requestmgr_shutdown() must not * have been called on 'source' prior to calling dns_requestmgr_attach(). * * Requires: * - * 'source' is a valid requestmgr. + *\li 'source' is a valid requestmgr. * - * 'targetp' to be non NULL and '*targetp' to be NULL. + *\li 'targetp' to be non NULL and '*targetp' to be NULL. */ void dns_requestmgr_detach(dns_requestmgr_t **requestmgrp); -/* - * +/*%< * Detach from the given requestmgr. If this is the final detach * requestmgr will be destroyed. dns_requestmgr_shutdown() must * be called before the final detach. * * Requires: * - * '*requestmgrp' is a valid requestmgr. + *\li '*requestmgrp' is a valid requestmgr. * * Ensures: - * '*requestmgrp' is NULL. + *\li '*requestmgrp' is NULL. */ isc_result_t @@ -167,31 +166,32 @@ dns_request_create(dns_requestmgr_t *requestmgr, dns_message_t *message, unsigned int timeout, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); -/* +/*%< * Create and send a request. * * Notes: * - * 'message' will be rendered and sent to 'address'. If the - * DNS_REQUESTOPT_TCP option is set, TCP will be used. The request + *\li 'message' will be rendered and sent to 'address'. If the + * #DNS_REQUESTOPT_TCP option is set, TCP will be used. The request * will timeout after 'timeout' seconds. * - * When the request completes, successfully, due to a timeout, or + *\li When the request completes, successfully, due to a timeout, or * because it was canceled, a completion event will be sent to 'task'. * * Requires: * - * 'message' is a valid DNS message. + *\li 'message' is a valid DNS message. * - * 'address' is a valid sockaddr. + *\li 'address' is a valid sockaddr. * - * 'timeout' > 0 + *\li 'timeout' > 0 * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * requestp != NULL && *requestp == NULL + *\li requestp != NULL && *requestp == NULL */ +/*% See dns_request_createvia3() */ isc_result_t dns_request_createvia(dns_requestmgr_t *requestmgr, dns_message_t *message, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, @@ -200,6 +200,7 @@ dns_request_createvia(dns_requestmgr_t *requestmgr, dns_message_t *message, isc_taskaction_t action, void *arg, dns_request_t **requestp); +/*% See dns_request_createvia3() */ isc_result_t dns_request_createvia2(dns_requestmgr_t *requestmgr, dns_message_t *message, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, @@ -216,36 +217,37 @@ dns_request_createvia3(dns_requestmgr_t *requestmgr, dns_message_t *message, unsigned int udpretries, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); -/* +/*%< * Create and send a request. * * Notes: * - * 'message' will be rendered and sent to 'address'. If the - * DNS_REQUESTOPT_TCP option is set, TCP will be used. The request + *\li 'message' will be rendered and sent to 'address'. If the + * #DNS_REQUESTOPT_TCP option is set, TCP will be used. The request * will timeout after 'timeout' seconds. UDP requests will be resent * at 'udptimeout' intervals if non-zero or 'udpretries' is non-zero. * - * When the request completes, successfully, due to a timeout, or + *\li When the request completes, successfully, due to a timeout, or * because it was canceled, a completion event will be sent to 'task'. * * Requires: * - * 'message' is a valid DNS message. + *\li 'message' is a valid DNS message. * - * 'dstaddr' is a valid sockaddr. + *\li 'dstaddr' is a valid sockaddr. * - * 'srcaddr' is a valid sockaddr or NULL. + *\li 'srcaddr' is a valid sockaddr or NULL. * - * 'srcaddr' and 'dstaddr' are the same protocol family. + *\li 'srcaddr' and 'dstaddr' are the same protocol family. * - * 'timeout' > 0 + *\li 'timeout' > 0 * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * requestp != NULL && *requestp == NULL + *\li requestp != NULL && *requestp == NULL */ +/*% See dns_request_createraw3() */ isc_result_t dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, @@ -253,6 +255,7 @@ dns_request_createraw(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); +/*% See dns_request_createraw3() */ isc_result_t dns_request_createraw2(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf, isc_sockaddr_t *srcaddr, isc_sockaddr_t *destaddr, @@ -268,55 +271,55 @@ dns_request_createraw3(dns_requestmgr_t *requestmgr, isc_buffer_t *msgbuf, unsigned int udptimeout, unsigned int udpretries, isc_task_t *task, isc_taskaction_t action, void *arg, dns_request_t **requestp); -/* - * Create and send a request. +/*!< + * \brief Create and send a request. * * Notes: * - * 'msgbuf' will be sent to 'destaddr' after setting the id. If the - * DNS_REQUESTOPT_TCP option is set, TCP will be used. The request + *\li 'msgbuf' will be sent to 'destaddr' after setting the id. If the + * #DNS_REQUESTOPT_TCP option is set, TCP will be used. The request * will timeout after 'timeout' seconds. UDP requests will be resent * at 'udptimeout' intervals if non-zero or if 'udpretries' is not zero. * - * When the request completes, successfully, due to a timeout, or + *\li When the request completes, successfully, due to a timeout, or * because it was canceled, a completion event will be sent to 'task'. * * Requires: * - * 'msgbuf' is a valid DNS message in compressed wire format. + *\li 'msgbuf' is a valid DNS message in compressed wire format. * - * 'destaddr' is a valid sockaddr. + *\li 'destaddr' is a valid sockaddr. * - * 'srcaddr' is a valid sockaddr or NULL. + *\li 'srcaddr' is a valid sockaddr or NULL. * - * 'srcaddr' and 'dstaddr' are the same protocol family. + *\li 'srcaddr' and 'dstaddr' are the same protocol family. * - * 'timeout' > 0 + *\li 'timeout' > 0 * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * requestp != NULL && *requestp == NULL + *\li requestp != NULL && *requestp == NULL */ void dns_request_cancel(dns_request_t *request); -/* +/*%< * Cancel 'request'. * * Requires: * - * 'request' is a valid request. + *\li 'request' is a valid request. * * Ensures: * - * If the completion event for 'request' has not yet been sent, it + *\li If the completion event for 'request' has not yet been sent, it * will be sent, and the result code will be ISC_R_CANCELED. */ isc_result_t dns_request_getresponse(dns_request_t *request, dns_message_t *message, unsigned int options); -/* +/*%< * Get the response to 'request' by filling in 'message'. * * 'options' is passed to dns_message_parse(). See dns_message_parse() @@ -324,46 +327,46 @@ dns_request_getresponse(dns_request_t *request, dns_message_t *message, * * Requires: * - * 'request' is a valid request for which the caller has received the + *\li 'request' is a valid request for which the caller has received the * completion event. * - * The result code of the completion event was ISC_R_SUCCESS. + *\li The result code of the completion event was #ISC_R_SUCCESS. * * Returns: * - * ISC_R_SUCCESS + *\li ISC_R_SUCCESS * - * Any result that dns_message_parse() can return. + *\li Any result that dns_message_parse() can return. */ isc_boolean_t dns_request_usedtcp(dns_request_t *request); -/* - * Return whether this query used TCP or not. Setting DNS_REQUESTOPT_TCP +/*%< + * Return whether this query used TCP or not. Setting #DNS_REQUESTOPT_TCP * in the call to dns_request_create() will cause the function to return - * ISC_TRUE, othewise the result is based on the query message size. + * #ISC_TRUE, othewise the result is based on the query message size. * * Requires: - * 'request' is a valid request. + *\li 'request' is a valid request. * * Returns: - * ISC_TRUE if TCP was used. - * ISC_FALSE if UDP was used. + *\li ISC_TRUE if TCP was used. + *\li ISC_FALSE if UDP was used. */ void dns_request_destroy(dns_request_t **requestp); -/* +/*%< * Destroy 'request'. * * Requires: * - * 'request' is a valid request for which the caller has received the + *\li 'request' is a valid request for which the caller has received the * completion event. * * Ensures: * - * *requestp == NULL + *\li *requestp == NULL */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/resolver.h b/lib/dns/include/dns/resolver.h index 13cdd4a3a1..6f42c7bae0 100644 --- a/lib/dns/include/dns/resolver.h +++ b/lib/dns/include/dns/resolver.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: resolver.h,v 1.43 2005/03/06 15:30:37 marka Exp $ */ +/* $Id: resolver.h,v 1.44 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_RESOLVER_H #define DNS_RESOLVER_H 1 @@ -24,9 +24,9 @@ ***** Module Info *****/ -/* - * DNS Resolver +/*! \file * + * \brief * This is the BIND 9 resolver, the module responsible for resolving DNS * requests by iteratively querying authoritative servers and following * referrals. This is a "full resolver", not to be confused with @@ -35,21 +35,21 @@ * daemon the stub resolver talks to. * * MP: - * The module ensures appropriate synchronization of data structures it + *\li The module ensures appropriate synchronization of data structures it * creates and manipulates. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * RFCs: 1034, 1035, 2181, - * Drafts: + *\li RFCs: 1034, 1035, 2181, TBS + *\li Drafts: TBS */ #include @@ -60,11 +60,11 @@ ISC_LANG_BEGINDECLS -/* +/*% * A dns_fetchevent_t is sent when a 'fetch' completes. Any of 'db', * 'node', 'rdataset', and 'sigrdataset' may be bound. It is the * receiver's responsibility to detach before freeing the event. - * + * \brief * 'rdataset' and 'sigrdataset' are the values that were supplied when * dns_resolver_createfetch() was called. They are returned to the * caller so that they may be freed. @@ -84,12 +84,12 @@ typedef struct dns_fetchevent { /* * Options that modify how a 'fetch' is done. */ -#define DNS_FETCHOPT_TCP 0x01 /* Use TCP. */ -#define DNS_FETCHOPT_UNSHARED 0x02 /* See below. */ -#define DNS_FETCHOPT_RECURSIVE 0x04 /* Set RD? */ -#define DNS_FETCHOPT_NOEDNS0 0x08 /* Do not use EDNS. */ -#define DNS_FETCHOPT_FORWARDONLY 0x10 /* Only use forwarders. */ -#define DNS_FETCHOPT_NOVALIDATE 0x20 /* Disable validation. */ +#define DNS_FETCHOPT_TCP 0x01 /*%< Use TCP. */ +#define DNS_FETCHOPT_UNSHARED 0x02 /*%< See below. */ +#define DNS_FETCHOPT_RECURSIVE 0x04 /*%< Set RD? */ +#define DNS_FETCHOPT_NOEDNS0 0x08 /*%< Do not use EDNS. */ +#define DNS_FETCHOPT_FORWARDONLY 0x10 /*%< Only use forwarders. */ +#define DNS_FETCHOPT_NOVALIDATE 0x20 /*%< Disable validation. */ /* * XXXRTH Should this API be made semi-private? (I.e. @@ -110,114 +110,114 @@ dns_resolver_create(dns_view_t *view, dns_dispatch_t *dispatchv6, dns_resolver_t **resp); -/* +/*%< * Create a resolver. * * Notes: * - * Generally, applications should not create a resolver directly, but + *\li Generally, applications should not create a resolver directly, but * should instead call dns_view_createresolver(). * - * No options are currently defined. + *\li No options are currently defined. * * Requires: * - * 'view' is a valid view. + *\li 'view' is a valid view. * - * 'taskmgr' is a valid task manager. + *\li 'taskmgr' is a valid task manager. * - * 'ntasks' > 0. + *\li 'ntasks' > 0. * - * 'socketmgr' is a valid socket manager. + *\li 'socketmgr' is a valid socket manager. * - * 'timermgr' is a valid timer manager. + *\li 'timermgr' is a valid timer manager. * - * 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL. + *\li 'dispatchv4' is a valid dispatcher with an IPv4 UDP socket, or is NULL. * - * 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL. + *\li 'dispatchv6' is a valid dispatcher with an IPv6 UDP socket, or is NULL. * - * *resp != NULL && *resp == NULL. + *\li *resp != NULL && *resp == NULL. * * Returns: * - * ISC_R_SUCCESS On success. + *\li #ISC_R_SUCCESS On success. * - * Anything else Failure. + *\li Anything else Failure. */ void dns_resolver_freeze(dns_resolver_t *res); -/* +/*%< * Freeze resolver. * * Notes: * - * Certain configuration changes cannot be made after the resolver + *\li Certain configuration changes cannot be made after the resolver * is frozen. Fetches cannot be created until the resolver is frozen. * * Requires: * - * 'res' is a valid, unfrozen resolver. + *\li 'res' is a valid, unfrozen resolver. * * Ensures: * - * 'res' is frozen. + *\li 'res' is frozen. */ void dns_resolver_prime(dns_resolver_t *res); -/* +/*%< * Prime resolver. * * Notes: * - * Resolvers which have a forwarding policy other than dns_fwdpolicy_only + *\li Resolvers which have a forwarding policy other than dns_fwdpolicy_only * need to be primed with the root nameservers, otherwise the root * nameserver hints data may be used indefinitely. This function requests * that the resolver start a priming fetch, if it isn't already priming. * * Requires: * - * 'res' is a valid, frozen resolver. + *\li 'res' is a valid, frozen resolver. */ void dns_resolver_whenshutdown(dns_resolver_t *res, isc_task_t *task, isc_event_t **eventp); -/* +/*%< * Send '*eventp' to 'task' when 'res' has completed shutdown. * * Notes: * - * It is not safe to detach the last reference to 'res' until + *\li It is not safe to detach the last reference to 'res' until * shutdown is complete. * * Requires: * - * 'res' is a valid resolver. + *\li 'res' is a valid resolver. * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * *eventp is a valid event. + *\li *eventp is a valid event. * * Ensures: * - * *eventp == NULL. + *\li *eventp == NULL. */ void dns_resolver_shutdown(dns_resolver_t *res); -/* +/*%< * Start the shutdown process for 'res'. * * Notes: * - * This call has no effect if the resolver is already shutting down. + *\li This call has no effect if the resolver is already shutting down. * * Requires: * - * 'res' is a valid resolver. + *\li 'res' is a valid resolver. */ void @@ -236,88 +236,88 @@ dns_resolver_createfetch(dns_resolver_t *res, dns_name_t *name, dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset, dns_fetch_t **fetchp); -/* +/*%< * Recurse to answer a question. * * Notes: * - * This call starts a query for 'name', type 'type'. + *\li This call starts a query for 'name', type 'type'. * - * The 'domain' is a parent domain of 'name' for which + *\li The 'domain' is a parent domain of 'name' for which * a set of name servers 'nameservers' is known. If no * such name server information is available, set * 'domain' and 'nameservers' to NULL. * - * 'forwarders' is unimplemented, and subject to change when + *\li 'forwarders' is unimplemented, and subject to change when * we figure out how selective forwarding will work. * - * When the fetch completes (successfully or otherwise), a - * DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be + *\li When the fetch completes (successfully or otherwise), a + * #DNS_EVENT_FETCHDONE event with action 'action' and arg 'arg' will be * posted to 'task'. * - * The values of 'rdataset' and 'sigrdataset' will be returned in + *\li The values of 'rdataset' and 'sigrdataset' will be returned in * the FETCHDONE event. * * Requires: * - * 'res' is a valid resolver that has been frozen. + *\li 'res' is a valid resolver that has been frozen. * - * 'name' is a valid name. + *\li 'name' is a valid name. * - * 'type' is not a meta type other than ANY. + *\li 'type' is not a meta type other than ANY. * - * 'domain' is a valid name or NULL. + *\li 'domain' is a valid name or NULL. * - * 'nameservers' is a valid NS rdataset (whose owner name is 'domain') + *\li 'nameservers' is a valid NS rdataset (whose owner name is 'domain') * iff. 'domain' is not NULL. * - * 'forwarders' is NULL. + *\li 'forwarders' is NULL. * - * 'options' contains valid options. + *\li 'options' contains valid options. * - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. * - * 'sigrdataset' is NULL, or is a valid, disassociated rdataset. + *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. * - * fetchp != NULL && *fetchp == NULL. + *\li fetchp != NULL && *fetchp == NULL. * * Returns: * - * ISC_R_SUCCESS Success + *\li #ISC_R_SUCCESS Success * - * Many other values are possible, all of which indicate failure. + *\li Many other values are possible, all of which indicate failure. */ void dns_resolver_cancelfetch(dns_fetch_t *fetch); -/* +/*%< * Cancel 'fetch'. * * Notes: * - * If 'fetch' has not completed, post its FETCHDONE event with a - * result code of ISC_R_CANCELED. + *\li If 'fetch' has not completed, post its FETCHDONE event with a + * result code of #ISC_R_CANCELED. * * Requires: * - * 'fetch' is a valid fetch. + *\li 'fetch' is a valid fetch. */ void dns_resolver_destroyfetch(dns_fetch_t **fetchp); -/* +/*%< * Destroy 'fetch'. * * Requires: * - * '*fetchp' is a valid fetch. + *\li '*fetchp' is a valid fetch. * - * The caller has received the FETCHDONE event (either because the + *\li The caller has received the FETCHDONE event (either because the * fetch completed or because dns_resolver_cancelfetch() was called). * * Ensures: * - * *fetchp == NULL. + *\li *fetchp == NULL. */ dns_dispatchmgr_t * @@ -337,25 +337,25 @@ dns_resolver_taskmgr(dns_resolver_t *resolver); isc_uint32_t dns_resolver_getlamettl(dns_resolver_t *resolver); -/* +/*%< * Get the resolver's lame-ttl. zero => no lame processing. * * Requires: - * 'resolver' to be valid. + *\li 'resolver' to be valid. */ void dns_resolver_setlamettl(dns_resolver_t *resolver, isc_uint32_t lame_ttl); -/* +/*%< * Set the resolver's lame-ttl. zero => no lame processing. * * Requires: - * 'resolver' to be valid. + *\li 'resolver' to be valid. */ unsigned int dns_resolver_nrunning(dns_resolver_t *resolver); -/* +/*%< * Return the number of currently running resolutions in this * resolver. This is may be less than the number of outstanding * fetches due to multiple identical fetches, or more than the @@ -366,50 +366,50 @@ dns_resolver_nrunning(dns_resolver_t *resolver); isc_result_t dns_resolver_addalternate(dns_resolver_t *resolver, isc_sockaddr_t *alt, dns_name_t *name, in_port_t port); -/* +/*%< * Add alternate addresses to be tried in the event that the nameservers * for a zone are not available in the address families supported by the * operating system. * * Require: - * only one of 'name' or 'alt' to be valid. + * \li only one of 'name' or 'alt' to be valid. */ void dns_resolver_setudpsize(dns_resolver_t *resolver, isc_uint16_t udpsize); -/* +/*%< * Set the EDNS UDP buffer size advertised by the server. */ isc_uint16_t dns_resolver_getudpsize(dns_resolver_t *resolver); -/* +/*%< * Get the current EDNS UDP buffer size. */ void dns_resolver_reset_algorithms(dns_resolver_t *resolver); -/* +/*%< * Clear the disabled DNSSEC algorithms. */ isc_result_t dns_resolver_disable_algorithm(dns_resolver_t *resolver, dns_name_t *name, unsigned int alg); -/* +/*%< * Mark the give DNSSEC algorithm as disabled and below 'name'. * Valid algorithms are less than 256. * * Returns: - * ISC_R_SUCCESS - * ISC_R_RANGE - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_RANGE + *\li #ISC_R_NOMEMORY */ isc_boolean_t dns_resolver_algorithm_supported(dns_resolver_t *resolver, dns_name_t *name, unsigned int alg); -/* +/*%< * Check if the given algorithm is supported by this resolver. * This checks if the algorithm has been disabled via * dns_resolver_disable_algorithm() then the underlying diff --git a/lib/dns/include/dns/result.h b/lib/dns/include/dns/result.h index c134a9f398..75cb5a8fdd 100644 --- a/lib/dns/include/dns/result.h +++ b/lib/dns/include/dns/result.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: result.h,v 1.106 2004/05/14 04:45:58 marka Exp $ */ +/* $Id: result.h,v 1.107 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_RESULT_H #define DNS_RESULT_H 1 +/*! \file */ + #include #include @@ -144,7 +146,7 @@ #define DNS_R_MUSTBESECURE (ISC_RESULTCLASS_DNS + 100) #define DNS_R_COVERINGNSEC (ISC_RESULTCLASS_DNS + 101) -#define DNS_R_NRESULTS 102 /* Number of results */ +#define DNS_R_NRESULTS 102 /*%< Number of results */ /* * DNS wire format rcodes. @@ -165,7 +167,7 @@ #define DNS_R_NOTZONE (ISC_RESULTCLASS_DNSRCODE + 10) #define DNS_R_BADVERS (ISC_RESULTCLASS_DNSRCODE + 16) -#define DNS_R_NRCODERESULTS 17 /* Number of rcode results */ +#define DNS_R_NRCODERESULTS 17 /*%< Number of rcode results */ #define DNS_RESULT_ISRCODE(result) \ (ISC_RESULTCLASS_INCLASS(ISC_RESULTCLASS_DNSRCODE, (result))) diff --git a/lib/dns/include/dns/rootns.h b/lib/dns/include/dns/rootns.h index 5e32868d48..834d13ca06 100644 --- a/lib/dns/include/dns/rootns.h +++ b/lib/dns/include/dns/rootns.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rootns.h,v 1.11 2005/02/07 23:57:01 marka Exp $ */ +/* $Id: rootns.h,v 1.12 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_ROOTNS_H #define DNS_ROOTNS_H 1 +/*! \file */ + #include #include diff --git a/lib/dns/include/dns/sdb.h b/lib/dns/include/dns/sdb.h index 1c9f9c2472..7fb952cffa 100644 --- a/lib/dns/include/dns/sdb.h +++ b/lib/dns/include/dns/sdb.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sdb.h,v 1.15 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: sdb.h,v 1.16 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_SDB_H #define DNS_SDB_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * Simple database API. */ @@ -40,17 +41,17 @@ *** Types ***/ -/* +/*% * A simple database. This is an opaque type. */ typedef struct dns_sdb dns_sdb_t; -/* +/*% * A simple database lookup in progress. This is an opaque type. */ typedef struct dns_sdblookup dns_sdblookup_t; -/* +/*% * A simple database traversal in progress. This is an opaque type. */ typedef struct dns_sdballnodes dns_sdballnodes_t; @@ -96,7 +97,7 @@ isc_result_t dns_sdb_register(const char *drivername, const dns_sdbmethods_t *methods, void *driverdata, unsigned int flags, isc_mem_t *mctx, dns_sdbimplementation_t **sdbimp); -/* +/*%< * Register a simple database driver for the database type 'drivername', * implemented by the functions in '*methods'. * @@ -126,7 +127,7 @@ dns_sdb_register(const char *drivername, const dns_sdbmethods_t *methods, * The allnodes function, if non-NULL, fills in an opaque structure to be * used by a database iterator. This allows the zone to be transferred. * This may use a considerable amount of memory for large zones, and the - * zone transfer may not be fully RFC 1035 compliant if the zone is + * zone transfer may not be fully RFC1035 compliant if the zone is * frequently changed. * * The create function will be called for each zone configured @@ -156,19 +157,20 @@ dns_sdb_register(const char *drivername, const dns_sdbmethods_t *methods, void dns_sdb_unregister(dns_sdbimplementation_t **sdbimp); -/* +/*%< * Removes the simple database driver from the list of registered database * types. There must be no active databases of this type when this function * is called. */ +/*% See dns_sdb_putradata() */ isc_result_t dns_sdb_putrr(dns_sdblookup_t *lookup, const char *type, dns_ttl_t ttl, const char *data); isc_result_t dns_sdb_putrdata(dns_sdblookup_t *lookup, dns_rdatatype_t type, dns_ttl_t ttl, const unsigned char *rdata, unsigned int rdlen); -/* +/*%< * Add a single resource record to the lookup structure to be * returned in the query response. dns_sdb_putrr() takes the * resource record in master file text format as a null-terminated @@ -176,6 +178,7 @@ dns_sdb_putrdata(dns_sdblookup_t *lookup, dns_rdatatype_t type, dns_ttl_t ttl, * uncompressed wire format. */ +/*% See dns_sdb_putnamerdata() */ isc_result_t dns_sdb_putnamedrr(dns_sdballnodes_t *allnodes, const char *name, const char *type, dns_ttl_t ttl, const char *data); @@ -183,7 +186,7 @@ isc_result_t dns_sdb_putnamedrdata(dns_sdballnodes_t *allnodes, const char *name, dns_rdatatype_t type, dns_ttl_t ttl, const void *rdata, unsigned int rdlen); -/* +/*%< * Add a single resource record to the allnodes structure to be * included in a zone transfer response, in text or wire * format as above. @@ -192,7 +195,7 @@ dns_sdb_putnamedrdata(dns_sdballnodes_t *allnodes, const char *name, isc_result_t dns_sdb_putsoa(dns_sdblookup_t *lookup, const char *mname, const char *rname, isc_uint32_t serial); -/* +/*%< * This function may optionally be called from the 'authority' callback * to simplify construction of the SOA record for 'zone'. It will * provide a SOA listing 'mname' as as the master server and 'rname' as diff --git a/lib/dns/include/dns/secalg.h b/lib/dns/include/dns/secalg.h index 2570c45d1a..2227face9e 100644 --- a/lib/dns/include/dns/secalg.h +++ b/lib/dns/include/dns/secalg.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: secalg.h,v 1.13 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: secalg.h,v 1.14 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_SECALG_H #define DNS_SECALG_H 1 +/*! \file */ + #include #include @@ -28,40 +30,40 @@ ISC_LANG_BEGINDECLS isc_result_t dns_secalg_fromtext(dns_secalg_t *secalgp, isc_textregion_t *source); -/* +/*%< * Convert the text 'source' refers to into a DNSSEC security algorithm value. * The text may contain either a mnemonic algorithm name or a decimal algorithm * number. * * Requires: - * 'secalgp' is a valid pointer. + *\li 'secalgp' is a valid pointer. * - * 'source' is a valid text region. + *\li 'source' is a valid text region. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_RANGE numeric type is out of range - * DNS_R_UNKNOWN mnemonic type is unknown + *\li ISC_R_SUCCESS on success + *\li ISC_R_RANGE numeric type is out of range + *\li DNS_R_UNKNOWN mnemonic type is unknown */ isc_result_t dns_secalg_totext(dns_secalg_t secalg, isc_buffer_t *target); -/* +/*%< * Put a textual representation of the DNSSEC security algorithm 'secalg' * into 'target'. * * Requires: - * 'secalg' is a valid secalg. + *\li 'secalg' is a valid secalg. * - * 'target' is a valid text buffer. + *\li 'target' is a valid text buffer. * - * Ensures: - * If the result is success: - * The used space in 'target' is updated. + * Ensures, + * if the result is success: + *\li The used space in 'target' is updated. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_NOSPACE target buffer is too small + *\li ISC_R_SUCCESS on success + *\li ISC_R_NOSPACE target buffer is too small */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/secproto.h b/lib/dns/include/dns/secproto.h index fe91ed457f..f571080f8d 100644 --- a/lib/dns/include/dns/secproto.h +++ b/lib/dns/include/dns/secproto.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: secproto.h,v 1.10 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: secproto.h,v 1.11 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_SECPROTO_H #define DNS_SECPROTO_H 1 +/*! \file */ + #include #include @@ -28,40 +30,40 @@ ISC_LANG_BEGINDECLS isc_result_t dns_secproto_fromtext(dns_secproto_t *secprotop, isc_textregion_t *source); -/* +/*%< * Convert the text 'source' refers to into a DNSSEC security protocol value. * The text may contain either a mnemonic protocol name or a decimal protocol * number. * * Requires: - * 'secprotop' is a valid pointer. + *\li 'secprotop' is a valid pointer. * - * 'source' is a valid text region. + *\li 'source' is a valid text region. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_RANGE numeric type is out of range - * DNS_R_UNKNOWN mnemonic type is unknown + *\li ISC_R_SUCCESS on success + *\li ISC_R_RANGE numeric type is out of range + *\li DNS_R_UNKNOWN mnemonic type is unknown */ isc_result_t dns_secproto_totext(dns_secproto_t secproto, isc_buffer_t *target); -/* +/*%< * Put a textual representation of the DNSSEC security protocol 'secproto' * into 'target'. * * Requires: - * 'secproto' is a valid secproto. + *\li 'secproto' is a valid secproto. * - * 'target' is a valid text buffer. + *\li 'target' is a valid text buffer. * - * Ensures: - * If the result is success: - * The used space in 'target' is updated. + * Ensures, + * if the result is success: + * \li The used space in 'target' is updated. * * Returns: - * ISC_R_SUCCESS on success - * ISC_R_NOSPACE target buffer is too small + *\li ISC_R_SUCCESS on success + *\li ISC_R_NOSPACE target buffer is too small */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/soa.h b/lib/dns/include/dns/soa.h index 7d938c1cb0..f2ad28ad62 100644 --- a/lib/dns/include/dns/soa.h +++ b/lib/dns/include/dns/soa.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: soa.h,v 1.3 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: soa.h,v 1.4 2005/04/27 04:56:59 sra Exp $ */ #ifndef DNS_SOA_H #define DNS_SOA_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * SOA utilities. */ diff --git a/lib/dns/include/dns/ssu.h b/lib/dns/include/dns/ssu.h index fa4cf68851..90cac87c54 100644 --- a/lib/dns/include/dns/ssu.h +++ b/lib/dns/include/dns/ssu.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ssu.h,v 1.13 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: ssu.h,v 1.14 2005/04/27 04:57:00 sra Exp $ */ #ifndef DNS_SSU_H #define DNS_SSU_H 1 +/*! \file */ + #include #include @@ -33,43 +35,43 @@ ISC_LANG_BEGINDECLS isc_result_t dns_ssutable_create(isc_mem_t *mctx, dns_ssutable_t **table); -/* +/*%< * Creates a table that will be used to store simple-secure-update rules. * Note: all locking must be provided by the client. * * Requires: - * 'mctx' is a valid memory context - * 'table' is not NULL, and '*table' is NULL + *\li 'mctx' is a valid memory context + *\li 'table' is not NULL, and '*table' is NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li ISC_R_SUCCESS + *\li ISC_R_NOMEMORY */ void dns_ssutable_attach(dns_ssutable_t *source, dns_ssutable_t **targetp); -/* +/*%< * Attach '*targetp' to 'source'. * * Requires: - * 'source' is a valid SSU table - * 'targetp' points to a NULL dns_ssutable_t *. + *\li 'source' is a valid SSU table + *\li 'targetp' points to a NULL dns_ssutable_t *. * * Ensures: - * *targetp is attached to source. + *\li *targetp is attached to source. */ void dns_ssutable_detach(dns_ssutable_t **tablep); -/* +/*%< * Detach '*tablep' from its simple-secure-update rule table. * * Requires: - * 'tablep' points to a valid dns_ssutable_t + *\li 'tablep' points to a valid dns_ssutable_t * * Ensures: - * *tablep is NULL - * If '*tablep' is the last reference to the SSU table, all + *\li *tablep is NULL + *\li If '*tablep' is the last reference to the SSU table, all * resources used by the table will be freed. */ @@ -78,78 +80,80 @@ dns_ssutable_addrule(dns_ssutable_t *table, isc_boolean_t grant, dns_name_t *identity, unsigned int matchtype, dns_name_t *name, unsigned int ntypes, dns_rdatatype_t *types); -/* +/*%< * Adds a new rule to a simple-secure-update rule table. The rule * either grants or denies update privileges of an identity (or set of * identities) to modify a name (or set of names) or certain types present * at that name. * * Notes: - * If 'matchtype' is SELF, this rule only matches if the name + *\li If 'matchtype' is SELF, this rule only matches if the name * to be updated matches the signing identity. * - * If 'ntypes' is 0, this rule applies to all types except + *\li If 'ntypes' is 0, this rule applies to all types except * NS, SOA, RRSIG, and NSEC. * - * If 'types' includes ANY, this rule applies to all types + *\li If 'types' includes ANY, this rule applies to all types * except NSEC. * * Requires: - * 'table' is a valid SSU table - * 'identity' is a valid absolute name - * 'matchtype' must be one of the defined constants. - * 'name' is a valid absolute name - * If 'ntypes' > 0, 'types' must not be NULL + *\li 'table' is a valid SSU table + *\li 'identity' is a valid absolute name + *\li 'matchtype' must be one of the defined constants. + *\li 'name' is a valid absolute name + *\li If 'ntypes' > 0, 'types' must not be NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li ISC_R_SUCCESS + *\li ISC_R_NOMEMORY */ isc_boolean_t dns_ssutable_checkrules(dns_ssutable_t *table, dns_name_t *signer, dns_name_t *name, dns_rdatatype_t type); -/* +/*%< * Checks that the attempted update of (name, type) is allowed according * to the rules specified in the simple-secure-update rule table. If * no rules are matched, access is denied. If signer is NULL, access * is denied. * * Requires: - * 'table' is a valid SSU table - * 'signer' is NULL or a valid absolute name - * 'name' is a valid absolute name + *\li 'table' is a valid SSU table + *\li 'signer' is NULL or a valid absolute name + *\li 'name' is a valid absolute name */ +/*% Accessor functions to extract rule components */ isc_boolean_t dns_ssurule_isgrant(const dns_ssurule_t *rule); +/*% Accessor functions to extract rule components */ dns_name_t * dns_ssurule_identity(const dns_ssurule_t *rule); +/*% Accessor functions to extract rule components */ unsigned int dns_ssurule_matchtype(const dns_ssurule_t *rule); +/*% Accessor functions to extract rule components */ dns_name_t * dns_ssurule_name(const dns_ssurule_t *rule); +/*% Accessor functions to extract rule components */ unsigned int dns_ssurule_types(const dns_ssurule_t *rule, dns_rdatatype_t **types); -/* - * Accessor functions to extract rule components - */ isc_result_t dns_ssutable_firstrule(const dns_ssutable_t *table, dns_ssurule_t **rule); -/* +/*%< * Initiates a rule iterator. There is no need to maintain any state. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE */ isc_result_t dns_ssutable_nextrule(dns_ssurule_t *rule, dns_ssurule_t **nextrule); -/* +/*%< * Returns the next rule in the table. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/stats.h b/lib/dns/include/dns/stats.h index 737a448642..597b088267 100644 --- a/lib/dns/include/dns/stats.h +++ b/lib/dns/include/dns/stats.h @@ -15,23 +15,25 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: stats.h,v 1.5 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: stats.h,v 1.6 2005/04/27 04:57:00 sra Exp $ */ #ifndef DNS_STATS_H #define DNS_STATS_H 1 +/*! \file */ + #include -/* +/*% * Query statistics counter types. */ typedef enum { - dns_statscounter_success = 0, /* Successful lookup */ - dns_statscounter_referral = 1, /* Referral result */ - dns_statscounter_nxrrset = 2, /* NXRRSET result */ - dns_statscounter_nxdomain = 3, /* NXDOMAIN result */ - dns_statscounter_recursion = 4, /* Recursion was used */ - dns_statscounter_failure = 5 /* Some other failure */ + dns_statscounter_success = 0, /*%< Successful lookup */ + dns_statscounter_referral = 1, /*%< Referral result */ + dns_statscounter_nxrrset = 2, /*%< NXRRSET result */ + dns_statscounter_nxdomain = 3, /*%< NXDOMAIN result */ + dns_statscounter_recursion = 4, /*%< Recursion was used */ + dns_statscounter_failure = 5 /*%< Some other failure */ } dns_statscounter_t; #define DNS_STATS_NCOUNTERS 6 @@ -40,14 +42,14 @@ LIBDNS_EXTERNAL_DATA extern const char *dns_statscounter_names[]; isc_result_t dns_stats_alloccounters(isc_mem_t *mctx, isc_uint64_t **ctrp); -/* +/*%< * Allocate an array of query statistics counters from the memory * context 'mctx'. */ void dns_stats_freecounters(isc_mem_t *mctx, isc_uint64_t **ctrp); -/* +/*%< * Free an array of query statistics counters allocated from the memory * context 'mctx'. */ diff --git a/lib/dns/include/dns/tcpmsg.h b/lib/dns/include/dns/tcpmsg.h index fbcc9be08f..4492367bf3 100644 --- a/lib/dns/include/dns/tcpmsg.h +++ b/lib/dns/include/dns/tcpmsg.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: tcpmsg.h,v 1.16 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: tcpmsg.h,v 1.17 2005/04/27 04:57:00 sra Exp $ */ #ifndef DNS_TCPMSG_H #define DNS_TCPMSG_H 1 +/*! \file */ + #include #include #include @@ -45,56 +47,56 @@ ISC_LANG_BEGINDECLS void dns_tcpmsg_init(isc_mem_t *mctx, isc_socket_t *sock, dns_tcpmsg_t *tcpmsg); -/* +/*%< * Associate a tcp message state with a given memory context and * TCP socket. * * Requires: * - * "mctx" and "sock" be non-NULL and valid types. + *\li "mctx" and "sock" be non-NULL and valid types. * - * "sock" be a read/write TCP socket. + *\li "sock" be a read/write TCP socket. * - * "tcpmsg" be non-NULL and an uninitialized or invalidated structure. + *\li "tcpmsg" be non-NULL and an uninitialized or invalidated structure. * * Ensures: * - * "tcpmsg" is a valid structure. + *\li "tcpmsg" is a valid structure. */ void dns_tcpmsg_setmaxsize(dns_tcpmsg_t *tcpmsg, unsigned int maxsize); -/* +/*%< * Set the maximum packet size to "maxsize" * * Requires: * - * "tcpmsg" be valid. + *\li "tcpmsg" be valid. * - * 512 <= "maxsize" <= 65536 + *\li 512 <= "maxsize" <= 65536 */ isc_result_t dns_tcpmsg_readmessage(dns_tcpmsg_t *tcpmsg, isc_task_t *task, isc_taskaction_t action, void *arg); -/* +/*%< * Schedule an event to be delivered when a DNS message is readable, or * when an error occurs on the socket. * * Requires: * - * "tcpmsg" be valid. + *\li "tcpmsg" be valid. * - * "task", "taskaction", and "arg" be valid. + *\li "task", "taskaction", and "arg" be valid. * * Returns: * - * ISC_R_SUCCESS -- no error - * Anything that the isc_socket_recv() call can return. XXXMLG + *\li ISC_R_SUCCESS -- no error + *\li Anything that the isc_socket_recv() call can return. XXXMLG * * Notes: * - * The event delivered is a fully generic event. It will contain no + *\li The event delivered is a fully generic event. It will contain no * actual data. The sender will be a pointer to the dns_tcpmsg_t. * The result code inside that structure should be checked to see * what the final result was. @@ -102,41 +104,41 @@ dns_tcpmsg_readmessage(dns_tcpmsg_t *tcpmsg, void dns_tcpmsg_cancelread(dns_tcpmsg_t *tcpmsg); -/* +/*%< * Cancel a readmessage() call. The event will still be posted with a * CANCELED result code. * * Requires: * - * "tcpmsg" be valid. + *\li "tcpmsg" be valid. */ void dns_tcpmsg_keepbuffer(dns_tcpmsg_t *tcpmsg, isc_buffer_t *buffer); -/* +/*%< * If a dns buffer is to be kept between calls, this function marks the * internal state-machine buffer as invalid, and copies all the contents * of the state into "buffer". * * Requires: * - * "tcpmsg" be valid. + *\li "tcpmsg" be valid. * - * "buffer" be non-NULL. + *\li "buffer" be non-NULL. */ void dns_tcpmsg_invalidate(dns_tcpmsg_t *tcpmsg); -/* +/*%< * Clean up all allocated state, and invalidate the structure. * * Requires: * - * "tcpmsg" be valid. + *\li "tcpmsg" be valid. * * Ensures: * - * "tcpmsg" is invalidated and disassociated with all memory contexts, + *\li "tcpmsg" is invalidated and disassociated with all memory contexts, * sockets, etc. */ diff --git a/lib/dns/include/dns/time.h b/lib/dns/include/dns/time.h index bc74f17ffe..95d02092c5 100644 --- a/lib/dns/include/dns/time.h +++ b/lib/dns/include/dns/time.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: time.h,v 1.11 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: time.h,v 1.12 2005/04/27 04:57:00 sra Exp $ */ #ifndef DNS_TIME_H #define DNS_TIME_H 1 +/*! \file */ + /*** *** Imports ***/ @@ -35,7 +37,7 @@ ISC_LANG_BEGINDECLS isc_result_t dns_time64_fromtext(const char *source, isc_int64_t *target); -/* +/*%< * Convert a date and time in YYYYMMDDHHMMSS text format at 'source' * into to a 64-bit count of seconds since Jan 1 1970 0:00 GMT. * Store the count at 'target'. @@ -43,7 +45,7 @@ dns_time64_fromtext(const char *source, isc_int64_t *target); isc_result_t dns_time32_fromtext(const char *source, isc_uint32_t *target); -/* +/*%< * Like dns_time64_fromtext, but returns the second count modulo 2^32 * as per RFC2535. */ @@ -51,14 +53,14 @@ dns_time32_fromtext(const char *source, isc_uint32_t *target); isc_result_t dns_time64_totext(isc_int64_t value, isc_buffer_t *target); -/* +/*%< * Convert a 64-bit count of seconds since Jan 1 1970 0:00 GMT into * a YYYYMMDDHHMMSS text representation and append it to 'target'. */ isc_result_t dns_time32_totext(isc_uint32_t value, isc_buffer_t *target); -/* +/*%< * Like dns_time64_totext, but for a 32-bit cyclic time value. * Of those dates whose counts of seconds since Jan 1 1970 0:00 GMT * are congruent with 'value' modulo 2^32, the one closest to the diff --git a/lib/dns/include/dns/timer.h b/lib/dns/include/dns/timer.h index 6edb21abe3..1f79fb8706 100644 --- a/lib/dns/include/dns/timer.h +++ b/lib/dns/include/dns/timer.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: timer.h,v 1.3 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: timer.h,v 1.4 2005/04/27 04:57:00 sra Exp $ */ #ifndef DNS_TIMER_H #define DNS_TIMER_H 1 +/*! \file */ + /*** *** Imports ***/ @@ -36,10 +38,10 @@ ISC_LANG_BEGINDECLS isc_result_t dns_timer_setidle(isc_timer_t *timer, unsigned int maxtime, unsigned int idletime, isc_boolean_t purge); -/* +/*%< * Convenience function for setting up simple, one-second-granularity * idle timers as used by zone transfers. - * + * \brief * Set the timer 'timer' to go off after 'idletime' seconds of inactivity, * or after 'maxtime' at the very latest. Events are purged iff * 'purge' is ISC_TRUE. diff --git a/lib/dns/include/dns/tkey.h b/lib/dns/include/dns/tkey.h index ff27cbf2db..541a4cc2f6 100644 --- a/lib/dns/include/dns/tkey.h +++ b/lib/dns/include/dns/tkey.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: tkey.h,v 1.19 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: tkey.h,v 1.20 2005/04/27 04:57:00 sra Exp $ */ #ifndef DNS_TKEY_H #define DNS_TKEY_H 1 +/*! \file */ + #include #include @@ -45,55 +47,55 @@ struct dns_tkeyctx { isc_result_t dns_tkeyctx_create(isc_mem_t *mctx, isc_entropy_t *ectx, dns_tkeyctx_t **tctxp); -/* +/*%< * Create an empty TKEY context. * * Requires: - * 'mctx' is not NULL - * 'tctx' is not NULL - * '*tctx' is NULL + *\li 'mctx' is not NULL + *\li 'tctx' is not NULL + *\li '*tctx' is NULL * * Returns - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * return codes from dns_name_fromtext() + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li return codes from dns_name_fromtext() */ void dns_tkeyctx_destroy(dns_tkeyctx_t **tctxp); -/* +/*%< * Frees all data associated with the TKEY context * * Requires: - * 'tctx' is not NULL - * '*tctx' is not NULL + *\li 'tctx' is not NULL + *\li '*tctx' is not NULL */ isc_result_t dns_tkey_processquery(dns_message_t *msg, dns_tkeyctx_t *tctx, dns_tsig_keyring_t *ring); -/* +/*%< * Processes a query containing a TKEY record, adding or deleting TSIG * keys if necessary, and modifies the message to contain the response. * * Requires: - * 'msg' is a valid message - * 'tctx' is a valid TKEY context - * 'ring' is a valid TSIG keyring + *\li 'msg' is a valid message + *\li 'tctx' is a valid TKEY context + *\li 'ring' is a valid TSIG keyring * * Returns - * ISC_R_SUCCESS msg was updated (the TKEY operation succeeded, + *\li #ISC_R_SUCCESS msg was updated (the TKEY operation succeeded, * or msg now includes a TKEY with an error set) * DNS_R_FORMERR the packet was malformed (missing a TKEY * or KEY). - * other An error occurred while processing the message + *\li other An error occurred while processing the message */ isc_result_t dns_tkey_builddhquery(dns_message_t *msg, dst_key_t *key, dns_name_t *name, dns_name_t *algorithm, isc_buffer_t *nonce, isc_uint32_t lifetime); -/* +/*%< * Builds a query containing a TKEY that will generate a shared * secret using a Diffie-Hellman key exchange. The shared key * will be of the specified algorithm (only DNS_TSIG_HMACMD5_NAME @@ -105,61 +107,61 @@ dns_tkey_builddhquery(dns_message_t *msg, dst_key_t *key, dns_name_t *name, * * * Requires: - * 'msg' is a valid message - * 'key' is a valid Diffie Hellman dst key - * 'name' is a valid name - * 'algorithm' is a valid name + *\li 'msg' is a valid message + *\li 'key' is a valid Diffie Hellman dst key + *\li 'name' is a valid name + *\li 'algorithm' is a valid name * * Returns: - * ISC_R_SUCCESS msg was successfully updated to include the + *\li #ISC_R_SUCCESS msg was successfully updated to include the * query to be sent - * other an error occurred while building the message + *\li other an error occurred while building the message */ isc_result_t dns_tkey_buildgssquery(dns_message_t *msg, dns_name_t *name, dns_name_t *gname, void *cred, isc_uint32_t lifetime, void **context); -/* +/*%< * XXX */ isc_result_t dns_tkey_builddeletequery(dns_message_t *msg, dns_tsigkey_t *key); -/* +/*%< * Builds a query containing a TKEY record that will delete the * specified shared secret from the server. * * Requires: - * 'msg' is a valid message - * 'key' is a valid TSIG key + *\li 'msg' is a valid message + *\li 'key' is a valid TSIG key * * Returns: - * ISC_R_SUCCESS msg was successfully updated to include the + *\li #ISC_R_SUCCESS msg was successfully updated to include the * query to be sent - * other an error occurred while building the message + *\li other an error occurred while building the message */ isc_result_t dns_tkey_processdhresponse(dns_message_t *qmsg, dns_message_t *rmsg, dst_key_t *key, isc_buffer_t *nonce, dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring); -/* +/*%< * Processes a response to a query containing a TKEY that was * designed to generate a shared secret using a Diffie-Hellman key * exchange. If the query was successful, a new shared key * is created and added to the list of shared keys. * * Requires: - * 'qmsg' is a valid message (the query) - * 'rmsg' is a valid message (the response) - * 'key' is a valid Diffie Hellman dst key - * 'outkey' is either NULL or a pointer to NULL - * 'ring' is a valid keyring or NULL + *\li 'qmsg' is a valid message (the query) + *\li 'rmsg' is a valid message (the response) + *\li 'key' is a valid Diffie Hellman dst key + *\li 'outkey' is either NULL or a pointer to NULL + *\li 'ring' is a valid keyring or NULL * * Returns: - * ISC_R_SUCCESS the shared key was successfully added - * ISC_R_NOTFOUND an error occurred while looking for a + *\li #ISC_R_SUCCESS the shared key was successfully added + *\li #ISC_R_NOTFOUND an error occurred while looking for a * component of the query or response */ @@ -167,26 +169,26 @@ isc_result_t dns_tkey_processgssresponse(dns_message_t *qmsg, dns_message_t *rmsg, dns_name_t *gname, void *cred, void **context, dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring); -/* +/*%< * XXX */ isc_result_t dns_tkey_processdeleteresponse(dns_message_t *qmsg, dns_message_t *rmsg, dns_tsig_keyring_t *ring); -/* +/*%< * Processes a response to a query containing a TKEY that was * designed to delete a shared secret. If the query was successful, * the shared key is deleted from the list of shared keys. * * Requires: - * 'qmsg' is a valid message (the query) - * 'rmsg' is a valid message (the response) - * 'ring' is not NULL + *\li 'qmsg' is a valid message (the query) + *\li 'rmsg' is a valid message (the response) + *\li 'ring' is not NULL * * Returns: - * ISC_R_SUCCESS the shared key was successfully deleted - * ISC_R_NOTFOUND an error occurred while looking for a + *\li #ISC_R_SUCCESS the shared key was successfully deleted + *\li #ISC_R_NOTFOUND an error occurred while looking for a * component of the query or response */ diff --git a/lib/dns/include/dns/tsig.h b/lib/dns/include/dns/tsig.h index e02681901b..b7d3e288ab 100644 --- a/lib/dns/include/dns/tsig.h +++ b/lib/dns/include/dns/tsig.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: tsig.h,v 1.43 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: tsig.h,v 1.44 2005/04/27 04:57:00 sra Exp $ */ #ifndef DNS_TSIG_H #define DNS_TSIG_H 1 +/*! \file */ + #include #include #include @@ -40,7 +42,7 @@ LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapi_name; LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapims_name; #define DNS_TSIG_GSSAPIMS_NAME dns_tsig_gssapims_name -/* +/*% * Default fudge value. */ #define DNS_TSIG_FUDGE 300 @@ -53,17 +55,17 @@ struct dns_tsig_keyring { struct dns_tsigkey { /* Unlocked */ - unsigned int magic; /* Magic number. */ + unsigned int magic; /*%< Magic number. */ isc_mem_t *mctx; - dst_key_t *key; /* Key */ - dns_name_t name; /* Key name */ - dns_name_t *algorithm; /* Algorithm name */ - dns_name_t *creator; /* name that created secret */ - isc_boolean_t generated; /* was this generated? */ - isc_stdtime_t inception; /* start of validity period */ - isc_stdtime_t expire; /* end of validity period */ - dns_tsig_keyring_t *ring; /* the enclosing keyring */ - isc_refcount_t refs; /* reference counter */ + dst_key_t *key; /*%< Key */ + dns_name_t name; /*%< Key name */ + dns_name_t *algorithm; /*%< Algorithm name */ + dns_name_t *creator; /*%< name that created secret */ + isc_boolean_t generated; /*%< was this generated? */ + isc_stdtime_t inception; /*%< start of validity period */ + isc_stdtime_t expire; /*%< end of validity period */ + dns_tsig_keyring_t *ring; /*%< the enclosing keyring */ + isc_refcount_t refs; /*%< reference counter */ }; #define dns_tsigkey_identity(tsigkey) \ @@ -84,7 +86,7 @@ dns_tsigkey_createfromkey(dns_name_t *name, dns_name_t *algorithm, dns_name_t *creator, isc_stdtime_t inception, isc_stdtime_t expire, isc_mem_t *mctx, dns_tsig_keyring_t *ring, dns_tsigkey_t **key); -/* +/*%< * Creates a tsig key structure and saves it in the keyring. If key is * not NULL, *key will contain a copy of the key. The keys validity * period is specified by (inception, expire), and will not expire if @@ -95,100 +97,100 @@ dns_tsigkey_createfromkey(dns_name_t *name, dns_name_t *algorithm, * to generate a BADKEY response. * * Requires: - * 'name' is a valid dns_name_t - * 'algorithm' is a valid dns_name_t - * 'secret' is a valid pointer - * 'length' is an integer >= 0 - * 'key' is a valid dst key or NULL - * 'creator' points to a valid dns_name_t or is NULL - * 'mctx' is a valid memory context - * 'ring' is a valid TSIG keyring or NULL - * 'key' or '*key' must be NULL + *\li 'name' is a valid dns_name_t + *\li 'algorithm' is a valid dns_name_t + *\li 'secret' is a valid pointer + *\li 'length' is an integer >= 0 + *\li 'key' is a valid dst key or NULL + *\li 'creator' points to a valid dns_name_t or is NULL + *\li 'mctx' is a valid memory context + *\li 'ring' is a valid TSIG keyring or NULL + *\li 'key' or '*key' must be NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_EXISTS - a key with this name already exists - * ISC_R_NOTIMPLEMENTED - algorithm is not implemented - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_EXISTS - a key with this name already exists + *\li #ISC_R_NOTIMPLEMENTED - algorithm is not implemented + *\li #ISC_R_NOMEMORY */ void dns_tsigkey_attach(dns_tsigkey_t *source, dns_tsigkey_t **targetp); -/* +/*%< * Attach '*targetp' to 'source'. * * Requires: - * 'key' is a valid TSIG key + *\li 'key' is a valid TSIG key * * Ensures: - * *targetp is attached to source. + *\li *targetp is attached to source. */ void dns_tsigkey_detach(dns_tsigkey_t **keyp); -/* +/*%< * Detaches from the tsig key structure pointed to by '*key'. * * Requires: - * 'keyp' is not NULL and '*keyp' is a valid TSIG key + *\li 'keyp' is not NULL and '*keyp' is a valid TSIG key * * Ensures: - * 'keyp' points to NULL + *\li 'keyp' points to NULL */ void dns_tsigkey_setdeleted(dns_tsigkey_t *key); -/* +/*%< * Prevents this key from being used again. It will be deleted when * no references exist. * * Requires: - * 'key' is a valid TSIG key on a keyring + *\li 'key' is a valid TSIG key on a keyring */ isc_result_t dns_tsig_sign(dns_message_t *msg); -/* +/*%< * Generates a TSIG record for this message * * Requires: - * 'msg' is a valid message - * 'msg->tsigkey' is a valid TSIG key - * 'msg->tsig' is NULL + *\li 'msg' is a valid message + *\li 'msg->tsigkey' is a valid TSIG key + *\li 'msg->tsig' is NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_NOSPACE - * DNS_R_EXPECTEDTSIG + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_NOSPACE + *\li #DNS_R_EXPECTEDTSIG * - this is a response & msg->querytsig is NULL */ isc_result_t dns_tsig_verify(isc_buffer_t *source, dns_message_t *msg, dns_tsig_keyring_t *ring1, dns_tsig_keyring_t *ring2); -/* +/*%< * Verifies the TSIG record in this message * * Requires: - * 'source' is a valid buffer containing the unparsed message - * 'msg' is a valid message - * 'msg->tsigkey' is a valid TSIG key if this is a response - * 'msg->tsig' is NULL - * 'msg->querytsig' is not NULL if this is a response - * 'ring1' and 'ring2' are each either a valid keyring or NULL + *\li 'source' is a valid buffer containing the unparsed message + *\li 'msg' is a valid message + *\li 'msg->tsigkey' is a valid TSIG key if this is a response + *\li 'msg->tsig' is NULL + *\li 'msg->querytsig' is not NULL if this is a response + *\li 'ring1' and 'ring2' are each either a valid keyring or NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * DNS_R_EXPECTEDTSIG - A TSIG was expected but not seen - * DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected - * DNS_R_TSIGERRORSET - the TSIG verified but ->error was set + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #DNS_R_EXPECTEDTSIG - A TSIG was expected but not seen + *\li #DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected + *\li #DNS_R_TSIGERRORSET - the TSIG verified but ->error was set * and this is a query - * DNS_R_CLOCKSKEW - the TSIG failed to verify because of + *\li #DNS_R_CLOCKSKEW - the TSIG failed to verify because of * the time was out of the allowed range. - * DNS_R_TSIGVERIFYFAILURE - the TSIG failed to verify - * DNS_R_EXPECTEDRESPONSE - the message was set over TCP and + *\li #DNS_R_TSIGVERIFYFAILURE - the TSIG failed to verify + *\li #DNS_R_EXPECTEDRESPONSE - the message was set over TCP and * should have been a response, * but was not. */ @@ -196,45 +198,45 @@ dns_tsig_verify(isc_buffer_t *source, dns_message_t *msg, isc_result_t dns_tsigkey_find(dns_tsigkey_t **tsigkey, dns_name_t *name, dns_name_t *algorithm, dns_tsig_keyring_t *ring); -/* +/*%< * Returns the TSIG key corresponding to this name and (possibly) * algorithm. Also increments the key's reference counter. * * Requires: - * 'tsigkey' is not NULL - * '*tsigkey' is NULL - * 'name' is a valid dns_name_t - * 'algorithm' is a valid dns_name_t or NULL - * 'ring' is a valid keyring + *\li 'tsigkey' is not NULL + *\li '*tsigkey' is NULL + *\li 'name' is a valid dns_name_t + *\li 'algorithm' is a valid dns_name_t or NULL + *\li 'ring' is a valid keyring * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOTFOUND + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOTFOUND */ isc_result_t dns_tsigkeyring_create(isc_mem_t *mctx, dns_tsig_keyring_t **ringp); -/* +/*%< * Create an empty TSIG key ring. * * Requires: - * 'mctx' is not NULL - * 'ringp' is not NULL, and '*ringp' is NULL + *\li 'mctx' is not NULL + *\li 'ringp' is not NULL, and '*ringp' is NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ void dns_tsigkeyring_destroy(dns_tsig_keyring_t **ringp); -/* +/*%< * Destroy a TSIG key ring. * * Requires: - * 'ringp' is not NULL + *\li 'ringp' is not NULL */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/ttl.h b/lib/dns/include/dns/ttl.h index 49295c837a..bf4f1ebd21 100644 --- a/lib/dns/include/dns/ttl.h +++ b/lib/dns/include/dns/ttl.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ttl.h,v 1.13 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: ttl.h,v 1.14 2005/04/27 04:57:00 sra Exp $ */ #ifndef DNS_TTL_H #define DNS_TTL_H 1 +/*! \file */ + /*** *** Imports ***/ @@ -36,7 +38,7 @@ ISC_LANG_BEGINDECLS isc_result_t dns_ttl_totext(isc_uint32_t src, isc_boolean_t verbose, isc_buffer_t *target); -/* +/*%< * Output a TTL or other time interval in a human-readable form. * The time interval is given as a count of seconds in 'src'. * The text representation is appended to 'target'. @@ -47,28 +49,28 @@ dns_ttl_totext(isc_uint32_t src, isc_boolean_t verbose, * in "dig", like "1 week 2 days 3 hours 4 minutes 5 seconds". * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE + * \li ISC_R_SUCCESS + * \li ISC_R_NOSPACE */ isc_result_t dns_counter_fromtext(isc_textregion_t *source, isc_uint32_t *ttl); -/* +/*%< * Converts a counter from either a plain number or a BIND 8 style value. * * Returns: - * ISC_R_SUCCESS - * DNS_R_SYNTAX + *\li ISC_R_SUCCESS + *\li DNS_R_SYNTAX */ isc_result_t dns_ttl_fromtext(isc_textregion_t *source, isc_uint32_t *ttl); -/* +/*%< * Converts a ttl from either a plain number or a BIND 8 style value. * * Returns: - * ISC_R_SUCCESS - * DNS_R_BADTTL + *\li ISC_R_SUCCESS + *\li DNS_R_BADTTL */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/types.h b/lib/dns/include/dns/types.h index 5fd54ce836..15031b102b 100644 --- a/lib/dns/include/dns/types.h +++ b/lib/dns/include/dns/types.h @@ -15,15 +15,16 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: types.h,v 1.113 2005/02/11 00:01:58 marka Exp $ */ +/* $Id: types.h,v 1.114 2005/04/27 04:57:00 sra Exp $ */ #ifndef DNS_TYPES_H #define DNS_TYPES_H 1 -/* +/*! \file + * \brief * Including this file gives you type declarations suitable for use in * .h files, which lets us avoid circular type reference problems. - * + * \brief * To actually use a type or get declarations of its methods, you must * include the appropriate .h file too. */ @@ -157,7 +158,7 @@ typedef enum { #include /* Provides dns_rdatatype_t. */ #include /* Provides dns_rdataclass_t. */ -/* +/*% * rcodes. */ enum { @@ -193,7 +194,7 @@ enum { #define dns_rcode_badvers ((dns_rcode_t)dns_rcode_badvers) }; -/* +/*% * TSIG errors. */ enum { @@ -205,7 +206,7 @@ enum { dns_tsigerror_badalg = 21 }; -/* +/*% * Opcodes. */ enum { @@ -221,7 +222,7 @@ enum { #define dns_opcode_update ((dns_opcode_t)dns_opcode_update) }; -/* +/*% * Trust levels. Must be kept in sync with trustnames[] in masterdump.c. */ enum { @@ -229,11 +230,11 @@ enum { dns_trust_none = 0, #define dns_trust_none ((dns_trust_t)dns_trust_none) - /* Subject to DNSSEC validation but has not yet been validated */ + /*% Subject to DNSSEC validation but has not yet been validated */ dns_trust_pending = 1, #define dns_trust_pending ((dns_trust_t)dns_trust_pending) - /* Received in the additional section of a response. */ + /*% Received in the additional section of a response. */ dns_trust_additional = 2, #define dns_trust_additional ((dns_trust_t)dns_trust_additional) @@ -263,7 +264,7 @@ enum { #define dns_trust_ultimate ((dns_trust_t)dns_trust_ultimate) }; -/* +/*% * Name checking severites. */ typedef enum { diff --git a/lib/dns/include/dns/validator.h b/lib/dns/include/dns/validator.h index 21be023d71..5ae2986be1 100644 --- a/lib/dns/include/dns/validator.h +++ b/lib/dns/include/dns/validator.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: validator.h,v 1.29 2004/05/14 04:45:58 marka Exp $ */ +/* $Id: validator.h,v 1.30 2005/04/27 04:57:01 sra Exp $ */ #ifndef DNS_VALIDATOR_H #define DNS_VALIDATOR_H 1 @@ -24,27 +24,28 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * DNS Validator * - * XXX XXX + * XXX TBS XXX * * MP: - * The module ensures appropriate synchronization of data structures it + *\li The module ensures appropriate synchronization of data structures it * creates and manipulates. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * RFCs: 1034, 1035, 2181, 2535, - * Drafts: + *\li RFCs: 1034, 1035, 2181, 2535, TBS + *\li Drafts: TBS */ #include @@ -58,9 +59,9 @@ #include -/* +/*% * A dns_validatorevent_t is sent when a 'validation' completes. - * + * \brief * 'name', 'rdataset', 'sigrdataset', and 'message' are the values that were * supplied when dns_validator_create() was called. They are returned to the * caller so that they may be freed. @@ -81,9 +82,9 @@ typedef struct dns_validatorevent { #define DNS_VALIDATOR_NODATAPROOF 1 #define DNS_VALIDATOR_NOWILDCARDPROOF 2 -/* - * A validator object represents a validation in procgress. - * +/*% + * A validator object represents a validation in progress. + * \brief * Clients are strongly discouraged from using this type directly, with * the exception of the 'link' field, which may be used directly for * whatever purpose the client desires. @@ -134,7 +135,7 @@ dns_validator_create(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type, dns_message_t *message, unsigned int options, isc_task_t *task, isc_taskaction_t action, void *arg, dns_validator_t **validatorp); -/* +/*%< * Start a DNSSEC validation. * * This validates a response to the question given by @@ -170,30 +171,30 @@ dns_validator_create(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type, void dns_validator_cancel(dns_validator_t *validator); -/* +/*%< * Cancel a DNSSEC validation in progress. * * Requires: - * 'validator' points to a valid DNSSEC validator, which + *\li 'validator' points to a valid DNSSEC validator, which * may or may not already have completed. * * Ensures: - * It the validator has not already sent its completion + *\li It the validator has not already sent its completion * event, it will send it with result code ISC_R_CANCELED. */ void dns_validator_destroy(dns_validator_t **validatorp); -/* +/*%< * Destroy a DNSSEC validator. * * Requires: - * '*validatorp' points to a valid DNSSEC validator. - * The validator must have completed and sent its completion + *\li '*validatorp' points to a valid DNSSEC validator. + * \li The validator must have completed and sent its completion * event. * * Ensures: - * All resources used by the validator are freed. + *\li All resources used by the validator are freed. */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dns/version.h b/lib/dns/include/dns/version.h index ea8ba3c757..8a4b636f66 100644 --- a/lib/dns/include/dns/version.h +++ b/lib/dns/include/dns/version.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.h,v 1.3 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: version.h,v 1.4 2005/04/27 04:57:01 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/include/dns/view.h b/lib/dns/include/dns/view.h index 79846796fe..09f30bd68f 100644 --- a/lib/dns/include/dns/view.h +++ b/lib/dns/include/dns/view.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: view.h,v 1.94 2005/01/17 04:11:33 marka Exp $ */ +/* $Id: view.h,v 1.95 2005/04/27 04:57:01 sra Exp $ */ #ifndef DNS_VIEW_H #define DNS_VIEW_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * DNS View * * A "view" is a DNS namespace, together with an optional resolver and a @@ -41,22 +42,22 @@ * to be accessed without locking. * * MP: - * Before the view is frozen, the caller must ensure synchronization. + *\li Before the view is frozen, the caller must ensure synchronization. * - * After the view is frozen, the module guarantees appropriate + *\li After the view is frozen, the module guarantees appropriate * synchronization of any data structures it creates and manipulates. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * None. + *\li None. */ #include @@ -157,109 +158,109 @@ struct dns_view { isc_result_t dns_view_create(isc_mem_t *mctx, dns_rdataclass_t rdclass, const char *name, dns_view_t **viewp); -/* +/*%< * Create a view. * * Notes: * - * The newly created view has no cache, no resolver, and an empty + *\li The newly created view has no cache, no resolver, and an empty * zone table. The view is not frozen. * * Requires: * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. * - * 'rdclass' is a valid class. + *\li 'rdclass' is a valid class. * - * 'name' is a valid C string. + *\li 'name' is a valid C string. * - * viewp != NULL && *viewp == NULL + *\li viewp != NULL && *viewp == NULL * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY * - * Other errors are possible. + *\li Other errors are possible. */ void dns_view_attach(dns_view_t *source, dns_view_t **targetp); -/* +/*%< * Attach '*targetp' to 'source'. * * Requires: * - * 'source' is a valid, frozen view. + *\li 'source' is a valid, frozen view. * - * 'targetp' points to a NULL dns_view_t *. + *\li 'targetp' points to a NULL dns_view_t *. * * Ensures: * - * *targetp is attached to source. + *\li *targetp is attached to source. * - * While *targetp is attached, the view will not shut down. + *\li While *targetp is attached, the view will not shut down. */ void dns_view_detach(dns_view_t **viewp); -/* +/*%< * Detach '*viewp' from its view. * * Requires: * - * 'viewp' points to a valid dns_view_t * + *\li 'viewp' points to a valid dns_view_t * * * Ensures: * - * *viewp is NULL. + *\li *viewp is NULL. */ void dns_view_flushanddetach(dns_view_t **viewp); -/* +/*%< * Detach '*viewp' from its view. If this was the last reference * uncommited changed in zones will be flushed to disk. * * Requires: * - * 'viewp' points to a valid dns_view_t * + *\li 'viewp' points to a valid dns_view_t * * * Ensures: * - * *viewp is NULL. + *\li *viewp is NULL. */ void dns_view_weakattach(dns_view_t *source, dns_view_t **targetp); -/* +/*%< * Weakly attach '*targetp' to 'source'. * * Requires: * - * 'source' is a valid, frozen view. + *\li 'source' is a valid, frozen view. * - * 'targetp' points to a NULL dns_view_t *. + *\li 'targetp' points to a NULL dns_view_t *. * * Ensures: * - * *targetp is attached to source. + *\li *targetp is attached to source. * - * While *targetp is attached, the view will not be freed. + * \li While *targetp is attached, the view will not be freed. */ void dns_view_weakdetach(dns_view_t **targetp); -/* +/*%< * Detach '*viewp' from its view. * * Requires: * - * 'viewp' points to a valid dns_view_t *. + *\li 'viewp' points to a valid dns_view_t *. * * Ensures: * - * *viewp is NULL. + *\li *viewp is NULL. */ isc_result_t @@ -271,94 +272,94 @@ dns_view_createresolver(dns_view_t *view, dns_dispatchmgr_t *dispatchmgr, dns_dispatch_t *dispatchv4, dns_dispatch_t *dispatchv6); -/* +/*%< * Create a resolver and address database for the view. * * Requires: * - * 'view' is a valid, unfrozen view. + *\li 'view' is a valid, unfrozen view. * - * 'view' does not have a resolver already. + *\li 'view' does not have a resolver already. * - * The requirements of dns_resolver_create() apply to 'taskmgr', + *\li The requirements of dns_resolver_create() apply to 'taskmgr', * 'ntasks', 'socketmgr', 'timermgr', 'options', 'dispatchv4', and * 'dispatchv6'. * * Returns: * - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * - * Any error that dns_resolver_create() can return. + *\li Any error that dns_resolver_create() can return. */ void dns_view_setcache(dns_view_t *view, dns_cache_t *cache); -/* +/*%< * Set the view's cache database. * * Requires: * - * 'view' is a valid, unfrozen view. + *\li 'view' is a valid, unfrozen view. * - * 'cache' is a valid cache. + *\li 'cache' is a valid cache. * * Ensures: * - * The cache of 'view' is 'cached. + * \li The cache of 'view' is 'cached. * - * If this is not the first call to dns_view_setcache() for this + *\li If this is not the first call to dns_view_setcache() for this * view, then previously set cache is detached. */ void dns_view_sethints(dns_view_t *view, dns_db_t *hints); -/* +/*%< * Set the view's hints database. * * Requires: * - * 'view' is a valid, unfrozen view, whose hints database has not been + *\li 'view' is a valid, unfrozen view, whose hints database has not been * set. * - * 'hints' is a valid zone database. + *\li 'hints' is a valid zone database. * * Ensures: * - * The hints database of 'view' is 'hints'. + * \li The hints database of 'view' is 'hints'. */ void dns_view_setkeyring(dns_view_t *view, dns_tsig_keyring_t *ring); -/* +/*%< * Set the view's static TSIG keys * * Requires: * - * 'view' is a valid, unfrozen view, whose static TSIG keyring has not + * \li 'view' is a valid, unfrozen view, whose static TSIG keyring has not * been set. * - * 'ring' is a valid TSIG keyring + *\li 'ring' is a valid TSIG keyring * * Ensures: * - * The static TSIG keyring of 'view' is 'ring'. + *\li The static TSIG keyring of 'view' is 'ring'. */ void dns_view_setdstport(dns_view_t *view, in_port_t dstport); -/* +/*%< * Set the view's destination port. This is the port to * which outgoing queries are sent. The default is 53, * the standard DNS port. * * Requires: * - * 'view' is a valid view. + *\li 'view' is a valid view. * - * 'dstport' is a valid TCP/UDP port number. + *\li 'dstport' is a valid TCP/UDP port number. * * Ensures: - * External name servers will be assumed to be listning + *\li External name servers will be assumed to be listning * on 'dstport'. For servers whose address has already * obtained obtained at the time of the call, the view may * continue to use the previously set port until the address @@ -368,28 +369,28 @@ dns_view_setdstport(dns_view_t *view, in_port_t dstport); isc_result_t dns_view_addzone(dns_view_t *view, dns_zone_t *zone); -/* +/*%< * Add zone 'zone' to 'view'. * * Requires: * - * 'view' is a valid, unfrozen view. + *\li 'view' is a valid, unfrozen view. * - * 'zone' is a valid zone. + *\li 'zone' is a valid zone. */ void dns_view_freeze(dns_view_t *view); -/* +/*%< * Freeze view. * * Requires: * - * 'view' is a valid, unfrozen view. + *\li 'view' is a valid, unfrozen view. * * Ensures: * - * 'view' is frozen. + *\li 'view' is frozen. */ isc_result_t @@ -397,63 +398,63 @@ dns_view_find(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type, isc_stdtime_t now, unsigned int options, isc_boolean_t use_hints, dns_db_t **dbp, dns_dbnode_t **nodep, dns_name_t *foundname, dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); -/* +/*%< * Find an rdataset whose owner name is 'name', and whose type is * 'type'. * * Notes: * - * See the description of dns_db_find() for information about 'options'. - * If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name' + *\li See the description of dns_db_find() for information about 'options'. + * If the caller sets #DNS_DBFIND_GLUEOK, it must ensure that 'name' * and 'type' are appropriate for glue retrieval. * - * If 'now' is zero, then the current time will be used. + *\li If 'now' is zero, then the current time will be used. * - * If 'use_hints' is ISC_TRUE, and the view has a hints database, then + *\li If 'use_hints' is ISC_TRUE, and the view has a hints database, then * it will be searched last. If the answer is found in the hints * database, the result code will be DNS_R_HINT. If the name is found * in the hints database but not the type, the result code will be - * DNS_R_HINTNXRRSET. + * #DNS_R_HINTNXRRSET. * - * 'foundname' must meet the requirements of dns_db_find(). + *\li 'foundname' must meet the requirements of dns_db_find(). * - * If 'sigrdataset' is not NULL, and there is a SIG rdataset which + *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which * covers 'type', then 'sigrdataset' will be bound to it. * * Requires: * - * 'view' is a valid, frozen view. + *\li 'view' is a valid, frozen view. * - * 'name' is valid name. + *\li 'name' is valid name. * - * 'type' is a valid dns_rdatatype_t, and is not a meta query type + *\li 'type' is a valid dns_rdatatype_t, and is not a meta query type * except dns_rdatatype_any. * - * dbp == NULL || *dbp == NULL + *\li dbp == NULL || *dbp == NULL * - * nodep == NULL || *nodep == NULL. If nodep != NULL, dbp != NULL. + *\li nodep == NULL || *nodep == NULL. If nodep != NULL, dbp != NULL. * - * 'foundname' is a valid name with a dedicated buffer or NULL. + *\li 'foundname' is a valid name with a dedicated buffer or NULL. * - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. * - * 'sigrdataset' is NULL, or is a valid, disassociated rdataset. + *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. * * Ensures: * - * In successful cases, 'rdataset', and possibly 'sigrdataset', are + *\li In successful cases, 'rdataset', and possibly 'sigrdataset', are * bound to the found data. * - * If dbp != NULL, it points to the database containing the data. + *\li If dbp != NULL, it points to the database containing the data. * - * If nodep != NULL, it points to the database node containing the data. + *\li If nodep != NULL, it points to the database node containing the data. * - * If foundname != NULL, it contains the full name of the found data. + *\li If foundname != NULL, it contains the full name of the found data. * * Returns: * - * Any result that dns_db_find() can return, with the exception of - * DNS_R_DELEGATION. + *\li Any result that dns_db_find() can return, with the exception of + * #DNS_R_DELEGATION. */ isc_result_t @@ -461,62 +462,63 @@ dns_view_simplefind(dns_view_t *view, dns_name_t *name, dns_rdatatype_t type, isc_stdtime_t now, unsigned int options, isc_boolean_t use_hints, dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); -/* +/*%< * Find an rdataset whose owner name is 'name', and whose type is * 'type'. * * Notes: * - * This routine is appropriate for simple, exact-match queries of the + *\li This routine is appropriate for simple, exact-match queries of the * view. 'name' must be a canonical name; there is no DNAME or CNAME * processing. * - * See the description of dns_db_find() for information about 'options'. + *\li See the description of dns_db_find() for information about 'options'. * If the caller sets DNS_DBFIND_GLUEOK, it must ensure that 'name' * and 'type' are appropriate for glue retrieval. * - * If 'now' is zero, then the current time will be used. + *\li If 'now' is zero, then the current time will be used. * - * If 'use_hints' is ISC_TRUE, and the view has a hints database, then + *\li If 'use_hints' is ISC_TRUE, and the view has a hints database, then * it will be searched last. If the answer is found in the hints * database, the result code will be DNS_R_HINT. If the name is found * in the hints database but not the type, the result code will be * DNS_R_HINTNXRRSET. * - * If 'sigrdataset' is not NULL, and there is a SIG rdataset which + *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which * covers 'type', then 'sigrdataset' will be bound to it. * * Requires: * - * 'view' is a valid, frozen view. + *\li 'view' is a valid, frozen view. * - * 'name' is valid name. + *\li 'name' is valid name. * - * 'type' is a valid dns_rdatatype_t, and is not a meta query type + *\li 'type' is a valid dns_rdatatype_t, and is not a meta query type * (e.g. dns_rdatatype_any), or dns_rdatatype_rrsig. * - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. * - * 'sigrdataset' is NULL, or is a valid, disassociated rdataset. + *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. * * Ensures: * - * In successful cases, 'rdataset', and possibly 'sigrdataset', are + *\li In successful cases, 'rdataset', and possibly 'sigrdataset', are * bound to the found data. * * Returns: * - * ISC_R_SUCCESS Success; result is desired type. - * DNS_R_GLUE Success; result is glue. - * DNS_R_HINT Success; result is a hint. - * DNS_R_NCACHENXDOMAIN Success; result is a ncache entry. - * DNS_R_NCACHENXRRSET Success; result is a ncache entry. - * DNS_R_NXDOMAIN The name does not exist. - * DNS_R_NXRRSET The rrset does not exist. - * ISC_R_NOTFOUND No matching data found, + *\li #ISC_R_SUCCESS Success; result is desired type. + *\li DNS_R_GLUE Success; result is glue. + *\li DNS_R_HINT Success; result is a hint. + *\li DNS_R_NCACHENXDOMAIN Success; result is a ncache entry. + *\li DNS_R_NCACHENXRRSET Success; result is a ncache entry. + *\li DNS_R_NXDOMAIN The name does not exist. + *\li DNS_R_NXRRSET The rrset does not exist. + *\li #ISC_R_NOTFOUND No matching data found, * or an error occurred. */ +/*% See dns_view_findzonecut2() */ isc_result_t dns_view_findzonecut(dns_view_t *view, dns_name_t *name, dns_name_t *fname, isc_stdtime_t now, unsigned int options, @@ -528,7 +530,7 @@ dns_view_findzonecut2(dns_view_t *view, dns_name_t *name, dns_name_t *fname, isc_stdtime_t now, unsigned int options, isc_boolean_t use_hints, isc_boolean_t use_cache, dns_rdataset_t *rdataset, dns_rdataset_t *sigrdataset); -/* +/*%< * Find the best known zonecut containing 'name'. * * This uses local authority, cache, and optionally hints data. @@ -536,69 +538,69 @@ dns_view_findzonecut2(dns_view_t *view, dns_name_t *name, dns_name_t *fname, * * Notes: * - * If 'now' is zero, then the current time will be used. + *\li If 'now' is zero, then the current time will be used. * - * If 'use_hints' is ISC_TRUE, and the view has a hints database, then + *\li If 'use_hints' is ISC_TRUE, and the view has a hints database, then * it will be searched last. * - * If 'use_cache' is ISC_TRUE, and the view has a cache, then it will be + *\li If 'use_cache' is ISC_TRUE, and the view has a cache, then it will be * searched. * - * If 'sigrdataset' is not NULL, and there is a SIG rdataset which + *\li If 'sigrdataset' is not NULL, and there is a SIG rdataset which * covers 'type', then 'sigrdataset' will be bound to it. * - * If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned + *\li If the DNS_DBFIND_NOEXACT option is set, then the zonecut returned * (if any) will be the deepest known ancestor of 'name'. * * Requires: * - * 'view' is a valid, frozen view. + *\li 'view' is a valid, frozen view. * - * 'name' is valid name. + *\li 'name' is valid name. * - * 'rdataset' is a valid, disassociated rdataset. + *\li 'rdataset' is a valid, disassociated rdataset. * - * 'sigrdataset' is NULL, or is a valid, disassociated rdataset. + *\li 'sigrdataset' is NULL, or is a valid, disassociated rdataset. * * Returns: * - * ISC_R_SUCCESS Success. + *\li #ISC_R_SUCCESS Success. * - * Many other results are possible. + *\li Many other results are possible. */ isc_result_t dns_viewlist_find(dns_viewlist_t *list, const char *name, dns_rdataclass_t rdclass, dns_view_t **viewp); -/* +/*%< * Search for a view with name 'name' and class 'rdclass' in 'list'. * If found, '*viewp' is (strongly) attached to it. * * Requires: * - * 'viewp' points to a NULL dns_view_t *. + *\li 'viewp' points to a NULL dns_view_t *. * * Returns: * - * ISC_R_SUCCESS A matching view was found. - * ISC_R_NOTFOUND No matching view was found. + *\li #ISC_R_SUCCESS A matching view was found. + *\li #ISC_R_NOTFOUND No matching view was found. */ isc_result_t dns_view_findzone(dns_view_t *view, dns_name_t *name, dns_zone_t **zonep); -/* +/*%< * Search for the zone 'name' in the zone table of 'view'. * If found, 'zonep' is (strongly) attached to it. There * are no partial matches. * * Requires: * - * 'zonep' points to a NULL dns_zone_t *. + *\li 'zonep' points to a NULL dns_zone_t *. * * Returns: - * ISC_R_SUCCESS A matching zone was found. - * ISC_R_NOTFOUND No matching zone was found. - * others An error occurred. + *\li #ISC_R_SUCCESS A matching zone was found. + *\li #ISC_R_NOTFOUND No matching zone was found. + *\li others An error occurred. */ isc_result_t @@ -606,7 +608,7 @@ dns_view_load(dns_view_t *view, isc_boolean_t stop); isc_result_t dns_view_loadnew(dns_view_t *view, isc_boolean_t stop); -/* +/*%< * Load zones attached to this view. dns_view_load() loads * all zones whose master file has changed since the last * load; dns_view_loadnew() loads only zones that have never @@ -617,29 +619,29 @@ dns_view_loadnew(dns_view_t *view, isc_boolean_t stop); * * Requires: * - * 'view' is valid. + *\li 'view' is valid. */ isc_result_t dns_view_gettsig(dns_view_t *view, dns_name_t *keyname, dns_tsigkey_t **keyp); -/* +/*%< * Find the TSIG key configured in 'view' with name 'keyname', * if any. * * Reqires: - * keyp points to a NULL dns_tsigkey_t *. + *\li keyp points to a NULL dns_tsigkey_t *. * * Returns: - * ISC_R_SUCCESS A key was found and '*keyp' now points to it. - * ISC_R_NOTFOUND No key was found. - * others An error occurred. + *\li #ISC_R_SUCCESS A key was found and '*keyp' now points to it. + *\li #ISC_R_NOTFOUND No key was found. + *\li others An error occurred. */ isc_result_t dns_view_getpeertsig(dns_view_t *view, isc_netaddr_t *peeraddr, dns_tsigkey_t **keyp); -/* +/*%< * Find the TSIG key configured in 'view' for the server whose * address is 'peeraddr', if any. * @@ -647,35 +649,35 @@ dns_view_getpeertsig(dns_view_t *view, isc_netaddr_t *peeraddr, * keyp points to a NULL dns_tsigkey_t *. * * Returns: - * ISC_R_SUCCESS A key was found and '*keyp' now points to it. - * ISC_R_NOTFOUND No key was found. - * others An error occurred. + *\li #ISC_R_SUCCESS A key was found and '*keyp' now points to it. + *\li #ISC_R_NOTFOUND No key was found. + *\li others An error occurred. */ isc_result_t dns_view_checksig(dns_view_t *view, isc_buffer_t *source, dns_message_t *msg); -/* +/*%< * Verifies the signature of a message. * * Requires: * - * 'view' is a valid view. - * 'source' is a valid buffer containing the message - * 'msg' is a valid message + *\li 'view' is a valid view. + *\li 'source' is a valid buffer containing the message + *\li 'msg' is a valid message * * Returns: - * see dns_tsig_verify() + *\li see dns_tsig_verify() */ void dns_view_dialup(dns_view_t *view); -/* +/*%< * Perform dialup-time maintenance on the zones of 'view'. */ isc_result_t dns_view_dumpdbtostream(dns_view_t *view, FILE *fp); -/* +/*%< * Dump the current state of the view 'view' to the stream 'fp' * for purposes of analysis or debugging. * @@ -686,18 +688,18 @@ dns_view_dumpdbtostream(dns_view_t *view, FILE *fp); * * Requires: * - * 'view' is valid. + *\li 'view' is valid. * - * 'fp' refers to a file open for writing. + *\li 'fp' refers to a file open for writing. * * Returns: - * ISC_R_SUCCESS The cache was successfully dumped. - * others An error occurred (see dns_master_dump) + * \li ISC_R_SUCCESS The cache was successfully dumped. + * \li others An error occurred (see dns_master_dump) */ isc_result_t dns_view_flushcache(dns_view_t *view); -/* +/*%< * Flush the view's cache (and ADB). * * Requires: @@ -706,85 +708,85 @@ dns_view_flushcache(dns_view_t *view); * No other tasks are executing. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ isc_result_t dns_view_flushname(dns_view_t *view, dns_name_t *); -/* +/*%< * Flush the given name from the view's cache (and ADB). * * Requires: - * 'view' is valid. - * 'name' is valid. + *\li 'view' is valid. + *\li 'name' is valid. * * Returns: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * other returns are failures. */ isc_result_t dns_view_adddelegationonly(dns_view_t *view, dns_name_t *name); -/* +/*%< * Add the given name to the delegation only table. * * * Requires: - * 'view' is valid. - * 'name' is valid. + *\li 'view' is valid. + *\li 'name' is valid. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ isc_result_t dns_view_excludedelegationonly(dns_view_t *view, dns_name_t *name); -/* +/*%< * Add the given name to be excluded from the root-delegation-only. * * * Requires: - * 'view' is valid. - * 'name' is valid. + *\li 'view' is valid. + *\li 'name' is valid. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ isc_boolean_t dns_view_isdelegationonly(dns_view_t *view, dns_name_t *name); -/* +/*%< * Check if 'name' is in the delegation only table or if * rootdelonly is set that name is not being excluded. * * Requires: - * 'view' is valid. - * 'name' is valid. + *\li 'view' is valid. + *\li 'name' is valid. * * Returns: - * ISC_TRUE if the name is is the table. - * ISC_FALSE othewise. + *\li #ISC_TRUE if the name is is the table. + *\li #ISC_FALSE othewise. */ void dns_view_setrootdelonly(dns_view_t *view, isc_boolean_t value); -/* +/*%< * Set the root delegation only flag. * * Requires: - * 'view' is valid. + *\li 'view' is valid. */ isc_boolean_t dns_view_getrootdelonly(dns_view_t *view); -/* +/*%< * Get the root delegation only flag. * * Requires: - * 'view' is valid. + *\li 'view' is valid. */ isc_result_t diff --git a/lib/dns/include/dns/xfrin.h b/lib/dns/include/dns/xfrin.h index e7a907aa41..ef0d62ee26 100644 --- a/lib/dns/include/dns/xfrin.h +++ b/lib/dns/include/dns/xfrin.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: xfrin.h,v 1.20 2004/03/05 05:09:47 marka Exp $ */ +/* $Id: xfrin.h,v 1.21 2005/04/27 04:57:01 sra Exp $ */ #ifndef DNS_XFRIN_H #define DNS_XFRIN_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * Incoming zone transfers (AXFR + IXFR). */ @@ -40,7 +41,7 @@ *** Types ***/ -/* +/*% * A transfer in progress. This is an opaque type. */ typedef struct dns_xfrin_ctx dns_xfrin_ctx_t; @@ -51,6 +52,7 @@ typedef struct dns_xfrin_ctx dns_xfrin_ctx_t; ISC_LANG_BEGINDECLS +/*% see dns_xfrin_create2() */ isc_result_t dns_xfrin_create(dns_zone_t *zone, dns_rdatatype_t xfrtype, isc_sockaddr_t *masteraddr, dns_tsigkey_t *tsigkey, @@ -65,7 +67,7 @@ dns_xfrin_create2(dns_zone_t *zone, dns_rdatatype_t xfrtype, isc_timermgr_t *timermgr, isc_socketmgr_t *socketmgr, isc_task_t *task, dns_xfrindone_t done, dns_xfrin_ctx_t **xfrp); -/* +/*%< * Attempt to start an incoming zone transfer of 'zone' * from 'masteraddr', creating a dns_xfrin_ctx_t object to * manage it. Attach '*xfrp' to the newly created object. @@ -75,15 +77,15 @@ dns_xfrin_create2(dns_zone_t *zone, dns_rdatatype_t xfrtype, * code as arguments when the transfer finishes. * * Requires: - * 'xfrtype' is dns_rdatatype_axfr or dns_rdatatype_ixfr. + *\li 'xfrtype' is dns_rdatatype_axfr or dns_rdatatype_ixfr. * - * If 'xfrtype' is dns_rdatatype_ixfr, the zone has a + *\li If 'xfrtype' is dns_rdatatype_ixfr, the zone has a * database. */ void dns_xfrin_shutdown(dns_xfrin_ctx_t *xfr); -/* +/*%< * If the zone transfer 'xfr' has already finished, * do nothing. Otherwise, abort it and cause it to call * its done callback with a status of ISC_R_CANCELLED. @@ -91,14 +93,14 @@ dns_xfrin_shutdown(dns_xfrin_ctx_t *xfr); void dns_xfrin_detach(dns_xfrin_ctx_t **xfrp); -/* +/*%< * Detach a reference to a zone transfer object. * Caller to maintain external locking if required. */ void dns_xfrin_attach(dns_xfrin_ctx_t *source, dns_xfrin_ctx_t **target); -/* +/*%< * Caller to maintain external locking if required. */ diff --git a/lib/dns/include/dns/zone.h b/lib/dns/include/dns/zone.h index 3df380b588..75f2f63148 100644 --- a/lib/dns/include/dns/zone.h +++ b/lib/dns/include/dns/zone.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: zone.h,v 1.132 2005/02/10 05:53:43 marka Exp $ */ +/* $Id: zone.h,v 1.133 2005/04/27 04:57:01 sra Exp $ */ #ifndef DNS_ZONE_H #define DNS_ZONE_H 1 +/*! \file */ + /*** *** Imports ***/ @@ -39,20 +41,20 @@ typedef enum { dns_zone_stub } dns_zonetype_t; -#define DNS_ZONEOPT_SERVERS 0x00000001U /* perform server checks */ -#define DNS_ZONEOPT_PARENTS 0x00000002U /* perform parent checks */ -#define DNS_ZONEOPT_CHILDREN 0x00000004U /* perform child checks */ -#define DNS_ZONEOPT_NOTIFY 0x00000008U /* perform NOTIFY */ -#define DNS_ZONEOPT_MANYERRORS 0x00000010U /* return many errors on load */ -#define DNS_ZONEOPT_IXFRFROMDIFFS 0x00000020U /* calculate differences */ -#define DNS_ZONEOPT_NOMERGE 0x00000040U /* don't merge journal */ -#define DNS_ZONEOPT_CHECKNS 0x00000080U /* check if NS's are addresses */ -#define DNS_ZONEOPT_FATALNS 0x00000100U /* DNS_ZONEOPT_CHECKNS is fatal */ -#define DNS_ZONEOPT_MULTIMASTER 0x00000200U /* this zone has multiple masters */ -#define DNS_ZONEOPT_USEALTXFRSRC 0x00000400U /* use alternate transfer sources */ -#define DNS_ZONEOPT_CHECKNAMES 0x00000800U /* check-names */ -#define DNS_ZONEOPT_CHECKNAMESFAIL 0x00001000U /* fatal check-name failures */ -#define DNS_ZONEOPT_CHECKWILDCARD 0x00002000U /* check for internal wildcards */ +#define DNS_ZONEOPT_SERVERS 0x00000001U /*%< perform server checks */ +#define DNS_ZONEOPT_PARENTS 0x00000002U /*%< perform parent checks */ +#define DNS_ZONEOPT_CHILDREN 0x00000004U /*%< perform child checks */ +#define DNS_ZONEOPT_NOTIFY 0x00000008U /*%< perform NOTIFY */ +#define DNS_ZONEOPT_MANYERRORS 0x00000010U /*%< return many errors on load */ +#define DNS_ZONEOPT_IXFRFROMDIFFS 0x00000020U /*%< calculate differences */ +#define DNS_ZONEOPT_NOMERGE 0x00000040U /*%< don't merge journal */ +#define DNS_ZONEOPT_CHECKNS 0x00000080U /*%< check if NS's are addresses */ +#define DNS_ZONEOPT_FATALNS 0x00000100U /*%< DNS_ZONEOPT_CHECKNS is fatal */ +#define DNS_ZONEOPT_MULTIMASTER 0x00000200U /*%< this zone has multiple masters */ +#define DNS_ZONEOPT_USEALTXFRSRC 0x00000400U /*%< use alternate transfer sources */ +#define DNS_ZONEOPT_CHECKNAMES 0x00000800U /*%< check-names */ +#define DNS_ZONEOPT_CHECKNAMESFAIL 0x00001000U /*%< fatal check-name failures */ +#define DNS_ZONEOPT_CHECKWILDCARD 0x00002000U /*%< check for internal wildcards */ #ifndef NOMINUM_PUBLIC /* @@ -62,22 +64,22 @@ typedef enum { #endif /* NOMINUM_PUBLIC */ #ifndef DNS_ZONE_MINREFRESH -#define DNS_ZONE_MINREFRESH 300 /* 5 minutes */ +#define DNS_ZONE_MINREFRESH 300 /*%< 5 minutes */ #endif #ifndef DNS_ZONE_MAXREFRESH -#define DNS_ZONE_MAXREFRESH 2419200 /* 4 weeks */ +#define DNS_ZONE_MAXREFRESH 2419200 /*%< 4 weeks */ #endif #ifndef DNS_ZONE_DEFAULTREFRESH -#define DNS_ZONE_DEFAULTREFRESH 3600 /* 1 hour */ +#define DNS_ZONE_DEFAULTREFRESH 3600 /*%< 1 hour */ #endif #ifndef DNS_ZONE_MINRETRY -#define DNS_ZONE_MINRETRY 300 /* 5 minutes */ +#define DNS_ZONE_MINRETRY 300 /*%< 5 minutes */ #endif #ifndef DNS_ZONE_MAXRETRY -#define DNS_ZONE_MAXRETRY 1209600 /* 2 weeks */ +#define DNS_ZONE_MAXRETRY 1209600 /*%< 2 weeks */ #endif #ifndef DNS_ZONE_DEFAULTRETRY -#define DNS_ZONE_DEFAULTRETRY 60 /* 1 minute, subject to +#define DNS_ZONE_DEFAULTRETRY 60 /*%< 1 minute, subject to exponential backoff */ #endif @@ -94,101 +96,101 @@ ISC_LANG_BEGINDECLS isc_result_t dns_zone_create(dns_zone_t **zonep, isc_mem_t *mctx); -/* +/*%< * Creates a new empty zone and attach '*zonep' to it. * * Requires: - * 'zonep' to point to a NULL pointer. - * 'mctx' to be a valid memory context. + *\li 'zonep' to point to a NULL pointer. + *\li 'mctx' to be a valid memory context. * * Ensures: - * '*zonep' refers to a valid zone. + *\li '*zonep' refers to a valid zone. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED */ void dns_zone_setclass(dns_zone_t *zone, dns_rdataclass_t rdclass); -/* +/*%< * Sets the class of a zone. This operation can only be performed * once on a zone. * * Require: - * 'zone' to be a valid zone. - * dns_zone_setclass() not to have been called since the zone was + *\li 'zone' to be a valid zone. + *\li dns_zone_setclass() not to have been called since the zone was * created. - * 'rdclass' != dns_rdataclass_none. + *\li 'rdclass' != dns_rdataclass_none. */ dns_rdataclass_t dns_zone_getclass(dns_zone_t *zone); -/* +/*%< * Returns the current zone class. * * Requires: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_settype(dns_zone_t *zone, dns_zonetype_t type); -/* +/*%< * Sets the zone type. This operation can only be performed once on * a zone. * * Requires: - * 'zone' to be a valid zone. - * dns_zone_settype() not to have been called since the zone was + *\li 'zone' to be a valid zone. + *\li dns_zone_settype() not to have been called since the zone was * created. - * 'type' != dns_zone_none + *\li 'type' != dns_zone_none */ void dns_zone_setview(dns_zone_t *zone, dns_view_t *view); -/* +/*%< * Associate the zone with a view. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ dns_view_t * dns_zone_getview(dns_zone_t *zone); -/* +/*%< * Returns the zone's associated view. * * Requires: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_setorigin(dns_zone_t *zone, dns_name_t *origin); -/* +/*%< * Sets the zones origin to 'origin'. * * Require: - * 'zone' to be a valid zone. - * 'origin' to be non NULL. + *\li 'zone' to be a valid zone. + *\li 'origin' to be non NULL. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ dns_name_t * dns_zone_getorigin(dns_zone_t *zone); -/* +/*%< * Returns the value of the origin. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_setfile(dns_zone_t *zone, const char *file); -/* +/*%< * Sets the name of the master file from which the zone * loads its database to 'file'. For zones that have * no associated master file, 'file' will be NULL. @@ -197,23 +199,23 @@ dns_zone_setfile(dns_zone_t *zone, const char *file); * setting is ignored. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. * * Returns: - * ISC_R_NOMEMORY - * ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS */ const char * dns_zone_getfile(dns_zone_t *zone); -/* +/*%< * Gets the name of the zone's master file, if any. * * Requires: - * 'zone' to be valid initialised zone. + *\li 'zone' to be valid initialised zone. * * Returns: - * Pointer to null-terminated file name, or NULL. + *\li Pointer to null-terminated file name, or NULL. */ isc_result_t @@ -221,7 +223,7 @@ dns_zone_load(dns_zone_t *zone); isc_result_t dns_zone_loadnew(dns_zone_t *zone); -/* +/*%< * Cause the database to be loaded from its backing store. * Confirm that the minimum requirements for the zone type are * met, otherwise DNS_R_BADZONE is returned. @@ -231,187 +233,187 @@ dns_zone_loadnew(dns_zone_t *zone); * and whose master file has changed since the last load. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. * * Returns: - * ISC_R_UNEXPECTED - * ISC_R_SUCCESS - * DNS_R_CONTINUE Incremental load has been queued. - * DNS_R_UPTODATE The zone has already been loaded based on + *\li #ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li DNS_R_CONTINUE Incremental load has been queued. + *\li DNS_R_UPTODATE The zone has already been loaded based on * file system timestamps. - * DNS_R_BADZONE - * Any result value from dns_db_load(). + *\li DNS_R_BADZONE + *\li Any result value from dns_db_load(). */ void dns_zone_attach(dns_zone_t *source, dns_zone_t **target); -/* +/*%< * Attach '*target' to 'source' incrementing its external * reference count. * * Require: - * 'zone' to be a valid zone. - * 'target' to be non NULL and '*target' to be NULL. + *\li 'zone' to be a valid zone. + *\li 'target' to be non NULL and '*target' to be NULL. */ void dns_zone_detach(dns_zone_t **zonep); -/* +/*%< * Detach from a zone decrementing its external reference count. * If this was the last external reference to the zone it will be * shut down and eventually freed. * * Require: - * 'zonep' to point to a valid zone. + *\li 'zonep' to point to a valid zone. */ void dns_zone_iattach(dns_zone_t *source, dns_zone_t **target); -/* +/*%< * Attach '*target' to 'source' incrementing its internal * reference count. This is intended for use by operations * such as zone transfers that need to prevent the zone * object from being freed but not from shutting down. * * Require: - * The caller is running in the context of the zone's task. - * 'zone' to be a valid zone. - * 'target' to be non NULL and '*target' to be NULL. + *\li The caller is running in the context of the zone's task. + *\li 'zone' to be a valid zone. + *\li 'target' to be non NULL and '*target' to be NULL. */ void dns_zone_idetach(dns_zone_t **zonep); -/* +/*%< * Detach from a zone decrementing its internal reference count. * If there are no more internal or external references to the * zone, it will be freed. * * Require: - * The caller is running in the context of the zone's task. - * 'zonep' to point to a valid zone. + *\li The caller is running in the context of the zone's task. + *\li 'zonep' to point to a valid zone. */ void dns_zone_setflag(dns_zone_t *zone, unsigned int flags, isc_boolean_t value); -/* +/*%< * Sets ('value' == 'ISC_TRUE') / clears ('value' == 'IS_FALSE') * zone flags. Valid flag bits are DNS_ZONE_F_*. * * Requires - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_getdb(dns_zone_t *zone, dns_db_t **dbp); -/* +/*%< * Attach '*dbp' to the database to if it exists otherwise * return DNS_R_NOTLOADED. * * Require: - * 'zone' to be a valid zone. - * 'dbp' to be != NULL && '*dbp' == NULL. + *\li 'zone' to be a valid zone. + *\li 'dbp' to be != NULL && '*dbp' == NULL. * * Returns: - * ISC_R_SUCCESS - * DNS_R_NOTLOADED + *\li #ISC_R_SUCCESS + *\li DNS_R_NOTLOADED */ isc_result_t dns_zone_setdbtype(dns_zone_t *zone, unsigned int dbargc, const char * const *dbargv); -/* +/*%< * Sets the database type to dbargv[0] and database arguments * to subsequent dbargv elements. * 'db_type' is not checked to see if it is a valid database type. * * Require: - * 'zone' to be a valid zone. - * 'database' to be non NULL. - * 'dbargc' to be >= 1 - * 'dbargv' to point to dbargc NULL-terminated strings + *\li 'zone' to be a valid zone. + *\li 'database' to be non NULL. + *\li 'dbargc' to be >= 1 + *\li 'dbargv' to point to dbargc NULL-terminated strings * * Returns: - * ISC_R_NOMEMORY - * ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS */ void dns_zone_markdirty(dns_zone_t *zone); -/* +/*%< * Mark a zone as 'dirty'. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_expire(dns_zone_t *zone); -/* +/*%< * Mark the zone as expired. If the zone requires dumping cause it to * be initiated. Set the refresh and retry intervals to there default * values and unload the zone. * * Require - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_refresh(dns_zone_t *zone); -/* +/*%< * Initiate zone up to date checks. The zone must already be being * managed. * * Require - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_flush(dns_zone_t *zone); -/* +/*%< * Write the zone to database if there are uncommited changes. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_dump(dns_zone_t *zone); -/* +/*%< * Write the zone to database. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_dumptostream(dns_zone_t *zone, FILE *fd); -/* +/*%< * Write the zone to stream 'fd'. * * Require: - * 'zone' to be a valid zone. - * 'fd' to be a stream open for writing. + *\li 'zone' to be a valid zone. + *\li 'fd' to be a stream open for writing. */ isc_result_t dns_zone_fulldumptostream(dns_zone_t *zone, FILE *fd); -/* +/*%< * The same as dns_zone_dumptostream, but dumps the zone with * different dump settings (dns_master_style_full). * * Require: - * 'zone' to be a valid zone. - * 'fd' to be a stream open for writing. + *\li 'zone' to be a valid zone. + *\li 'fd' to be a stream open for writing. */ void dns_zone_maintenance(dns_zone_t *zone); -/* +/*%< * Perform regular maintenace on the zone. This is called as a * result of a zone being managed. * * Require - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t @@ -420,108 +422,108 @@ dns_zone_setmasters(dns_zone_t *zone, isc_sockaddr_t *masters, isc_result_t dns_zone_setmasterswithkeys(dns_zone_t *zone, isc_sockaddr_t *masters, dns_name_t **keynames, isc_uint32_t count); -/* +/*%< * Set the list of master servers for the zone. * * Require: - * 'zone' to be a valid zone. - * 'masters' array of isc_sockaddr_t with port set or NULL. - * 'count' the number of masters. - * 'keynames' array of dns_name_t's for tsig keys or NULL. + *\li 'zone' to be a valid zone. + *\li 'masters' array of isc_sockaddr_t with port set or NULL. + *\li 'count' the number of masters. + *\li 'keynames' array of dns_name_t's for tsig keys or NULL. * - * dns_zone_setmasters() is just a wrapper to setmasterswithkeys(), + * \li dns_zone_setmasters() is just a wrapper to setmasterswithkeys(), * passing NULL in the keynames field. * - * If 'masters' is NULL then 'count' must be zero. + * \li If 'masters' is NULL then 'count' must be zero. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * Any result dns_name_dup() can return, if keynames!=NULL + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li Any result dns_name_dup() can return, if keynames!=NULL */ isc_result_t dns_zone_setalsonotify(dns_zone_t *zone, isc_sockaddr_t *notify, isc_uint32_t count); -/* +/*%< * Set the list of additional servers to be notified when * a zone changes. To clear the list use 'count = 0'. * * Require: - * 'zone' to be a valid zone. - * 'notify' to be non-NULL if count != 0. - * 'count' to be the number of notifyees. + *\li 'zone' to be a valid zone. + *\li 'notify' to be non-NULL if count != 0. + *\li 'count' to be the number of notifyees. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ void dns_zone_unload(dns_zone_t *zone); -/* +/*%< * detach the database from the zone structure. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_setoption(dns_zone_t *zone, unsigned int option, isc_boolean_t value); -/* +/*%< * Set given options on ('value' == ISC_TRUE) or off ('value' == - * ISC_FALSE). + * #ISC_FALSE). * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ unsigned int dns_zone_getoptions(dns_zone_t *zone); -/* +/*%< * Returns the current zone options. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_setminrefreshtime(dns_zone_t *zone, isc_uint32_t val); -/* +/*%< * Set the minimum refresh time. * * Requires: - * 'zone' is valid. - * val > 0. + *\li 'zone' is valid. + *\li val > 0. */ void dns_zone_setmaxrefreshtime(dns_zone_t *zone, isc_uint32_t val); -/* +/*%< * Set the maximum refresh time. * * Requires: - * 'zone' is valid. - * val > 0. + *\li 'zone' is valid. + *\li val > 0. */ void dns_zone_setminretrytime(dns_zone_t *zone, isc_uint32_t val); -/* +/*%< * Set the minimum retry time. * * Requires: - * 'zone' is valid. - * val > 0. + *\li 'zone' is valid. + *\li val > 0. */ void dns_zone_setmaxretrytime(dns_zone_t *zone, isc_uint32_t val); -/* +/*%< * Set the maximum retry time. * * Requires: - * 'zone' is valid. + *\li 'zone' is valid. * val > 0. */ @@ -529,260 +531,260 @@ isc_result_t dns_zone_setxfrsource4(dns_zone_t *zone, isc_sockaddr_t *xfrsource); isc_result_t dns_zone_setaltxfrsource4(dns_zone_t *zone, isc_sockaddr_t *xfrsource); -/* +/*%< * Set the source address to be used in IPv4 zone transfers. * * Require: - * 'zone' to be a valid zone. - * 'xfrsource' to contain the address. + *\li 'zone' to be a valid zone. + *\li 'xfrsource' to contain the address. * * Returns: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS */ isc_sockaddr_t * dns_zone_getxfrsource4(dns_zone_t *zone); isc_sockaddr_t * dns_zone_getaltxfrsource4(dns_zone_t *zone); -/* +/*%< * Returns the source address set by a previous dns_zone_setxfrsource4 * call, or the default of inaddr_any, port 0. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_setxfrsource6(dns_zone_t *zone, isc_sockaddr_t *xfrsource); isc_result_t dns_zone_setaltxfrsource6(dns_zone_t *zone, isc_sockaddr_t *xfrsource); -/* +/*%< * Set the source address to be used in IPv6 zone transfers. * * Require: - * 'zone' to be a valid zone. - * 'xfrsource' to contain the address. + *\li 'zone' to be a valid zone. + *\li 'xfrsource' to contain the address. * * Returns: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS */ isc_sockaddr_t * dns_zone_getxfrsource6(dns_zone_t *zone); isc_sockaddr_t * dns_zone_getaltxfrsource6(dns_zone_t *zone); -/* +/*%< * Returns the source address set by a previous dns_zone_setxfrsource6 * call, or the default of in6addr_any, port 0. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_setnotifysrc4(dns_zone_t *zone, isc_sockaddr_t *notifysrc); -/* +/*%< * Set the source address to be used with IPv4 NOTIFY messages. * * Require: - * 'zone' to be a valid zone. - * 'notifysrc' to contain the address. + *\li 'zone' to be a valid zone. + *\li 'notifysrc' to contain the address. * * Returns: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS */ isc_sockaddr_t * dns_zone_getnotifysrc4(dns_zone_t *zone); -/* +/*%< * Returns the source address set by a previous dns_zone_setnotifysrc4 * call, or the default of inaddr_any, port 0. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_setnotifysrc6(dns_zone_t *zone, isc_sockaddr_t *notifysrc); -/* +/*%< * Set the source address to be used with IPv6 NOTIFY messages. * * Require: - * 'zone' to be a valid zone. - * 'notifysrc' to contain the address. + *\li 'zone' to be a valid zone. + *\li 'notifysrc' to contain the address. * * Returns: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS */ isc_sockaddr_t * dns_zone_getnotifysrc6(dns_zone_t *zone); -/* +/*%< * Returns the source address set by a previous dns_zone_setnotifysrc6 * call, or the default of in6addr_any, port 0. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_setnotifyacl(dns_zone_t *zone, dns_acl_t *acl); -/* +/*%< * Sets the notify acl list for the zone. * * Require: - * 'zone' to be a valid zone. - * 'acl' to be a valid acl. + *\li 'zone' to be a valid zone. + *\li 'acl' to be a valid acl. */ void dns_zone_setqueryacl(dns_zone_t *zone, dns_acl_t *acl); -/* +/*%< * Sets the query acl list for the zone. * * Require: - * 'zone' to be a valid zone. - * 'acl' to be a valid acl. + *\li 'zone' to be a valid zone. + *\li 'acl' to be a valid acl. */ void dns_zone_setupdateacl(dns_zone_t *zone, dns_acl_t *acl); -/* +/*%< * Sets the update acl list for the zone. * * Require: - * 'zone' to be a valid zone. - * 'acl' to be valid acl. + *\li 'zone' to be a valid zone. + *\li 'acl' to be valid acl. */ void dns_zone_setforwardacl(dns_zone_t *zone, dns_acl_t *acl); -/* +/*%< * Sets the forward unsigned updates acl list for the zone. * * Require: - * 'zone' to be a valid zone. - * 'acl' to be valid acl. + *\li 'zone' to be a valid zone. + *\li 'acl' to be valid acl. */ void dns_zone_setxfracl(dns_zone_t *zone, dns_acl_t *acl); -/* +/*%< * Sets the transfer acl list for the zone. * * Require: - * 'zone' to be a valid zone. - * 'acl' to be valid acl. + *\li 'zone' to be a valid zone. + *\li 'acl' to be valid acl. */ dns_acl_t * dns_zone_getnotifyacl(dns_zone_t *zone); -/* +/*%< * Returns the current notify acl or NULL. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. * * Returns: - * acl a pointer to the acl. - * NULL + *\li acl a pointer to the acl. + *\li NULL */ dns_acl_t * dns_zone_getqueryacl(dns_zone_t *zone); -/* +/*%< * Returns the current query acl or NULL. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. * * Returns: - * acl a pointer to the acl. - * NULL + *\li acl a pointer to the acl. + *\li NULL */ dns_acl_t * dns_zone_getupdateacl(dns_zone_t *zone); -/* +/*%< * Returns the current update acl or NULL. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. * * Returns: - * acl a pointer to the acl. - * NULL + *\li acl a pointer to the acl. + *\li NULL */ dns_acl_t * dns_zone_getforwardacl(dns_zone_t *zone); -/* +/*%< * Returns the current forward unsigned updates acl or NULL. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. * * Returns: - * acl a pointer to the acl. - * NULL + *\li acl a pointer to the acl. + *\li NULL */ dns_acl_t * dns_zone_getxfracl(dns_zone_t *zone); -/* +/*%< * Returns the current transfer acl or NULL. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. * * Returns: - * acl a pointer to the acl. - * NULL + *\li acl a pointer to the acl. + *\li NULL */ void dns_zone_clearupdateacl(dns_zone_t *zone); -/* +/*%< * Clear the current update acl. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_clearforwardacl(dns_zone_t *zone); -/* +/*%< * Clear the current forward unsigned updates acl. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_clearnotifyacl(dns_zone_t *zone); -/* +/*%< * Clear the current notify acl. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_clearqueryacl(dns_zone_t *zone); -/* +/*%< * Clear the current query acl. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_clearxfracl(dns_zone_t *zone); -/* +/*%< * Clear the current transfer acl. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_boolean_t @@ -793,171 +795,171 @@ dns_zone_setupdatedisabled(dns_zone_t *zone, isc_boolean_t state); void dns_zone_setchecknames(dns_zone_t *zone, dns_severity_t severity); -/* +/*%< * Set the severity of name checking when loading a zone. * * Require: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ dns_severity_t dns_zone_getchecknames(dns_zone_t *zone); -/* +/*%< * Return the current severity of name checking. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ void dns_zone_setjournalsize(dns_zone_t *zone, isc_int32_t size); -/* +/*%< * Sets the journal size for the zone. * * Requires: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_int32_t dns_zone_getjournalsize(dns_zone_t *zone); -/* +/*%< * Return the journal size as set with a previous call to * dns_zone_setjournalsize(). * * Requires: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_notifyreceive(dns_zone_t *zone, isc_sockaddr_t *from, dns_message_t *msg); -/* +/*%< * Tell the zone that it has recieved a NOTIFY message from another * server. This may cause some zone maintainence activity to occur. * * Requires: - * 'zone' to be a valid zone. - * '*from' to contain the address of the server from which 'msg' + *\li 'zone' to be a valid zone. + *\li '*from' to contain the address of the server from which 'msg' * was recieved. - * 'msg' a message with opcode NOTIFY and qr clear. + *\li 'msg' a message with opcode NOTIFY and qr clear. * * Returns: - * DNS_R_REFUSED - * DNS_R_NOTIMP - * DNS_R_FORMERR - * DNS_R_SUCCESS + *\li DNS_R_REFUSED + *\li DNS_R_NOTIMP + *\li DNS_R_FORMERR + *\li DNS_R_SUCCESS */ void dns_zone_setmaxxfrin(dns_zone_t *zone, isc_uint32_t maxxfrin); -/* +/*%< * Set the maximum time (in seconds) that a zone transfer in (AXFR/IXFR) * of this zone will use before being aborted. * * Requires: - * 'zone' to be valid initialised zone. + * \li 'zone' to be valid initialised zone. */ isc_uint32_t dns_zone_getmaxxfrin(dns_zone_t *zone); -/* +/*%< * Returns the maximum transfer time for this zone. This will be * either the value set by the last call to dns_zone_setmaxxfrin() or * the default value of 1 hour. * * Requires: - * 'zone' to be valid initialised zone. + *\li 'zone' to be valid initialised zone. */ void dns_zone_setmaxxfrout(dns_zone_t *zone, isc_uint32_t maxxfrout); -/* +/*%< * Set the maximum time (in seconds) that a zone transfer out (AXFR/IXFR) * of this zone will use before being aborted. * * Requires: - * 'zone' to be valid initialised zone. + * \li 'zone' to be valid initialised zone. */ isc_uint32_t dns_zone_getmaxxfrout(dns_zone_t *zone); -/* +/*%< * Returns the maximum transfer time for this zone. This will be * either the value set by the last call to dns_zone_setmaxxfrout() or * the default value of 1 hour. * * Requires: - * 'zone' to be valid initialised zone. + *\li 'zone' to be valid initialised zone. */ isc_result_t dns_zone_setjournal(dns_zone_t *zone, const char *journal); -/* +/*%< * Sets the filename used for journaling updates / IXFR transfers. * The default journal name is set by dns_zone_setfile() to be * "file.jnl". If 'journal' is NULL, the zone will have no * journal name. * * Requires: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ char * dns_zone_getjournal(dns_zone_t *zone); -/* +/*%< * Returns the journal name associated with this zone. * If no journal has been set this will be NULL. * * Requires: - * 'zone' to be valid initialised zone. + *\li 'zone' to be valid initialised zone. */ dns_zonetype_t dns_zone_gettype(dns_zone_t *zone); -/* +/*%< * Returns the type of the zone (master/slave/etc.) * * Requires: - * 'zone' to be valid initialised zone. + *\li 'zone' to be valid initialised zone. */ void dns_zone_settask(dns_zone_t *zone, isc_task_t *task); -/* +/*%< * Give a zone a task to work with. Any current task will be detached. * * Requires: - * 'zone' to be valid. - * 'task' to be valid. + *\li 'zone' to be valid. + *\li 'task' to be valid. */ void dns_zone_gettask(dns_zone_t *zone, isc_task_t **target); -/* +/*%< * Attach '*target' to the zone's task. * * Requires: - * 'zone' to be valid initialised zone. - * 'zone' to have a task. - * 'target' to be != NULL && '*target' == NULL. + *\li 'zone' to be valid initialised zone. + *\li 'zone' to have a task. + *\li 'target' to be != NULL && '*target' == NULL. */ void dns_zone_notify(dns_zone_t *zone); -/* +/*%< * Generate notify events for this zone. * * Requires: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zone_replacedb(dns_zone_t *zone, dns_db_t *db, isc_boolean_t dump); -/* +/*%< * Replace the database of "zone" with a new database "db". * * If "dump" is ISC_TRUE, then the new zone contents are dumped @@ -971,11 +973,11 @@ dns_zone_replacedb(dns_zone_t *zone, dns_db_t *db, isc_boolean_t dump); * journal file, and the master file dump is postponed. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. * * Returns: - * DNS_R_SUCCESS - * DNS_R_BADZONE zone failed basic consistancy checks: + * \li DNS_R_SUCCESS + * \li DNS_R_BADZONE zone failed basic consistancy checks: * * a single SOA must exist * * some NS records must exist. * Others @@ -983,111 +985,111 @@ dns_zone_replacedb(dns_zone_t *zone, dns_db_t *db, isc_boolean_t dump); isc_uint32_t dns_zone_getidlein(dns_zone_t *zone); -/* +/*%< * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. * * Returns: - * number of seconds of idle time before we abort the transfer in. + * \li number of seconds of idle time before we abort the transfer in. */ void dns_zone_setidlein(dns_zone_t *zone, isc_uint32_t idlein); -/* - * Set the idle timeout for transfer the. - * Zero set the default value, 1 hour. +/*%< + * \li Set the idle timeout for transfer the. + * \li Zero set the default value, 1 hour. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ isc_uint32_t dns_zone_getidleout(dns_zone_t *zone); -/* +/*%< * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. * * Returns: - * number of seconds of idle time before we abort a transfer out. + * \li number of seconds of idle time before we abort a transfer out. */ void dns_zone_setidleout(dns_zone_t *zone, isc_uint32_t idleout); -/* - * Set the idle timeout for transfers out. - * Zero set the default value, 1 hour. +/*%< + * \li Set the idle timeout for transfers out. + * \li Zero set the default value, 1 hour. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ void dns_zone_getssutable(dns_zone_t *zone, dns_ssutable_t **table); -/* +/*%< * Get the simple-secure-update policy table. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ void dns_zone_setssutable(dns_zone_t *zone, dns_ssutable_t *table); -/* +/*%< * Set / clear the simple-secure-update policy table. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ isc_mem_t * dns_zone_getmctx(dns_zone_t *zone); -/* +/*%< * Get the memory context of a zone. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ dns_zonemgr_t * dns_zone_getmgr(dns_zone_t *zone); -/* +/*%< * If 'zone' is managed return the zone manager otherwise NULL. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ void dns_zone_setsigvalidityinterval(dns_zone_t *zone, isc_uint32_t interval); -/* +/*%< * Set the zone's SIG validity interval. This is the length of time * for which DNSSEC signatures created as a result of dynamic updates * to secure zones will remain valid, in seconds. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ isc_uint32_t dns_zone_getsigvalidityinterval(dns_zone_t *zone); -/* +/*%< * Get the zone's SIG validity interval. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ void dns_zone_setnotifytype(dns_zone_t *zone, dns_notifytype_t notifytype); -/* +/*%< * Sets zone notify method to "notifytype" */ isc_result_t dns_zone_forwardupdate(dns_zone_t *zone, dns_message_t *msg, dns_updatecallback_t callback, void *callback_arg); -/* +/*%< * Forward 'msg' to each master in turn until we get an answer or we * have exausted the list of masters. 'callback' will be called with * ISC_R_SUCCESS if we get an answer and the returned message will be @@ -1097,69 +1099,69 @@ dns_zone_forwardupdate(dns_zone_t *zone, dns_message_t *msg, * (callback)(callback_arg, result, answer_message); * * Require: - * 'zone' to be valid - * 'msg' to be valid. - * 'callback' to be non NULL. + *\li 'zone' to be valid + *\li 'msg' to be valid. + *\li 'callback' to be non NULL. * Returns: - * ISC_R_SUCCESS if the message has been forwarded, - * ISC_R_NOMEMORY - * Others + *\li #ISC_R_SUCCESS if the message has been forwarded, + *\li #ISC_R_NOMEMORY + *\li Others */ isc_result_t dns_zone_next(dns_zone_t *zone, dns_zone_t **next); -/* +/*%< * Find the next zone in the list of managed zones. * * Requires: - * 'zone' to be valid - * The zone manager for the indicated zone MUST be locked + *\li 'zone' to be valid + *\li The zone manager for the indicated zone MUST be locked * by the caller. This is not checked. - * 'next' be non-NULL, and '*next' be NULL. + *\li 'next' be non-NULL, and '*next' be NULL. * * Ensures: - * 'next' points to a valid zone (result ISC_R_SUCCESS) or to NULL + *\li 'next' points to a valid zone (result ISC_R_SUCCESS) or to NULL * (result ISC_R_NOMORE). */ isc_result_t dns_zone_first(dns_zonemgr_t *zmgr, dns_zone_t **first); -/* +/*%< * Find the first zone in the list of managed zones. * * Requires: - * 'zonemgr' to be valid - * The zone manager for the indicated zone MUST be locked + *\li 'zonemgr' to be valid + *\li The zone manager for the indicated zone MUST be locked * by the caller. This is not checked. - * 'first' be non-NULL, and '*first' be NULL + *\li 'first' be non-NULL, and '*first' be NULL * * Ensures: - * 'first' points to a valid zone (result ISC_R_SUCCESS) or to NULL + *\li 'first' points to a valid zone (result ISC_R_SUCCESS) or to NULL * (result ISC_R_NOMORE). */ isc_result_t dns_zone_setkeydirectory(dns_zone_t *zone, const char *directory); -/* +/*%< * Sets the name of the directory where private keys used for * online signing of dynamic zones are found. * * Require: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. * * Returns: - * ISC_R_NOMEMORY - * ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS */ const char * dns_zone_getkeydirectory(dns_zone_t *zone); -/* +/*%< * Gets the name of the directory where private keys used for * online signing of dynamic zones are found. * * Requires: - * 'zone' to be valid initialised zone. + *\li 'zone' to be valid initialised zone. * * Returns: * Pointer to null-terminated file name, or NULL. @@ -1170,231 +1172,231 @@ isc_result_t dns_zonemgr_create(isc_mem_t *mctx, isc_taskmgr_t *taskmgr, isc_timermgr_t *timermgr, isc_socketmgr_t *socketmgr, dns_zonemgr_t **zmgrp); -/* +/*%< * Create a zone manager. * * Requires: - * 'mctx' to be a valid memory context. - * 'taskmgr' to be a valid task manager. - * 'timermgr' to be a valid timer manager. - * 'zmgrp' to point to a NULL pointer. + *\li 'mctx' to be a valid memory context. + *\li 'taskmgr' to be a valid task manager. + *\li 'timermgr' to be a valid timer manager. + *\li 'zmgrp' to point to a NULL pointer. */ isc_result_t dns_zonemgr_managezone(dns_zonemgr_t *zmgr, dns_zone_t *zone); -/* +/*%< * Bring the zone under control of a zone manager. * * Require: - * 'zmgr' to be a valid zone manager. - * 'zone' to be a valid zone. + *\li 'zmgr' to be a valid zone manager. + *\li 'zone' to be a valid zone. */ isc_result_t dns_zonemgr_forcemaint(dns_zonemgr_t *zmgr); -/* +/*%< * Force zone maintenance of all zones managed by 'zmgr' at its * earliest conveniene. */ void dns_zonemgr_resumexfrs(dns_zonemgr_t *zmgr); -/* +/*%< * Attempt to start any stalled zone transfers. */ void dns_zonemgr_shutdown(dns_zonemgr_t *zmgr); -/* +/*%< * Shut down the zone manager. * * Requires: - * 'zmgr' to be a valid zone manager. + *\li 'zmgr' to be a valid zone manager. */ void dns_zonemgr_attach(dns_zonemgr_t *source, dns_zonemgr_t **target); -/* +/*%< * Attach '*target' to 'source' incrementing its external * reference count. * * Require: - * 'zone' to be a valid zone. - * 'target' to be non NULL and '*target' to be NULL. + *\li 'zone' to be a valid zone. + *\li 'target' to be non NULL and '*target' to be NULL. */ void dns_zonemgr_detach(dns_zonemgr_t **zmgrp); -/* +/*%< * Detach from a zone manager. * * Requires: - * '*zmgrp' is a valid, non-NULL zone manager pointer. + *\li '*zmgrp' is a valid, non-NULL zone manager pointer. * * Ensures: - * '*zmgrp' is NULL. + *\li '*zmgrp' is NULL. */ void dns_zonemgr_releasezone(dns_zonemgr_t *zmgr, dns_zone_t *zone); -/* +/*%< * Release 'zone' from the managed by 'zmgr'. 'zmgr' is implicitly * detached from 'zone'. * * Requires: - * 'zmgr' to be a valid zone manager. - * 'zone' to be a valid zone. - * 'zmgr' == 'zone->zmgr' + *\li 'zmgr' to be a valid zone manager. + *\li 'zone' to be a valid zone. + *\li 'zmgr' == 'zone->zmgr' * * Ensures: - * 'zone->zmgr' == NULL; + *\li 'zone->zmgr' == NULL; */ void dns_zonemgr_settransfersin(dns_zonemgr_t *zmgr, isc_uint32_t value); -/* +/*%< * Set the maximum number of simultanious transfers in allowed by * the zone manager. * * Requires: - * 'zmgr' to be a valid zone manager. + *\li 'zmgr' to be a valid zone manager. */ isc_uint32_t dns_zonemgr_getttransfersin(dns_zonemgr_t *zmgr); -/* +/*%< * Return the the maximum number of simultanious transfers in allowed. * * Requires: - * 'zmgr' to be a valid zone manager. + *\li 'zmgr' to be a valid zone manager. */ void dns_zonemgr_settransfersperns(dns_zonemgr_t *zmgr, isc_uint32_t value); -/* +/*%< * Set the number of zone transfers allowed per nameserver. * * Requires: - * 'zmgr' to be a valid zone manager + *\li 'zmgr' to be a valid zone manager */ isc_uint32_t dns_zonemgr_getttransfersperns(dns_zonemgr_t *zmgr); -/* +/*%< * Return the number of transfers allowed per nameserver. * * Requires: - * 'zmgr' to be a valid zone manager. + *\li 'zmgr' to be a valid zone manager. */ void dns_zonemgr_setiolimit(dns_zonemgr_t *zmgr, isc_uint32_t iolimit); -/* +/*%< * Set the number of simultaneous file descriptors available for * reading and writing masterfiles. * * Requires: - * 'zmgr' to be a valid zone manager. - * 'iolimit' to be positive. + *\li 'zmgr' to be a valid zone manager. + *\li 'iolimit' to be positive. */ isc_uint32_t dns_zonemgr_getiolimit(dns_zonemgr_t *zmgr); -/* +/*%< * Get the number of simultaneous file descriptors available for * reading and writing masterfiles. * * Requires: - * 'zmgr' to be a valid zone manager. + *\li 'zmgr' to be a valid zone manager. */ void dns_zonemgr_setserialqueryrate(dns_zonemgr_t *zmgr, unsigned int value); -/* +/*%< * Set the number of SOA queries sent per second. * * Requires: - * 'zmgr' to be a valid zone manager + *\li 'zmgr' to be a valid zone manager */ unsigned int dns_zonemgr_getserialqueryrate(dns_zonemgr_t *zmgr); -/* +/*%< * Return the number of SOA queries sent per second. * * Requires: - * 'zmgr' to be a valid zone manager. + *\li 'zmgr' to be a valid zone manager. */ unsigned int dns_zonemgr_getcount(dns_zonemgr_t *zmgr, int state); -/* +/*%< * Returns the number of zones in the specified state. * * Requires: - * 'zmgr' to be a valid zone manager. - * 'state' to be a valid DNS_ZONESTATE_ constant. + *\li 'zmgr' to be a valid zone manager. + *\li 'state' to be a valid DNS_ZONESTATE_ constant. */ void dns_zone_forcereload(dns_zone_t *zone); -/* +/*%< * Force a reload of specified zone. * * Requires: - * 'zone' to be a valid zone. + *\li 'zone' to be a valid zone. */ isc_boolean_t dns_zone_isforced(dns_zone_t *zone); -/* +/*%< * Check if the zone is waiting a forced reload. * * Requires: - * 'zone' to be a valid zone. + * \li 'zone' to be a valid zone. */ isc_result_t dns_zone_setstatistics(dns_zone_t *zone, isc_boolean_t on); -/* +/*%< * Make the zone keep or not keep an array of statistics * counter. * * Requires: - * zone be a valid zone. + * \li zone be a valid zone. */ isc_uint64_t * dns_zone_getstatscounters(dns_zone_t *zone); -/* +/*%< * Requires: * zone be a valid zone. * * Returns: - * A pointer to the zone's array of statistics counters, + * \li A pointer to the zone's array of statistics counters, * or NULL if it has none. */ void dns_zone_dialup(dns_zone_t *zone); -/* +/*%< * Perform dialup-time maintenance on 'zone'. */ void dns_zone_setdialup(dns_zone_t *zone, dns_dialuptype_t dialup); -/* +/*%< * Set the dialup type of 'zone' to 'dialup'. * * Requires: - * 'zone' to be valid initialised zone. - * 'dialup' to be a valid dialup type. + * \li 'zone' to be valid initialised zone. + *\li 'dialup' to be a valid dialup type. */ void dns_zone_log(dns_zone_t *zone, int level, const char *msg, ...) ISC_FORMAT_PRINTF(3, 4); -/* +/*%< * Log the message 'msg...' at 'level', including text that identifies * the message as applying to 'zone'. */ @@ -1402,19 +1404,19 @@ dns_zone_log(dns_zone_t *zone, int level, const char *msg, ...) void dns_zone_logc(dns_zone_t *zone, isc_logcategory_t *category, int level, const char *msg, ...) ISC_FORMAT_PRINTF(4, 5); -/* +/*%< * Log the message 'msg...' at 'level', including text that identifies * the message as applying to 'zone'. */ void dns_zone_name(dns_zone_t *zone, char *buf, size_t len); -/* +/*%< * Return the name of the zone with class and view. * * Requires: - * 'zone' to be valid. - * 'buf' to be non NULL. + *\li 'zone' to be valid. + *\li 'buf' to be non NULL. */ isc_result_t diff --git a/lib/dns/include/dns/zonekey.h b/lib/dns/include/dns/zonekey.h index bfd548044e..60a78160c6 100644 --- a/lib/dns/include/dns/zonekey.h +++ b/lib/dns/include/dns/zonekey.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: zonekey.h,v 1.4 2004/03/05 05:09:48 marka Exp $ */ +/* $Id: zonekey.h,v 1.5 2005/04/27 04:57:01 sra Exp $ */ #ifndef DNS_ZONEKEY_H #define DNS_ZONEKEY_H 1 +/*! \file */ + #include #include @@ -28,7 +30,7 @@ ISC_LANG_BEGINDECLS isc_boolean_t dns_zonekey_iszonekey(dns_rdata_t *keyrdata); -/* +/*%< * Determines if the key record contained in the rdata is a zone key. * * Requires: diff --git a/lib/dns/include/dns/zt.h b/lib/dns/include/dns/zt.h index f405d296e5..c6848d3c5d 100644 --- a/lib/dns/include/dns/zt.h +++ b/lib/dns/include/dns/zt.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: zt.h,v 1.32 2005/01/17 04:11:34 marka Exp $ */ +/* $Id: zt.h,v 1.33 2005/04/27 04:57:01 sra Exp $ */ #ifndef DNS_ZT_H #define DNS_ZT_H 1 +/*! \file */ + #include #include @@ -30,101 +32,101 @@ ISC_LANG_BEGINDECLS isc_result_t dns_zt_create(isc_mem_t *mctx, dns_rdataclass_t rdclass, dns_zt_t **zt); -/* +/*%< * Creates a new zone table. * * Requires: - * 'mctx' to be initialized. + * \li 'mctx' to be initialized. * * Returns: - * ISC_R_SUCCESS on success. - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS on success. + *\li #ISC_R_NOMEMORY */ isc_result_t dns_zt_mount(dns_zt_t *zt, dns_zone_t *zone); -/* +/*%< * Mounts the zone on the zone table. * * Requires: - * 'zt' to be valid - * 'zone' to be valid + *\li 'zt' to be valid + *\li 'zone' to be valid * * Returns: - * ISC_R_SUCCESS - * ISC_R_EXISTS - * ISC_R_NOSPACE - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_EXISTS + *\li #ISC_R_NOSPACE + *\li #ISC_R_NOMEMORY */ isc_result_t dns_zt_unmount(dns_zt_t *zt, dns_zone_t *zone); -/* +/*%< * Unmount the given zone from the table. * * Requires: * 'zt' to be valid - * 'zone' to be valid + *\li 'zone' to be valid * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOTFOUND - * ISC_R_NOMEMORY + * \li #ISC_R_SUCCESS + *\li #ISC_R_NOTFOUND + *\li #ISC_R_NOMEMORY */ isc_result_t dns_zt_find(dns_zt_t *zt, dns_name_t *name, unsigned int options, dns_name_t *foundname, dns_zone_t **zone); -/* +/*%< * Find the best match for 'name' in 'zt'. If foundname is non NULL * then the name of the zone found is returned. * * Notes: - * If the DNS_ZTFIND_NOEXACT is set, the best partial match (if any) + *\li If the DNS_ZTFIND_NOEXACT is set, the best partial match (if any) * to 'name' will be returned. * * Requires: - * 'zt' to be valid - * 'name' to be valid - * 'foundname' to be initialized and associated with a fixedname or NULL - * 'zone' to be non NULL and '*zone' to be NULL + *\li 'zt' to be valid + *\li 'name' to be valid + *\li 'foundname' to be initialized and associated with a fixedname or NULL + *\li 'zone' to be non NULL and '*zone' to be NULL * * Returns: - * ISC_R_SUCCESS - * DNS_R_PARTIALMATCH - * ISC_R_NOTFOUND - * ISC_R_NOSPACE + * \li #ISC_R_SUCCESS + *\li #DNS_R_PARTIALMATCH + *\li #ISC_R_NOTFOUND + *\li #ISC_R_NOSPACE */ void dns_zt_detach(dns_zt_t **ztp); -/* +/*%< * Detach the given zonetable, if the reference count goes to zero the * zonetable will be freed. In either case 'ztp' is set to NULL. * * Requires: - * '*ztp' to be valid + *\li '*ztp' to be valid */ void dns_zt_flushanddetach(dns_zt_t **ztp); -/* +/*%< * Detach the given zonetable, if the reference count goes to zero the * zonetable will be flushed and then freed. In either case 'ztp' is * set to NULL. * * Requires: - * '*ztp' to be valid + *\li '*ztp' to be valid */ void dns_zt_attach(dns_zt_t *zt, dns_zt_t **ztp); -/* +/*%< * Attach 'zt' to '*ztp'. * * Requires: - * 'zt' to be valid - * '*ztp' to be NULL + *\li 'zt' to be valid + *\li '*ztp' to be NULL */ isc_result_t @@ -132,7 +134,7 @@ dns_zt_load(dns_zt_t *zt, isc_boolean_t stop); isc_result_t dns_zt_loadnew(dns_zt_t *zt, isc_boolean_t stop); -/* +/*%< * Load all zones in the table. If 'stop' is ISC_TRUE, * stop on the first error and return it. If 'stop' * is ISC_FALSE, ignore errors. @@ -142,12 +144,12 @@ dns_zt_loadnew(dns_zt_t *zt, isc_boolean_t stop); * and whose master file has changed since the last load. * * Requires: - * 'zt' to be valid + * \li 'zt' to be valid */ isc_result_t dns_zt_freezezones(dns_zt_t *zt, isc_boolean_t freeze); -/* +/*%< * Freeze/thaw updates to master zones. * Any pending updates will be flushed. * Zones will be reloaded on thaw. @@ -160,17 +162,17 @@ dns_zt_apply(dns_zt_t *zt, isc_boolean_t stop, isc_result_t dns_zt_apply2(dns_zt_t *zt, isc_boolean_t stop, isc_result_t *sub, isc_result_t (*action)(dns_zone_t *, void *), void *uap); -/* +/*%< * Apply a given 'action' to all zone zones in the table. * If 'stop' is 'ISC_TRUE' then walking the zone tree will stop if * 'action' does not return ISC_R_SUCCESS. * * Requires: - * 'zt' to be valid. - * 'action' to be non NULL. + * \li 'zt' to be valid. + * \li 'action' to be non NULL. * * Returns: - * ISC_R_SUCCESS if action was applied to all nodes. If 'stop' is + * \li ISC_R_SUCCESS if action was applied to all nodes. If 'stop' is * ISC_FALSE and 'sub' is non NULL then the first error (if any) * reported by 'action' is returned in '*sub'; * any error code from 'action'. diff --git a/lib/dns/include/dst/dst.h b/lib/dns/include/dst/dst.h index 7967b3114e..232cbfe284 100644 --- a/lib/dns/include/dst/dst.h +++ b/lib/dns/include/dst/dst.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dst.h,v 1.1 2004/12/09 01:41:05 marka Exp $ */ +/* $Id: dst.h,v 1.2 2005/04/27 04:57:02 sra Exp $ */ #ifndef DST_DST_H #define DST_DST_H 1 +/*! \file */ + #include #include @@ -30,7 +32,7 @@ ISC_LANG_BEGINDECLS *** Types ***/ -/* +/*% * The dst_key structure is opaque. Applications should use the accessor * functions provided to retrieve key attributes. If an application needs * to set attributes, new accessor functions will be written. @@ -42,7 +44,7 @@ typedef struct dst_context dst_context_t; /* DST algorithm codes */ #define DST_ALG_UNKNOWN 0 #define DST_ALG_RSAMD5 1 -#define DST_ALG_RSA DST_ALG_RSAMD5 /* backwards compatibility */ +#define DST_ALG_RSA DST_ALG_RSAMD5 /*%< backwards compatibility */ #define DST_ALG_DH 2 #define DST_ALG_DSA 3 #define DST_ALG_ECC 4 @@ -53,16 +55,16 @@ typedef struct dst_context dst_context_t; #define DST_ALG_EXPAND 255 #define DST_MAX_ALGS 255 -/* A buffer of this size is large enough to hold any key */ +/*% A buffer of this size is large enough to hold any key */ #define DST_KEY_MAXSIZE 1280 -/* +/*% * A buffer of this size is large enough to hold the textual representation * of any key */ #define DST_KEY_MAXTEXTSIZE 2048 -/* 'Type' for dst_read_key() */ +/*% 'Type' for dst_read_key() */ #define DST_TYPE_KEY 0x1000000 /* KEY key */ #define DST_TYPE_PRIVATE 0x2000000 #define DST_TYPE_PUBLIC 0x4000000 @@ -73,262 +75,262 @@ typedef struct dst_context dst_context_t; isc_result_t dst_lib_init(isc_mem_t *mctx, isc_entropy_t *ectx, unsigned int eflags); -/* +/*%< * Initializes the DST subsystem. * * Requires: - * "mctx" is a valid memory context - * "ectx" is a valid entropy context + * \li "mctx" is a valid memory context + * \li "ectx" is a valid entropy context * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + * \li ISC_R_SUCCESS + * \li ISC_R_NOMEMORY * * Ensures: - * DST is properly initialized. + * \li DST is properly initialized. */ void dst_lib_destroy(void); -/* +/*%< * Releases all resources allocated by DST. */ isc_boolean_t dst_algorithm_supported(unsigned int alg); -/* +/*%< * Checks that a given algorithm is supported by DST. * * Returns: - * ISC_TRUE - * ISC_FALSE + * \li ISC_TRUE + * \li ISC_FALSE */ isc_result_t dst_context_create(dst_key_t *key, isc_mem_t *mctx, dst_context_t **dctxp); -/* +/*%< * Creates a context to be used for a sign or verify operation. * * Requires: - * "key" is a valid key. - * "mctx" is a valid memory context. - * dctxp != NULL && *dctxp == NULL + * \li "key" is a valid key. + * \li "mctx" is a valid memory context. + * \li dctxp != NULL && *dctxp == NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + * \li ISC_R_SUCCESS + * \li ISC_R_NOMEMORY * * Ensures: - * *dctxp will contain a usable context. + * \li *dctxp will contain a usable context. */ void dst_context_destroy(dst_context_t **dctxp); -/* +/*%< * Destroys all memory associated with a context. * * Requires: - * *dctxp != NULL && *dctxp == NULL + * \li *dctxp != NULL && *dctxp == NULL * * Ensures: - * *dctxp == NULL + * \li *dctxp == NULL */ isc_result_t dst_context_adddata(dst_context_t *dctx, const isc_region_t *data); -/* +/*%< * Incrementally adds data to the context to be used in a sign or verify * operation. * * Requires: - * "dctx" is a valid context - * "data" is a valid region + * \li "dctx" is a valid context + * \li "data" is a valid region * * Returns: - * ISC_R_SUCCESS - * DST_R_SIGNFAILURE - * all other errors indicate failure + * \li ISC_R_SUCCESS + * \li DST_R_SIGNFAILURE + * \li all other errors indicate failure */ isc_result_t dst_context_sign(dst_context_t *dctx, isc_buffer_t *sig); -/* +/*%< * Computes a signature using the data and key stored in the context. * * Requires: - * "dctx" is a valid context. - * "sig" is a valid buffer. + * \li "dctx" is a valid context. + * \li "sig" is a valid buffer. * * Returns: - * ISC_R_SUCCESS - * DST_R_VERIFYFAILURE - * all other errors indicate failure + * \li ISC_R_SUCCESS + * \li DST_R_VERIFYFAILURE + * \li all other errors indicate failure * * Ensures: - * "sig" will contain the signature + * \li "sig" will contain the signature */ isc_result_t dst_context_verify(dst_context_t *dctx, isc_region_t *sig); -/* +/*%< * Verifies the signature using the data and key stored in the context. * * Requires: - * "dctx" is a valid context. - * "sig" is a valid region. + * \li "dctx" is a valid context. + * \li "sig" is a valid region. * * Returns: - * ISC_R_SUCCESS - * all other errors indicate failure + * \li ISC_R_SUCCESS + * \li all other errors indicate failure * * Ensures: - * "sig" will contain the signature + * \li "sig" will contain the signature */ isc_result_t dst_key_computesecret(const dst_key_t *pub, const dst_key_t *priv, isc_buffer_t *secret); -/* +/*%< * Computes a shared secret from two (Diffie-Hellman) keys. * * Requires: - * "pub" is a valid key that can be used to derive a shared secret - * "priv" is a valid private key that can be used to derive a shared secret - * "secret" is a valid buffer + * \li "pub" is a valid key that can be used to derive a shared secret + * \li "priv" is a valid private key that can be used to derive a shared secret + * \li "secret" is a valid buffer * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + * \li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, secret will contain the derived shared secret. + * \li If successful, secret will contain the derived shared secret. */ isc_result_t dst_key_fromfile(dns_name_t *name, dns_keytag_t id, unsigned int alg, int type, const char *directory, isc_mem_t *mctx, dst_key_t **keyp); -/* +/*%< * Reads a key from permanent storage. The key can either be a public or * private key, and is specified by name, algorithm, and id. If a private key * is specified, the public key must also be present. If directory is NULL, * the current directory is assumed. * * Requires: - * "name" is a valid absolute dns name. - * "id" is a valid key tag identifier. - * "alg" is a supported key algorithm. - * "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. + * \li "name" is a valid absolute dns name. + * \li "id" is a valid key tag identifier. + * \li "alg" is a supported key algorithm. + * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union. * DST_TYPE_KEY look for a KEY record otherwise DNSKEY - * "mctx" is a valid memory context. - * "keyp" is not NULL and "*keyp" is NULL. + * \li "mctx" is a valid memory context. + * \li "keyp" is not NULL and "*keyp" is NULL. * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + * \li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, *keyp will contain a valid key. + * \li If successful, *keyp will contain a valid key. */ isc_result_t dst_key_fromnamedfile(const char *filename, int type, isc_mem_t *mctx, dst_key_t **keyp); -/* +/*%< * Reads a key from permanent storage. The key can either be a public or * key, and is specified by filename. If a private key is specified, the * public key must also be present. * * Requires: - * "filename" is not NULL - * "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union + * \li "filename" is not NULL + * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union * DST_TYPE_KEY look for a KEY record otherwise DNSKEY - * "mctx" is a valid memory context - * "keyp" is not NULL and "*keyp" is NULL. + * \li "mctx" is a valid memory context + * \li "keyp" is not NULL and "*keyp" is NULL. * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + * \li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, *keyp will contain a valid key. + * \li If successful, *keyp will contain a valid key. */ isc_result_t dst_key_read_public(const char *filename, int type, isc_mem_t *mctx, dst_key_t **keyp); -/* +/*%< * Reads a public key from permanent storage. The key must be a public key. * * Requires: - * "filename" is not NULL - * "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY - * "mctx" is a valid memory context - * "keyp" is not NULL and "*keyp" is NULL. + * \li "filename" is not NULL + * \li "type" is DST_TYPE_KEY look for a KEY record otherwise DNSKEY + * \li "mctx" is a valid memory context + * \li "keyp" is not NULL and "*keyp" is NULL. * * Returns: - * ISC_R_SUCCESS - * DST_R_BADKEYTYPE if the key type is not the expected one - * ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key - * any other result indicates failure + * \li ISC_R_SUCCESS + * \li DST_R_BADKEYTYPE if the key type is not the expected one + * \li ISC_R_UNEXPECTEDTOKEN if the file can not be parsed as a public key + * \li any other result indicates failure * * Ensures: - * If successful, *keyp will contain a valid key. + * \li If successful, *keyp will contain a valid key. */ isc_result_t dst_key_tofile(const dst_key_t *key, int type, const char *directory); -/* +/*%< * Writes a key to permanent storage. The key can either be a public or * private key. Public keys are written in DNS format and private keys * are written as a set of base64 encoded values. If directory is NULL, * the current directory is assumed. * * Requires: - * "key" is a valid key. - * "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union + * \li "key" is a valid key. + * \li "type" is DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or the bitwise union * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + * \li ISC_R_SUCCESS + * \li any other result indicates failure */ isc_result_t dst_key_fromdns(dns_name_t *name, dns_rdataclass_t rdclass, isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); -/* +/*%< * Converts a DNS KEY record into a DST key. * * Requires: - * "name" is a valid absolute dns name. - * "source" is a valid buffer. There must be at least 4 bytes available. - * "mctx" is a valid memory context. - * "keyp" is not NULL and "*keyp" is NULL. + * \li "name" is a valid absolute dns name. + * \li "source" is a valid buffer. There must be at least 4 bytes available. + * \li "mctx" is a valid memory context. + * \li "keyp" is not NULL and "*keyp" is NULL. * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + * \li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, *keyp will contain a valid key, and the consumed + * \li If successful, *keyp will contain a valid key, and the consumed * pointer in data will be advanced. */ isc_result_t dst_key_todns(const dst_key_t *key, isc_buffer_t *target); -/* +/*%< * Converts a DST key into a DNS KEY record. * * Requires: - * "key" is a valid key. - * "target" is a valid buffer. There must be at least 4 bytes unused. + * \li "key" is a valid key. + * \li "target" is a valid buffer. There must be at least 4 bytes unused. * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + * \li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, the used pointer in 'target' is advanced by at least 4. + * \li If successful, the used pointer in 'target' is advanced by at least 4. */ isc_result_t @@ -336,80 +338,80 @@ dst_key_frombuffer(dns_name_t *name, unsigned int alg, unsigned int flags, unsigned int protocol, dns_rdataclass_t rdclass, isc_buffer_t *source, isc_mem_t *mctx, dst_key_t **keyp); -/* +/*%< * Converts a buffer containing DNS KEY RDATA into a DST key. * * Requires: - * "name" is a valid absolute dns name. - * "alg" is a supported key algorithm. - * "source" is a valid buffer. - * "mctx" is a valid memory context. - * "keyp" is not NULL and "*keyp" is NULL. + *\li "name" is a valid absolute dns name. + *\li "alg" is a supported key algorithm. + *\li "source" is a valid buffer. + *\li "mctx" is a valid memory context. + *\li "keyp" is not NULL and "*keyp" is NULL. * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + *\li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, *keyp will contain a valid key, and the consumed + *\li If successful, *keyp will contain a valid key, and the consumed * pointer in source will be advanced. */ isc_result_t dst_key_tobuffer(const dst_key_t *key, isc_buffer_t *target); -/* +/*%< * Converts a DST key into DNS KEY RDATA format. * * Requires: - * "key" is a valid key. - * "target" is a valid buffer. + *\li "key" is a valid key. + *\li "target" is a valid buffer. * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + *\li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, the used pointer in 'target' is advanced. + *\li If successful, the used pointer in 'target' is advanced. */ isc_result_t dst_key_privatefrombuffer(dst_key_t *key, isc_buffer_t *buffer); -/* +/*%< * Converts a public key into a private key, reading the private key * information from the buffer. The buffer should contain the same data * as the .private key file would. * * Requires: - * "key" is a valid public key. - * "buffer" is not NULL. + *\li "key" is a valid public key. + *\li "buffer" is not NULL. * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + *\li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, key will contain a valid private key. + *\li If successful, key will contain a valid private key. */ isc_result_t dst_key_fromgssapi(dns_name_t *name, void *opaque, isc_mem_t *mctx, dst_key_t **keyp); -/* +/*%< * Converts a GSSAPI opaque context id into a DST key. * * Requires: - * "name" is a valid absolute dns name. - * "opaque" is a GSSAPI context id. - * "mctx" is a valid memory context. - * "keyp" is not NULL and "*keyp" is NULL. + *\li "name" is a valid absolute dns name. + *\li "opaque" is a GSSAPI context id. + *\li "mctx" is a valid memory context. + *\li "keyp" is not NULL and "*keyp" is NULL. * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + *\li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, *keyp will contain a valid key and be responsible for + *\li If successful, *keyp will contain a valid key and be responsible for * the context id. */ @@ -419,9 +421,10 @@ dst_key_generate(dns_name_t *name, unsigned int alg, unsigned int flags, unsigned int protocol, dns_rdataclass_t rdclass, isc_mem_t *mctx, dst_key_t **keyp); -/* +/*%< * Generate a DST key (or keypair) with the supplied parameters. The * interpretation of the "param" field depends on the algorithm: + * \code * RSA: exponent * 0 use exponent 3 * !0 use Fermat4 (2^16 + 1) @@ -433,66 +436,67 @@ dst_key_generate(dns_name_t *name, unsigned int alg, * HMACMD5: entropy * 0 default - require good entropy * !0 lack of good entropy is ok + *\endcode * * Requires: - * "name" is a valid absolute dns name. - * "keyp" is not NULL and "*keyp" is NULL. + *\li "name" is a valid absolute dns name. + *\li "keyp" is not NULL and "*keyp" is NULL. * * Returns: - * ISC_R_SUCCESS - * any other result indicates failure + *\li ISC_R_SUCCESS + * \li any other result indicates failure * * Ensures: - * If successful, *keyp will contain a valid key. + *\li If successful, *keyp will contain a valid key. */ isc_boolean_t dst_key_compare(const dst_key_t *key1, const dst_key_t *key2); -/* +/*%< * Compares two DST keys. * * Requires: - * "key1" is a valid key. - * "key2" is a valid key. + *\li "key1" is a valid key. + *\li "key2" is a valid key. * * Returns: - * ISC_TRUE - * ISC_FALSE + *\li ISC_TRUE + * \li ISC_FALSE */ isc_boolean_t dst_key_paramcompare(const dst_key_t *key1, const dst_key_t *key2); -/* +/*%< * Compares the parameters of two DST keys. This is used to determine if * two (Diffie-Hellman) keys can be used to derive a shared secret. * * Requires: - * "key1" is a valid key. - * "key2" is a valid key. + *\li "key1" is a valid key. + *\li "key2" is a valid key. * * Returns: - * ISC_TRUE - * ISC_FALSE + *\li ISC_TRUE + * \li ISC_FALSE */ void dst_key_free(dst_key_t **keyp); -/* +/*%< * Release all memory associated with the key. * * Requires: - * "keyp" is not NULL and "*keyp" is a valid key. + *\li "keyp" is not NULL and "*keyp" is a valid key. * * Ensures: - * All memory associated with "*keyp" will be freed. - * *keyp == NULL + *\li All memory associated with "*keyp" will be freed. + *\li *keyp == NULL */ -/* +/*%< * Accessor functions to obtain key fields. * * Require: - * "key" is a valid key. + *\li "key" is a valid key. */ dns_name_t * dst_key_name(const dst_key_t *key); @@ -527,65 +531,65 @@ dst_key_isnullkey(const dst_key_t *key); isc_result_t dst_key_buildfilename(const dst_key_t *key, int type, const char *directory, isc_buffer_t *out); -/* +/*%< * Generates the filename used by dst to store the specified key. * If directory is NULL, the current directory is assumed. * * Requires: - * "key" is a valid key - * "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. - * "out" is a valid buffer + *\li "key" is a valid key + *\li "type" is either DST_TYPE_PUBLIC, DST_TYPE_PRIVATE, or 0 for no suffix. + *\li "out" is a valid buffer * * Ensures: - * the file name will be written to "out", and the used pointer will + *\li the file name will be written to "out", and the used pointer will * be advanced. */ isc_result_t dst_key_sigsize(const dst_key_t *key, unsigned int *n); -/* +/*%< * Computes the size of a signature generated by the given key. * * Requires: - * "key" is a valid key. - * "n" is not NULL + *\li "key" is a valid key. + *\li "n" is not NULL * * Returns: - * ISC_R_SUCCESS - * DST_R_UNSUPPORTEDALG + *\li #ISC_R_SUCCESS + *\li DST_R_UNSUPPORTEDALG * * Ensures: - * "n" stores the size of a generated signature + *\li "n" stores the size of a generated signature */ isc_result_t dst_key_secretsize(const dst_key_t *key, unsigned int *n); -/* +/*%< * Computes the size of a shared secret generated by the given key. * * Requires: - * "key" is a valid key. - * "n" is not NULL + *\li "key" is a valid key. + *\li "n" is not NULL * * Returns: - * ISC_R_SUCCESS - * DST_R_UNSUPPORTEDALG + *\li #ISC_R_SUCCESS + *\li DST_R_UNSUPPORTEDALG * * Ensures: - * "n" stores the size of a generated shared secret + *\li "n" stores the size of a generated shared secret */ isc_uint16_t dst_region_computeid(const isc_region_t *source, unsigned int alg); -/* +/*%< * Computes the key id of the key stored in the provided region with the * given algorithm. * * Requires: - * "source" contains a valid, non-NULL region. + *\li "source" contains a valid, non-NULL region. * * Returns: - * the key id + *\li the key id */ ISC_LANG_ENDDECLS diff --git a/lib/dns/include/dst/gssapi.h b/lib/dns/include/dst/gssapi.h index db46a2471c..259cd1cc3c 100644 --- a/lib/dns/include/dst/gssapi.h +++ b/lib/dns/include/dst/gssapi.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gssapi.h,v 1.1 2004/12/09 01:41:06 marka Exp $ */ +/* $Id: gssapi.h,v 1.2 2005/04/27 04:57:02 sra Exp $ */ #ifndef DST_GSSAPI_H #define DST_GSSAPI_H 1 +/*! \file */ + #include #include diff --git a/lib/dns/include/dst/lib.h b/lib/dns/include/dst/lib.h index f5addc1a7f..d1d591ff9b 100644 --- a/lib/dns/include/dst/lib.h +++ b/lib/dns/include/dst/lib.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lib.h,v 1.1 2004/12/09 01:41:06 marka Exp $ */ +/* $Id: lib.h,v 1.2 2005/04/27 04:57:02 sra Exp $ */ #ifndef DST_LIB_H #define DST_LIB_H 1 +/*! \file */ + #include #include diff --git a/lib/dns/include/dst/result.h b/lib/dns/include/dst/result.h index 3ea2f84192..8c3dfce7ad 100644 --- a/lib/dns/include/dst/result.h +++ b/lib/dns/include/dst/result.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: result.h,v 1.1 2004/12/09 01:41:06 marka Exp $ */ +/* $Id: result.h,v 1.2 2005/04/27 04:57:02 sra Exp $ */ #ifndef DST_RESULT_H #define DST_RESULT_H 1 +/*! \file */ + #include #include diff --git a/lib/dns/journal.c b/lib/dns/journal.c index b2b0306b7f..1f2ef1e263 100644 --- a/lib/dns/journal.c +++ b/lib/dns/journal.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: journal.c,v 1.89 2004/09/16 04:54:03 marka Exp $ */ +/* $Id: journal.c,v 1.90 2005/04/27 04:56:47 sra Exp $ */ #include @@ -39,7 +39,44 @@ #include #include -/* +/*! \file + * \brief Journalling. + * + * A journal file consists of + * + * \li A fixed-size header of type journal_rawheader_t. + * + * \li The index. This is an unordered array of index entries + * of type journal_rawpos_t giving the locations + * of some arbitrary subset of the journal's addressable + * transactions. The index entries are used as hints to + * speed up the process of locating a transaction with a given + * serial number. Unused index entries have an "offset" + * field of zero. The size of the index can vary between + * journal files, but does not change during the lifetime + * of a file. The size can be zero. + * + * \li The journal data. This consists of one or more transactions. + * Each transaction begins with a transaction header of type + * journal_rawxhdr_t. The transaction header is followed by a + * sequence of RRs, similar in structure to an IXFR difference + * sequence (RFC1995). That is, the pre-transaction SOA, + * zero or more other deleted RRs, the post-transaction SOA, + * and zero or more other added RRs. Unlike in IXFR, each RR + * is prefixed with a 32-bit length. + * + * The journal data part grows as new transactions are + * appended to the file. Only those transactions + * whose serial number is current-(2^31-1) to current + * are considered "addressable" and may be pointed + * to from the header or index. They may be preceded + * by old transactions that are no longer addressable, + * and they may be followed by transactions that were + * appended to the journal but never committed by updating + * the "end" position in the header. The latter will + * be overwritten when new transactions are added. + */ +/*% * When true, accept IXFR difference sequences where the * SOA serial number does not change (BIND 8 sends such * sequences). @@ -57,7 +94,7 @@ static isc_boolean_t bind8_compat = ISC_TRUE; /* XXX config */ #define JOURNAL_DEBUG_LOGARGS(n) \ JOURNAL_COMMON_LOGARGS, ISC_LOG_DEBUG(n) -/* +/*% * It would be non-sensical (or at least obtuse) to use FAIL() with an * ISC_R_SUCCESS code, but the test is there to keep the Solaris compiler * from complaining about "end-of-loop code not reached". @@ -133,55 +170,16 @@ dns_db_createsoatuple(dns_db_t *db, dns_dbversion_t *ver, isc_mem_t *mctx, return (result); } -/**************************************************************************/ -/* - * Journalling. - */ +/* Journalling */ -/* - * A journal file consists of - * - * - A fixed-size header of type journal_rawheader_t. - * - * - The index. This is an unordered array of index entries - * of type journal_rawpos_t giving the locations - * of some arbitrary subset of the journal's addressable - * transactions. The index entries are used as hints to - * speed up the process of locating a transaction with a given - * serial number. Unused index entries have an "offset" - * field of zero. The size of the index can vary between - * journal files, but does not change during the lifetime - * of a file. The size can be zero. - * - * - The journal data. This consists of one or more transactions. - * Each transaction begins with a transaction header of type - * journal_rawxhdr_t. The transaction header is followed by a - * sequence of RRs, similar in structure to an IXFR difference - * sequence (RFC1995). That is, the pre-transaction SOA, - * zero or more other deleted RRs, the post-transaction SOA, - * and zero or more other added RRs. Unlike in IXFR, each RR - * is prefixed with a 32-bit length. - * - * The journal data part grows as new transactions are - * appended to the file. Only those transactions - * whose serial number is current-(2^31-1) to current - * are considered "addressable" and may be pointed - * to from the header or index. They may be preceded - * by old transactions that are no longer addressable, - * and they may be followed by transactions that were - * appended to the journal but never committed by updating - * the "end" position in the header. The latter will - * be overwritten when new transactions are added. - */ - -/* +/*% * On-disk representation of a "pointer" to a journal entry. * These are used in the journal header to locate the beginning * and end of the journal, and in the journal index to locate * other transactions. */ typedef struct { - unsigned char serial[4]; /* SOA serial before update. */ + unsigned char serial[4]; /*%< SOA serial before update. */ /* * XXXRTH Should offset be 8 bytes? * XXXDCL ... probably, since isc_offset_t is 8 bytes on many OSs. @@ -189,54 +187,54 @@ typedef struct { * platforms as long as we are using fseek() rather * than lseek(). */ - unsigned char offset[4]; /* Offset from beginning of file. */ + unsigned char offset[4]; /*%< Offset from beginning of file. */ } journal_rawpos_t; -/* - * The on-disk representation of the journal header. - * All numbers are stored in big-endian order. - */ -/* +/*% * The header is of a fixed size, with some spare room for future * extensions. */ #define JOURNAL_HEADER_SIZE 64 /* Bytes. */ +/*% + * The on-disk representation of the journal header. + * All numbers are stored in big-endian order. + */ typedef union { struct { - /* File format version ID. */ + /*% File format version ID. */ unsigned char format[16]; - /* Position of the first addressable transaction */ + /*% Position of the first addressable transaction */ journal_rawpos_t begin; - /* Position of the next (yet nonexistent) transaction. */ + /*% Position of the next (yet nonexistent) transaction. */ journal_rawpos_t end; - /* Number of index entries following the header. */ + /*% Number of index entries following the header. */ unsigned char index_size[4]; } h; /* Pad the header to a fixed size. */ unsigned char pad[JOURNAL_HEADER_SIZE]; } journal_rawheader_t; -/* +/*% * The on-disk representation of the transaction header. * There is one of these at the beginning of each transaction. */ typedef struct { - unsigned char size[4]; /* In bytes, excluding header. */ - unsigned char serial0[4]; /* SOA serial before update. */ - unsigned char serial1[4]; /* SOA serial after update. */ + unsigned char size[4]; /*%< In bytes, excluding header. */ + unsigned char serial0[4]; /*%< SOA serial before update. */ + unsigned char serial1[4]; /*%< SOA serial after update. */ } journal_rawxhdr_t; -/* +/*% * The on-disk representation of the RR header. * There is one of these at the beginning of each RR. */ typedef struct { - unsigned char size[4]; /* In bytes, excluding header. */ + unsigned char size[4]; /*%< In bytes, excluding header. */ } journal_rawrrhdr_t; -/* +/*% * The in-core representation of the journal header. */ typedef struct { @@ -254,7 +252,7 @@ typedef struct { isc_uint32_t index_size; } journal_header_t; -/* +/*% * The in-core representation of the transaction header. */ @@ -264,7 +262,7 @@ typedef struct { isc_uint32_t serial1; } journal_xhdr_t; -/* +/*% * The in-core representation of the RR header. */ typedef struct { @@ -272,7 +270,7 @@ typedef struct { } journal_rrhdr_t; -/* +/*% * Initial contents to store in the header of a newly created * journal file. * @@ -296,40 +294,38 @@ typedef enum { } journal_state_t; struct dns_journal { - unsigned int magic; /* JOUR */ - isc_mem_t *mctx; /* Memory context */ + unsigned int magic; /*%< JOUR */ + isc_mem_t *mctx; /*%< Memory context */ journal_state_t state; - const char *filename; /* Journal file name */ - FILE * fp; /* File handle */ - isc_offset_t offset; /* Current file offset */ - journal_header_t header; /* In-core journal header */ - unsigned char *rawindex; /* In-core buffer for journal - index in on-disk format */ - journal_pos_t *index; /* In-core journal index */ + const char *filename; /*%< Journal file name */ + FILE * fp; /*%< File handle */ + isc_offset_t offset; /*%< Current file offset */ + journal_header_t header; /*%< In-core journal header */ + unsigned char *rawindex; /*%< In-core buffer for journal index in on-disk format */ + journal_pos_t *index; /*%< In-core journal index */ - /* Current transaction state (when writing). */ + /*% Current transaction state (when writing). */ struct { - unsigned int n_soa; /* Number of SOAs seen */ - journal_pos_t pos[2]; /* Begin/end position */ + unsigned int n_soa; /*%< Number of SOAs seen */ + journal_pos_t pos[2]; /*%< Begin/end position */ } x; - /* Iteration state (when reading). */ + /*% Iteration state (when reading). */ struct { /* These define the part of the journal we iterate over. */ - journal_pos_t bpos; /* Position before first, */ - journal_pos_t epos; /* and after last - transaction */ + journal_pos_t bpos; /*%< Position before first, */ + journal_pos_t epos; /*%< and after last transaction */ /* The rest is iterator state. */ - isc_uint32_t current_serial; /* Current SOA serial */ - isc_buffer_t source; /* Data from disk */ - isc_buffer_t target; /* Data from _fromwire check */ - dns_decompress_t dctx; /* Dummy decompression ctx */ - dns_name_t name; /* Current domain name */ - dns_rdata_t rdata; /* Current rdata */ - isc_uint32_t ttl; /* Current TTL */ - unsigned int xsize; /* Size of transaction data */ - unsigned int xpos; /* Current position in it */ - isc_result_t result; /* Result of last call */ + isc_uint32_t current_serial; /*%< Current SOA serial */ + isc_buffer_t source; /*%< Data from disk */ + isc_buffer_t target; /*%< Data from _fromwire check */ + dns_decompress_t dctx; /*%< Dummy decompression ctx */ + dns_name_t name; /*%< Current domain name */ + dns_rdata_t rdata; /*%< Current rdata */ + isc_uint32_t ttl; /*%< Current TTL */ + unsigned int xsize; /*%< Size of transaction data */ + unsigned int xpos; /*%< Current position in it */ + isc_result_t result; /*%< Result of last call */ } it; }; diff --git a/lib/dns/key.c b/lib/dns/key.c index 3f218bba7c..323709b7f1 100644 --- a/lib/dns/key.c +++ b/lib/dns/key.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: key.c,v 1.1 2004/12/09 01:41:03 marka Exp $ */ +/* $Id: key.c,v 1.2 2005/04/27 04:56:47 sra Exp $ */ #include @@ -124,3 +124,5 @@ dst_key_isnullkey(const dst_key_t *key) { return (ISC_FALSE); return (ISC_TRUE); } + +/*! \file */ diff --git a/lib/dns/keytable.c b/lib/dns/keytable.c index 2af62f8a3d..c05222a71a 100644 --- a/lib/dns/keytable.c +++ b/lib/dns/keytable.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: keytable.c,v 1.28 2004/03/05 05:09:20 marka Exp $ */ +/* $Id: keytable.c,v 1.29 2005/04/27 04:56:47 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/lib.c b/lib/dns/lib.c index 9a7c9bdb2c..4a6d323436 100644 --- a/lib/dns/lib.c +++ b/lib/dns/lib.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lib.c,v 1.11 2004/03/05 05:09:20 marka Exp $ */ +/* $Id: lib.c,v 1.12 2005/04/27 04:56:47 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/log.c b/lib/dns/log.c index 0ce419f18c..94f573ab15 100644 --- a/lib/dns/log.c +++ b/lib/dns/log.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: log.c,v 1.37 2004/12/21 10:45:16 jinmei Exp $ */ +/* $Id: log.c,v 1.38 2005/04/27 04:56:47 sra Exp $ */ + +/*! \file */ /* Principal Authors: DCL */ @@ -25,7 +27,7 @@ #include -/* +/*% * When adding a new category, be sure to add the appropriate * #define to . */ @@ -44,7 +46,7 @@ LIBDNS_EXTERNAL_DATA isc_logcategory_t dns_categories[] = { { NULL, 0 } }; -/* +/*% * When adding a new module, be sure to add the appropriate * #define to . */ diff --git a/lib/dns/lookup.c b/lib/dns/lookup.c index 3a994b3896..690d286706 100644 --- a/lib/dns/lookup.c +++ b/lib/dns/lookup.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lookup.c,v 1.15 2004/04/15 01:58:24 marka Exp $ */ +/* $Id: lookup.c,v 1.16 2005/04/27 04:56:47 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/master.c b/lib/dns/master.c index be86774871..6ce43f46d9 100644 --- a/lib/dns/master.c +++ b/lib/dns/master.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: master.c,v 1.151 2005/01/10 23:43:22 marka Exp $ */ +/* $Id: master.c,v 1.152 2005/04/27 04:56:47 sra Exp $ */ + +/*! \file */ #include @@ -46,33 +48,34 @@ #include #include -/* - * Grow the number of dns_rdatalist_t (RDLSZ) and dns_rdata_t (RDSZ) structures +/*! + * Grow the number of dns_rdatalist_t (#RDLSZ) and dns_rdata_t (#RDSZ) structures * by these sizes when we need to. * - * RDLSZ reflects the number of different types with the same name expected. + */ +/*% RDLSZ reflects the number of different types with the same name expected. */ +#define RDLSZ 32 +/*% * RDSZ reflects the number of rdata expected at a give name that can fit into * 64k. */ - -#define RDLSZ 32 #define RDSZ 512 #define NBUFS 4 #define MAXWIRESZ 255 -/* +/*% * Target buffer size and minimum target size. * MINTSIZ must be big enough to hold the largest rdata record. - * + * \brief * TSIZ >= MINTSIZ */ #define TSIZ (128*1024) -/* +/*% * max message size - header - root - type - class - ttl - rdlen */ #define MINTSIZ (65535 - 12 - 1 - 2 - 2 - 4 - 2) -/* +/*% * Size for tokens in the presentation format, * The largest tokens are the base64 blocks in KEY and CERT records, * Largest key allowed is about 1372 bytes but @@ -87,7 +90,7 @@ typedef ISC_LIST(dns_rdatalist_t) rdatalist_head_t; typedef struct dns_incctx dns_incctx_t; -/* +/*% * Master file load state. */ @@ -111,9 +114,9 @@ struct dns_loadctx { isc_uint32_t default_ttl; dns_rdataclass_t zclass; dns_fixedname_t fixed_top; - dns_name_t *top; /* top of zone */ + dns_name_t *top; /*%< top of zone */ /* Which fixed buffers we are using? */ - unsigned int loop_cnt; /* records per quantum, + unsigned int loop_cnt; /*% records per quantum, * 0 => all. */ isc_boolean_t canceled; isc_mutex_t lock; @@ -1533,7 +1536,7 @@ load(dns_loadctx_t *lctx) { current_has_delegation = ISC_TRUE; /* - * RFC 1123: MD and MF are not allowed to be loaded from + * RFC1123: MD and MF are not allowed to be loaded from * master files. */ if ((lctx->options & DNS_MASTER_ZONE) != 0 && @@ -1711,7 +1714,7 @@ load(dns_loadctx_t *lctx) { } else if (!explicit_ttl && lctx->warn_1035) { (*callbacks->warn)(callbacks, "%s:%lu: " - "using RFC 1035 TTL semantics", + "using RFC1035 TTL semantics", source, line); lctx->warn_1035 = ISC_FALSE; } diff --git a/lib/dns/masterdump.c b/lib/dns/masterdump.c index 6309b025d0..110472e0a8 100644 --- a/lib/dns/masterdump.c +++ b/lib/dns/masterdump.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: masterdump.c,v 1.75 2004/08/28 06:16:56 marka Exp $ */ +/* $Id: masterdump.c,v 1.76 2005/04/27 04:56:48 sra Exp $ */ + +/*! \file */ #include @@ -65,7 +67,7 @@ struct dns_master_style { unsigned int tab_width; }; -/* +/*% * The maximum length of the newline+indentation that is output * when inserting a line break in an RR. This effectively puts an * upper limits on the value of "rdata_column", because if it is @@ -73,7 +75,7 @@ struct dns_master_style { */ #define DNS_TOTEXT_LINEBREAK_MAXLEN 100 -/* +/*% * Context structure for a masterfile dump in progress. */ typedef struct dns_totext_ctx { @@ -134,7 +136,7 @@ dns_master_style_simple = { 24, 32, 32, 40, 80, 8 }; -/* +/*% * A style suitable for dns_rdataset_totext(). */ LIBDNS_EXTERNAL_DATA const dns_master_style_t @@ -175,7 +177,7 @@ struct dns_dumpctx { #define NXDOMAIN(x) (((x)->attributes & DNS_RDATASETATTR_NXDOMAIN) != 0) -/* +/*% * Output tabs and spaces to go from column '*current' to * column 'to', and update '*current' to reflect the new * current column. diff --git a/lib/dns/message.c b/lib/dns/message.c index c7ed7ebc16..997cb16948 100644 --- a/lib/dns/message.c +++ b/lib/dns/message.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: message.c,v 1.225 2005/03/16 00:55:17 marka Exp $ */ +/* $Id: message.c,v 1.226 2005/04/27 04:56:48 sra Exp $ */ + +/*! \file */ /*** *** Imports @@ -63,7 +65,7 @@ #define VALID_PSEUDOSECTION(s) (((s) >= DNS_PSEUDOSECTION_ANY) \ && ((s) < DNS_PSEUDOSECTION_MAX)) -/* +/*% * This is the size of each individual scratchpad buffer, and the numbers * of various block allocations used within the server. * XXXMLG These should come from a config setting. @@ -75,7 +77,7 @@ #define RDATALIST_COUNT 8 #define RDATASET_COUNT RDATALIST_COUNT -/* +/*% * Text representation of the different items, for message_totext * functions. */ @@ -133,7 +135,7 @@ static const char *rcodetext[] = { }; -/* +/*% * "helper" type, which consists of a block of some type, and is linkable. * For it to work, sizeof(dns_msgblock_t) must be a multiple of the pointer * size, or the allocated elements will not be alligned correctly. @@ -1417,7 +1419,7 @@ getsection(isc_buffer_t *source, dns_message_t *msg, dns_decompress_t *dctx, /* * Minimize TTLs. * - * Section 5.2 of RFC 2181 says we should drop + * Section 5.2 of RFC2181 says we should drop * nonauthoritative rrsets where the TTLs differ, but we * currently treat them the as if they were authoritative and * minimize them. diff --git a/lib/dns/name.c b/lib/dns/name.c index e95189de97..7566a940e2 100644 --- a/lib/dns/name.c +++ b/lib/dns/name.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: name.c,v 1.149 2005/03/04 02:56:21 marka Exp $ */ +/* $Id: name.c,v 1.150 2005/04/27 04:56:48 sra Exp $ */ + +/*! \file */ #include @@ -122,7 +124,7 @@ static unsigned char maptolower[] = { set_offsets(name, var, NULL); \ } -/* +/*% * Note: If additional attributes are added that should not be set for * empty names, MAKE_EMPTY() must be changed so it clears them. */ @@ -134,7 +136,7 @@ do { \ name->attributes &= ~DNS_NAMEATTR_ABSOLUTE; \ } while (0); -/* +/*% * A name is "bindable" if it can be set to point to a new value, i.e. * name->ndata and name->length may be changed. */ @@ -142,7 +144,7 @@ do { \ ((name->attributes & (DNS_NAMEATTR_READONLY|DNS_NAMEATTR_DYNAMIC)) \ == 0) -/* +/*% * Note that the name data must be a char array, not a string * literal, to avoid compiler warnings about discarding * the const attribute of a string. diff --git a/lib/dns/ncache.c b/lib/dns/ncache.c index 5bec301b95..4a21d67c82 100644 --- a/lib/dns/ncache.c +++ b/lib/dns/ncache.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ncache.c,v 1.37 2004/12/21 10:45:17 jinmei Exp $ */ +/* $Id: ncache.c,v 1.38 2005/04/27 04:56:48 sra Exp $ */ + +/*! \file */ #include @@ -184,7 +186,7 @@ dns_ncache_add(dns_message_t *message, dns_db_t *cache, dns_dbnode_t *node, * * We trust that the caller wants negative caching, so this * means we have a "type 3 nxdomain" or "type 3 nodata" - * response (see RFC 2308 for details). + * response (see RFC2308 for details). * * We will now build a suitable negative cache rdataset that * will cause zero bytes to be emitted when converted to @@ -208,7 +210,7 @@ dns_ncache_add(dns_message_t *message, dns_db_t *cache, dns_dbnode_t *node, isc_buffer_putuint16(&buffer, 0); isc_buffer_putuint16(&buffer, 0); /* - * RFC 2308, section 5, says that negative answers without + * RFC2308, section 5, says that negative answers without * SOAs should not be cached. */ ttl = 0; diff --git a/lib/dns/nsec.c b/lib/dns/nsec.c index 93496e24ce..cd419e686d 100644 --- a/lib/dns/nsec.c +++ b/lib/dns/nsec.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: nsec.c,v 1.5 2004/03/05 05:09:21 marka Exp $ */ +/* $Id: nsec.c,v 1.6 2005/04/27 04:56:48 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/openssl_link.c b/lib/dns/openssl_link.c index 10f94ebb28..c0cb4a20b3 100644 --- a/lib/dns/openssl_link.c +++ b/lib/dns/openssl_link.c @@ -18,7 +18,7 @@ /* * Principal Author: Brian Wellington - * $Id: openssl_link.c,v 1.1 2004/12/09 01:41:03 marka Exp $ + * $Id: openssl_link.c,v 1.2 2005/04/27 04:56:48 sra Exp $ */ #ifdef OPENSSL @@ -217,3 +217,4 @@ dst__openssl_toresult(isc_result_t fallback) { EMPTY_TRANSLATION_UNIT #endif /* OPENSSL */ +/*! \file */ diff --git a/lib/dns/openssldh_link.c b/lib/dns/openssldh_link.c index 6aca209c0b..a50a795b2a 100644 --- a/lib/dns/openssldh_link.c +++ b/lib/dns/openssldh_link.c @@ -18,7 +18,7 @@ /* * Principal Author: Brian Wellington - * $Id: openssldh_link.c,v 1.1 2004/12/09 01:41:03 marka Exp $ + * $Id: openssldh_link.c,v 1.2 2005/04/27 04:56:48 sra Exp $ */ #ifdef OPENSSL @@ -564,11 +564,11 @@ openssldh_cleanup(void) { } static dst_func_t openssldh_functions = { - NULL, /* createctx */ - NULL, /* destroyctx */ - NULL, /* adddata */ - NULL, /* openssldh_sign */ - NULL, /* openssldh_verify */ + NULL, /*%< createctx */ + NULL, /*%< destroyctx */ + NULL, /*%< adddata */ + NULL, /*%< openssldh_sign */ + NULL, /*%< openssldh_verify */ openssldh_computesecret, openssldh_compare, openssldh_paramcompare, @@ -606,3 +606,4 @@ dst__openssldh_init(dst_func_t **funcp) { EMPTY_TRANSLATION_UNIT #endif /* OPENSSL */ +/*! \file */ diff --git a/lib/dns/openssldsa_link.c b/lib/dns/openssldsa_link.c index 1079d329f2..4b6dce3e3e 100644 --- a/lib/dns/openssldsa_link.c +++ b/lib/dns/openssldsa_link.c @@ -16,7 +16,7 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: openssldsa_link.c,v 1.1 2004/12/09 01:41:04 marka Exp $ */ +/* $Id: openssldsa_link.c,v 1.2 2005/04/27 04:56:49 sra Exp $ */ #ifdef OPENSSL @@ -124,7 +124,7 @@ openssldsa_verify(dst_context_t *dctx, const isc_region_t *sig) { if (sig->length < 2 * ISC_SHA1_DIGESTLENGTH + 1) return (DST_R_VERIFYFAILURE); - cp++; /* Skip T */ + cp++; /*%< Skip T */ dsasig = DSA_SIG_new(); dsasig->r = BN_bin2bn(cp, ISC_SHA1_DIGESTLENGTH, NULL); cp += ISC_SHA1_DIGESTLENGTH; @@ -413,9 +413,9 @@ static dst_func_t openssldsa_functions = { openssldsa_adddata, openssldsa_sign, openssldsa_verify, - NULL, /* computesecret */ + NULL, /*%< computesecret */ openssldsa_compare, - NULL, /* paramcompare */ + NULL, /*%< paramcompare */ openssldsa_generate, openssldsa_isprivate, openssldsa_destroy, @@ -423,7 +423,7 @@ static dst_func_t openssldsa_functions = { openssldsa_fromdns, openssldsa_tofile, openssldsa_parse, - NULL, /* cleanup */ + NULL, /*%< cleanup */ }; isc_result_t @@ -441,3 +441,4 @@ dst__openssldsa_init(dst_func_t **funcp) { EMPTY_TRANSLATION_UNIT #endif /* OPENSSL */ +/*! \file */ diff --git a/lib/dns/opensslrsa_link.c b/lib/dns/opensslrsa_link.c index 22274819be..b81dab8a6c 100644 --- a/lib/dns/opensslrsa_link.c +++ b/lib/dns/opensslrsa_link.c @@ -17,7 +17,7 @@ /* * Principal Author: Brian Wellington - * $Id: opensslrsa_link.c,v 1.1 2004/12/09 01:41:04 marka Exp $ + * $Id: opensslrsa_link.c,v 1.2 2005/04/27 04:56:49 sra Exp $ */ #ifdef OPENSSL @@ -306,7 +306,7 @@ opensslrsa_todns(const dst_key_t *key, isc_buffer_t *data) { e_bytes = BN_num_bytes(rsa->e); mod_bytes = BN_num_bytes(rsa->n); - if (e_bytes < 256) { /* key exponent is <= 2040 bits */ + if (e_bytes < 256) { /*%< key exponent is <= 2040 bits */ if (r.length < 1) return (ISC_R_NOSPACE); isc_buffer_putuint8(data, (isc_uint8_t) e_bytes); @@ -537,9 +537,9 @@ static dst_func_t opensslrsa_functions = { opensslrsa_adddata, opensslrsa_sign, opensslrsa_verify, - NULL, /* computesecret */ + NULL, /*%< computesecret */ opensslrsa_compare, - NULL, /* paramcompare */ + NULL, /*%< paramcompare */ opensslrsa_generate, opensslrsa_isprivate, opensslrsa_destroy, @@ -547,7 +547,7 @@ static dst_func_t opensslrsa_functions = { opensslrsa_fromdns, opensslrsa_tofile, opensslrsa_parse, - NULL, /* cleanup */ + NULL, /*%< cleanup */ }; isc_result_t @@ -565,3 +565,4 @@ dst__opensslrsa_init(dst_func_t **funcp) { EMPTY_TRANSLATION_UNIT #endif /* OPENSSL */ +/*! \file */ diff --git a/lib/dns/order.c b/lib/dns/order.c index 3f73eddc20..9439e7b6d5 100644 --- a/lib/dns/order.c +++ b/lib/dns/order.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: order.c,v 1.5 2004/03/05 05:09:22 marka Exp $ */ +/* $Id: order.c,v 1.6 2005/04/27 04:56:49 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/peer.c b/lib/dns/peer.c index 0badd73738..081398168a 100644 --- a/lib/dns/peer.c +++ b/lib/dns/peer.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: peer.c,v 1.21 2005/01/17 23:58:32 marka Exp $ */ +/* $Id: peer.c,v 1.22 2005/04/27 04:56:49 sra Exp $ */ + +/*! \file */ #include @@ -29,7 +31,7 @@ #include #include -/* +/*% * Bit positions in the dns_peer_t structure flags field */ #define BOGUS_BIT 0 diff --git a/lib/dns/portlist.c b/lib/dns/portlist.c index 0906a06720..31083acda4 100644 --- a/lib/dns/portlist.c +++ b/lib/dns/portlist.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: portlist.c,v 1.6 2004/03/18 02:58:03 marka Exp $ */ +/* $Id: portlist.c,v 1.7 2005/04/27 04:56:49 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/rbt.c b/lib/dns/rbt.c index 86f4d303e3..d882e739d9 100644 --- a/lib/dns/rbt.c +++ b/lib/dns/rbt.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rbt.c,v 1.130 2004/10/25 01:27:54 marka Exp $ */ +/* $Id: rbt.c,v 1.131 2005/04/27 04:56:49 sra Exp $ */ + +/*! \file */ /* Principal Authors: DCL */ @@ -27,7 +29,7 @@ #include #include -/* +/*% * This define is so dns/name.h (included by dns/fixedname.h) uses more * efficient macro calls instead of functions for a few operations. */ @@ -52,7 +54,7 @@ #ifdef RBT_MEM_TEST #undef RBT_HASH_SIZE -#define RBT_HASH_SIZE 2 /* To give the reallocation code a workout. */ +#define RBT_HASH_SIZE 2 /*%< To give the reallocation code a workout. */ #endif struct dns_rbt { @@ -69,7 +71,7 @@ struct dns_rbt { #define RED 0 #define BLACK 1 -/* +/*% * Elements of the rbtnode structure. */ #define PARENT(node) ((node)->parent) @@ -87,7 +89,7 @@ struct dns_rbt { #define IS_ROOT(node) ISC_TF((node)->is_root == 1) #define FINDCALLBACK(node) ISC_TF((node)->find_callback == 1) -/* +/*% * Structure elements from the rbtdb.c, not * used as part of the rbt.c algorithms. */ @@ -96,7 +98,7 @@ struct dns_rbt { #define LOCKNUM(node) ((node)->locknum) #define REFS(node) ((node)->references) -/* +/*% * The variable length stuff stored after the node. */ #define NAME(node) ((unsigned char *)((node) + 1)) @@ -105,7 +107,7 @@ struct dns_rbt { #define NODE_SIZE(node) (sizeof(*node) + \ NAMELEN(node) + OFFSETLEN(node) + PADBYTES(node)) -/* +/*% * Color management. */ #define IS_RED(node) ((node) != NULL && (node)->color == RED) @@ -113,7 +115,7 @@ struct dns_rbt { #define MAKE_RED(node) ((node)->color = RED) #define MAKE_BLACK(node) ((node)->color = BLACK) -/* +/*% * Chain management. * * The "ancestors" member of chains were removed, with their job now @@ -123,7 +125,7 @@ struct dns_rbt { #define ADD_LEVEL(chain, node) \ (chain)->levels[(chain)->level_count++] = (node) -/* +/*% * The following macros directly access normally private name variables. * These macros are used to avoid a lot of function calls in the critical * path of the tree traversal code. diff --git a/lib/dns/rbtdb.c b/lib/dns/rbtdb.c index a8a4ce65e3..3a96203c9e 100644 --- a/lib/dns/rbtdb.c +++ b/lib/dns/rbtdb.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rbtdb.c,v 1.205 2005/04/01 07:00:34 marka Exp $ */ +/* $Id: rbtdb.c,v 1.206 2005/04/27 04:56:49 sra Exp $ */ + +/*! \file */ /* * Principal Author: Bob Halley @@ -63,7 +65,7 @@ #define RBTDB_MAGIC ISC_MAGIC('R', 'B', 'D', '4') #endif -/* +/*% * Note that "impmagic" is not the first four bytes of the struct, so * ISC_MAGIC_VALID cannot be used. */ @@ -72,7 +74,7 @@ #ifdef DNS_RBTDB_VERSION64 typedef isc_uint64_t rbtdb_serial_t; -/* +/*% * Make casting easier in symbolic debuggers by using different names * for the 64 bit version. */ @@ -109,7 +111,7 @@ struct noqname { typedef struct acachectl acachectl_t; typedef struct rdatasetheader { - /* + /*% * Locked by the owning node's lock. */ rbtdb_serial_t serial; @@ -118,13 +120,13 @@ typedef struct rdatasetheader { isc_uint16_t attributes; dns_trust_t trust; struct noqname *noqname; - /* + /*%< * We don't use the LIST macros, because the LIST structure has * both head and tail pointers, and is doubly linked. */ struct rdatasetheader *next; - /* + /*%< * If this is the top header for an rdataset, 'next' points * to the top header for the next rdataset (i.e., the next type). * Otherwise, it points up to the header whose down pointer points @@ -132,13 +134,13 @@ typedef struct rdatasetheader { */ struct rdatasetheader *down; - /* + /*%< * Points to the header for the next older version of * this rdataset. */ isc_uint32_t count; - /* + /*%< * Monotonously increased every time this rdataset is bound so that * it is used as the base of the starting point in DNS responses * when the "cyclic" rrset-order is required. Since the ordering @@ -190,7 +192,7 @@ struct acachectl { #define NXDOMAIN(header) \ (((header)->attributes & RDATASET_ATTR_NXDOMAIN) != 0) -#define DEFAULT_NODE_LOCK_COUNT 7 /* Should be prime. */ +#define DEFAULT_NODE_LOCK_COUNT 7 /*%< Should be prime. */ typedef struct { isc_mutex_t lock; @@ -250,7 +252,7 @@ typedef struct { #define RBTDB_ATTR_LOADED 0x01 #define RBTDB_ATTR_LOADING 0x02 -/* +/*% * Search Context */ typedef struct { @@ -269,7 +271,7 @@ typedef struct { isc_stdtime_t now; } rbtdb_search_t; -/* +/*% * Load Context */ typedef struct { @@ -2265,7 +2267,7 @@ zone_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version, /* * Certain DNSSEC types are not subject to CNAME matching - * (RFC 2535, section 2.3.5). + * (RFC2535, section 2.3.5). * * We don't check for RRSIG, because we don't store RRSIG records * directly. @@ -2998,7 +3000,7 @@ cache_find(dns_db_t *db, dns_name_t *name, dns_dbversion_t *version, /* * Certain DNSSEC types are not subject to CNAME matching - * (RFC 2535, section 2.3.5). + * (RFC2535, section 2.3.5). * * We don't check for RRSIG, because we don't store RRSIG records * directly. diff --git a/lib/dns/rbtdb.h b/lib/dns/rbtdb.h index 00a1ca07b1..800b08e0c0 100644 --- a/lib/dns/rbtdb.h +++ b/lib/dns/rbtdb.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rbtdb.h,v 1.14 2004/03/05 05:09:22 marka Exp $ */ +/* $Id: rbtdb.h,v 1.15 2005/04/27 04:56:50 sra Exp $ */ #ifndef DNS_RBTDB_H #define DNS_RBTDB_H 1 @@ -27,7 +27,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * DNS Red-Black Tree DB Implementation */ diff --git a/lib/dns/rbtdb64.c b/lib/dns/rbtdb64.c index cc122e376e..24ac05f22c 100644 --- a/lib/dns/rbtdb64.c +++ b/lib/dns/rbtdb64.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rbtdb64.c,v 1.7 2004/03/05 05:09:22 marka Exp $ */ +/* $Id: rbtdb64.c,v 1.8 2005/04/27 04:56:50 sra Exp $ */ + +/*! \file */ #define DNS_RBTDB_VERSION64 1 #include "rbtdb.c" diff --git a/lib/dns/rbtdb64.h b/lib/dns/rbtdb64.h index b3a80692b4..346bb4e0d7 100644 --- a/lib/dns/rbtdb64.h +++ b/lib/dns/rbtdb64.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rbtdb64.h,v 1.13 2004/03/05 05:09:23 marka Exp $ */ +/* $Id: rbtdb64.h,v 1.14 2005/04/27 04:56:50 sra Exp $ */ #ifndef DNS_RBTDB64_H #define DNS_RBTDB64_H 1 @@ -26,7 +26,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * DNS Red-Black Tree DB Implementation with 64-bit version numbers */ diff --git a/lib/dns/rdata.c b/lib/dns/rdata.c index 1b82a50c68..64b630942f 100644 --- a/lib/dns/rdata.c +++ b/lib/dns/rdata.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdata.c,v 1.187 2005/03/20 22:32:57 marka Exp $ */ +/* $Id: rdata.c,v 1.188 2005/04/27 04:56:50 sra Exp $ */ + +/*! \file */ #include #include @@ -100,16 +102,16 @@ #define ARGS_CHECKNAMES dns_rdata_t *rdata, dns_name_t *owner, dns_name_t *bad -/* +/*% * Context structure for the totext_ functions. * Contains formatting options for rdata-to-text * conversion. */ typedef struct dns_rdata_textctx { - dns_name_t *origin; /* Current origin, or NULL. */ - unsigned int flags; /* DNS_STYLEFLAG_* */ - unsigned int width; /* Width of rdata column. */ - const char *linebreak; /* Line break string. */ + dns_name_t *origin; /*%< Current origin, or NULL. */ + unsigned int flags; /*%< DNS_STYLEFLAG_* */ + unsigned int width; /*%< Width of rdata column. */ + const char *linebreak; /*%< Line break string. */ } dns_rdata_textctx_t; static isc_result_t diff --git a/lib/dns/rdata/any_255/tsig_250.h b/lib/dns/rdata/any_255/tsig_250.h index 99bfc54fe7..c6664caf2c 100644 --- a/lib/dns/rdata/any_255/tsig_250.h +++ b/lib/dns/rdata/any_255/tsig_250.h @@ -15,13 +15,12 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: tsig_250.h,v 1.21 2004/03/05 05:10:07 marka Exp $ */ - -/* RFC 2845 */ +/* $Id: tsig_250.h,v 1.22 2005/04/27 04:57:02 sra Exp $ */ #ifndef ANY_255_TSIG_250_H #define ANY_255_TSIG_250_H 1 +/*% RFC2845 */ typedef struct dns_rdata_any_tsig { dns_rdatacommon_t common; isc_mem_t * mctx; diff --git a/lib/dns/rdata/generic/afsdb_18.c b/lib/dns/rdata/generic/afsdb_18.c index c03c33d771..7778ab7c76 100644 --- a/lib/dns/rdata/generic/afsdb_18.c +++ b/lib/dns/rdata/generic/afsdb_18.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: afsdb_18.c,v 1.43 2004/03/05 05:10:09 marka Exp $ */ +/* $Id: afsdb_18.c,v 1.44 2005/04/27 04:57:02 sra Exp $ */ /* Reviewed: Wed Mar 15 14:59:00 PST 2000 by explorer */ -/* RFC 1183 */ +/* RFC1183 */ #ifndef RDATA_GENERIC_AFSDB_18_C #define RDATA_GENERIC_AFSDB_18_C diff --git a/lib/dns/rdata/generic/afsdb_18.h b/lib/dns/rdata/generic/afsdb_18.h index a593d83820..a3d9d285d4 100644 --- a/lib/dns/rdata/generic/afsdb_18.h +++ b/lib/dns/rdata/generic/afsdb_18.h @@ -18,9 +18,10 @@ #ifndef GENERIC_AFSDB_18_H #define GENERIC_AFSDB_18_H 1 -/* $Id: afsdb_18.h,v 1.16 2004/03/05 05:10:10 marka Exp $ */ +/* $Id: afsdb_18.h,v 1.17 2005/04/27 04:57:02 sra Exp $ */ -/* RFC 1183 */ +/*! + * \brief Per RFC1183 */ typedef struct dns_rdata_afsdb { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/cert_37.c b/lib/dns/rdata/generic/cert_37.c index 375632acee..624cfddfc3 100644 --- a/lib/dns/rdata/generic/cert_37.c +++ b/lib/dns/rdata/generic/cert_37.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: cert_37.c,v 1.46 2004/03/05 05:10:10 marka Exp $ */ +/* $Id: cert_37.c,v 1.47 2005/04/27 04:57:03 sra Exp $ */ /* Reviewed: Wed Mar 15 21:14:32 EST 2000 by tale */ -/* RFC 2538 */ +/* RFC2538 */ #ifndef RDATA_GENERIC_CERT_37_C #define RDATA_GENERIC_CERT_37_C diff --git a/lib/dns/rdata/generic/cert_37.h b/lib/dns/rdata/generic/cert_37.h index 6b138ed0e9..25f56b9c11 100644 --- a/lib/dns/rdata/generic/cert_37.h +++ b/lib/dns/rdata/generic/cert_37.h @@ -15,12 +15,12 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: cert_37.h,v 1.16 2004/03/05 05:10:10 marka Exp $ */ +/* $Id: cert_37.h,v 1.17 2005/04/27 04:57:03 sra Exp $ */ -/* RFC 2538 */ #ifndef GENERIC_CERT_37_H #define GENERIC_CERT_37_H 1 +/*% RFC2538 */ typedef struct dns_rdata_cert { dns_rdatacommon_t common; isc_mem_t *mctx; diff --git a/lib/dns/rdata/generic/dname_39.h b/lib/dns/rdata/generic/dname_39.h index ef12533887..cc0f74f3ef 100644 --- a/lib/dns/rdata/generic/dname_39.h +++ b/lib/dns/rdata/generic/dname_39.h @@ -18,9 +18,10 @@ #ifndef GENERIC_DNAME_39_H #define GENERIC_DNAME_39_H 1 -/* $Id: dname_39.h,v 1.17 2004/03/05 05:10:11 marka Exp $ */ +/* $Id: dname_39.h,v 1.18 2005/04/27 04:57:03 sra Exp $ */ -/* RFC2672 */ +/*! + * \brief per RFC2672 */ typedef struct dns_rdata_dname { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/dnskey_48.c b/lib/dns/rdata/generic/dnskey_48.c index 970c4b27c7..691ee2651c 100644 --- a/lib/dns/rdata/generic/dnskey_48.c +++ b/lib/dns/rdata/generic/dnskey_48.c @@ -15,13 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dnskey_48.c,v 1.4 2004/03/05 05:10:11 marka Exp $ */ +/* $Id: dnskey_48.c,v 1.5 2005/04/27 04:57:03 sra Exp $ */ /* * Reviewed: Wed Mar 15 16:47:10 PST 2000 by halley. */ -/* RFC 2535 */ +/* RFC2535 */ #ifndef RDATA_GENERIC_DNSKEY_48_C #define RDATA_GENERIC_DNSKEY_48_C diff --git a/lib/dns/rdata/generic/dnskey_48.h b/lib/dns/rdata/generic/dnskey_48.h index c22b956401..b89e28ada4 100644 --- a/lib/dns/rdata/generic/dnskey_48.h +++ b/lib/dns/rdata/generic/dnskey_48.h @@ -18,9 +18,10 @@ #ifndef GENERIC_DNSKEY_48_H #define GENERIC_DNSKEY_48_H 1 -/* $Id: dnskey_48.h,v 1.3 2004/03/05 05:10:11 marka Exp $ */ +/* $Id: dnskey_48.h,v 1.4 2005/04/27 04:57:03 sra Exp $ */ -/* RFC 2535 */ +/*! + * \brief per RFC2535 */ typedef struct dns_rdata_dnskey { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/ds_43.h b/lib/dns/rdata/generic/ds_43.h index d547c16a6f..6af23aca11 100644 --- a/lib/dns/rdata/generic/ds_43.h +++ b/lib/dns/rdata/generic/ds_43.h @@ -15,12 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ds_43.h,v 1.3 2004/03/05 05:10:11 marka Exp $ */ +/* $Id: ds_43.h,v 1.4 2005/04/27 04:57:03 sra Exp $ */ -/* draft-ietf-dnsext-delegation-signer-05.txt */ #ifndef GENERIC_DS_43_H #define GENERIC_DS_43_H 1 +/*! + * \brief per draft-ietf-dnsext-delegation-signer-05.txt */ typedef struct dns_rdata_ds { dns_rdatacommon_t common; isc_mem_t *mctx; diff --git a/lib/dns/rdata/generic/gpos_27.c b/lib/dns/rdata/generic/gpos_27.c index cfb5ea3c28..edfc567542 100644 --- a/lib/dns/rdata/generic/gpos_27.c +++ b/lib/dns/rdata/generic/gpos_27.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gpos_27.c,v 1.37 2004/03/05 05:10:11 marka Exp $ */ +/* $Id: gpos_27.c,v 1.38 2005/04/27 04:57:03 sra Exp $ */ /* reviewed: Wed Mar 15 16:48:45 PST 2000 by brister */ -/* RFC 1712 */ +/* RFC1712 */ #ifndef RDATA_GENERIC_GPOS_27_C #define RDATA_GENERIC_GPOS_27_C diff --git a/lib/dns/rdata/generic/gpos_27.h b/lib/dns/rdata/generic/gpos_27.h index b3e70b369f..3a50477896 100644 --- a/lib/dns/rdata/generic/gpos_27.h +++ b/lib/dns/rdata/generic/gpos_27.h @@ -18,9 +18,10 @@ #ifndef GENERIC_GPOS_27_H #define GENERIC_GPOS_27_H 1 -/* $Id: gpos_27.h,v 1.13 2004/03/05 05:10:11 marka Exp $ */ +/* $Id: gpos_27.h,v 1.14 2005/04/27 04:57:03 sra Exp $ */ -/* RFC 1712 */ +/*! + * \brief per RFC1712 */ typedef struct dns_rdata_gpos { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/isdn_20.c b/lib/dns/rdata/generic/isdn_20.c index a14c513f17..3173bf446c 100644 --- a/lib/dns/rdata/generic/isdn_20.c +++ b/lib/dns/rdata/generic/isdn_20.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: isdn_20.c,v 1.34 2004/03/05 05:10:12 marka Exp $ */ +/* $Id: isdn_20.c,v 1.35 2005/04/27 04:57:03 sra Exp $ */ /* Reviewed: Wed Mar 15 16:53:11 PST 2000 by bwelling */ -/* RFC 1183 */ +/* RFC1183 */ #ifndef RDATA_GENERIC_ISDN_20_C #define RDATA_GENERIC_ISDN_20_C diff --git a/lib/dns/rdata/generic/isdn_20.h b/lib/dns/rdata/generic/isdn_20.h index 24fa16d131..ed3062efbc 100644 --- a/lib/dns/rdata/generic/isdn_20.h +++ b/lib/dns/rdata/generic/isdn_20.h @@ -18,9 +18,10 @@ #ifndef GENERIC_ISDN_20_H #define GENERIC_ISDN_20_H 1 -/* $Id: isdn_20.h,v 1.14 2004/03/05 05:10:12 marka Exp $ */ +/* $Id: isdn_20.h,v 1.15 2005/04/27 04:57:03 sra Exp $ */ -/* RFC 1183 */ +/*! + * \brief Per RFC1183 */ typedef struct dns_rdata_isdn { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/key_25.c b/lib/dns/rdata/generic/key_25.c index ddf7076bd3..d556a2fc28 100644 --- a/lib/dns/rdata/generic/key_25.c +++ b/lib/dns/rdata/generic/key_25.c @@ -15,13 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: key_25.c,v 1.47 2004/03/05 05:10:12 marka Exp $ */ +/* $Id: key_25.c,v 1.48 2005/04/27 04:57:03 sra Exp $ */ /* * Reviewed: Wed Mar 15 16:47:10 PST 2000 by halley. */ -/* RFC 2535 */ +/* RFC2535 */ #ifndef RDATA_GENERIC_KEY_25_C #define RDATA_GENERIC_KEY_25_C diff --git a/lib/dns/rdata/generic/key_25.h b/lib/dns/rdata/generic/key_25.h index ef93be66e2..889cbd25d7 100644 --- a/lib/dns/rdata/generic/key_25.h +++ b/lib/dns/rdata/generic/key_25.h @@ -18,9 +18,10 @@ #ifndef GENERIC_KEY_25_H #define GENERIC_KEY_25_H 1 -/* $Id: key_25.h,v 1.15 2004/03/05 05:10:12 marka Exp $ */ +/* $Id: key_25.h,v 1.16 2005/04/27 04:57:03 sra Exp $ */ -/* RFC 2535 */ +/*! + * \brief Per RFC2535 */ typedef struct dns_rdata_key_t { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/loc_29.c b/lib/dns/rdata/generic/loc_29.c index 7e0b154328..57baaf2d59 100644 --- a/lib/dns/rdata/generic/loc_29.c +++ b/lib/dns/rdata/generic/loc_29.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: loc_29.c,v 1.41 2004/03/05 05:10:12 marka Exp $ */ +/* $Id: loc_29.c,v 1.42 2005/04/27 04:57:04 sra Exp $ */ /* Reviewed: Wed Mar 15 18:13:09 PST 2000 by explorer */ -/* RFC 1876 */ +/* RFC1876 */ #ifndef RDATA_GENERIC_LOC_29_C #define RDATA_GENERIC_LOC_29_C diff --git a/lib/dns/rdata/generic/loc_29.h b/lib/dns/rdata/generic/loc_29.h index e1c79022a1..ecfee636b0 100644 --- a/lib/dns/rdata/generic/loc_29.h +++ b/lib/dns/rdata/generic/loc_29.h @@ -18,9 +18,10 @@ #ifndef GENERIC_LOC_29_H #define GENERIC_LOC_29_H 1 -/* $Id: loc_29.h,v 1.15 2004/03/05 05:10:13 marka Exp $ */ +/* $Id: loc_29.h,v 1.16 2005/04/27 04:57:04 sra Exp $ */ -/* RFC 1876 */ +/*! + * \brief Per RFC1876 */ typedef struct dns_rdata_loc_0 { isc_uint8_t version; /* must be first and zero */ diff --git a/lib/dns/rdata/generic/mb_7.h b/lib/dns/rdata/generic/mb_7.h index 386e12eea3..c18d8e84e1 100644 --- a/lib/dns/rdata/generic/mb_7.h +++ b/lib/dns/rdata/generic/mb_7.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_MB_7_H #define GENERIC_MB_7_H 1 -/* $Id: mb_7.h,v 1.23 2004/03/05 05:10:13 marka Exp $ */ +/* $Id: mb_7.h,v 1.24 2005/04/27 04:57:04 sra Exp $ */ typedef struct dns_rdata_mb { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/md_3.h b/lib/dns/rdata/generic/md_3.h index 9d8b5c3805..763412fdcb 100644 --- a/lib/dns/rdata/generic/md_3.h +++ b/lib/dns/rdata/generic/md_3.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_MD_3_H #define GENERIC_MD_3_H 1 -/* $Id: md_3.h,v 1.24 2004/03/05 05:10:13 marka Exp $ */ +/* $Id: md_3.h,v 1.25 2005/04/27 04:57:04 sra Exp $ */ typedef struct dns_rdata_md { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/mf_4.h b/lib/dns/rdata/generic/mf_4.h index 0c8f3c1ffd..9a9991d201 100644 --- a/lib/dns/rdata/generic/mf_4.h +++ b/lib/dns/rdata/generic/mf_4.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_MF_4_H #define GENERIC_MF_4_H 1 -/* $Id: mf_4.h,v 1.22 2004/03/05 05:10:14 marka Exp $ */ +/* $Id: mf_4.h,v 1.23 2005/04/27 04:57:04 sra Exp $ */ typedef struct dns_rdata_mf { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/mg_8.h b/lib/dns/rdata/generic/mg_8.h index 1cd9335b07..e8f3ba713f 100644 --- a/lib/dns/rdata/generic/mg_8.h +++ b/lib/dns/rdata/generic/mg_8.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_MG_8_H #define GENERIC_MG_8_H 1 -/* $Id: mg_8.h,v 1.22 2004/03/05 05:10:14 marka Exp $ */ +/* $Id: mg_8.h,v 1.23 2005/04/27 04:57:04 sra Exp $ */ typedef struct dns_rdata_mg { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/minfo_14.h b/lib/dns/rdata/generic/minfo_14.h index 2c7b0cb53e..1021cd7d1b 100644 --- a/lib/dns/rdata/generic/minfo_14.h +++ b/lib/dns/rdata/generic/minfo_14.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_MINFO_14_H #define GENERIC_MINFO_14_H 1 -/* $Id: minfo_14.h,v 1.23 2004/03/05 05:10:15 marka Exp $ */ +/* $Id: minfo_14.h,v 1.24 2005/04/27 04:57:04 sra Exp $ */ typedef struct dns_rdata_minfo { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/mr_9.h b/lib/dns/rdata/generic/mr_9.h index e2658315e8..450e485155 100644 --- a/lib/dns/rdata/generic/mr_9.h +++ b/lib/dns/rdata/generic/mr_9.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_MR_9_H #define GENERIC_MR_9_H 1 -/* $Id: mr_9.h,v 1.22 2004/03/05 05:10:15 marka Exp $ */ +/* $Id: mr_9.h,v 1.23 2005/04/27 04:57:04 sra Exp $ */ typedef struct dns_rdata_mr { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/mx_15.h b/lib/dns/rdata/generic/mx_15.h index 7d265c6af3..d2f37ce42f 100644 --- a/lib/dns/rdata/generic/mx_15.h +++ b/lib/dns/rdata/generic/mx_15.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_MX_15_H #define GENERIC_MX_15_H 1 -/* $Id: mx_15.h,v 1.25 2004/03/05 05:10:15 marka Exp $ */ +/* $Id: mx_15.h,v 1.26 2005/04/27 04:57:04 sra Exp $ */ typedef struct dns_rdata_mx { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/ns_2.h b/lib/dns/rdata/generic/ns_2.h index b676cd31f0..5862d7824d 100644 --- a/lib/dns/rdata/generic/ns_2.h +++ b/lib/dns/rdata/generic/ns_2.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_NS_2_H #define GENERIC_NS_2_H 1 -/* $Id: ns_2.h,v 1.23 2004/03/05 05:10:15 marka Exp $ */ +/* $Id: ns_2.h,v 1.24 2005/04/27 04:57:04 sra Exp $ */ typedef struct dns_rdata_ns { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/nsec_47.h b/lib/dns/rdata/generic/nsec_47.h index f65d27c843..32e945f848 100644 --- a/lib/dns/rdata/generic/nsec_47.h +++ b/lib/dns/rdata/generic/nsec_47.h @@ -18,9 +18,10 @@ #ifndef GENERIC_NSEC_47_H #define GENERIC_NSEC_47_H 1 -/* $Id: nsec_47.h,v 1.4 2004/03/05 05:10:15 marka Exp $ */ +/* $Id: nsec_47.h,v 1.5 2005/04/27 04:57:04 sra Exp $ */ -/* draft-ietf-dnsext-nsec-rdata-01.txt */ +/*! + * \brief Per draft-ietf-dnsext-nsec-rdata-01.txt */ typedef struct dns_rdata_nsec { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/null_10.h b/lib/dns/rdata/generic/null_10.h index 6c74915d86..f2bf5a1dca 100644 --- a/lib/dns/rdata/generic/null_10.h +++ b/lib/dns/rdata/generic/null_10.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_NULL_10_H #define GENERIC_NULL_10_H 1 -/* $Id: null_10.h,v 1.21 2004/03/05 05:10:16 marka Exp $ */ +/* $Id: null_10.h,v 1.22 2005/04/27 04:57:04 sra Exp $ */ typedef struct dns_rdata_null { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/nxt_30.c b/lib/dns/rdata/generic/nxt_30.c index d40dba80f0..7190daf906 100644 --- a/lib/dns/rdata/generic/nxt_30.c +++ b/lib/dns/rdata/generic/nxt_30.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: nxt_30.c,v 1.59 2004/03/05 05:10:16 marka Exp $ */ +/* $Id: nxt_30.c,v 1.60 2005/04/27 04:57:05 sra Exp $ */ /* reviewed: Wed Mar 15 18:21:15 PST 2000 by brister */ -/* RFC 2535 */ +/* RFC2535 */ #ifndef RDATA_GENERIC_NXT_30_C #define RDATA_GENERIC_NXT_30_C diff --git a/lib/dns/rdata/generic/nxt_30.h b/lib/dns/rdata/generic/nxt_30.h index 764d4b7cca..0dc00c3c36 100644 --- a/lib/dns/rdata/generic/nxt_30.h +++ b/lib/dns/rdata/generic/nxt_30.h @@ -18,9 +18,10 @@ #ifndef GENERIC_NXT_30_H #define GENERIC_NXT_30_H 1 -/* $Id: nxt_30.h,v 1.21 2004/03/05 05:10:16 marka Exp $ */ +/* $Id: nxt_30.h,v 1.22 2005/04/27 04:57:05 sra Exp $ */ -/* RFC 2535 */ +/*! + * \brief RFC2535 */ typedef struct dns_rdata_nxt { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/opt_41.c b/lib/dns/rdata/generic/opt_41.c index 35772b79fd..e6e7c61ec0 100644 --- a/lib/dns/rdata/generic/opt_41.c +++ b/lib/dns/rdata/generic/opt_41.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: opt_41.c,v 1.29 2004/03/05 05:10:16 marka Exp $ */ +/* $Id: opt_41.c,v 1.30 2005/04/27 04:57:05 sra Exp $ */ /* Reviewed: Thu Mar 16 14:06:44 PST 2000 by gson */ -/* RFC 2671 */ +/* RFC2671 */ #ifndef RDATA_GENERIC_OPT_41_C #define RDATA_GENERIC_OPT_41_C diff --git a/lib/dns/rdata/generic/opt_41.h b/lib/dns/rdata/generic/opt_41.h index 9793ad39ec..d42ebb0c64 100644 --- a/lib/dns/rdata/generic/opt_41.h +++ b/lib/dns/rdata/generic/opt_41.h @@ -18,9 +18,10 @@ #ifndef GENERIC_OPT_41_H #define GENERIC_OPT_41_H 1 -/* $Id: opt_41.h,v 1.14 2004/03/05 05:10:17 marka Exp $ */ +/* $Id: opt_41.h,v 1.15 2005/04/27 04:57:05 sra Exp $ */ -/* RFC 2671 */ +/*! + * \brief Per RFC2671 */ typedef struct dns_rdata_opt_opcode { isc_uint16_t opcode; diff --git a/lib/dns/rdata/generic/proforma.h b/lib/dns/rdata/generic/proforma.h index 1afa9f5952..cc4be3e6b1 100644 --- a/lib/dns/rdata/generic/proforma.h +++ b/lib/dns/rdata/generic/proforma.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_PROFORMA_H #define GENERIC_PROFORMA_H 1 -/* $Id: proforma.h,v 1.19 2004/03/05 05:10:17 marka Exp $ */ +/* $Id: proforma.h,v 1.20 2005/04/27 04:57:05 sra Exp $ */ typedef struct dns_rdata_# { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/ptr_12.h b/lib/dns/rdata/generic/ptr_12.h index 25595e615c..6ae1c73533 100644 --- a/lib/dns/rdata/generic/ptr_12.h +++ b/lib/dns/rdata/generic/ptr_12.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_PTR_12_H #define GENERIC_PTR_12_H 1 -/* $Id: ptr_12.h,v 1.23 2004/03/05 05:10:17 marka Exp $ */ +/* $Id: ptr_12.h,v 1.24 2005/04/27 04:57:05 sra Exp $ */ typedef struct dns_rdata_ptr { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/rp_17.c b/lib/dns/rdata/generic/rp_17.c index b5edb8d179..077981e37e 100644 --- a/lib/dns/rdata/generic/rp_17.c +++ b/lib/dns/rdata/generic/rp_17.c @@ -15,9 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rp_17.c,v 1.38 2004/03/05 05:10:17 marka Exp $ */ +/* $Id: rp_17.c,v 1.39 2005/04/27 04:57:05 sra Exp $ */ -/* RFC 1183 */ +/* RFC1183 */ #ifndef RDATA_GENERIC_RP_17_C #define RDATA_GENERIC_RP_17_C diff --git a/lib/dns/rdata/generic/rp_17.h b/lib/dns/rdata/generic/rp_17.h index 011a8288e1..2124c64bcc 100644 --- a/lib/dns/rdata/generic/rp_17.h +++ b/lib/dns/rdata/generic/rp_17.h @@ -18,9 +18,10 @@ #ifndef GENERIC_RP_17_H #define GENERIC_RP_17_H 1 -/* $Id: rp_17.h,v 1.17 2004/03/05 05:10:17 marka Exp $ */ +/* $Id: rp_17.h,v 1.18 2005/04/27 04:57:05 sra Exp $ */ -/* RFC 1183 */ +/*! + * \brief Per RFC1183 */ typedef struct dns_rdata_rp { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/rrsig_46.c b/lib/dns/rdata/generic/rrsig_46.c index 16eb610442..57aa8b76bc 100644 --- a/lib/dns/rdata/generic/rrsig_46.c +++ b/lib/dns/rdata/generic/rrsig_46.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rrsig_46.c,v 1.6 2004/06/24 00:43:15 marka Exp $ */ +/* $Id: rrsig_46.c,v 1.7 2005/04/27 04:57:05 sra Exp $ */ /* Reviewed: Fri Mar 17 09:05:02 PST 2000 by gson */ -/* RFC 2535 */ +/* RFC2535 */ #ifndef RDATA_GENERIC_RRSIG_46_C #define RDATA_GENERIC_RRSIG_46_C diff --git a/lib/dns/rdata/generic/rrsig_46.h b/lib/dns/rdata/generic/rrsig_46.h index 210fca77df..2f67e26bdf 100644 --- a/lib/dns/rdata/generic/rrsig_46.h +++ b/lib/dns/rdata/generic/rrsig_46.h @@ -18,9 +18,10 @@ #ifndef GENERIC_DNSSIG_46_H #define GENERIC_DNSSIG_46_H 1 -/* $Id: rrsig_46.h,v 1.3 2004/03/05 05:10:17 marka Exp $ */ +/* $Id: rrsig_46.h,v 1.4 2005/04/27 04:57:05 sra Exp $ */ -/* RFC 2535 */ +/*! + * \brief Per RFC2535 */ typedef struct dns_rdata_rrsig { dns_rdatacommon_t common; isc_mem_t * mctx; diff --git a/lib/dns/rdata/generic/rt_21.c b/lib/dns/rdata/generic/rt_21.c index 514c4327ee..04d15c2fb5 100644 --- a/lib/dns/rdata/generic/rt_21.c +++ b/lib/dns/rdata/generic/rt_21.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rt_21.c,v 1.43 2005/03/16 00:55:18 marka Exp $ */ +/* $Id: rt_21.c,v 1.44 2005/04/27 04:57:05 sra Exp $ */ /* reviewed: Thu Mar 16 15:02:31 PST 2000 by brister */ -/* RFC 1183 */ +/* RFC1183 */ #ifndef RDATA_GENERIC_RT_21_C #define RDATA_GENERIC_RT_21_C diff --git a/lib/dns/rdata/generic/rt_21.h b/lib/dns/rdata/generic/rt_21.h index f8350906ad..f308a6c589 100644 --- a/lib/dns/rdata/generic/rt_21.h +++ b/lib/dns/rdata/generic/rt_21.h @@ -18,9 +18,10 @@ #ifndef GENERIC_RT_21_H #define GENERIC_RT_21_H 1 -/* $Id: rt_21.h,v 1.17 2004/03/05 05:10:17 marka Exp $ */ +/* $Id: rt_21.h,v 1.18 2005/04/27 04:57:06 sra Exp $ */ -/* RFC 1183 */ +/*! + * \brief Per RFC1183 */ typedef struct dns_rdata_rt { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/sig_24.c b/lib/dns/rdata/generic/sig_24.c index 3f1c3c3237..ecc6fdc75b 100644 --- a/lib/dns/rdata/generic/sig_24.c +++ b/lib/dns/rdata/generic/sig_24.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sig_24.c,v 1.62 2004/03/05 05:10:17 marka Exp $ */ +/* $Id: sig_24.c,v 1.63 2005/04/27 04:57:06 sra Exp $ */ /* Reviewed: Fri Mar 17 09:05:02 PST 2000 by gson */ -/* RFC 2535 */ +/* RFC2535 */ #ifndef RDATA_GENERIC_SIG_24_C #define RDATA_GENERIC_SIG_24_C diff --git a/lib/dns/rdata/generic/sig_24.h b/lib/dns/rdata/generic/sig_24.h index 9185859c8d..551f377aa5 100644 --- a/lib/dns/rdata/generic/sig_24.h +++ b/lib/dns/rdata/generic/sig_24.h @@ -18,9 +18,10 @@ #ifndef GENERIC_SIG_24_H #define GENERIC_SIG_24_H 1 -/* $Id: sig_24.h,v 1.22 2004/03/05 05:10:17 marka Exp $ */ +/* $Id: sig_24.h,v 1.23 2005/04/27 04:57:06 sra Exp $ */ -/* RFC 2535 */ +/*! + * \brief Per RFC2535 */ typedef struct dns_rdata_sig_t { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/soa_6.h b/lib/dns/rdata/generic/soa_6.h index 9f3c29d01a..91e0df675e 100644 --- a/lib/dns/rdata/generic/soa_6.h +++ b/lib/dns/rdata/generic/soa_6.h @@ -15,21 +15,22 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_SOA_6_H #define GENERIC_SOA_6_H 1 -/* $Id: soa_6.h,v 1.28 2004/03/05 05:10:18 marka Exp $ */ +/* $Id: soa_6.h,v 1.29 2005/04/27 04:57:06 sra Exp $ */ typedef struct dns_rdata_soa { dns_rdatacommon_t common; isc_mem_t *mctx; dns_name_t origin; dns_name_t contact; - isc_uint32_t serial; /* host order */ - isc_uint32_t refresh; /* host order */ - isc_uint32_t retry; /* host order */ - isc_uint32_t expire; /* host order */ - isc_uint32_t minimum; /* host order */ + isc_uint32_t serial; /*%< host order */ + isc_uint32_t refresh; /*%< host order */ + isc_uint32_t retry; /*%< host order */ + isc_uint32_t expire; /*%< host order */ + isc_uint32_t minimum; /*%< host order */ } dns_rdata_soa_t; diff --git a/lib/dns/rdata/generic/sshfp_44.h b/lib/dns/rdata/generic/sshfp_44.h index 855162181b..30c0a9bfaf 100644 --- a/lib/dns/rdata/generic/sshfp_44.h +++ b/lib/dns/rdata/generic/sshfp_44.h @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sshfp_44.h,v 1.2 2004/03/05 05:10:18 marka Exp $ */ +/* $Id: sshfp_44.h,v 1.3 2005/04/27 04:57:06 sra Exp $ */ -/* draft-ietf-secsh-dns-05.txt */ +/*! + * \brief Per draft-ietf-secsh-dns-05.txt */ #ifndef GENERIC_SSHFP_44_H #define GENERIC_SSHFP_44_H 1 diff --git a/lib/dns/rdata/generic/tkey_249.h b/lib/dns/rdata/generic/tkey_249.h index 30f2e69fc3..8aeaf941cf 100644 --- a/lib/dns/rdata/generic/tkey_249.h +++ b/lib/dns/rdata/generic/tkey_249.h @@ -18,9 +18,10 @@ #ifndef GENERIC_TKEY_249_H #define GENERIC_TKEY_249_H 1 -/* $Id: tkey_249.h,v 1.20 2004/03/05 05:10:18 marka Exp $ */ +/* $Id: tkey_249.h,v 1.21 2005/04/27 04:57:06 sra Exp $ */ -/* draft-ietf-dnsind-tkey-00.txt */ +/*! + * \brief Per draft-ietf-dnsind-tkey-00.txt */ typedef struct dns_rdata_tkey { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/txt_16.h b/lib/dns/rdata/generic/txt_16.h index cb7e6d2347..fd6c686574 100644 --- a/lib/dns/rdata/generic/txt_16.h +++ b/lib/dns/rdata/generic/txt_16.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_TXT_16_H #define GENERIC_TXT_16_H 1 -/* $Id: txt_16.h,v 1.24 2004/03/05 05:10:18 marka Exp $ */ +/* $Id: txt_16.h,v 1.25 2005/04/27 04:57:06 sra Exp $ */ typedef struct dns_rdata_txt_string { isc_uint8_t length; diff --git a/lib/dns/rdata/generic/unspec_103.h b/lib/dns/rdata/generic/unspec_103.h index e213f75082..ba1af7511e 100644 --- a/lib/dns/rdata/generic/unspec_103.h +++ b/lib/dns/rdata/generic/unspec_103.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef GENERIC_UNSPEC_103_H #define GENERIC_UNSPEC_103_H 1 -/* $Id: unspec_103.h,v 1.13 2004/03/05 05:10:18 marka Exp $ */ +/* $Id: unspec_103.h,v 1.14 2005/04/27 04:57:06 sra Exp $ */ typedef struct dns_rdata_unspec_t { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/generic/x25_19.c b/lib/dns/rdata/generic/x25_19.c index f0fc11a9dd..efc2fa7cbc 100644 --- a/lib/dns/rdata/generic/x25_19.c +++ b/lib/dns/rdata/generic/x25_19.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: x25_19.c,v 1.35 2004/03/05 05:10:18 marka Exp $ */ +/* $Id: x25_19.c,v 1.36 2005/04/27 04:57:06 sra Exp $ */ /* Reviewed: Thu Mar 16 16:15:57 PST 2000 by bwelling */ -/* RFC 1183 */ +/* RFC1183 */ #ifndef RDATA_GENERIC_X25_19_C #define RDATA_GENERIC_X25_19_C diff --git a/lib/dns/rdata/generic/x25_19.h b/lib/dns/rdata/generic/x25_19.h index 12617be5dc..f0242a24e6 100644 --- a/lib/dns/rdata/generic/x25_19.h +++ b/lib/dns/rdata/generic/x25_19.h @@ -18,9 +18,10 @@ #ifndef GENERIC_X25_19_H #define GENERIC_X25_19_H 1 -/* $Id: x25_19.h,v 1.14 2004/03/05 05:10:18 marka Exp $ */ +/* $Id: x25_19.h,v 1.15 2005/04/27 04:57:06 sra Exp $ */ -/* RFC 1183 */ +/*! + * \brief Per RFC1183 */ typedef struct dns_rdata_x25 { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/hs_4/a_1.h b/lib/dns/rdata/hs_4/a_1.h index ebb395ce8e..3aec92f647 100644 --- a/lib/dns/rdata/hs_4/a_1.h +++ b/lib/dns/rdata/hs_4/a_1.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef HS_4_A_1_H #define HS_4_A_1_H 1 -/* $Id: a_1.h,v 1.8 2004/03/05 05:10:21 marka Exp $ */ +/* $Id: a_1.h,v 1.9 2005/04/27 04:57:07 sra Exp $ */ typedef struct dns_rdata_hs_a { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/in_1/a6_38.h b/lib/dns/rdata/in_1/a6_38.h index 4fad563ece..e9ec72f8a4 100644 --- a/lib/dns/rdata/in_1/a6_38.h +++ b/lib/dns/rdata/in_1/a6_38.h @@ -18,9 +18,10 @@ #ifndef IN_1_A6_38_H #define IN_1_A6_38_H 1 -/* $Id: a6_38.h,v 1.20 2004/03/05 05:10:23 marka Exp $ */ +/* $Id: a6_38.h,v 1.21 2005/04/27 04:57:07 sra Exp $ */ -/* RFC2874 */ +/*! + * \brief Per RFC2874 */ typedef struct dns_rdata_in_a6 { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/in_1/a_1.h b/lib/dns/rdata/in_1/a_1.h index c2b827cf50..1c479f3025 100644 --- a/lib/dns/rdata/in_1/a_1.h +++ b/lib/dns/rdata/in_1/a_1.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef IN_1_A_1_H #define IN_1_A_1_H 1 -/* $Id: a_1.h,v 1.24 2004/03/05 05:10:23 marka Exp $ */ +/* $Id: a_1.h,v 1.25 2005/04/27 04:57:07 sra Exp $ */ typedef struct dns_rdata_in_a { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/in_1/aaaa_28.c b/lib/dns/rdata/in_1/aaaa_28.c index 9b8f2d3ae2..3e14185c49 100644 --- a/lib/dns/rdata/in_1/aaaa_28.c +++ b/lib/dns/rdata/in_1/aaaa_28.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: aaaa_28.c,v 1.41 2004/03/05 05:10:23 marka Exp $ */ +/* $Id: aaaa_28.c,v 1.42 2005/04/27 04:57:07 sra Exp $ */ /* Reviewed: Thu Mar 16 16:52:50 PST 2000 by bwelling */ -/* RFC 1886 */ +/* RFC1886 */ #ifndef RDATA_IN_1_AAAA_28_C #define RDATA_IN_1_AAAA_28_C diff --git a/lib/dns/rdata/in_1/aaaa_28.h b/lib/dns/rdata/in_1/aaaa_28.h index 1342af6614..7ada22978e 100644 --- a/lib/dns/rdata/in_1/aaaa_28.h +++ b/lib/dns/rdata/in_1/aaaa_28.h @@ -18,9 +18,10 @@ #ifndef IN_1_AAAA_28_H #define IN_1_AAAA_28_H 1 -/* $Id: aaaa_28.h,v 1.17 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: aaaa_28.h,v 1.18 2005/04/27 04:57:07 sra Exp $ */ -/* RFC 1886 */ +/*! + * \brief Per RFC1886 */ typedef struct dns_rdata_in_aaaa { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/in_1/apl_42.c b/lib/dns/rdata/in_1/apl_42.c index e4e296c66f..8fb03e68b7 100644 --- a/lib/dns/rdata/in_1/apl_42.c +++ b/lib/dns/rdata/in_1/apl_42.c @@ -15,9 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: apl_42.c,v 1.8 2004/03/18 02:58:04 marka Exp $ */ +/* $Id: apl_42.c,v 1.9 2005/04/27 04:57:07 sra Exp $ */ -/* RFC 3123 */ +/* RFC3123 */ #ifndef RDATA_IN_1_APL_42_C #define RDATA_IN_1_APL_42_C diff --git a/lib/dns/rdata/in_1/apl_42.h b/lib/dns/rdata/in_1/apl_42.h index 35030c2f7e..40fe1c6f40 100644 --- a/lib/dns/rdata/in_1/apl_42.h +++ b/lib/dns/rdata/in_1/apl_42.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/* */ #ifndef IN_1_APL_42_H #define IN_1_APL_42_H 1 -/* $Id: apl_42.h,v 1.2 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: apl_42.h,v 1.3 2005/04/27 04:57:07 sra Exp $ */ typedef struct dns_rdata_apl_ent { isc_boolean_t negative; diff --git a/lib/dns/rdata/in_1/kx_36.c b/lib/dns/rdata/in_1/kx_36.c index 66bbbcf7d3..fcde94fe07 100644 --- a/lib/dns/rdata/in_1/kx_36.c +++ b/lib/dns/rdata/in_1/kx_36.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: kx_36.c,v 1.41 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: kx_36.c,v 1.42 2005/04/27 04:57:07 sra Exp $ */ /* Reviewed: Thu Mar 16 17:24:54 PST 2000 by explorer */ -/* RFC 2230 */ +/* RFC2230 */ #ifndef RDATA_IN_1_KX_36_C #define RDATA_IN_1_KX_36_C diff --git a/lib/dns/rdata/in_1/kx_36.h b/lib/dns/rdata/in_1/kx_36.h index b441f97e8f..1ea19af726 100644 --- a/lib/dns/rdata/in_1/kx_36.h +++ b/lib/dns/rdata/in_1/kx_36.h @@ -18,9 +18,10 @@ #ifndef IN_1_KX_36_H #define IN_1_KX_36_H 1 -/* $Id: kx_36.h,v 1.16 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: kx_36.h,v 1.17 2005/04/27 04:57:07 sra Exp $ */ -/* RFC 2230 */ +/*! + * \brief Per RFC2230 */ typedef struct dns_rdata_in_kx { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/in_1/naptr_35.c b/lib/dns/rdata/in_1/naptr_35.c index c0d7b348f3..ef01ec9ede 100644 --- a/lib/dns/rdata/in_1/naptr_35.c +++ b/lib/dns/rdata/in_1/naptr_35.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: naptr_35.c,v 1.47 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: naptr_35.c,v 1.48 2005/04/27 04:57:07 sra Exp $ */ /* Reviewed: Thu Mar 16 16:52:50 PST 2000 by bwelling */ -/* RFC 2915 */ +/* RFC2915 */ #ifndef RDATA_IN_1_NAPTR_35_C #define RDATA_IN_1_NAPTR_35_C diff --git a/lib/dns/rdata/in_1/naptr_35.h b/lib/dns/rdata/in_1/naptr_35.h index 49c995934c..12dc2b453c 100644 --- a/lib/dns/rdata/in_1/naptr_35.h +++ b/lib/dns/rdata/in_1/naptr_35.h @@ -18,9 +18,10 @@ #ifndef IN_1_NAPTR_35_H #define IN_1_NAPTR_35_H 1 -/* $Id: naptr_35.h,v 1.19 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: naptr_35.h,v 1.20 2005/04/27 04:57:10 sra Exp $ */ -/* RFC 2915 */ +/*! + * \brief Per RFC2915 */ typedef struct dns_rdata_in_naptr { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/in_1/nsap-ptr_23.c b/lib/dns/rdata/in_1/nsap-ptr_23.c index 376b63ab25..17d92224c1 100644 --- a/lib/dns/rdata/in_1/nsap-ptr_23.c +++ b/lib/dns/rdata/in_1/nsap-ptr_23.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: nsap-ptr_23.c,v 1.34 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: nsap-ptr_23.c,v 1.35 2005/04/27 04:57:10 sra Exp $ */ /* Reviewed: Fri Mar 17 10:16:02 PST 2000 by gson */ -/* RFC 1348. Obsoleted in RFC 1706 - use PTR instead. */ +/* RFC1348. Obsoleted in RFC 1706 - use PTR instead. */ #ifndef RDATA_IN_1_NSAP_PTR_23_C #define RDATA_IN_1_NSAP_PTR_23_C diff --git a/lib/dns/rdata/in_1/nsap-ptr_23.h b/lib/dns/rdata/in_1/nsap-ptr_23.h index 54700b8dfd..9ed8d5bcf7 100644 --- a/lib/dns/rdata/in_1/nsap-ptr_23.h +++ b/lib/dns/rdata/in_1/nsap-ptr_23.h @@ -18,9 +18,10 @@ #ifndef IN_1_NSAP_PTR_23_H #define IN_1_NSAP_PTR_23_H 1 -/* $Id: nsap-ptr_23.h,v 1.15 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: nsap-ptr_23.h,v 1.16 2005/04/27 04:57:10 sra Exp $ */ -/* RFC 1348. Obsoleted in RFC 1706 - use PTR instead. */ +/*! + * \brief Per RFC1348. Obsoleted in RFC 1706 - use PTR instead. */ typedef struct dns_rdata_in_nsap_ptr { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/in_1/nsap_22.c b/lib/dns/rdata/in_1/nsap_22.c index 863cac7f1c..7c7cbc1d09 100644 --- a/lib/dns/rdata/in_1/nsap_22.c +++ b/lib/dns/rdata/in_1/nsap_22.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: nsap_22.c,v 1.38 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: nsap_22.c,v 1.39 2005/04/27 04:57:10 sra Exp $ */ /* Reviewed: Fri Mar 17 10:41:07 PST 2000 by gson */ -/* RFC 1706 */ +/* RFC1706 */ #ifndef RDATA_IN_1_NSAP_22_C #define RDATA_IN_1_NSAP_22_C diff --git a/lib/dns/rdata/in_1/nsap_22.h b/lib/dns/rdata/in_1/nsap_22.h index 24e655b683..0f9611fc3a 100644 --- a/lib/dns/rdata/in_1/nsap_22.h +++ b/lib/dns/rdata/in_1/nsap_22.h @@ -18,9 +18,10 @@ #ifndef IN_1_NSAP_22_H #define IN_1_NSAP_22_H 1 -/* $Id: nsap_22.h,v 1.14 2004/03/05 05:10:24 marka Exp $ */ +/* $Id: nsap_22.h,v 1.15 2005/04/27 04:57:10 sra Exp $ */ -/* RFC 1706 */ +/*! + * \brief Per RFC1706 */ typedef struct dns_rdata_in_nsap { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/in_1/px_26.c b/lib/dns/rdata/in_1/px_26.c index 49be868951..a6ba3e37fd 100644 --- a/lib/dns/rdata/in_1/px_26.c +++ b/lib/dns/rdata/in_1/px_26.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: px_26.c,v 1.39 2004/03/05 05:10:25 marka Exp $ */ +/* $Id: px_26.c,v 1.40 2005/04/27 04:57:10 sra Exp $ */ /* Reviewed: Mon Mar 20 10:44:27 PST 2000 */ -/* RFC 2163 */ +/* RFC2163 */ #ifndef RDATA_IN_1_PX_26_C #define RDATA_IN_1_PX_26_C diff --git a/lib/dns/rdata/in_1/px_26.h b/lib/dns/rdata/in_1/px_26.h index 39e32d02ce..217ac75447 100644 --- a/lib/dns/rdata/in_1/px_26.h +++ b/lib/dns/rdata/in_1/px_26.h @@ -18,9 +18,10 @@ #ifndef IN_1_PX_26_H #define IN_1_PX_26_H 1 -/* $Id: px_26.h,v 1.15 2004/03/05 05:10:25 marka Exp $ */ +/* $Id: px_26.h,v 1.16 2005/04/27 04:57:10 sra Exp $ */ -/* RFC 2163 */ +/*! + * \brief Per RFC2163 */ typedef struct dns_rdata_in_px { dns_rdatacommon_t common; diff --git a/lib/dns/rdata/in_1/srv_33.c b/lib/dns/rdata/in_1/srv_33.c index a2a3c7343e..97324c7909 100644 --- a/lib/dns/rdata/in_1/srv_33.c +++ b/lib/dns/rdata/in_1/srv_33.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: srv_33.c,v 1.41 2004/03/05 05:10:25 marka Exp $ */ +/* $Id: srv_33.c,v 1.42 2005/04/27 04:57:11 sra Exp $ */ /* Reviewed: Fri Mar 17 13:01:00 PST 2000 by bwelling */ -/* RFC 2782 */ +/* RFC2782 */ #ifndef RDATA_IN_1_SRV_33_C #define RDATA_IN_1_SRV_33_C diff --git a/lib/dns/rdata/in_1/srv_33.h b/lib/dns/rdata/in_1/srv_33.h index de7bc09a40..cdca5b67fb 100644 --- a/lib/dns/rdata/in_1/srv_33.h +++ b/lib/dns/rdata/in_1/srv_33.h @@ -18,11 +18,12 @@ #ifndef IN_1_SRV_33_H #define IN_1_SRV_33_H 1 -/* $Id: srv_33.h,v 1.15 2004/03/05 05:10:25 marka Exp $ */ +/* $Id: srv_33.h,v 1.16 2005/04/27 04:57:11 sra Exp $ */ /* Reviewed: Fri Mar 17 13:01:00 PST 2000 by bwelling */ -/* RFC 2782 */ +/*! + * \brief Per RFC2782 */ typedef struct dns_rdata_in_srv { dns_rdatacommon_t common; diff --git a/lib/dns/rdatalist.c b/lib/dns/rdatalist.c index a181f5ccbf..15690d6cf2 100644 --- a/lib/dns/rdatalist.c +++ b/lib/dns/rdatalist.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdatalist.c,v 1.29 2004/12/21 10:45:17 jinmei Exp $ */ +/* $Id: rdatalist.c,v 1.30 2005/04/27 04:56:50 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/rdatalist_p.h b/lib/dns/rdatalist_p.h index bd04ee27b9..54963f10e6 100644 --- a/lib/dns/rdatalist_p.h +++ b/lib/dns/rdatalist_p.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdatalist_p.h,v 1.5 2004/03/05 05:09:23 marka Exp $ */ +/* $Id: rdatalist_p.h,v 1.6 2005/04/27 04:56:50 sra Exp $ */ #ifndef DNS_RDATALIST_P_H #define DNS_RDATALIST_P_H +/*! \file */ + #include #include diff --git a/lib/dns/rdataset.c b/lib/dns/rdataset.c index f65b4bd825..ecfcc930e8 100644 --- a/lib/dns/rdataset.c +++ b/lib/dns/rdataset.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdataset.c,v 1.73 2004/12/21 10:45:17 jinmei Exp $ */ +/* $Id: rdataset.c,v 1.74 2005/04/27 04:56:50 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/rdatasetiter.c b/lib/dns/rdatasetiter.c index 5e93b6dac8..35017c2794 100644 --- a/lib/dns/rdatasetiter.c +++ b/lib/dns/rdatasetiter.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdatasetiter.c,v 1.12 2004/03/05 05:09:23 marka Exp $ */ +/* $Id: rdatasetiter.c,v 1.13 2005/04/27 04:56:50 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/rdataslab.c b/lib/dns/rdataslab.c index 228cf1fe72..2c03b03ca0 100644 --- a/lib/dns/rdataslab.c +++ b/lib/dns/rdataslab.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rdataslab.c,v 1.36 2004/12/21 10:45:17 jinmei Exp $ */ +/* $Id: rdataslab.c,v 1.37 2005/04/27 04:56:50 sra Exp $ */ + +/*! \file */ #include @@ -31,7 +33,7 @@ #include #include -/* Note: the "const void *" are just to make qsort happy. */ +/*% Note: the "const void *" are just to make qsort happy. */ static int compare_rdata(const void *p1, const void *p2) { const dns_rdata_t *rdata1 = p1; diff --git a/lib/dns/request.c b/lib/dns/request.c index 458b7445df..2b79aaf237 100644 --- a/lib/dns/request.c +++ b/lib/dns/request.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: request.c,v 1.72 2004/03/05 05:09:24 marka Exp $ */ +/* $Id: request.c,v 1.73 2005/04/27 04:56:50 sra Exp $ */ + +/*! \file */ #include @@ -91,10 +93,10 @@ struct dns_request { #define DNS_REQUEST_F_CONNECTING 0x0001 #define DNS_REQUEST_F_SENDING 0x0002 -#define DNS_REQUEST_F_CANCELED 0x0004 /* ctlevent received, or otherwise +#define DNS_REQUEST_F_CANCELED 0x0004 /*%< ctlevent received, or otherwise synchronously canceled */ -#define DNS_REQUEST_F_TIMEDOUT 0x0008 /* cancelled due to a timeout */ -#define DNS_REQUEST_F_TCP 0x0010 /* This request used TCP */ +#define DNS_REQUEST_F_TIMEDOUT 0x0008 /*%< cancelled due to a timeout */ +#define DNS_REQUEST_F_TCP 0x0010 /*%< This request used TCP */ #define DNS_REQUEST_CANCELED(r) \ (((r)->flags & DNS_REQUEST_F_CANCELED) != 0) #define DNS_REQUEST_CONNECTING(r) \ diff --git a/lib/dns/resolver.c b/lib/dns/resolver.c index 82d70165f7..38c713c00d 100644 --- a/lib/dns/resolver.c +++ b/lib/dns/resolver.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: resolver.c,v 1.306 2005/03/16 03:50:47 marka Exp $ */ +/* $Id: resolver.c,v 1.307 2005/04/27 04:56:51 sra Exp $ */ + +/*! \file */ #include @@ -99,12 +101,12 @@ #define QTRACE(m) #endif -/* +/*% * Maximum EDNS0 input packet size. */ #define RECV_BUFFER_SIZE 4096 /* XXXRTH Constant. */ -/* +/*% * This defines the maximum number of timeouts we will permit before we * disable EDNS0 on the query. */ @@ -146,13 +148,13 @@ typedef struct query { #define RESQUERY_SENDING(q) ((q)->sends > 0) typedef enum { - fetchstate_init = 0, /* Start event has not run yet. */ + fetchstate_init = 0, /*%< Start event has not run yet. */ fetchstate_active, - fetchstate_done /* FETCHDONE events posted. */ + fetchstate_done /*%< FETCHDONE events posted. */ } fetchstate; struct fetchctx { - /* Not locked. */ + /*% Not locked. */ unsigned int magic; dns_resolver_t * res; dns_name_t name; @@ -160,7 +162,7 @@ struct fetchctx { unsigned int options; unsigned int bucketnum; char * info; - /* Locked by appropriate bucket lock. */ + /*% Locked by appropriate bucket lock. */ fetchstate state; isc_boolean_t want_shutdown; isc_boolean_t cloned; @@ -168,7 +170,7 @@ struct fetchctx { isc_event_t control_event; ISC_LINK(struct fetchctx) link; ISC_LIST(dns_fetchevent_t) events; - /* Locked by task event serialization. */ + /*% Locked by task event serialization. */ dns_name_t domain; dns_rdataset_t nameservers; unsigned int attributes; @@ -191,12 +193,12 @@ struct fetchctx { dns_db_t * cache; dns_adb_t * adb; - /* + /*% * The number of events we're waiting for. */ unsigned int pending; - /* + /*% * The number of times we've "restarted" the current * nameserver set. This acts as a failsafe to prevent * us from pounding constantly on a particular set of @@ -206,13 +208,13 @@ struct fetchctx { */ unsigned int restarts; - /* + /*% * The number of timeouts that have occurred since we * last successfully received a response packet. This * is used for EDNS0 black hole detection. */ unsigned int timeouts; - /* + /*% * Look aside state for DS lookups. */ dns_name_t nsname; @@ -319,7 +321,7 @@ struct dns_resolver { #define RES_MAGIC ISC_MAGIC('R', 'e', 's', '!') #define VALID_RESOLVER(res) ISC_MAGIC_VALID(res, RES_MAGIC) -/* +/*% * Private addrinfo flags. These must not conflict with DNS_FETCHOPT_NOEDNS0, * which we also use as an addrinfo flag. */ diff --git a/lib/dns/result.c b/lib/dns/result.c index d5ba87ce12..ce0bd6472a 100644 --- a/lib/dns/result.c +++ b/lib/dns/result.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: result.c,v 1.117 2004/05/14 04:45:57 marka Exp $ */ +/* $Id: result.c,v 1.118 2005/04/27 04:56:51 sra Exp $ */ + +/*! \file */ #include @@ -26,155 +28,155 @@ #include static const char *text[DNS_R_NRESULTS] = { - "label too long", /* 0 DNS_R_LABELTOOLONG */ - "bad escape", /* 1 DNS_R_BADESCAPE */ - /* + "label too long", /*%< 0 DNS_R_LABELTOOLONG */ + "bad escape", /*%< 1 DNS_R_BADESCAPE */ + /*! * Note that DNS_R_BADBITSTRING and DNS_R_BITSTRINGTOOLONG are * deprecated. */ - "bad bitstring", /* 2 DNS_R_BADBITSTRING */ - "bitstring too long", /* 3 DNS_R_BITSTRINGTOOLONG */ - "empty label", /* 4 DNS_R_EMPTYLABEL */ + "bad bitstring", /*%< 2 DNS_R_BADBITSTRING */ + "bitstring too long", /*%< 3 DNS_R_BITSTRINGTOOLONG */ + "empty label", /*%< 4 DNS_R_EMPTYLABEL */ - "bad dotted quad", /* 5 DNS_R_BADDOTTEDQUAD */ - "invalid NS owner name (wildcard)", /* 6 DNS_R_INVALIDNS */ - "unknown class/type", /* 7 DNS_R_UNKNOWN */ - "bad label type", /* 8 DNS_R_BADLABELTYPE */ - "bad compression pointer", /* 9 DNS_R_BADPOINTER */ + "bad dotted quad", /*%< 5 DNS_R_BADDOTTEDQUAD */ + "invalid NS owner name (wildcard)", /*%< 6 DNS_R_INVALIDNS */ + "unknown class/type", /*%< 7 DNS_R_UNKNOWN */ + "bad label type", /*%< 8 DNS_R_BADLABELTYPE */ + "bad compression pointer", /*%< 9 DNS_R_BADPOINTER */ - "too many hops", /* 10 DNS_R_TOOMANYHOPS */ - "disallowed (by application policy)", /* 11 DNS_R_DISALLOWED */ - "extra input text", /* 12 DNS_R_EXTRATOKEN */ - "extra input data", /* 13 DNS_R_EXTRADATA */ - "text too long", /* 14 DNS_R_TEXTTOOLONG */ + "too many hops", /*%< 10 DNS_R_TOOMANYHOPS */ + "disallowed (by application policy)", /*%< 11 DNS_R_DISALLOWED */ + "extra input text", /*%< 12 DNS_R_EXTRATOKEN */ + "extra input data", /*%< 13 DNS_R_EXTRADATA */ + "text too long", /*%< 14 DNS_R_TEXTTOOLONG */ - "not at top of zone", /* 15 DNS_R_NOTZONETOP */ - "syntax error", /* 16 DNS_R_SYNTAX */ - "bad checksum", /* 17 DNS_R_BADCKSUM */ - "bad IPv6 address", /* 18 DNS_R_BADAAAA */ - "no owner", /* 19 DNS_R_NOOWNER */ + "not at top of zone", /*%< 15 DNS_R_NOTZONETOP */ + "syntax error", /*%< 16 DNS_R_SYNTAX */ + "bad checksum", /*%< 17 DNS_R_BADCKSUM */ + "bad IPv6 address", /*%< 18 DNS_R_BADAAAA */ + "no owner", /*%< 19 DNS_R_NOOWNER */ - "no ttl", /* 20 DNS_R_NOTTL */ - "bad class", /* 21 DNS_R_BADCLASS */ - "name too long", /* 22 DNS_R_NAMETOOLONG */ - "partial match", /* 23 DNS_R_PARTIALMATCH */ - "new origin", /* 24 DNS_R_NEWORIGIN */ + "no ttl", /*%< 20 DNS_R_NOTTL */ + "bad class", /*%< 21 DNS_R_BADCLASS */ + "name too long", /*%< 22 DNS_R_NAMETOOLONG */ + "partial match", /*%< 23 DNS_R_PARTIALMATCH */ + "new origin", /*%< 24 DNS_R_NEWORIGIN */ - "unchanged", /* 25 DNS_R_UNCHANGED */ - "bad ttl", /* 26 DNS_R_BADTTL */ - "more data needed/to be rendered", /* 27 DNS_R_NOREDATA */ - "continue", /* 28 DNS_R_CONTINUE */ - "delegation", /* 29 DNS_R_DELEGATION */ + "unchanged", /*%< 25 DNS_R_UNCHANGED */ + "bad ttl", /*%< 26 DNS_R_BADTTL */ + "more data needed/to be rendered", /*%< 27 DNS_R_NOREDATA */ + "continue", /*%< 28 DNS_R_CONTINUE */ + "delegation", /*%< 29 DNS_R_DELEGATION */ - "glue", /* 30 DNS_R_GLUE */ - "dname", /* 31 DNS_R_DNAME */ - "cname", /* 32 DNS_R_CNAME */ - "bad database", /* 33 DNS_R_BADDB */ - "zonecut", /* 34 DNS_R_ZONECUT */ + "glue", /*%< 30 DNS_R_GLUE */ + "dname", /*%< 31 DNS_R_DNAME */ + "cname", /*%< 32 DNS_R_CNAME */ + "bad database", /*%< 33 DNS_R_BADDB */ + "zonecut", /*%< 34 DNS_R_ZONECUT */ - "bad zone", /* 35 DNS_R_BADZONE */ - "more data", /* 36 DNS_R_MOREDATA */ - "up to date", /* 37 DNS_R_UPTODATE */ - "tsig verify failure", /* 38 DNS_R_TSIGVERIFYFAILURE */ - "tsig indicates error", /* 39 DNS_R_TSIGERRORSET */ + "bad zone", /*%< 35 DNS_R_BADZONE */ + "more data", /*%< 36 DNS_R_MOREDATA */ + "up to date", /*%< 37 DNS_R_UPTODATE */ + "tsig verify failure", /*%< 38 DNS_R_TSIGVERIFYFAILURE */ + "tsig indicates error", /*%< 39 DNS_R_TSIGERRORSET */ - "RRSIG failed to verify", /* 40 DNS_R_SIGINVALID */ - "RRSIG has expired", /* 41 DNS_R_SIGEXPIRED */ - "RRSIG validity period has not begun", /* 42 DNS_R_SIGFUTURE */ - "key is unauthorized to sign data", /* 43 DNS_R_KEYUNAUTHORIZED */ - "invalid time", /* 44 DNS_R_INVALIDTIME */ + "RRSIG failed to verify", /*%< 40 DNS_R_SIGINVALID */ + "RRSIG has expired", /*%< 41 DNS_R_SIGEXPIRED */ + "RRSIG validity period has not begun", /*%< 42 DNS_R_SIGFUTURE */ + "key is unauthorized to sign data", /*%< 43 DNS_R_KEYUNAUTHORIZED */ + "invalid time", /*%< 44 DNS_R_INVALIDTIME */ - "expected a TSIG or SIG(0)", /* 45 DNS_R_EXPECTEDTSIG */ - "did not expect a TSIG or SIG(0)", /* 46 DNS_R_UNEXPECTEDTSIG */ - "TKEY is unacceptable", /* 47 DNS_R_INVALIDTKEY */ - "hint", /* 48 DNS_R_HINT */ - "drop", /* 49 DNS_R_DROP */ + "expected a TSIG or SIG(0)", /*%< 45 DNS_R_EXPECTEDTSIG */ + "did not expect a TSIG or SIG(0)", /*%< 46 DNS_R_UNEXPECTEDTSIG */ + "TKEY is unacceptable", /*%< 47 DNS_R_INVALIDTKEY */ + "hint", /*%< 48 DNS_R_HINT */ + "drop", /*%< 49 DNS_R_DROP */ - "zone not loaded", /* 50 DNS_R_NOTLOADED */ - "ncache nxdomain", /* 51 DNS_R_NCACHENXDOMAIN */ - "ncache nxrrset", /* 52 DNS_R_NCACHENXRRSET */ - "wait", /* 53 DNS_R_WAIT */ - "not verified yet", /* 54 DNS_R_NOTVERIFIEDYET */ + "zone not loaded", /*%< 50 DNS_R_NOTLOADED */ + "ncache nxdomain", /*%< 51 DNS_R_NCACHENXDOMAIN */ + "ncache nxrrset", /*%< 52 DNS_R_NCACHENXRRSET */ + "wait", /*%< 53 DNS_R_WAIT */ + "not verified yet", /*%< 54 DNS_R_NOTVERIFIEDYET */ - "no identity", /* 55 DNS_R_NOIDENTITY */ - "no journal", /* 56 DNS_R_NOJOURNAL */ - "alias", /* 57 DNS_R_ALIAS */ - "use TCP", /* 58 DNS_R_USETCP */ - "no valid RRSIG", /* 59 DNS_R_NOVALIDSIG */ + "no identity", /*%< 55 DNS_R_NOIDENTITY */ + "no journal", /*%< 56 DNS_R_NOJOURNAL */ + "alias", /*%< 57 DNS_R_ALIAS */ + "use TCP", /*%< 58 DNS_R_USETCP */ + "no valid RRSIG", /*%< 59 DNS_R_NOVALIDSIG */ - "no valid NSEC", /* 60 DNS_R_NOVALIDNSEC */ - "not insecure", /* 61 DNS_R_NOTINSECURE */ - "unknown service", /* 62 DNS_R_UNKNOWNSERVICE */ - "recoverable error occurred", /* 63 DNS_R_RECOVERABLE */ - "unknown opt attribute record", /* 64 DNS_R_UNKNOWNOPT */ + "no valid NSEC", /*%< 60 DNS_R_NOVALIDNSEC */ + "not insecure", /*%< 61 DNS_R_NOTINSECURE */ + "unknown service", /*%< 62 DNS_R_UNKNOWNSERVICE */ + "recoverable error occurred", /*%< 63 DNS_R_RECOVERABLE */ + "unknown opt attribute record", /*%< 64 DNS_R_UNKNOWNOPT */ - "unexpected message id", /* 65 DNS_R_UNEXPECTEDID */ - "seen include file", /* 66 DNS_R_SEENINCLUDE */ - "not exact", /* 67 DNS_R_NOTEXACT */ - "address blackholed", /* 68 DNS_R_BLACKHOLED */ - "bad algorithm", /* 69 DNS_R_BADALG */ + "unexpected message id", /*%< 65 DNS_R_UNEXPECTEDID */ + "seen include file", /*%< 66 DNS_R_SEENINCLUDE */ + "not exact", /*%< 67 DNS_R_NOTEXACT */ + "address blackholed", /*%< 68 DNS_R_BLACKHOLED */ + "bad algorithm", /*%< 69 DNS_R_BADALG */ - "invalid use of a meta type", /* 70 DNS_R_METATYPE */ - "CNAME and other data", /* 71 DNS_R_CNAMEANDOTHER */ - "multiple RRs of singleton type", /* 72 DNS_R_SINGLETON */ - "hint nxrrset", /* 73 DNS_R_HINTNXRRSET */ - "no master file configured", /* 74 DNS_R_NOMASTERFILE */ + "invalid use of a meta type", /*%< 70 DNS_R_METATYPE */ + "CNAME and other data", /*%< 71 DNS_R_CNAMEANDOTHER */ + "multiple RRs of singleton type", /*%< 72 DNS_R_SINGLETON */ + "hint nxrrset", /*%< 73 DNS_R_HINTNXRRSET */ + "no master file configured", /*%< 74 DNS_R_NOMASTERFILE */ - "unknown protocol", /* 75 DNS_R_UNKNOWNPROTO */ - "clocks are unsynchronized", /* 76 DNS_R_CLOCKSKEW */ - "IXFR failed", /* 77 DNS_R_BADIXFR */ - "not authoritative", /* 78 DNS_R_NOTAUTHORITATIVE */ - "no valid KEY", /* 79 DNS_R_NOVALIDKEY */ + "unknown protocol", /*%< 75 DNS_R_UNKNOWNPROTO */ + "clocks are unsynchronized", /*%< 76 DNS_R_CLOCKSKEW */ + "IXFR failed", /*%< 77 DNS_R_BADIXFR */ + "not authoritative", /*%< 78 DNS_R_NOTAUTHORITATIVE */ + "no valid KEY", /*%< 79 DNS_R_NOVALIDKEY */ - "obsolete", /* 80 DNS_R_OBSOLETE */ - "already frozen", /* 81 DNS_R_FROZEN */ - "unknown flag", /* 82 DNS_R_UNKNOWNFLAG */ - "expected a response", /* 83 DNS_R_EXPECTEDRESPONSE */ - "no valid DS", /* 84 DNS_R_NOVALIDDS */ + "obsolete", /*%< 80 DNS_R_OBSOLETE */ + "already frozen", /*%< 81 DNS_R_FROZEN */ + "unknown flag", /*%< 82 DNS_R_UNKNOWNFLAG */ + "expected a response", /*%< 83 DNS_R_EXPECTEDRESPONSE */ + "no valid DS", /*%< 84 DNS_R_NOVALIDDS */ - "NS is an address", /* 85 DNS_R_NSISADDRESS */ - "received FORMERR", /* 86 DNS_R_REMOTEFORMERR */ - "truncated TCP response", /* 87 DNS_R_TRUNCATEDTCP */ - "lame server detected", /* 88 DNS_R_LAME */ - "unexpected RCODE", /* 89 DNS_R_UNEXPECTEDRCODE */ + "NS is an address", /*%< 85 DNS_R_NSISADDRESS */ + "received FORMERR", /*%< 86 DNS_R_REMOTEFORMERR */ + "truncated TCP response", /*%< 87 DNS_R_TRUNCATEDTCP */ + "lame server detected", /*%< 88 DNS_R_LAME */ + "unexpected RCODE", /*%< 89 DNS_R_UNEXPECTEDRCODE */ - "unexpected OPCODE", /* 90 DNS_R_UNEXPECTEDOPCODE */ - "chase DS servers", /* 91 DNS_R_CHASEDSSERVERS */ - "empty name", /* 92 DNS_R_EMPTYNAME */ - "empty wild", /* 93 DNS_R_EMPTYWILD */ - "bad bitmap", /* 94 DNS_R_BADBITMAP */ + "unexpected OPCODE", /*%< 90 DNS_R_UNEXPECTEDOPCODE */ + "chase DS servers", /*%< 91 DNS_R_CHASEDSSERVERS */ + "empty name", /*%< 92 DNS_R_EMPTYNAME */ + "empty wild", /*%< 93 DNS_R_EMPTYWILD */ + "bad bitmap", /*%< 94 DNS_R_BADBITMAP */ - "from wildcard", /* 95 DNS_R_FROMWILDCARD */ - "bad owner name (check-names)", /* 96 DNS_R_BADOWNERNAME */ - "bad name (check-names)", /* 97 DNS_R_BADNAME */ - "dynamic zone", /* 98 DNS_R_DYNAMIC */ - "unknown command", /* 99 DNS_R_UNKNOWNCOMMAND */ + "from wildcard", /*%< 95 DNS_R_FROMWILDCARD */ + "bad owner name (check-names)", /*%< 96 DNS_R_BADOWNERNAME */ + "bad name (check-names)", /*%< 97 DNS_R_BADNAME */ + "dynamic zone", /*%< 98 DNS_R_DYNAMIC */ + "unknown command", /*%< 99 DNS_R_UNKNOWNCOMMAND */ - "must-be-secure", /* 100 DNS_R_MUSTBESECURE */ - "covering NSEC record returned" /* 101 DNS_R_COVERINGNSEC */ + "must-be-secure", /*%< 100 DNS_R_MUSTBESECURE */ + "covering NSEC record returned" /*%< 101 DNS_R_COVERINGNSEC */ }; static const char *rcode_text[DNS_R_NRCODERESULTS] = { - "NOERROR", /* 0 DNS_R_NOEROR */ - "FORMERR", /* 1 DNS_R_FORMERR */ - "SERVFAIL", /* 2 DNS_R_SERVFAIL */ - "NXDOMAIN", /* 3 DNS_R_NXDOMAIN */ - "NOTIMP", /* 4 DNS_R_NOTIMP */ + "NOERROR", /*%< 0 DNS_R_NOEROR */ + "FORMERR", /*%< 1 DNS_R_FORMERR */ + "SERVFAIL", /*%< 2 DNS_R_SERVFAIL */ + "NXDOMAIN", /*%< 3 DNS_R_NXDOMAIN */ + "NOTIMP", /*%< 4 DNS_R_NOTIMP */ - "REFUSED", /* 5 DNS_R_REFUSED */ - "YXDOMAIN", /* 6 DNS_R_YXDOMAIN */ - "YXRRSET", /* 7 DNS_R_YXRRSET */ - "NXRRSET", /* 8 DNS_R_NXRRSET */ - "NOTAUTH", /* 9 DNS_R_NOTAUTH */ + "REFUSED", /*%< 5 DNS_R_REFUSED */ + "YXDOMAIN", /*%< 6 DNS_R_YXDOMAIN */ + "YXRRSET", /*%< 7 DNS_R_YXRRSET */ + "NXRRSET", /*%< 8 DNS_R_NXRRSET */ + "NOTAUTH", /*%< 9 DNS_R_NOTAUTH */ - "NOTZONE", /* 10 DNS_R_NOTZONE */ - "", /* 11 has no macro */ - "", /* 12 has no macro */ - "", /* 13 has no macro */ - "", /* 14 has no macro */ + "NOTZONE", /*%< 10 DNS_R_NOTZONE */ + "", /*%< 11 has no macro */ + "", /*%< 12 has no macro */ + "", /*%< 13 has no macro */ + "", /*%< 14 has no macro */ - "", /* 15 has no macro */ - "BADVERS", /* 16 DNS_R_BADVERS */ + "", /*%< 15 has no macro */ + "BADVERS", /*%< 16 DNS_R_BADVERS */ }; #define DNS_RESULT_RESULTSET 2 diff --git a/lib/dns/rootns.c b/lib/dns/rootns.c index 159558ac00..d7ae94f707 100644 --- a/lib/dns/rootns.c +++ b/lib/dns/rootns.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rootns.c,v 1.28 2005/02/07 23:57:02 marka Exp $ */ +/* $Id: rootns.c,v 1.29 2005/04/27 04:56:51 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/sdb.c b/lib/dns/sdb.c index ebf113ae19..1abee56a08 100644 --- a/lib/dns/sdb.c +++ b/lib/dns/sdb.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sdb.c,v 1.47 2004/12/21 10:45:18 jinmei Exp $ */ +/* $Id: sdb.c,v 1.48 2005/04/27 04:56:51 sra Exp $ */ + +/*! \file */ #include @@ -99,7 +101,7 @@ typedef struct sdb_rdatasetiter { #define SDB_MAGIC ISC_MAGIC('S', 'D', 'B', '-') -/* +/*% * Note that "impmagic" is not the first four bytes of the struct, so * ISC_MAGIC_VALID cannot be used. */ @@ -110,7 +112,7 @@ typedef struct sdb_rdatasetiter { #define VALID_SDBLOOKUP(sdbl) ISC_MAGIC_VALID(sdbl, SDBLOOKUP_MAGIC) #define VALID_SDBNODE(sdbn) VALID_SDBLOOKUP(sdbn) -/* These values are taken from RFC 1537 */ +/* These values are taken from RFC1537 */ #define SDB_DEFAULT_REFRESH (60 * 60 * 8) #define SDB_DEFAULT_RETRY (60 * 60 * 2) #define SDB_DEFAULT_EXPIRE (60 * 60 * 24 * 7) diff --git a/lib/dns/soa.c b/lib/dns/soa.c index afb7478dd7..990abbeaad 100644 --- a/lib/dns/soa.c +++ b/lib/dns/soa.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: soa.c,v 1.4 2004/03/05 05:09:24 marka Exp $ */ +/* $Id: soa.c,v 1.5 2005/04/27 04:56:51 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/ssu.c b/lib/dns/ssu.c index bef5207e49..e11a0830da 100644 --- a/lib/dns/ssu.c +++ b/lib/dns/ssu.c @@ -14,9 +14,9 @@ * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR * PERFORMANCE OF THIS SOFTWARE. */ - +/*! \file */ /* - * $Id: ssu.c,v 1.24 2004/03/05 05:09:25 marka Exp $ + * $Id: ssu.c,v 1.25 2005/04/27 04:56:51 sra Exp $ * Principal Author: Brian Wellington */ @@ -38,13 +38,13 @@ struct dns_ssurule { unsigned int magic; - isc_boolean_t grant; /* is this a grant or a deny? */ - unsigned int matchtype; /* which type of pattern match? */ - dns_name_t *identity; /* the identity to match */ - dns_name_t *name; /* the name being updated */ - unsigned int ntypes; /* number of data types covered */ - dns_rdatatype_t *types; /* the data types. Can include ANY, */ - /* defaults to all but SIG,SOA,NS if NULL*/ + isc_boolean_t grant; /*%< is this a grant or a deny? */ + unsigned int matchtype; /*%< which type of pattern match? */ + dns_name_t *identity; /*%< the identity to match */ + dns_name_t *name; /*%< the name being updated */ + unsigned int ntypes; /*%< number of data types covered */ + dns_rdatatype_t *types; /*%< the data types. Can include ANY, */ + /*%< defaults to all but SIG,SOA,NS if NULL */ ISC_LINK(dns_ssurule_t) link; }; diff --git a/lib/dns/stats.c b/lib/dns/stats.c index 4741b8f0be..031a33b761 100644 --- a/lib/dns/stats.c +++ b/lib/dns/stats.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: stats.c,v 1.6 2004/03/05 05:09:25 marka Exp $ */ +/* $Id: stats.c,v 1.7 2005/04/27 04:56:51 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/tcpmsg.c b/lib/dns/tcpmsg.c index 073c461080..85c8a67f48 100644 --- a/lib/dns/tcpmsg.c +++ b/lib/dns/tcpmsg.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: tcpmsg.c,v 1.25 2004/03/05 05:09:25 marka Exp $ */ +/* $Id: tcpmsg.c,v 1.26 2005/04/27 04:56:52 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/time.c b/lib/dns/time.c index 3ec9d4497d..d36c90615d 100644 --- a/lib/dns/time.c +++ b/lib/dns/time.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: time.c,v 1.27 2004/08/28 06:16:56 marka Exp $ */ +/* $Id: time.c,v 1.28 2005/04/27 04:56:52 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/timer.c b/lib/dns/timer.c index c9fb7e0875..c7def7d717 100644 --- a/lib/dns/timer.c +++ b/lib/dns/timer.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: timer.c,v 1.3 2004/03/05 05:09:25 marka Exp $ */ +/* $Id: timer.c,v 1.4 2005/04/27 04:56:52 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/tkey.c b/lib/dns/tkey.c index 27ac05b4e0..d49e99684e 100644 --- a/lib/dns/tkey.c +++ b/lib/dns/tkey.c @@ -16,9 +16,9 @@ */ /* - * $Id: tkey.c,v 1.77 2004/06/11 00:27:00 marka Exp $ + * $Id: tkey.c,v 1.78 2005/04/27 04:56:52 sra Exp $ */ - +/*! \file */ #include #include diff --git a/lib/dns/tsig.c b/lib/dns/tsig.c index e4e8b339cf..8db2b51107 100644 --- a/lib/dns/tsig.c +++ b/lib/dns/tsig.c @@ -16,9 +16,9 @@ */ /* - * $Id: tsig.c,v 1.119 2005/03/17 03:56:12 marka Exp $ + * $Id: tsig.c,v 1.120 2005/04/27 04:56:52 sra Exp $ */ - +/*! \file */ #include #include diff --git a/lib/dns/ttl.c b/lib/dns/ttl.c index bece5d8cf5..6e79c855ce 100644 --- a/lib/dns/ttl.c +++ b/lib/dns/ttl.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ttl.c,v 1.25 2004/03/05 05:09:26 marka Exp $ */ +/* $Id: ttl.c,v 1.26 2005/04/27 04:56:52 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/validator.c b/lib/dns/validator.c index 8668beb3ad..1c733e56eb 100644 --- a/lib/dns/validator.c +++ b/lib/dns/validator.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: validator.c,v 1.127 2005/03/04 03:53:21 marka Exp $ */ +/* $Id: validator.c,v 1.128 2005/04/27 04:56:52 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/version.c b/lib/dns/version.c index 4fc1aed5ec..0ff9a87fbe 100644 --- a/lib/dns/version.c +++ b/lib/dns/version.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.c,v 1.11 2004/03/05 05:09:26 marka Exp $ */ +/* $Id: version.c,v 1.12 2005/04/27 04:56:52 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/view.c b/lib/dns/view.c index 43c3fab225..2d83fafcbe 100644 --- a/lib/dns/view.c +++ b/lib/dns/view.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: view.c,v 1.130 2005/01/17 04:11:33 marka Exp $ */ +/* $Id: view.c,v 1.131 2005/04/27 04:56:53 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/xfrin.c b/lib/dns/xfrin.c index c1f62a78d5..9fda08b911 100644 --- a/lib/dns/xfrin.c +++ b/lib/dns/xfrin.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: xfrin.c,v 1.138 2004/10/13 22:24:18 marka Exp $ */ +/* $Id: xfrin.c,v 1.139 2005/04/27 04:56:53 sra Exp $ */ + +/*! \file */ #include @@ -51,7 +53,7 @@ * Incoming AXFR and IXFR. */ -/* +/*% * It would be non-sensical (or at least obtuse) to use FAIL() with an * ISC_R_SUCCESS code, but the test is there to keep the Solaris compiler * from complaining about "end-of-loop code not reached". @@ -66,7 +68,7 @@ if (result != ISC_R_SUCCESS) goto failure; \ } while (0) -/* +/*% * The states of the *XFR state machine. We handle both IXFR and AXFR * with a single integrated state machine because they cannot be distinguished * immediately - an AXFR response to an IXFR request can only be detected @@ -83,7 +85,7 @@ typedef enum { XFRST_END } xfrin_state_t; -/* +/*% * Incoming zone transfer context. */ @@ -98,18 +100,18 @@ struct dns_xfrin_ctx { isc_timer_t *timer; isc_socketmgr_t *socketmgr; - int connects; /* Connect in progress */ - int sends; /* Send in progress */ - int recvs; /* Receive in progress */ + int connects; /*%< Connect in progress */ + int sends; /*%< Send in progress */ + int recvs; /*%< Receive in progress */ isc_boolean_t shuttingdown; - dns_name_t name; /* Name of zone to transfer */ + dns_name_t name; /*%< Name of zone to transfer */ dns_rdataclass_t rdclass; isc_boolean_t checkid; dns_messageid_t id; - /* + /*% * Requested transfer type (dns_rdatatype_axfr or * dns_rdatatype_ixfr). The actual transfer type * may differ due to IXFR->AXFR fallback. @@ -120,32 +122,32 @@ struct dns_xfrin_ctx { isc_sockaddr_t sourceaddr; isc_socket_t *socket; - /* Buffer for IXFR/AXFR request message */ + /*% Buffer for IXFR/AXFR request message */ isc_buffer_t qbuffer; unsigned char qbuffer_data[512]; - /* Incoming reply TCP message */ + /*% Incoming reply TCP message */ dns_tcpmsg_t tcpmsg; isc_boolean_t tcpmsg_valid; dns_db_t *db; dns_dbversion_t *ver; - dns_diff_t diff; /* Pending database changes */ - int difflen; /* Number of pending tuples */ + dns_diff_t diff; /*%< Pending database changes */ + int difflen; /*%< Number of pending tuples */ xfrin_state_t state; isc_uint32_t end_serial; isc_boolean_t is_ixfr; - unsigned int nmsg; /* Number of messages recvd */ + unsigned int nmsg; /*%< Number of messages recvd */ - dns_tsigkey_t *tsigkey; /* Key used to create TSIG */ - isc_buffer_t *lasttsig; /* The last TSIG */ - dst_context_t *tsigctx; /* TSIG verification context */ - unsigned int sincetsig; /* recvd since the last TSIG */ + dns_tsigkey_t *tsigkey; /*%< Key used to create TSIG */ + isc_buffer_t *lasttsig; /*%< The last TSIG */ + dst_context_t *tsigctx; /*%< TSIG verification context */ + unsigned int sincetsig; /*%< recvd since the last TSIG */ dns_xfrindone_t done; - /* + /*% * AXFR- and IXFR-specific data. Only one is used at a time * according to the is_ixfr flag, so this could be a union, * but keeping them separate makes it a bit simpler to clean diff --git a/lib/dns/zone.c b/lib/dns/zone.c index 7bbaec0d5c..a2a1d7d548 100644 --- a/lib/dns/zone.c +++ b/lib/dns/zone.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: zone.c,v 1.432 2005/03/15 00:20:59 marka Exp $ */ +/* $Id: zone.c,v 1.433 2005/04/27 04:56:53 sra Exp $ */ + +/*! \file */ #include @@ -80,7 +82,7 @@ #define IO_MAGIC ISC_MAGIC('Z', 'm', 'I', 'O') #define DNS_IO_VALID(load) ISC_MAGIC_VALID(load, IO_MAGIC) -/* +/*% * Ensure 'a' is at least 'min' but not more than 'max'. */ #define RANGE(a, min, max) \ @@ -89,16 +91,16 @@ /* * Default values. */ -#define DNS_DEFAULT_IDLEIN 3600 /* 1 hour */ -#define DNS_DEFAULT_IDLEOUT 3600 /* 1 hour */ -#define MAX_XFER_TIME (2*3600) /* Documented default is 2 hours */ +#define DNS_DEFAULT_IDLEIN 3600 /*%< 1 hour */ +#define DNS_DEFAULT_IDLEOUT 3600 /*%< 1 hour */ +#define MAX_XFER_TIME (2*3600) /*%< Documented default is 2 hours */ #ifndef DNS_MAX_EXPIRE -#define DNS_MAX_EXPIRE 14515200 /* 24 weeks */ +#define DNS_MAX_EXPIRE 14515200 /*%< 24 weeks */ #endif #ifndef DNS_DUMP_DELAY -#define DNS_DUMP_DELAY 900 /* 15 minutes */ +#define DNS_DUMP_DELAY 900 /*%< 15 minutes */ #endif typedef struct dns_notify dns_notify_t; @@ -209,7 +211,7 @@ struct dns_zone { isc_uint32_t sigvalidityinterval; dns_view_t *view; dns_acache_t *acache; - /* + /*% * Zones in certain states such as "waiting for zone transfer" * or "zone transfer in progress" are kept on per-state linked lists * in the zone manager using the 'statelink' field. The 'statelist' @@ -218,7 +220,7 @@ struct dns_zone { */ ISC_LINK(dns_zone_t) statelink; dns_zonelist_t *statelist; - /* + /*% * Optional per-zone statistics counters (NULL if not present). */ isc_uint64_t *counters; @@ -237,35 +239,35 @@ struct dns_zone { (z)->flags &= ~(f); \ } while (0) /* XXX MPA these may need to go back into zone.h */ -#define DNS_ZONEFLG_REFRESH 0x00000001U /* refresh check in progress */ -#define DNS_ZONEFLG_NEEDDUMP 0x00000002U /* zone need consolidation */ -#define DNS_ZONEFLG_USEVC 0x00000004U /* use tcp for refresh query */ -#define DNS_ZONEFLG_DUMPING 0x00000008U /* a dump is in progress */ -#define DNS_ZONEFLG_HASINCLUDE 0x00000010U /* $INCLUDE in zone file */ -#define DNS_ZONEFLG_LOADED 0x00000020U /* database has loaded */ -#define DNS_ZONEFLG_EXITING 0x00000040U /* zone is being destroyed */ -#define DNS_ZONEFLG_EXPIRED 0x00000080U /* zone has expired */ -#define DNS_ZONEFLG_NEEDREFRESH 0x00000100U /* refresh check needed */ -#define DNS_ZONEFLG_UPTODATE 0x00000200U /* zone contents are +#define DNS_ZONEFLG_REFRESH 0x00000001U /*%< refresh check in progress */ +#define DNS_ZONEFLG_NEEDDUMP 0x00000002U /*%< zone need consolidation */ +#define DNS_ZONEFLG_USEVC 0x00000004U /*%< use tcp for refresh query */ +#define DNS_ZONEFLG_DUMPING 0x00000008U /*%< a dump is in progress */ +#define DNS_ZONEFLG_HASINCLUDE 0x00000010U /*%< $INCLUDE in zone file */ +#define DNS_ZONEFLG_LOADED 0x00000020U /*%< database has loaded */ +#define DNS_ZONEFLG_EXITING 0x00000040U /*%< zone is being destroyed */ +#define DNS_ZONEFLG_EXPIRED 0x00000080U /*%< zone has expired */ +#define DNS_ZONEFLG_NEEDREFRESH 0x00000100U /*%< refresh check needed */ +#define DNS_ZONEFLG_UPTODATE 0x00000200U /*%< zone contents are * uptodate */ -#define DNS_ZONEFLG_NEEDNOTIFY 0x00000400U /* need to send out notify +#define DNS_ZONEFLG_NEEDNOTIFY 0x00000400U /*%< need to send out notify * messages */ -#define DNS_ZONEFLG_DIFFONRELOAD 0x00000800U /* generate a journal diff on +#define DNS_ZONEFLG_DIFFONRELOAD 0x00000800U /*%< generate a journal diff on * reload */ -#define DNS_ZONEFLG_NOMASTERS 0x00001000U /* an attempt to refresh a +#define DNS_ZONEFLG_NOMASTERS 0x00001000U /*%< an attempt to refresh a * zone with no masters * occured */ -#define DNS_ZONEFLG_LOADING 0x00002000U /* load from disk in progress*/ -#define DNS_ZONEFLG_HAVETIMERS 0x00004000U /* timer values have been set +#define DNS_ZONEFLG_LOADING 0x00002000U /*%< load from disk in progress*/ +#define DNS_ZONEFLG_HAVETIMERS 0x00004000U /*%< timer values have been set * from SOA (if not set, we * are still using * default timer values) */ -#define DNS_ZONEFLG_FORCEXFER 0x00008000U /* Force a zone xfer */ +#define DNS_ZONEFLG_FORCEXFER 0x00008000U /*%< Force a zone xfer */ #define DNS_ZONEFLG_NOREFRESH 0x00010000U #define DNS_ZONEFLG_DIALNOTIFY 0x00020000U #define DNS_ZONEFLG_DIALREFRESH 0x00040000U #define DNS_ZONEFLG_SHUTDOWN 0x00080000U -#define DNS_ZONEFLAG_NOIXFR 0x00100000U /* IXFR failed, force AXFR */ +#define DNS_ZONEFLAG_NOIXFR 0x00100000U /*%< IXFR failed, force AXFR */ #define DNS_ZONEFLG_FLUSH 0x00200000U #define DNS_ZONEFLG_NOEDNS 0x00400000U #define DNS_ZONEFLG_USEALTXFRSRC 0x00800000U @@ -305,7 +307,7 @@ struct dns_zonemgr { dns_iolist_t low; }; -/* +/*% * Hold notify state. */ struct dns_notify { @@ -322,7 +324,7 @@ struct dns_notify { #define DNS_NOTIFY_NOSOA 0x0001U -/* +/*% * dns_stub holds state while performing a 'stub' transfer. * 'db' is the zone's 'db' or a new one if this is the initial * transfer. @@ -336,7 +338,7 @@ struct dns_stub { dns_dbversion_t *version; }; -/* +/*% * Hold load state. */ struct dns_load { @@ -348,7 +350,7 @@ struct dns_load { dns_rdatacallbacks_t callbacks; }; -/* +/*% * Hold forward state. */ struct dns_forward { @@ -363,7 +365,7 @@ struct dns_forward { void *callback_arg; }; -/* +/*% * Hold IO request state. */ struct dns_io { @@ -4771,7 +4773,7 @@ dns_zone_notifyreceive(dns_zone_t *zone, isc_sockaddr_t *from, * If type != T_SOA return DNS_R_REFUSED. We don't yet support * ROLLOVER. * - * SOA: RFC 1996 + * SOA: RFC1996 * Check that 'from' is a valid notify source, (zone->masters). * Return DNS_R_REFUSED if not. * diff --git a/lib/dns/zonekey.c b/lib/dns/zonekey.c index 68f96a052f..8a1e7d0ef5 100644 --- a/lib/dns/zonekey.c +++ b/lib/dns/zonekey.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: zonekey.c,v 1.5 2004/03/05 05:09:26 marka Exp $ */ +/* $Id: zonekey.c,v 1.6 2005/04/27 04:56:53 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/dns/zt.c b/lib/dns/zt.c index faf6513b45..ae6a7f6c6d 100644 --- a/lib/dns/zt.c +++ b/lib/dns/zt.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: zt.c,v 1.40 2005/01/17 04:11:33 marka Exp $ */ +/* $Id: zt.c,v 1.41 2005/04/27 04:56:53 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/assertions.c b/lib/isc/assertions.c index dabcff8c3a..7803589f13 100644 --- a/lib/isc/assertions.c +++ b/lib/isc/assertions.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: assertions.c,v 1.17 2004/03/05 05:10:43 marka Exp $ */ +/* $Id: assertions.c,v 1.18 2005/04/27 04:57:11 sra Exp $ */ + +/*! \file */ #include @@ -25,20 +27,20 @@ #include #include -/* +/*% * Forward. */ - static void default_callback(const char *, int, isc_assertiontype_t, const char *); -/* +/*% * Public. */ LIBISC_EXTERNAL_DATA isc_assertioncallback_t isc_assertion_failed = default_callback; +/*% Set callback. */ void isc_assertion_setcallback(isc_assertioncallback_t cb) { if (cb == NULL) @@ -47,6 +49,7 @@ isc_assertion_setcallback(isc_assertioncallback_t cb) { isc_assertion_failed = cb; } +/*% Type to Text */ const char * isc_assertion_typetotext(isc_assertiontype_t type) { const char *result; diff --git a/lib/isc/base64.c b/lib/isc/base64.c index 36e76e4f8f..e3ed3b7d80 100644 --- a/lib/isc/base64.c +++ b/lib/isc/base64.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: base64.c,v 1.28 2004/03/05 05:10:43 marka Exp $ */ +/* $Id: base64.c,v 1.29 2005/04/27 04:57:11 sra Exp $ */ + +/*! \file */ #include @@ -32,7 +34,8 @@ } while (0) -/* +/*@{*/ +/*! * These static functions are also present in lib/dns/rdata.c. I'm not * sure where they should go. -- bwelling */ @@ -44,6 +47,7 @@ mem_tobuffer(isc_buffer_t *target, void *base, unsigned int length); static const char base64[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/="; +/*@}*/ isc_result_t isc_base64_totext(isc_region_t *source, int wordlength, @@ -90,14 +94,14 @@ isc_base64_totext(isc_region_t *source, int wordlength, return (ISC_R_SUCCESS); } -/* +/*% * State of a base64 decoding process in progress. */ typedef struct { - int length; /* Desired length of binary data or -1 */ - isc_buffer_t *target; /* Buffer for resulting binary data */ - int digits; /* Number of buffered base64 digits */ - isc_boolean_t seen_end; /* True if "=" end marker seen */ + int length; /*%< Desired length of binary data or -1 */ + isc_buffer_t *target; /*%< Buffer for resulting binary data */ + int digits; /*%< Number of buffered base64 digits */ + isc_boolean_t seen_end; /*%< True if "=" end marker seen */ int val[4]; } base64_decode_ctx_t; diff --git a/lib/isc/bitstring.c b/lib/isc/bitstring.c index 419be8d5f9..61d797cd25 100644 --- a/lib/isc/bitstring.c +++ b/lib/isc/bitstring.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: bitstring.c,v 1.13 2004/03/05 05:10:43 marka Exp $ */ +/* $Id: bitstring.c,v 1.14 2005/04/27 04:57:11 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/buffer.c b/lib/isc/buffer.c index eec3068ad0..32cd8fa01c 100644 --- a/lib/isc/buffer.c +++ b/lib/isc/buffer.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: buffer.c,v 1.40 2004/03/05 05:10:44 marka Exp $ */ +/* $Id: buffer.c,v 1.41 2005/04/27 04:57:11 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/bufferlist.c b/lib/isc/bufferlist.c index d1063bca56..0ecbcc8a25 100644 --- a/lib/isc/bufferlist.c +++ b/lib/isc/bufferlist.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: bufferlist.c,v 1.13 2004/03/05 05:10:44 marka Exp $ */ +/* $Id: bufferlist.c,v 1.14 2005/04/27 04:57:11 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/commandline.c b/lib/isc/commandline.c index 4a1ff50525..5d7187b464 100644 --- a/lib/isc/commandline.c +++ b/lib/isc/commandline.c @@ -48,9 +48,9 @@ * SUCH DAMAGE. */ -/* $Id: commandline.c,v 1.16 2004/03/05 05:10:44 marka Exp $ */ +/* $Id: commandline.c,v 1.17 2005/04/27 04:57:11 sra Exp $ */ -/* +/*! \file * This file was adapted from the NetBSD project's source tree, RCS ID: * NetBSD: getopt.c,v 1.15 1999/09/20 04:39:37 lukem Exp * @@ -59,8 +59,8 @@ */ /* - * Principal Authors: Computer Systems Research Group at UC Berkeley - * Principal ISC caretaker: DCL + * \author Principal Authors: Computer Systems Research Group at UC Berkeley + * \author Principal ISC caretaker: DCL */ #include @@ -72,17 +72,17 @@ #include #include -/* Index into parent argv vector. */ +/*% Index into parent argv vector. */ LIBISC_EXTERNAL_DATA int isc_commandline_index = 1; -/* Character checked for validity. */ +/*% Character checked for validity. */ LIBISC_EXTERNAL_DATA int isc_commandline_option; -/* Argument associated with option. */ +/*% Argument associated with option. */ LIBISC_EXTERNAL_DATA char *isc_commandline_argument; -/* For printing error messages. */ +/*% For printing error messages. */ LIBISC_EXTERNAL_DATA char *isc_commandline_progname; -/* Print error messages. */ +/*% Print error messages. */ LIBISC_EXTERNAL_DATA isc_boolean_t isc_commandline_errprint = ISC_TRUE; -/* Reset processing. */ +/*% Reset processing. */ LIBISC_EXTERNAL_DATA isc_boolean_t isc_commandline_reset = ISC_TRUE; static char endopt = '\0'; @@ -91,7 +91,7 @@ static char endopt = '\0'; #define BADARG ':' #define ENDOPT &endopt -/* +/*! * getopt -- * Parse argc/argv argument vector. */ diff --git a/lib/isc/entropy.c b/lib/isc/entropy.c index 60d1a883c0..54a0c23e58 100644 --- a/lib/isc/entropy.c +++ b/lib/isc/entropy.c @@ -15,12 +15,16 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: entropy.c,v 1.11 2004/03/05 05:10:44 marka Exp $ */ +/* $Id: entropy.c,v 1.12 2005/04/27 04:57:11 sra Exp $ */ -/* +/*! \file + * \brief * This is the system independent part of the entropy module. It is * compiled via inclusion from the relevant OS source file, ie, - * unix/entropy.c or win32/entropy.c. + * \link unix/entropy.c unix/entropy.c \endlink or win32/entropy.c. + * + * \author Much of this code is modeled after the NetBSD /dev/random implementation, + * written by Michael Graff . */ #include @@ -42,10 +46,6 @@ #include #include -/* - * Much of this code is modeled after the NetBSD /dev/random implementation, - * written by Michael Graff . - */ #define ENTROPY_MAGIC ISC_MAGIC('E', 'n', 't', 'e') #define SOURCE_MAGIC ISC_MAGIC('E', 'n', 't', 's') @@ -58,26 +58,28 @@ *** you are doing. ***/ -/* - * size of entropy pool in 32-bit words. This _MUST_ be a power of 2. +/*% + * Size of entropy pool in 32-bit words. This _MUST_ be a power of 2. */ #define RND_POOLWORDS 128 +/*% Pool in bytes. */ #define RND_POOLBYTES (RND_POOLWORDS * 4) +/*% Pool in bits. */ #define RND_POOLBITS (RND_POOLWORDS * 32) -/* +/*% * Number of bytes returned per hash. This must be true: * threshold * 2 <= digest_size_in_bytes */ #define RND_ENTROPY_THRESHOLD 10 #define THRESHOLD_BITS (RND_ENTROPY_THRESHOLD * 8) -/* +/*% * Size of the input event queue in samples. */ #define RND_EVENTQSIZE 32 -/* +/*% * The number of times we'll "reseed" for pseudorandom seeds. This is an * extremely weak pseudorandom seed. If the caller is using lots of * pseudorandom data and they cannot provide a stronger random source, @@ -86,12 +88,13 @@ */ #define RND_INITIALIZE 128 +/*% Entropy Pool */ typedef struct { - isc_uint32_t cursor; /* current add point in the pool */ - isc_uint32_t entropy; /* current entropy estimate in bits */ - isc_uint32_t pseudo; /* bits extracted in pseudorandom */ - isc_uint32_t rotate; /* how many bits to rotate by */ - isc_uint32_t pool[RND_POOLWORDS]; /* random pool data */ + isc_uint32_t cursor; /*%< current add point in the pool */ + isc_uint32_t entropy; /*%< current entropy estimate in bits */ + isc_uint32_t pseudo; /*%< bits extracted in pseudorandom */ + isc_uint32_t rotate; /*%< how many bits to rotate by */ + isc_uint32_t pool[RND_POOLWORDS]; /*%< random pool data */ } isc_entropypool_t; struct isc_entropy { @@ -107,13 +110,14 @@ struct isc_entropy { ISC_LIST(isc_entropysource_t) sources; }; +/*% Sample Queue */ typedef struct { - isc_uint32_t last_time; /* last time recorded */ - isc_uint32_t last_delta; /* last delta value */ - isc_uint32_t last_delta2; /* last delta2 value */ - isc_uint32_t nsamples; /* number of samples filled in */ - isc_uint32_t *samples; /* the samples */ - isc_uint32_t *extra; /* extra samples added in */ + isc_uint32_t last_time; /*%< last time recorded */ + isc_uint32_t last_delta; /*%< last delta value */ + isc_uint32_t last_delta2; /*%< last delta2 value */ + isc_uint32_t nsamples; /*%< number of samples filled in */ + isc_uint32_t *samples; /*%< the samples */ + isc_uint32_t *extra; /*%< extra samples added in */ } sample_queue_t; typedef struct { @@ -137,7 +141,7 @@ struct isc_entropysource { unsigned int magic; unsigned int type; isc_entropy_t *ent; - isc_uint32_t total; /* entropy from this source */ + isc_uint32_t total; /*%< entropy from this source */ ISC_LINK(isc_entropysource_t) link; char name[32]; isc_boolean_t bad; @@ -151,12 +155,13 @@ struct isc_entropysource { } sources; }; -#define ENTROPY_SOURCETYPE_SAMPLE 1 /* Type is a sample source */ -#define ENTROPY_SOURCETYPE_FILE 2 /* Type is a file source */ -#define ENTROPY_SOURCETYPE_CALLBACK 3 /* Type is a callback source */ -#define ENTROPY_SOURCETYPE_USOCKET 4 /* Type is a Unix socket source */ +#define ENTROPY_SOURCETYPE_SAMPLE 1 /*%< Type is a sample source */ +#define ENTROPY_SOURCETYPE_FILE 2 /*%< Type is a file source */ +#define ENTROPY_SOURCETYPE_CALLBACK 3 /*%< Type is a callback source */ +#define ENTROPY_SOURCETYPE_USOCKET 4 /*%< Type is a Unix socket source */ -/* +/*@{*/ +/*% * The random pool "taps" */ #define TAP1 99 @@ -164,8 +169,10 @@ struct isc_entropysource { #define TAP3 31 #define TAP4 9 #define TAP5 7 +/*@}*/ -/* +/*@{*/ +/*% * Declarations for function provided by the system dependent sources that * include this file. */ @@ -181,6 +188,7 @@ destroyfilesource(isc_entropyfilesource_t *source); static void destroyusocketsource(isc_entropyusocketsource_t *source); +/*@}*/ static void samplequeue_release(isc_entropy_t *ent, sample_queue_t *sq) { @@ -211,7 +219,7 @@ samplesource_allocate(isc_entropy_t *ent, sample_queue_t *sq) { return (ISC_R_SUCCESS); } -/* +/*% * Add in entropy, even when the value we're adding in could be * very large. */ @@ -225,7 +233,7 @@ add_entropy(isc_entropy_t *ent, isc_uint32_t entropy) { ent->pool.entropy = ISC_MIN(entropy, RND_POOLBITS); } -/* +/*% * Decrement the amount of entropy the pool has. */ static inline void @@ -234,7 +242,7 @@ subtract_entropy(isc_entropy_t *ent, isc_uint32_t entropy) { ent->pool.entropy -= entropy; } -/* +/*! * Add in entropy, even when the value we're adding in could be * very large. */ @@ -248,7 +256,7 @@ add_pseudo(isc_entropy_t *ent, isc_uint32_t pseudo) { ent->pool.pseudo = ISC_MIN(pseudo, RND_POOLBITS * 8); } -/* +/*! * Decrement the amount of pseudo the pool has. */ static inline void @@ -257,7 +265,7 @@ subtract_pseudo(isc_entropy_t *ent, isc_uint32_t pseudo) { ent->pool.pseudo -= pseudo; } -/* +/*! * Add one word to the pool, rotating the input as needed. */ static inline void @@ -292,7 +300,7 @@ entropypool_add_word(isc_entropypool_t *rp, isc_uint32_t val) { } } -/* +/*! * Add a buffer's worth of data to the pool. * * Requires that the lock is held on the entropy pool. @@ -362,7 +370,7 @@ reseed(isc_entropy_t *ent) { entropypool_adddata(ent, &pid, sizeof(pid), 0); } - /* + /*! * After we've reseeded 100 times, only add new timing info every * 50 requests. This will keep us from using lots and lots of * CPU just to return bad pseudorandom data anyway. @@ -382,7 +390,7 @@ estimate_entropy(sample_queue_t *sq, isc_uint32_t t) { isc_int32_t delta2; isc_int32_t delta3; - /* + /*! * If the time counter has overflowed, calculate the real difference. * If it has not, it is simpler. */ @@ -703,7 +711,7 @@ isc_entropy_create(isc_mem_t *mctx, isc_entropy_t **entp) { return (ret); } -/* +/*! * Requires "ent" be locked. */ static void @@ -989,7 +997,7 @@ isc_entropy_createsamplesource(isc_entropy_t *ent, return (ret); } -/* +/*! * Add a sample, and return ISC_R_SUCCESS if the queue has become full, * ISC_R_NOENTROPY if it has space remaining, and ISC_R_NOMORE if the * queue was full when this function was called. diff --git a/lib/isc/error.c b/lib/isc/error.c index 202021bd74..bdea3ac069 100644 --- a/lib/isc/error.c +++ b/lib/isc/error.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: error.c,v 1.17 2004/03/05 05:10:44 marka Exp $ */ +/* $Id: error.c,v 1.18 2005/04/27 04:57:12 sra Exp $ */ + +/*! \file */ #include @@ -25,14 +27,17 @@ #include #include +/*% Default unexpected callback. */ static void default_unexpected_callback(const char *, int, const char *, va_list) ISC_FORMAT_PRINTF(3, 0); +/*% Default fatal callback. */ static void default_fatal_callback(const char *, int, const char *, va_list) ISC_FORMAT_PRINTF(3, 0); +/*% unexpected_callback */ static isc_errorcallback_t unexpected_callback = default_unexpected_callback; static isc_errorcallback_t fatal_callback = default_fatal_callback; diff --git a/lib/isc/event.c b/lib/isc/event.c index b2eb671d0e..0fe784620a 100644 --- a/lib/isc/event.c +++ b/lib/isc/event.c @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: event.c,v 1.17 2004/03/05 05:10:44 marka Exp $ */ +/* $Id: event.c,v 1.18 2005/04/27 04:57:12 sra Exp $ */ -/* - * Principal Author: Bob Halley +/*! + * \file + * \author Principal Author: Bob Halley */ #include diff --git a/lib/isc/fsaccess.c b/lib/isc/fsaccess.c index 5c8da376a1..f482ddd84c 100644 --- a/lib/isc/fsaccess.c +++ b/lib/isc/fsaccess.c @@ -15,16 +15,17 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: fsaccess.c,v 1.6 2004/03/05 05:10:45 marka Exp $ */ +/* $Id: fsaccess.c,v 1.7 2005/04/27 04:57:12 sra Exp $ */ -/* +/*! \file + * \brief * This file contains the OS-independent functionality of the API. */ #include #include #include -/* +/*! * Shorthand. Maybe ISC__FSACCESS_PERMISSIONBITS should not even be in * . Could check consistency with sizeof(isc_fsaccess_t) * and the number of bits in each function. diff --git a/lib/isc/hash.c b/lib/isc/hash.c index 4c771aee94..492346f4e8 100644 --- a/lib/isc/hash.c +++ b/lib/isc/hash.c @@ -15,14 +15,12 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: hash.c,v 1.6 2004/03/05 05:10:45 marka Exp $ */ +/* $Id: hash.c,v 1.7 2005/04/27 04:57:12 sra Exp $ */ -/* +/*! \file * Some portion of this code was derived from universal hash function * libraries of Rice University. - */ - -/* "UH Universal Hashing Library" +\section license UH Universal Hashing Library Copyright ((c)) 2002, Rice University All rights reserved. @@ -75,28 +73,31 @@ if advised of the possibility of such damage. #define HASH_MAGIC ISC_MAGIC('H', 'a', 's', 'h') #define VALID_HASH(h) ISC_MAGIC_VALID((h), HASH_MAGIC) -/* +/*% * A large 32-bit prime number that specifies the range of the hash output. */ #define PRIME32 0xFFFFFFFB /* 2^32 - 5 */ -/* +/*@{*/ +/*% * Types of random seed and hash accumulator. Perhaps they can be system * dependent. */ typedef isc_uint32_t hash_accum_t; typedef isc_uint16_t hash_random_t; +/*@}*/ +/*% isc hash structure */ struct isc_hash { unsigned int magic; isc_mem_t *mctx; isc_mutex_t lock; isc_boolean_t initialized; isc_refcount_t refcnt; - isc_entropy_t *entropy; /* entropy source */ - unsigned int limit; /* upper limit of key length */ - size_t vectorlen; /* size of the vector below */ - hash_random_t *rndvector; /* random vector for universal hashing */ + isc_entropy_t *entropy; /*%< entropy source */ + unsigned int limit; /*%< upper limit of key length */ + size_t vectorlen; /*%< size of the vector below */ + hash_random_t *rndvector; /*%< random vector for universal hashing */ }; static isc_rwlock_t createlock; diff --git a/lib/isc/heap.c b/lib/isc/heap.c index 37b47f6fc0..617e239ee8 100644 --- a/lib/isc/heap.c +++ b/lib/isc/heap.c @@ -15,15 +15,15 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: heap.c,v 1.30 2004/03/05 05:10:45 marka Exp $ */ +/* $Id: heap.c,v 1.31 2005/04/27 04:57:12 sra Exp $ */ -/* +/*! \file * Heap implementation of priority queues adapted from the following: * - * _Introduction to Algorithms_, Cormen, Leiserson, and Rivest, + * \li "Introduction to Algorithms," Cormen, Leiserson, and Rivest, * MIT Press / McGraw Hill, 1990, ISBN 0-262-03141-8, chapter 7. * - * _Algorithms_, Second Edition, Sedgewick, Addison-Wesley, 1988, + * \li "Algorithms," Second Edition, Sedgewick, Addison-Wesley, 1988, * ISBN 0-201-06673-4, chapter 11. */ @@ -35,20 +35,22 @@ #include /* Required for memcpy. */ #include -/* +/*@{*/ +/*% * Note: to make heap_parent and heap_left easy to compute, the first * element of the heap array is not used; i.e. heap subscripts are 1-based, * not 0-based. */ #define heap_parent(i) ((i) >> 1) #define heap_left(i) ((i) << 1) +/*@}*/ #define SIZE_INCREMENT 1024 #define HEAP_MAGIC ISC_MAGIC('H', 'E', 'A', 'P') #define VALID_HEAP(h) ISC_MAGIC_VALID(h, HEAP_MAGIC) -/* +/*% * When the heap is in a consistent state, the following invariant * holds true: for every element i > 1, heap_parent(i) has a priority * higher than or equal to that of i. @@ -57,6 +59,7 @@ ! heap->compare(heap->array[(i)], \ heap->array[heap_parent(i)])) +/*% ISC heap structure. */ struct isc_heap { unsigned int magic; isc_mem_t * mctx; @@ -68,6 +71,7 @@ struct isc_heap { isc_heapindex_t index; }; +/*% Create a heap. */ isc_result_t isc_heap_create(isc_mem_t *mctx, isc_heapcompare_t compare, isc_heapindex_t index, unsigned int size_increment, @@ -98,6 +102,7 @@ isc_heap_create(isc_mem_t *mctx, isc_heapcompare_t compare, return (ISC_R_SUCCESS); } +/*% Destroy a heap. */ void isc_heap_destroy(isc_heap_t **heapp) { isc_heap_t *heap; @@ -180,6 +185,7 @@ sink_down(isc_heap_t *heap, unsigned int i, void *elt) { INSIST(HEAPCONDITION(i)); } +/*% Insert a heap. */ isc_result_t isc_heap_insert(isc_heap_t *heap, void *elt) { unsigned int i; @@ -195,6 +201,7 @@ isc_heap_insert(isc_heap_t *heap, void *elt) { return (ISC_R_SUCCESS); } +/*% Delete a heap. */ void isc_heap_delete(isc_heap_t *heap, unsigned int i) { void *elt; diff --git a/lib/isc/hex.c b/lib/isc/hex.c index 50a9a85980..4b3f414df5 100644 --- a/lib/isc/hex.c +++ b/lib/isc/hex.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: hex.c,v 1.14 2004/03/05 05:10:45 marka Exp $ */ +/* $Id: hex.c,v 1.15 2005/04/27 04:57:12 sra Exp $ */ + +/*! \file */ #include @@ -73,13 +75,13 @@ isc_hex_totext(isc_region_t *source, int wordlength, return (ISC_R_SUCCESS); } -/* +/*% * State of a hex decoding process in progress. */ typedef struct { - int length; /* Desired length of binary data or -1 */ - isc_buffer_t *target; /* Buffer for resulting binary data */ - int digits; /* Number of buffered hex digits */ + int length; /*%< Desired length of binary data or -1 */ + isc_buffer_t *target; /*%< Buffer for resulting binary data */ + int digits; /*%< Number of buffered hex digits */ int val[2]; } hex_decode_ctx_t; diff --git a/lib/isc/hmacmd5.c b/lib/isc/hmacmd5.c index aba1b23956..fff1018de6 100644 --- a/lib/isc/hmacmd5.c +++ b/lib/isc/hmacmd5.c @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: hmacmd5.c,v 1.7 2004/03/05 05:10:45 marka Exp $ */ +/* $Id: hmacmd5.c,v 1.8 2005/04/27 04:57:12 sra Exp $ */ -/* +/*! \file * This code implements the HMAC-MD5 keyed hash algorithm - * described in RFC 2104. + * described in RFC2104. */ #include "config.h" @@ -35,7 +35,7 @@ #define IPAD 0x36 #define OPAD 0x5C -/* +/*! * Start HMAC-MD5 process. Initialize an md5 context and digest the key. */ void @@ -68,7 +68,7 @@ isc_hmacmd5_invalidate(isc_hmacmd5_t *ctx) { memset(ctx, 0, sizeof(ctx)); } -/* +/*! * Update context to reflect the concatenation of another buffer full * of bytes. */ @@ -79,7 +79,7 @@ isc_hmacmd5_update(isc_hmacmd5_t *ctx, const unsigned char *buf, isc_md5_update(&ctx->md5ctx, buf, len); } -/* +/*! * Compute signature - finalize MD5 operation and reapply MD5. */ void @@ -100,7 +100,7 @@ isc_hmacmd5_sign(isc_hmacmd5_t *ctx, unsigned char *digest) { isc_hmacmd5_invalidate(ctx); } -/* +/*! * Verify signature - finalize MD5 operation and reapply MD5, then * compare to the supplied digest. */ diff --git a/lib/isc/include/isc/app.h b/lib/isc/include/isc/app.h index 27b0bd7429..1b5a307100 100644 --- a/lib/isc/include/isc/app.h +++ b/lib/isc/include/isc/app.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: app.h,v 1.2 2004/03/05 05:10:55 marka Exp $ */ +/* $Id: app.h,v 1.3 2005/04/27 04:57:16 sra Exp $ */ #ifndef ISC_APP_H #define ISC_APP_H 1 @@ -24,18 +24,18 @@ ***** Module Info *****/ -/* - * ISC Application Support +/*! \file + * \brief ISC Application Support * * Dealing with program termination can be difficult, especially in a * multithreaded program. The routines in this module help coordinate * the shutdown process. They are used as follows by the initial (main) * thread of the application: * - * isc_app_start(); Call very early in main(), before + *\li isc_app_start(); Call very early in main(), before * any other threads have been created. * - * isc_app_run(); This will post any on-run events, + *\li isc_app_run(); This will post any on-run events, * and then block until application * shutdown is requested. A shutdown * request is made by calling @@ -44,7 +44,7 @@ * After isc_app_run() returns, the * application should shutdown itself. * - * isc_app_finish(); Call very late in main(). + *\li isc_app_finish(); Call very late in main(). * * Applications that want to use SIGHUP/isc_app_reload() to trigger reloading * should check the result of isc_app_run() and call the reload routine if @@ -54,22 +54,22 @@ * Use of this module is not required. In particular, isc_app_start() is * NOT an ISC library initialization routine. * - * MP: + * \li MP: * Clients must ensure that isc_app_start(), isc_app_run(), and * isc_app_finish() are called at most once. isc_app_shutdown() * is safe to use by any thread (provided isc_app_start() has been * called previously). * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: + * \li Resources: * None. * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ @@ -87,8 +87,8 @@ ISC_LANG_BEGINDECLS isc_result_t isc_app_start(void); -/* - * Start an ISC library application. +/*!< + * \brief Start an ISC library application. * * Notes: * This call should be made before any other ISC library call, and as @@ -98,8 +98,8 @@ isc_app_start(void); isc_result_t isc_app_onrun(isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action, void *arg); -/* - * Request delivery of an event when the application is run. +/*!< + * \brief Request delivery of an event when the application is run. * * Requires: * isc_app_start() has been called. @@ -111,99 +111,99 @@ isc_app_onrun(isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action, isc_result_t isc_app_run(void); -/* - * Run an ISC library application. +/*!< + * \brief Run an ISC library application. * * Notes: - * The caller (typically the initial thread of an application) will + *\li The caller (typically the initial thread of an application) will * block until shutdown is requested. When the call returns, the * caller should start shutting down the application. * * Requires: - * isc_app_start() has been called. + *\li isc_app_start() has been called. * * Ensures: - * Any events requested via isc_app_onrun() will have been posted (in + *\li Any events requested via isc_app_onrun() will have been posted (in * FIFO order) before isc_app_run() blocks. * * Returns: - * ISC_R_SUCCESS Shutdown has been requested. - * ISC_R_RELOAD Reload has been requested. + *\li ISC_R_SUCCESS Shutdown has been requested. + *\li ISC_R_RELOAD Reload has been requested. */ isc_result_t isc_app_shutdown(void); -/* - * Request application shutdown. +/*!< + * \brief Request application shutdown. * * Notes: - * It is safe to call isc_app_shutdown() multiple times. Shutdown will + *\li It is safe to call isc_app_shutdown() multiple times. Shutdown will * only be triggered once. * * Requires: - * isc_app_run() has been called. + *\li isc_app_run() has been called. * * Returns: - * ISC_R_SUCCESS - * ISC_R_UNEXPECTED + *\li ISC_R_SUCCESS + *\li ISC_R_UNEXPECTED */ isc_result_t isc_app_reload(void); -/* - * Request application reload. +/*!< + * \brief Request application reload. * * Requires: - * isc_app_run() has been called. + *\li isc_app_run() has been called. * * Returns: - * ISC_R_SUCCESS - * ISC_R_UNEXPECTED + *\li ISC_R_SUCCESS + *\li ISC_R_UNEXPECTED */ void isc_app_finish(void); -/* - * Finish an ISC library application. +/*!< + * \brief Finish an ISC library application. * * Notes: - * This call should be made at or near the end of main(). + *\li This call should be made at or near the end of main(). * * Requires: - * isc_app_start() has been called. + *\li isc_app_start() has been called. * * Ensures: - * Any resources allocated by isc_app_start() have been released. + *\li Any resources allocated by isc_app_start() have been released. */ void isc_app_block(void); -/* - * Indicate that a blocking operation will be performed. +/*!< + * \brief Indicate that a blocking operation will be performed. * * Notes: - * If a blocking operation is in process, a call to isc_app_shutdown() + *\li If a blocking operation is in process, a call to isc_app_shutdown() * or an external signal will abort the program, rather than allowing * clean shutdown. This is primarily useful for reading user input. * * Requires: - * isc_app_start() has been called. - * No other blocking operations are in progress. + * \li isc_app_start() has been called. + * \li No other blocking operations are in progress. */ void isc_app_unblock(void); -/* - * Indicate that a blocking operation is complete. +/*!< + * \brief Indicate that a blocking operation is complete. * * Notes: - * When a blocking operation has completed, return the program to a + * \li When a blocking operation has completed, return the program to a * state where a call to isc_app_shutdown() or an external signal will * shutdown normally. * * Requires: - * isc_app_start() has been called. - * isc_app_block() has been called by the same thread. + * \li isc_app_start() has been called. + * \li isc_app_block() has been called by the same thread. */ diff --git a/lib/isc/include/isc/assertions.h b/lib/isc/include/isc/assertions.h index f2d6e36c54..889a6f8565 100644 --- a/lib/isc/include/isc/assertions.h +++ b/lib/isc/include/isc/assertions.h @@ -16,7 +16,9 @@ */ /* - * $Id: assertions.h,v 1.18 2004/03/05 05:10:55 marka Exp $ + * $Id: assertions.h,v 1.19 2005/04/27 04:57:16 sra Exp $ + */ +/*! \file assertions.h */ #ifndef ISC_ASSERTIONS_H @@ -27,6 +29,7 @@ ISC_LANG_BEGINDECLS +/*% isc assertion type */ typedef enum { isc_assertiontype_require, isc_assertiontype_ensure, diff --git a/lib/isc/include/isc/base64.h b/lib/isc/include/isc/base64.h index e83d0ce157..1632f3d28d 100644 --- a/lib/isc/include/isc/base64.h +++ b/lib/isc/include/isc/base64.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: base64.h,v 1.16 2004/03/05 05:10:55 marka Exp $ */ +/* $Id: base64.h,v 1.17 2005/04/27 04:57:16 sra Exp $ */ #ifndef ISC_BASE64_H #define ISC_BASE64_H 1 +/*! \file */ + #include #include @@ -32,59 +34,59 @@ ISC_LANG_BEGINDECLS isc_result_t isc_base64_totext(isc_region_t *source, int wordlength, const char *wordbreak, isc_buffer_t *target); -/* - * Convert data into base64 encoded text. +/*!< + * \brief Convert data into base64 encoded text. * * Notes: - * The base64 encoded text in 'target' will be divided into + *\li The base64 encoded text in 'target' will be divided into * words of at most 'wordlength' characters, separated by * the 'wordbreak' string. No parentheses will surround * the text. * * Requires: - * 'source' is a region containing binary data - * 'target' is a text buffer containing available space - * 'wordbreak' points to a null-terminated string of + *\li 'source' is a region containing binary data + *\li 'target' is a text buffer containing available space + *\li 'wordbreak' points to a null-terminated string of * zero or more whitespace characters * * Ensures: - * target will contain the base64 encoded version of the data + *\li target will contain the base64 encoded version of the data * in source. The 'used' pointer in target will be advanced as * necessary. */ isc_result_t isc_base64_decodestring(const char *cstr, isc_buffer_t *target); -/* - * Decode a null-terminated base64 string. +/*!< + * \brief Decode a null-terminated base64 string. * * Requires: - * 'cstr' is non-null. - * 'target' is a valid buffer. + *\li 'cstr' is non-null. + *\li 'target' is a valid buffer. * * Returns: - * ISC_R_SUCCESS -- the entire decoded representation of 'cstring' + *\li #ISC_R_SUCCESS -- the entire decoded representation of 'cstring' * fit in 'target'. - * ISC_R_BADBASE64 -- 'cstr' is not a valid base64 encoding. + *\li #ISC_R_BADBASE64 -- 'cstr' is not a valid base64 encoding. * * Other error returns are any possible error code from: - * isc_lex_create(), - * isc_lex_openbuffer(), - * isc_base64_tobuffer(). + *\li isc_lex_create(), + *\li isc_lex_openbuffer(), + *\li isc_base64_tobuffer(). */ isc_result_t isc_base64_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length); -/* - * Convert base64 encoded text from a lexer context into data. +/*!< + * \brief Convert base64 encoded text from a lexer context into data. * * Requires: - * 'lex' is a valid lexer context - * 'target' is a buffer containing binary data - * 'length' is an integer + *\li 'lex' is a valid lexer context + *\li 'target' is a buffer containing binary data + *\li 'length' is an integer * * Ensures: - * target will contain the data represented by the base64 encoded + *\li target will contain the data represented by the base64 encoded * string parsed by the lexer. No more than length bytes will be read, * if length is positive. The 'used' pointer in target will be * advanced as necessary. diff --git a/lib/isc/include/isc/bitstring.h b/lib/isc/include/isc/bitstring.h index 5422a331e3..9f44d9c462 100644 --- a/lib/isc/include/isc/bitstring.h +++ b/lib/isc/include/isc/bitstring.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: bitstring.h,v 1.8 2004/03/05 05:10:55 marka Exp $ */ +/* $Id: bitstring.h,v 1.9 2005/04/27 04:57:16 sra Exp $ */ #ifndef ISC_BITSTRING_H #define ISC_BITSTRING_H 1 @@ -24,8 +24,9 @@ ***** Module Info *****/ -/* - * Bitstring +/*! \file bitstring.h + * + * \brief Bitstring manipulation functions. * * A bitstring is a packed array of bits, stored in a contiguous * sequence of octets. The "most significant bit" (msb) of a bitstring @@ -46,21 +47,25 @@ * long and will take two octets. Let "p" denote a pad bit. In the msb0 * encoding, it would be * + * \verbatim * Octet 0 Octet 1 * | * 1 1 0 1 0 0 0 1 | 1 1 1 p p p p p * ^ | ^ * | | * bit 0 bit 15 + * \endverbatim * * In the lsb0 encoding, it would be * + * \verbatim * Octet 0 Octet 1 * | * p p p p p 1 1 0 | 1 0 0 0 1 1 1 1 * ^ | ^ * | | * bit 15 bit 0 + * \endverbatim */ /*** @@ -91,59 +96,59 @@ struct isc_bitstring { void isc_bitstring_init(isc_bitstring_t *bitstring, unsigned char *data, unsigned int length, unsigned int size, isc_boolean_t lsb0); -/* - * Make 'bitstring' refer to the bitstring of 'size' bits starting +/*!< + * \brief Make 'bitstring' refer to the bitstring of 'size' bits starting * at 'data'. 'length' bits of the bitstring are valid. If 'lsb0' * is set then, bit 0 refers to the least significant bit of the * bitstring. Otherwise bit 0 is the most significant bit. * * Requires: * - * 'bitstring' points to a isc_bitstring_t. + *\li 'bitstring' points to a isc_bitstring_t. * - * 'data' points to an array of unsigned char large enough to hold + *\li 'data' points to an array of unsigned char large enough to hold * 'size' bits. * - * 'length' <= 'size'. + *\li 'length' <= 'size'. * * Ensures: * - * 'bitstring' is a valid bitstring. + *\li 'bitstring' is a valid bitstring. */ void isc_bitstring_invalidate(isc_bitstring_t *bitstring); -/* - * Invalidate 'bitstring'. +/*!< + * \brief Invalidate 'bitstring'. * * Requires: * - * 'bitstring' is a valid bitstring. + *\li 'bitstring' is a valid bitstring. * * Ensures: * - * 'bitstring' is not a valid bitstring. + *\li 'bitstring' is not a valid bitstring. */ void isc_bitstring_copy(isc_bitstring_t *source, unsigned int sbitpos, isc_bitstring_t *target, unsigned int tbitpos, unsigned int n); -/* - * Starting at bit 'sbitpos', copy 'n' bits from 'source' to +/*!< + * \brief Starting at bit 'sbitpos', copy 'n' bits from 'source' to * the 'n' bits of 'target' starting at 'tbitpos'. * * Requires: * - * 'source' and target are valid bitstrings with the same lsb0 setting. + *\li 'source' and target are valid bitstrings with the same lsb0 setting. * - * 'sbitpos' + 'n' is less than or equal to the length of 'source'. + *\li 'sbitpos' + 'n' is less than or equal to the length of 'source'. * - * 'tbitpos' + 'n' is less than or equal to the size of 'target'. + *\li 'tbitpos' + 'n' is less than or equal to the size of 'target'. * * Ensures: * - * The specified bits have been copied, and the length of 'target' + *\li The specified bits have been copied, and the length of 'target' * adjusted (if required). */ diff --git a/lib/isc/include/isc/boolean.h b/lib/isc/include/isc/boolean.h index 05e6722651..b86512a000 100644 --- a/lib/isc/include/isc/boolean.h +++ b/lib/isc/include/isc/boolean.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: boolean.h,v 1.13 2004/03/05 05:10:56 marka Exp $ */ +/* $Id: boolean.h,v 1.14 2005/04/27 04:57:16 sra Exp $ */ #ifndef ISC_BOOLEAN_H #define ISC_BOOLEAN_H 1 +/*! \file */ + typedef enum { isc_boolean_false = 0, isc_boolean_true = 1 } isc_boolean_t; #define ISC_FALSE isc_boolean_false diff --git a/lib/isc/include/isc/buffer.h b/lib/isc/include/isc/buffer.h index a3d45cb2e4..43fbfcaf1c 100644 --- a/lib/isc/include/isc/buffer.h +++ b/lib/isc/include/isc/buffer.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: buffer.h,v 1.43 2004/03/05 05:10:56 marka Exp $ */ +/* $Id: buffer.h,v 1.44 2005/04/27 04:57:16 sra Exp $ */ #ifndef ISC_BUFFER_H #define ISC_BUFFER_H 1 @@ -24,10 +24,9 @@ ***** Module Info *****/ -/* - * Buffers +/*! \file buffer.h * - * A buffer is a region of memory, together with a set of related subregions. + * \brief A buffer is a region of memory, together with a set of related subregions. * Buffers are used for parsing and I/O operations. * * The 'used region' and the 'available' region are disjoint, and their @@ -51,6 +50,7 @@ * is empty. If the current offset advances beyond the chosen offset, the * active region will also be empty. * + * \verbatim * /------------entire length---------------\ * /----- used region -----\/-- available --\ * +----------------------------------------+ @@ -69,9 +69,11 @@ * a-b == consumed region. * b-d == remaining region. * b-c == optional active region. + *\endverbatim * * The following invariants are maintained by all routines: * + *\code * length > 0 * * base is a valid pointer to length bytes of memory @@ -82,21 +84,22 @@ * * 0 <= active <= used * (although active < current implies empty active region) + *\endcode * - * MP: + * \li MP: * Buffers have no synchronization. Clients must ensure exclusive * access. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: + * \li Resources: * Memory: 1 pointer + 6 unsigned integers per buffer. * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ @@ -108,7 +111,7 @@ #include #include -/* +/*! * To make many functions be inline macros (via #define) define this. * If it is undefined, a function will be used. */ @@ -116,11 +119,13 @@ ISC_LANG_BEGINDECLS -/*** +/*@{*/ +/*! *** Magic numbers ***/ #define ISC_BUFFER_MAGIC 0x42756621U /* Buf!. */ #define ISC_BUFFER_VALID(b) ISC_MAGIC_VALID(b, ISC_BUFFER_MAGIC) +/*@}*/ /* * The following macros MUST be used only on valid buffers. It is the @@ -129,7 +134,8 @@ ISC_LANG_BEGINDECLS * another macro.) */ -/* +/*@{*/ +/*! * Fundamental buffer elements. (A through E in the introductory comment.) */ #define isc_buffer_base(b) ((void *)(b)->base) /*a*/ @@ -140,8 +146,10 @@ ISC_LANG_BEGINDECLS #define isc_buffer_used(b) \ ((void *)((unsigned char *)(b)->base + (b)->used)) /*d*/ #define isc_buffer_length(b) ((b)->length) /*e*/ +/*@}*/ -/* +/*@{*/ +/*! * Derived lengths. (Described in the introductory comment.) */ #define isc_buffer_usedlength(b) ((b)->used) /* d-a */ @@ -149,8 +157,9 @@ ISC_LANG_BEGINDECLS #define isc_buffer_remaininglength(b) ((b)->used - (b)->current) /* d-b */ #define isc_buffer_activelength(b) ((b)->active - (b)->current) /* c-b */ #define isc_buffer_availablelength(b) ((b)->length - (b)->used) /* e-d */ +/*@}*/ -/* +/*! * Note that the buffer structure is public. This is principally so buffer * operations can be implemented using macros. Applications are strongly * discouraged from directly manipulating the structure. @@ -159,14 +168,16 @@ ISC_LANG_BEGINDECLS struct isc_buffer { unsigned int magic; void *base; - /* The following integers are byte offsets from 'base'. */ + /*@{*/ + /*! The following integers are byte offsets from 'base'. */ unsigned int length; unsigned int used; unsigned int current; unsigned int active; - /* linkable */ + /*@}*/ + /*! linkable */ ISC_LINK(isc_buffer_t) link; - /* private internal elements */ + /*! private internal elements */ isc_mem_t *mctx; }; @@ -177,397 +188,397 @@ struct isc_buffer { isc_result_t isc_buffer_allocate(isc_mem_t *mctx, isc_buffer_t **dynbuffer, unsigned int length); -/* - * Allocate a dynamic linkable buffer which has "length" bytes in the +/*!< + * \brief Allocate a dynamic linkable buffer which has "length" bytes in the * data region. * * Requires: - * "mctx" is valid. + *\li "mctx" is valid. * - * "dynbuffer" is non-NULL, and "*dynbuffer" is NULL. + *\li "dynbuffer" is non-NULL, and "*dynbuffer" is NULL. * * Returns: - * ISC_R_SUCCESS - success - * ISC_R_NOMEMORY - no memory available + *\li ISC_R_SUCCESS - success + *\li ISC_R_NOMEMORY - no memory available * * Note: - * Changing the buffer's length field is not permitted. + *\li Changing the buffer's length field is not permitted. */ void isc_buffer_free(isc_buffer_t **dynbuffer); -/* - * Release resources allocated for a dynamic buffer. +/*!< + * \brief Release resources allocated for a dynamic buffer. * * Requires: - * "dynbuffer" is not NULL. + *\li "dynbuffer" is not NULL. * - * "*dynbuffer" is a valid dynamic buffer. + *\li "*dynbuffer" is a valid dynamic buffer. * * Ensures: - * "*dynbuffer" will be NULL on return, and all memory associated with + *\li "*dynbuffer" will be NULL on return, and all memory associated with * the dynamic buffer is returned to the memory context used in * isc_buffer_allocate(). */ void isc__buffer_init(isc_buffer_t *b, const void *base, unsigned int length); -/* - * Make 'b' refer to the 'length'-byte region starting at base. +/*!< + * \brief Make 'b' refer to the 'length'-byte region starting at base. * * Requires: * - * 'length' > 0 + *\li 'length' > 0 * - * 'base' is a pointer to a sequence of 'length' bytes. + *\li 'base' is a pointer to a sequence of 'length' bytes. * */ void isc__buffer_invalidate(isc_buffer_t *b); -/* - * Make 'b' an invalid buffer. +/*!< + * \brief Make 'b' an invalid buffer. * * Requires: - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * * Ensures: - * If assertion checking is enabled, future attempts to use 'b' without + *\li If assertion checking is enabled, future attempts to use 'b' without * calling isc_buffer_init() on it will cause an assertion failure. */ void isc__buffer_region(isc_buffer_t *b, isc_region_t *r); -/* - * Make 'r' refer to the region of 'b'. +/*!< + * \brief Make 'r' refer to the region of 'b'. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * 'r' points to a region structure. + *\li 'r' points to a region structure. */ void isc__buffer_usedregion(isc_buffer_t *b, isc_region_t *r); -/* - * Make 'r' refer to the used region of 'b'. +/*!< + * \brief Make 'r' refer to the used region of 'b'. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * 'r' points to a region structure. + *\li 'r' points to a region structure. */ void isc__buffer_availableregion(isc_buffer_t *b, isc_region_t *r); -/* - * Make 'r' refer to the available region of 'b'. +/*!< + * \brief Make 'r' refer to the available region of 'b'. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * 'r' points to a region structure. + *\li 'r' points to a region structure. */ void isc__buffer_add(isc_buffer_t *b, unsigned int n); -/* - * Increase the 'used' region of 'b' by 'n' bytes. +/*!< + * \brief Increase the 'used' region of 'b' by 'n' bytes. * * Requires: * - * 'b' is a valid buffer + *\li 'b' is a valid buffer * - * used + n <= length + *\li used + n <= length * */ void isc__buffer_subtract(isc_buffer_t *b, unsigned int n); -/* - * Decrease the 'used' region of 'b' by 'n' bytes. +/*!< + * \brief Decrease the 'used' region of 'b' by 'n' bytes. * * Requires: * - * 'b' is a valid buffer + *\li 'b' is a valid buffer * - * used >= n + *\li used >= n * */ void isc__buffer_clear(isc_buffer_t *b); -/* - * Make the used region empty. +/*!< + * \brief Make the used region empty. * * Requires: * - * 'b' is a valid buffer + *\li 'b' is a valid buffer * * Ensures: * - * used = 0 + *\li used = 0 * */ void isc__buffer_consumedregion(isc_buffer_t *b, isc_region_t *r); -/* - * Make 'r' refer to the consumed region of 'b'. +/*!< + * \brief Make 'r' refer to the consumed region of 'b'. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * 'r' points to a region structure. + *\li 'r' points to a region structure. */ void isc__buffer_remainingregion(isc_buffer_t *b, isc_region_t *r); -/* - * Make 'r' refer to the remaining region of 'b'. +/*!< + * \brief Make 'r' refer to the remaining region of 'b'. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * 'r' points to a region structure. + *\li 'r' points to a region structure. */ void isc__buffer_activeregion(isc_buffer_t *b, isc_region_t *r); -/* - * Make 'r' refer to the active region of 'b'. +/*!< + * \brief Make 'r' refer to the active region of 'b'. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * 'r' points to a region structure. + *\li 'r' points to a region structure. */ void isc__buffer_setactive(isc_buffer_t *b, unsigned int n); -/* - * Sets the end of the active region 'n' bytes after current. +/*!< + * \brief Sets the end of the active region 'n' bytes after current. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * current + n <= used + *\li current + n <= used */ void isc__buffer_first(isc_buffer_t *b); -/* - * Make the consumed region empty. +/*!< + * \brief Make the consumed region empty. * * Requires: * - * 'b' is a valid buffer + *\li 'b' is a valid buffer * * Ensures: * - * current == 0 + *\li current == 0 * */ void isc__buffer_forward(isc_buffer_t *b, unsigned int n); -/* - * Increase the 'consumed' region of 'b' by 'n' bytes. +/*!< + * \brief Increase the 'consumed' region of 'b' by 'n' bytes. * * Requires: * - * 'b' is a valid buffer + *\li 'b' is a valid buffer * - * current + n <= used + *\li current + n <= used * */ void isc__buffer_back(isc_buffer_t *b, unsigned int n); -/* - * Decrease the 'consumed' region of 'b' by 'n' bytes. +/*!< + * \brief Decrease the 'consumed' region of 'b' by 'n' bytes. * * Requires: * - * 'b' is a valid buffer + *\li 'b' is a valid buffer * - * n <= current + *\li n <= current * */ void isc_buffer_compact(isc_buffer_t *b); -/* - * Compact the used region by moving the remaining region so it occurs +/*!< + * \brief Compact the used region by moving the remaining region so it occurs * at the start of the buffer. The used region is shrunk by the size of * the consumed region, and the consumed region is then made empty. * * Requires: * - * 'b' is a valid buffer + *\li 'b' is a valid buffer * * Ensures: * - * current == 0 + *\li current == 0 * - * The size of the used region is now equal to the size of the remaining + *\li The size of the used region is now equal to the size of the remaining * region (as it was before the call). The contents of the used region * are those of the remaining region (as it was before the call). */ isc_uint8_t isc_buffer_getuint8(isc_buffer_t *b); -/* - * Read an unsigned 8-bit integer from 'b' and return it. +/*!< + * \brief Read an unsigned 8-bit integer from 'b' and return it. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * The length of the available region of 'b' is at least 1. + *\li The length of the available region of 'b' is at least 1. * * Ensures: * - * The current pointer in 'b' is advanced by 1. + *\li The current pointer in 'b' is advanced by 1. * * Returns: * - * A 8-bit unsigned integer. + *\li A 8-bit unsigned integer. */ void isc__buffer_putuint8(isc_buffer_t *b, isc_uint8_t val); -/* - * Store an unsigned 8-bit integer from 'val' into 'b'. +/*!< + * \brief Store an unsigned 8-bit integer from 'val' into 'b'. * * Requires: - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * The length of the unused region of 'b' is at least 1. + *\li The length of the unused region of 'b' is at least 1. * * Ensures: - * The used pointer in 'b' is advanced by 1. + *\li The used pointer in 'b' is advanced by 1. */ isc_uint16_t isc_buffer_getuint16(isc_buffer_t *b); -/* - * Read an unsigned 16-bit integer in network byte order from 'b', convert +/*!< + * \brief Read an unsigned 16-bit integer in network byte order from 'b', convert * it to host byte order, and return it. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * The length of the available region of 'b' is at least 2. + *\li The length of the available region of 'b' is at least 2. * * Ensures: * - * The current pointer in 'b' is advanced by 2. + *\li The current pointer in 'b' is advanced by 2. * * Returns: * - * A 16-bit unsigned integer. + *\li A 16-bit unsigned integer. */ void isc__buffer_putuint16(isc_buffer_t *b, isc_uint16_t val); -/* - * Store an unsigned 16-bit integer in host byte order from 'val' +/*!< + * \brief Store an unsigned 16-bit integer in host byte order from 'val' * into 'b' in network byte order. * * Requires: - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * The length of the unused region of 'b' is at least 2. + *\li The length of the unused region of 'b' is at least 2. * * Ensures: - * The used pointer in 'b' is advanced by 2. + *\li The used pointer in 'b' is advanced by 2. */ isc_uint32_t isc_buffer_getuint32(isc_buffer_t *b); -/* - * Read an unsigned 32-bit integer in network byte order from 'b', convert +/*!< + * \brief Read an unsigned 32-bit integer in network byte order from 'b', convert * it to host byte order, and return it. * * Requires: * - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * The length of the available region of 'b' is at least 4. + *\li The length of the available region of 'b' is at least 4. * * Ensures: * - * The current pointer in 'b' is advanced by 4. + *\li The current pointer in 'b' is advanced by 4. * * Returns: * - * A 32-bit unsigned integer. + *\li A 32-bit unsigned integer. */ void isc__buffer_putuint32(isc_buffer_t *b, isc_uint32_t val); -/* - * Store an unsigned 32-bit integer in host byte order from 'val' +/*!< + * \brief Store an unsigned 32-bit integer in host byte order from 'val' * into 'b' in network byte order. * * Requires: - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * The length of the unused region of 'b' is at least 4. + *\li The length of the unused region of 'b' is at least 4. * * Ensures: - * The used pointer in 'b' is advanced by 4. + *\li The used pointer in 'b' is advanced by 4. */ void isc__buffer_putmem(isc_buffer_t *b, const unsigned char *base, unsigned int length); -/* - * Copy 'length' bytes of memory at 'base' into 'b'. +/*!< + * \brief Copy 'length' bytes of memory at 'base' into 'b'. * * Requires: - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * 'base' points to 'length' bytes of valid memory. + *\li 'base' points to 'length' bytes of valid memory. * */ void isc__buffer_putstr(isc_buffer_t *b, const char *source); -/* - * Copy 'source' into 'b', not including terminating NUL. +/*!< + * \brief Copy 'source' into 'b', not including terminating NUL. * * Requires: - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * 'source' to be a valid NULL terminated string. + *\li 'source' to be a valid NULL terminated string. * - * strlen(source) <= isc_buffer_available(b) + *\li strlen(source) <= isc_buffer_available(b) */ isc_result_t isc_buffer_copyregion(isc_buffer_t *b, const isc_region_t *r); -/* - * Copy the contents of 'r' into 'b'. +/*!< + * \brief Copy the contents of 'r' into 'b'. * * Requires: - * 'b' is a valid buffer. + *\li 'b' is a valid buffer. * - * 'r' is a valid region. + *\li 'r' is a valid region. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOSPACE The available region of 'b' is not + *\li ISC_R_SUCCESS + *\li ISC_R_NOSPACE The available region of 'b' is not * big enough. */ @@ -580,7 +591,7 @@ ISC_LANG_ENDDECLS * ones beginning with "isc__" */ -/* +/*! \note * XXXDCL Something more could be done with initializing buffers that * point to const data. For example, a new function, isc_buffer_initconst, * could be used, and a new boolean flag in the buffer structure could diff --git a/lib/isc/include/isc/bufferlist.h b/lib/isc/include/isc/bufferlist.h index d03fe13799..739d1c2ddb 100644 --- a/lib/isc/include/isc/bufferlist.h +++ b/lib/isc/include/isc/bufferlist.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: bufferlist.h,v 1.11 2004/03/05 05:10:56 marka Exp $ */ +/* $Id: bufferlist.h,v 1.12 2005/04/27 04:57:16 sra Exp $ */ #ifndef ISC_BUFFERLIST_H #define ISC_BUFFERLIST_H 1 @@ -24,19 +24,19 @@ ***** Module Info *****/ -/* - * Buffer Lists +/*! \file bufferlist.h * - * Buffer lists have no synchronization. Clients must ensure exclusive + * + *\brief Buffer lists have no synchronization. Clients must ensure exclusive * access. * - * Reliability: + * \li Reliability: * No anticipated impact. - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ @@ -55,30 +55,30 @@ ISC_LANG_BEGINDECLS unsigned int isc_bufferlist_usedcount(isc_bufferlist_t *bl); -/* - * Return the length of the sum of all used regions of all buffers in +/*!< + * \brief Return the length of the sum of all used regions of all buffers in * the buffer list 'bl' * * Requires: * - * 'bl' is not NULL. + *\li 'bl' is not NULL. * * Returns: - * sum of all used regions' lengths. + *\li sum of all used regions' lengths. */ unsigned int isc_bufferlist_availablecount(isc_bufferlist_t *bl); -/* - * Return the length of the sum of all available regions of all buffers in +/*!< + * \brief Return the length of the sum of all available regions of all buffers in * the buffer list 'bl' * * Requires: * - * 'bl' is not NULL. + *\li 'bl' is not NULL. * * Returns: - * sum of all available regions' lengths. + *\li sum of all available regions' lengths. */ ISC_LANG_ENDDECLS diff --git a/lib/isc/include/isc/commandline.h b/lib/isc/include/isc/commandline.h index eb8e56d1e6..efc5e516f4 100644 --- a/lib/isc/include/isc/commandline.h +++ b/lib/isc/include/isc/commandline.h @@ -15,30 +15,33 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: commandline.h,v 1.10 2004/03/05 05:10:56 marka Exp $ */ +/* $Id: commandline.h,v 1.11 2005/04/27 04:57:16 sra Exp $ */ #ifndef ISC_COMMANDLINE_H #define ISC_COMMANDLINE_H 1 +/*! \file */ + #include #include #include -/* Index into parent argv vector. */ +/*% Index into parent argv vector. */ LIBISC_EXTERNAL_DATA extern int isc_commandline_index; -/* Character checked for validity. */ +/*% Character checked for validity. */ LIBISC_EXTERNAL_DATA extern int isc_commandline_option; -/* Argument associated with option. */ +/*% Argument associated with option. */ LIBISC_EXTERNAL_DATA extern char *isc_commandline_argument; -/* For printing error messages. */ +/*% For printing error messages. */ LIBISC_EXTERNAL_DATA extern char *isc_commandline_progname; -/* Print error message. */ +/*% Print error message. */ LIBISC_EXTERNAL_DATA extern isc_boolean_t isc_commandline_errprint; -/* Reset getopt. */ +/*% Reset getopt. */ LIBISC_EXTERNAL_DATA extern isc_boolean_t isc_commandline_reset; ISC_LANG_BEGINDECLS +/*% parse command line */ int isc_commandline_parse(int argc, char * const *argv, const char *options); diff --git a/lib/isc/include/isc/entropy.h b/lib/isc/include/isc/entropy.h index f7aa9df784..f9835442bd 100644 --- a/lib/isc/include/isc/entropy.h +++ b/lib/isc/include/isc/entropy.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: entropy.h,v 1.25 2004/03/05 05:10:56 marka Exp $ */ +/* $Id: entropy.h,v 1.26 2005/04/27 04:57:16 sra Exp $ */ #ifndef ISC_ENTROPY_H #define ISC_ENTROPY_H 1 @@ -24,33 +24,30 @@ ***** Module Info *****/ -/* - * Entropy +/*! \file entropy.h + * \brief The entropy API * - * The entropy API - * - * MP: + * \li MP: * The entropy object is locked internally. All callbacks into * application-provided functions (for setup, gathering, and * shutdown of sources) are guaranteed to be called with the * entropy API lock held. This means these functions are * not permitted to call back into the entropy API. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: + * \li Resources: * A buffer, used as an entropy pool. * - * Security: + * \li Security: * While this code is believed to implement good entropy gathering * and distribution, it has not been reviewed by a cryptographic * expert. - * * Since the added entropy is only as good as the sources used, * this module could hand out bad data and never know it. * - * Standards: + * \li Standards: * None. */ @@ -63,31 +60,37 @@ #include #include -/* - * Entropy callback function. - */ +/*@{*/ +/*% Entropy callback function. */ typedef isc_result_t (*isc_entropystart_t)(isc_entropysource_t *source, void *arg, isc_boolean_t blocking); typedef isc_result_t (*isc_entropyget_t)(isc_entropysource_t *source, void *arg, isc_boolean_t blocking); typedef void (*isc_entropystop_t)(isc_entropysource_t *source, void *arg); +/*@}*/ /*** *** Flags. ***/ -/* - * _GOODONLY +/*! + * \brief * Extract only "good" data; return failure if there is not enough * data available and there are no sources which we can poll to get * data, or those sources are empty. * - * _PARTIAL + * + */ +#define ISC_ENTROPY_GOODONLY 0x00000001U +/*! + * \brief * Extract as much good data as possible, but if there isn't enough * at hand, return what is available. This flag only makes sense * when used with _GOODONLY. - * - * _BLOCKING + */ +#define ISC_ENTROPY_PARTIAL 0x00000002U +/*! + * \brief * Block the task until data is available. This is contrary to the * ISC task system, where tasks should never block. However, if * this is a special purpose application where blocking a task is @@ -95,12 +98,10 @@ typedef void (*isc_entropystop_t)(isc_entropysource_t *source, void *arg); * This flag only makes sense when used with _GOODONLY, and will * block regardless of the setting for _PARTIAL. */ -#define ISC_ENTROPY_GOODONLY 0x00000001U -#define ISC_ENTROPY_PARTIAL 0x00000002U #define ISC_ENTROPY_BLOCKING 0x00000004U -/* - * _ESTIMATE +/*! + * \brief * Estimate the amount of entropy contained in the sample pool. * If this is not set, the source will be gathered and perodically * mixed into the entropy pool, but no increment in contained entropy @@ -110,17 +111,22 @@ typedef void (*isc_entropystop_t)(isc_entropysource_t *source, void *arg); /* * For use with isc_entropy_usebestsource(). - * - * _KEYBOARDYES + */ +/*! + * \brief * Use the keyboard as the only entropy source. - * _KEYBOARDNO + */ +#define ISC_ENTROPY_KEYBOARDYES 1 +/*! + * \brief * Never use the keyboard as an entropy source. - * _KEYBOARDMAYBE + */ +#define ISC_ENTROPY_KEYBOARDNO 2 +/*! + * \brief * Use the keyboard as an entropy source only if opening the * random device fails. */ -#define ISC_ENTROPY_KEYBOARDYES 1 -#define ISC_ENTROPY_KEYBOARDNO 2 #define ISC_ENTROPY_KEYBOARDMAYBE 3 ISC_LANG_BEGINDECLS @@ -131,26 +137,26 @@ ISC_LANG_BEGINDECLS isc_result_t isc_entropy_create(isc_mem_t *mctx, isc_entropy_t **entp); -/* - * Create a new entropy object. +/*!< + * \brief Create a new entropy object. */ void isc_entropy_attach(isc_entropy_t *ent, isc_entropy_t **entp); -/* +/*!< * Attaches to an entropy object. */ void isc_entropy_detach(isc_entropy_t **entp); -/* - * Detaches from an entropy object. +/*!< + * \brief Detaches from an entropy object. */ isc_result_t isc_entropy_createfilesource(isc_entropy_t *ent, const char *fname); -/* - * Create a new entropy source from a file. +/*!< + * \brief Create a new entropy source from a file. * * The file is assumed to contain good randomness, and will be mixed directly * into the pool with every byte adding 8 bits of entropy. @@ -168,15 +174,15 @@ isc_entropy_createfilesource(isc_entropy_t *ent, const char *fname); void isc_entropy_destroysource(isc_entropysource_t **sourcep); -/* - * Removes an entropy source from the entropy system. +/*!< + * \brief Removes an entropy source from the entropy system. */ isc_result_t isc_entropy_createsamplesource(isc_entropy_t *ent, isc_entropysource_t **sourcep); -/* - * Create an entropy source that consists of samples. Each sample is added +/*!< + * \brief Create an entropy source that consists of samples. Each sample is added * to the source via isc_entropy_addsamples(), below. */ @@ -187,8 +193,10 @@ isc_entropy_createcallbacksource(isc_entropy_t *ent, isc_entropystop_t stop, void *arg, isc_entropysource_t **sourcep); -/* - * Create an entropy source that is polled via a callback. This would +/*!< + * \brief Create an entropy source that is polled via a callback. + * + * This would * be used when keyboard input is used, or a GUI input method. It can * also be used to hook in any external entropy source. * @@ -199,19 +207,22 @@ isc_entropy_createcallbacksource(isc_entropy_t *ent, void isc_entropy_stopcallbacksources(isc_entropy_t *ent); -/* - * Call the stop functions for callback sources that have had their +/*!< + * \brief Call the stop functions for callback sources that have had their * start functions called. */ +/*@{*/ isc_result_t isc_entropy_addcallbacksample(isc_entropysource_t *source, isc_uint32_t sample, isc_uint32_t extra); isc_result_t isc_entropy_addsample(isc_entropysource_t *source, isc_uint32_t sample, isc_uint32_t extra); -/* - * Add a sample to the sample source. The sample MUST be a timestamp +/*!< + * \brief Add a sample to the sample source. + * + * The sample MUST be a timestamp * that increases over time, with the exception of wrap-around for * extremely high resolution timers which will quickly wrap-around * a 32-bit integer. @@ -222,20 +233,28 @@ isc_entropy_addsample(isc_entropysource_t *source, isc_uint32_t sample, * When in an entropy API callback function, _addcallbacksource() must be * used. At all other times, _addsample() must be used. */ +/*@}*/ isc_result_t isc_entropy_getdata(isc_entropy_t *ent, void *data, unsigned int length, unsigned int *returned, unsigned int flags); -/* - * Extract data from the entropy pool. This may load the pool from various +/*!< + * \brief Extract data from the entropy pool. This may load the pool from various * sources. + * + * Do this by stiring the pool and returning a part of hash as randomness. + * Note that no secrets are given away here since parts of the hash are + * xored together before returned. + * + * Honor the request from the caller to only return good data, any data, + * etc. */ void isc_entropy_putdata(isc_entropy_t *ent, void *data, unsigned int length, isc_uint32_t entropy); -/* - * Add "length" bytes in "data" to the entropy pool, incrementing the pool's +/*!< + * \brief Add "length" bytes in "data" to the entropy pool, incrementing the pool's * entropy count by "entropy." * * These bytes will prime the pseudorandom portion even no entropy is actually @@ -244,42 +263,42 @@ isc_entropy_putdata(isc_entropy_t *ent, void *data, unsigned int length, void isc_entropy_stats(isc_entropy_t *ent, FILE *out); -/* - * Dump some (trivial) stats to the stdio stream "out". +/*!< + * \brief Dump some (trivial) stats to the stdio stream "out". */ isc_result_t isc_entropy_usebestsource(isc_entropy_t *ectx, isc_entropysource_t **source, const char *randomfile, int use_keyboard); -/* - * Use whatever source of entropy is best. +/*!< + * \brief Use whatever source of entropy is best. * * Notes: - * If "randomfile" is not NULL, open it with + *\li If "randomfile" is not NULL, open it with * isc_entropy_createfilesource(). * - * If "randomfile" is NULL and the system's random device was detected + *\li If "randomfile" is NULL and the system's random device was detected * when the program was configured and built, open that device with * isc_entropy_createfilesource(). * - * If "use_keyboard" is ISC_ENTROPY_KEYBOARDYES, then always open + *\li If "use_keyboard" is #ISC_ENTROPY_KEYBOARDYES, then always open * the keyboard as an entropy source (possibly in addition to * "randomfile" or the random device). * - * If "use_keyboard" is ISC_ENTROPY_KEYBOARDMAYBE, open the keyboard only + *\li If "use_keyboard" is #ISC_ENTROPY_KEYBOARDMAYBE, open the keyboard only * if opening the random file/device fails. A message will be * printed describing the need for keyboard input. * - * If "use_keyboard" is ISC_ENTROPY_KEYBOARDNO, the keyboard will + *\li If "use_keyboard" is #ISC_ENTROPY_KEYBOARDNO, the keyboard will * never be opened. * * Returns: - * ISC_R_SUCCESS if at least one source of entropy could be started. + *\li #ISC_R_SUCCESS if at least one source of entropy could be started. * - * ISC_R_NOENTROPY if use_keyboard is ISC_ENTROPY_KEYBOARDNO and + *\li #ISC_R_NOENTROPY if use_keyboard is #ISC_ENTROPY_KEYBOARDNO and * there is no random device pathname compiled into the program. * - * A return code from isc_entropy_createfilesource() or + *\li A return code from isc_entropy_createfilesource() or * isc_entropy_createcallbacksource(). */ diff --git a/lib/isc/include/isc/error.h b/lib/isc/include/isc/error.h index a32de1b691..46d5943c4c 100644 --- a/lib/isc/include/isc/error.h +++ b/lib/isc/include/isc/error.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: error.h,v 1.14 2004/03/05 05:10:56 marka Exp $ */ +/* $Id: error.h,v 1.15 2005/04/27 04:57:16 sra Exp $ */ #ifndef ISC_ERROR_H #define ISC_ERROR_H 1 +/*! \file */ + #include #include @@ -29,20 +31,25 @@ ISC_LANG_BEGINDECLS typedef void (*isc_errorcallback_t)(const char *, int, const char *, va_list); +/*% set unexpected error */ void isc_error_setunexpected(isc_errorcallback_t); +/*% set fatal error */ void isc_error_setfatal(isc_errorcallback_t); +/*% unexpected error */ void isc_error_unexpected(const char *, int, const char *, ...) ISC_FORMAT_PRINTF(3, 4); +/*% fatal error */ void isc_error_fatal(const char *, int, const char *, ...) ISC_FORMAT_PRINTF(3, 4); +/*% runtimecheck error */ void isc_error_runtimecheck(const char *, int, const char *); diff --git a/lib/isc/include/isc/event.h b/lib/isc/include/isc/event.h index 90e078c951..93bf8dbaf1 100644 --- a/lib/isc/include/isc/event.h +++ b/lib/isc/include/isc/event.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: event.h,v 1.28 2004/04/15 01:58:25 marka Exp $ */ +/* $Id: event.h,v 1.29 2005/04/27 04:57:17 sra Exp $ */ #ifndef ISC_EVENT_H #define ISC_EVENT_H 1 +/*! \file */ + #include #include @@ -41,14 +43,14 @@ typedef void (*isc_eventdestructor_t)(isc_event_t *); void * ev_destroy_arg; \ ISC_LINK(ltype) ev_link -/* +/*% * Attributes matching a mask of 0x000000ff are reserved for the task library's * definition. Attributes of 0xffffff00 may be used by the application * or non-ISC libraries. */ #define ISC_EVENTATTR_NOPURGE 0x00000001 -/* +/*% * The ISC_EVENTATTR_CANCELED attribute is intended to indicate * that an event is delivered as a result of a canceled operation * rather than successful completion, by mutual agreement @@ -71,7 +73,7 @@ do { \ ISC_LINK_INIT((event), ev_link); \ } while (0) -/* +/*% * This structure is public because "subclassing" it may be useful when * defining new event types. */ @@ -89,22 +91,26 @@ ISC_LANG_BEGINDECLS isc_event_t * isc_event_allocate(isc_mem_t *mctx, void *sender, isc_eventtype_t type, isc_taskaction_t action, const void *arg, size_t size); -/* +/*%< + * Allocate an event structure. + * * Allocate and initialize in a structure with initial elements * defined by: * + * \code * struct { * ISC_EVENT_COMMON(struct isc_event); * ... * }; + * \endcode * * Requires: - * 'size' >= sizeof(struct isc_event) - * 'action' to be non NULL + *\li 'size' >= sizeof(struct isc_event) + *\li 'action' to be non NULL * * Returns: - * a pointer to a initialized structure of the requested size. - * NULL if unable to allocate memory. + *\li a pointer to a initialized structure of the requested size. + *\li NULL if unable to allocate memory. */ void diff --git a/lib/isc/include/isc/eventclass.h b/lib/isc/include/isc/eventclass.h index 7b5dce2c2e..e8b3d24c82 100644 --- a/lib/isc/include/isc/eventclass.h +++ b/lib/isc/include/isc/eventclass.h @@ -15,25 +15,28 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: eventclass.h,v 1.14 2004/03/05 05:10:56 marka Exp $ */ +/* $Id: eventclass.h,v 1.15 2005/04/27 04:57:17 sra Exp $ */ #ifndef ISC_EVENTCLASS_H #define ISC_EVENTCLASS_H 1 -/***** +/*! \file isc/eventclass.h ***** Registry of Predefined Event Type Classes *****/ -/* +/*% * An event class is an unsigned 16 bit number. Each class may contain up * to 65536 events. An event type is formed by adding the event number * within the class to the class number. + * */ #define ISC_EVENTCLASS(eclass) ((eclass) << 16) -/* +/*@{*/ +/*! * Classes < 1024 are reserved for ISC use. + * Event classes >= 1024 and <= 65535 are reserved for application use. */ #define ISC_EVENTCLASS_TASK ISC_EVENTCLASS(0) @@ -45,9 +48,6 @@ #define ISC_EVENTCLASS_OMAPI ISC_EVENTCLASS(6) #define ISC_EVENTCLASS_RATELIMITER ISC_EVENTCLASS(7) #define ISC_EVENTCLASS_ISCCC ISC_EVENTCLASS(8) - -/* - * Event classes >= 1024 and <= 65535 are reserved for application use. - */ +/*@}*/ #endif /* ISC_EVENTCLASS_H */ diff --git a/lib/isc/include/isc/file.h b/lib/isc/include/isc/file.h index 346b5f5ebe..d2c94dc33a 100644 --- a/lib/isc/include/isc/file.h +++ b/lib/isc/include/isc/file.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: file.h,v 1.27 2004/03/05 05:10:57 marka Exp $ */ +/* $Id: file.h,v 1.28 2005/04/27 04:57:17 sra Exp $ */ #ifndef ISC_FILE_H #define ISC_FILE_H 1 +/*! \file */ + #include #include @@ -32,81 +34,81 @@ isc_file_settime(const char *file, isc_time_t *time); isc_result_t isc_file_getmodtime(const char *file, isc_time_t *time); -/* - * Get the time of last modication of a file. +/*!< + * \brief Get the time of last modication of a file. * * Notes: - * The time that is set is relative to the (OS-specific) epoch, as are + *\li The time that is set is relative to the (OS-specific) epoch, as are * all isc_time_t structures. * * Requires: - * file != NULL. - * time != NULL. + *\li file != NULL. + *\li time != NULL. * * Ensures: - * If the file could not be accessed, 'time' is unchanged. + *\li If the file could not be accessed, 'time' is unchanged. * * Returns: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * Success. - * ISC_R_NOTFOUND + *\li #ISC_R_NOTFOUND * No such file exists. - * ISC_R_INVALIDFILE + *\li #ISC_R_INVALIDFILE * The path specified was not usable by the operating system. - * ISC_R_NOPERM + *\li #ISC_R_NOPERM * The file's metainformation could not be retrieved because * permission was denied to some part of the file's path. - * ISC_R_EIO + *\li #ISC_R_EIO * Hardware error interacting with the filesystem. - * ISC_R_UNEXPECTED + *\li #ISC_R_UNEXPECTED * Something totally unexpected happened. * */ isc_result_t isc_file_mktemplate(const char *path, char *buf, size_t buflen); -/* - * Generate a template string suitable for use with isc_file_openunique. +/*!< + * \brief Generate a template string suitable for use with isc_file_openunique(). * * Notes: - * This function is intended to make creating temporary files + *\li This function is intended to make creating temporary files * portable between different operating systems. * - * The path is prepended to an implementation-defined string and + *\li The path is prepended to an implementation-defined string and * placed into buf. The string has no path characters in it, * and its maximum length is 14 characters plus a NUL. Thus * buflen should be at least strlen(path) + 15 characters or * an error will be returned. * * Requires: - * buf != NULL. + *\li buf != NULL. * * Ensures: - * If result == ISC_R_SUCCESS: + *\li If result == #ISC_R_SUCCESS: * buf contains a string suitable for use as the template argument - * to isc_file_openunique. + * to isc_file_openunique(). * - * If result != ISC_R_SUCCESS: + *\li If result != #ISC_R_SUCCESS: * buf is unchanged. * * Returns: - * ISC_R_SUCCESS Success. - * ISC_R_NOSPACE buflen indicates buf is too small for the catenation + *\li #ISC_R_SUCCESS Success. + *\li #ISC_R_NOSPACE buflen indicates buf is too small for the catenation * of the path with the internal template string. */ isc_result_t isc_file_openunique(char *templet, FILE **fp); -/* - * Create and open a file with a unique name based on 'templet'. +/*!< + * \brief Create and open a file with a unique name based on 'templet'. * * Notes: - * 'template' is a reserved work in C++. If you want to complain + *\li 'template' is a reserved work in C++. If you want to complain * about the spelling of 'templet', first look it up in the * Merriam-Webster English dictionary. (http://www.m-w.com/) * - * This function works by using the template to generate file names. + *\li This function works by using the template to generate file names. * The template must be a writable string, as it is modified in place. * Trailing X characters in the file name (full file name on Unix, * basename on Win32 -- eg, tmp-XXXXXX vs XXXXXX.tmp, respectively) @@ -114,95 +116,97 @@ isc_file_openunique(char *templet, FILE **fp); * is found. If the template does not include pathname information, * the files in the working directory of the program are searched. * - * isc_file_mktemplate is a good, portable way to get a template. + *\li isc_file_mktemplate is a good, portable way to get a template. * * Requires: - * 'fp' is non-NULL and '*fp' is NULL. + *\li 'fp' is non-NULL and '*fp' is NULL. * - * 'template' is non-NULL, and of a form suitable for use by + *\li 'template' is non-NULL, and of a form suitable for use by * the system as described above. * * Ensures: - * If result is ISC_R_SUCCESS: + *\li If result is #ISC_R_SUCCESS: * *fp points to an stream opening in stdio's "w+" mode. * - * If result is not ISC_R_SUCCESS: + *\li If result is not #ISC_R_SUCCESS: * *fp is NULL. * * No file is open. Even if one was created (but unable * to be reopened as a stdio FILE pointer) then it has been * removed. * - * This function does *not* ensure that the template string has not been + *\li This function does *not* ensure that the template string has not been * modified, even if the operation was unsuccessful. * * Returns: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * Success. - * ISC_R_EXISTS + *\li #ISC_R_EXISTS * No file with a unique name could be created based on the * template. - * ISC_R_INVALIDFILE + *\li #ISC_R_INVALIDFILE * The path specified was not usable by the operating system. - * ISC_R_NOPERM + *\li #ISC_R_NOPERM * The file could not be created because permission was denied * to some part of the file's path. - * ISC_R_EIO + *\li #ISC_R_IOERROR * Hardware error interacting with the filesystem. - * ISC_R_UNEXPECTED + *\li #ISC_R_UNEXPECTED * Something totally unexpected happened. */ isc_result_t isc_file_remove(const char *filename); -/* - * Remove the file named by 'filename'. +/*!< + * \brief Remove the file named by 'filename'. */ isc_result_t isc_file_rename(const char *oldname, const char *newname); -/* - * Rename the file 'oldname' to 'newname'. +/*!< + * \brief Rename the file 'oldname' to 'newname'. */ isc_boolean_t isc_file_exists(const char *pathname); -/* - * Return ISC_TRUE iff the calling process can tell that the given file exists. +/*!< + * \brief Return #ISC_TRUE if the calling process can tell that the given file exists. * Will not return true if the calling process has insufficient privileges * to search the entire path. */ isc_boolean_t isc_file_isabsolute(const char *filename); -/* - * Return ISC_TRUE iff the given file name is absolute. +/*!< + * \brief Return #ISC_TRUE if the given file name is absolute. */ isc_boolean_t isc_file_iscurrentdir(const char *filename); -/* - * Return ISC_TRUE iff the given file name is the current directory ("."). +/*!< + * \brief Return #ISC_TRUE if the given file name is the current directory ("."). */ isc_boolean_t isc_file_ischdiridempotent(const char *filename); -/* - * Return ISC_TRUE if calling chdir(filename) multiple times will give +/*%< + * Return #ISC_TRUE if calling chdir(filename) multiple times will give * the same result as calling it once. */ const char * isc_file_basename(const char *filename); -/* +/*%< * Return the final component of the path in the file name. */ isc_result_t isc_file_progname(const char *filename, char *buf, size_t buflen); -/* - * Given an operating system specific file name "filename" +/*!< + * \brief Given an operating system specific file name "filename" * referring to a program, return the canonical program name. + * + * * Any directory prefix or executable file name extension (if * used on the OS in case) is stripped. On systems where program * names are case insensitive, the name is canonicalized to all @@ -210,14 +214,14 @@ isc_file_progname(const char *filename, char *buf, size_t buflen); * chars, and null terminated. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE The name did not fit in 'buf'. + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE The name did not fit in 'buf'. */ isc_result_t isc_file_template(const char *path, const char *templet, char *buf, size_t buflen); -/* +/*%< * Create an OS specific template using 'path' to define the directory * 'templet' to describe the filename and store the result in 'buf' * such that path can be renamed to buf atomically. @@ -225,13 +229,13 @@ isc_file_template(const char *path, const char *templet, char *buf, isc_result_t isc_file_renameunique(const char *file, char *templet); -/* +/*%< * Rename 'file' using 'templet' as a template for the new file name. */ isc_result_t isc_file_absolutepath(const char *filename, char *path, size_t pathlen); -/* +/*%< * Given a file name, return the fully qualified path to the file. */ @@ -243,7 +247,7 @@ isc_file_absolutepath(const char *filename, char *path, size_t pathlen); isc_result_t isc_file_truncate(const char *filename, isc_offset_t size); -/* +/*%< * Truncate/extend the file specified to 'size' bytes. */ diff --git a/lib/isc/include/isc/formatcheck.h b/lib/isc/include/isc/formatcheck.h index 734a0cba01..9525f57219 100644 --- a/lib/isc/include/isc/formatcheck.h +++ b/lib/isc/include/isc/formatcheck.h @@ -15,15 +15,21 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: formatcheck.h,v 1.7 2004/03/05 05:10:57 marka Exp $ */ +/* $Id: formatcheck.h,v 1.8 2005/04/27 04:57:17 sra Exp $ */ #ifndef ISC_FORMATCHECK_H #define ISC_FORMATCHECK_H 1 -/* - * fmt is the location of the format string parameter. - * args is the location of the first argument (or 0 for no argument checking). - * Note: the first parameter is 1, not 0. +/*! \file */ + +/*% + * ISC_FORMAT_PRINTF(). + * + * \li fmt is the location of the format string parameter. + * \li args is the location of the first argument (or 0 for no argument checking). + * + * Note: + * \li The first parameter is 1, not 0. */ #ifdef __GNUC__ #define ISC_FORMAT_PRINTF(fmt, args) __attribute__((__format__(__printf__, fmt, args))) diff --git a/lib/isc/include/isc/fsaccess.h b/lib/isc/include/isc/fsaccess.h index e9214e3c9e..4db922c885 100644 --- a/lib/isc/include/isc/fsaccess.h +++ b/lib/isc/include/isc/fsaccess.h @@ -15,13 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: fsaccess.h,v 1.8 2004/03/05 05:10:57 marka Exp $ */ +/* $Id: fsaccess.h,v 1.9 2005/04/27 04:57:17 sra Exp $ */ #ifndef ISC_FSACCESS_H #define ISC_FSACCESS_H 1 -/* - * The ISC filesystem access module encapsulates the setting of file +/*! \file + * \brief The ISC filesystem access module encapsulates the setting of file * and directory access permissions into one API that is meant to be * portable to multiple operating systems. * @@ -41,30 +41,30 @@ * * Some of the more notable dumbing down of NT for this API includes: * - * o Each of FILE_READ_DATA and FILE_READ_EA are set with ISC_FSACCESS_READ. + *\li Each of FILE_READ_DATA and FILE_READ_EA are set with #ISC_FSACCESS_READ. * - * o All of FILE_WRITE_DATA, FILE_WRITE_EA and FILE_APPEND_DATA are - * set with ISC_FSACCESS_WRITE. FILE_WRITE_ATTRIBUTES is not set + * \li All of FILE_WRITE_DATA, FILE_WRITE_EA and FILE_APPEND_DATA are + * set with #ISC_FSACCESS_WRITE. FILE_WRITE_ATTRIBUTES is not set * so as to be consistent with Unix, where only the owner of the file * or the superuser can change the attributes/mode of a file. * - * o Both of FILE_ADD_FILE and FILE_ADD_SUBDIRECTORY are set with - * ISC_FSACCESS_CREATECHILD. This is similar to setting the WRITE + * \li Both of FILE_ADD_FILE and FILE_ADD_SUBDIRECTORY are set with + * #ISC_FSACCESS_CREATECHILD. This is similar to setting the WRITE * permission on a Unix directory. * - * o SYNCHRONIZE is always set for files and directories, unless someone + * \li SYNCHRONIZE is always set for files and directories, unless someone * can give me a reason why this is a bad idea. * - * o READ_CONTROL and FILE_READ_ATTRIBUTES are always set; this is + * \li READ_CONTROL and FILE_READ_ATTRIBUTES are always set; this is * consistent with Unix, where any file or directory can be stat()'d * unless the directory path disallows complete access somewhere along * the way. * - * o WRITE_DAC is only set for the owner. This too is consistent with + * \li WRITE_DAC is only set for the owner. This too is consistent with * Unix, and is tighter security than allowing anyone else to be * able to set permissions. * - * o DELETE is only set for the owner. On Unix the ability to delete + * \li DELETE is only set for the owner. On Unix the ability to delete * a file is controlled by the directory permissions, but it isn't * currently clear to me what happens on NT if the directory has * FILE_DELETE_CHILD set but a file within it does not have DELETE @@ -72,19 +72,19 @@ * gives maximum flexibility to the owner without exposing the * file to deletion by others. * - * o WRITE_OWNER is never set. This too is consistent with Unix, + * \li WRITE_OWNER is never set. This too is consistent with Unix, * and is also tighter security than allowing anyone to change the * ownership of the file apart from the superu..ahem, Administrator. * - * o Inheritance is set to NO_INHERITANCE. + * \li Inheritance is set to NO_INHERITANCE. * * Unix's dumbing down includes: * - * o The sticky bit cannot be set. + * \li The sticky bit cannot be set. * - * o setuid and setgid cannot be set. + * \li setuid and setgid cannot be set. * - * o Only regular files and directories can be set. + * \li Only regular files and directories can be set. * * The rest of this comment discusses a few of the incompatibilities * between the two systems that need more thought if this API is to @@ -103,24 +103,24 @@ * set on a directory. You'd need to coordinate something with file creation * so that every file created had DELETE set for the owner but noone else. * - * On Unix systems, setting ISC_FSACCESS_LISTDIRECTORY sets READ. - * ... setting either of ISC_FSACCESS_(CREATE|DELETE)CHILD sets WRITE. - * ... setting ISC_FSACCESS_ACCESSCHILD sets EXECUTE. + * On Unix systems, setting #ISC_FSACCESS_LISTDIRECTORY sets READ. + * ... setting either of #ISC_FSACCESS_(CREATE|DELETE)CHILD sets WRITE. + * ... setting #ISC_FSACCESS_ACCESSCHILD sets EXECUTE. * - * On NT systems, setting ISC_FSACCESS_LISTDIRECTORY sets FILE_LIST_DIRECTORY. + * On NT systems, setting #ISC_FSACCESS_LISTDIRECTORY sets FILE_LIST_DIRECTORY. * ... setting ISC_FSACCESS_(CREATE|DELETE)CHILD sets * FILE_(CREATE|DELETE)_CHILD independently. - * ... setting ISC_FSACCESS_ACCESSCHILD sets FILE_TRAVERSE. + * ... setting #ISC_FSACCESS_ACCESSCHILD sets FILE_TRAVERSE. * * Unresolved: XXXDCL - * What NT access right controls the ability to rename a file? - * How does DELETE work? If a directory has FILE_DELETE_CHILD but a + * \li What NT access right controls the ability to rename a file? + * \li How does DELETE work? If a directory has FILE_DELETE_CHILD but a * file or directory within it does not have DELETE, is that file * or directory deletable? - * To implement isc_fsaccess_get(), mapping an existing Unix permission + * \li To implement isc_fsaccess_get(), mapping an existing Unix permission * mode_t back to an isc_fsaccess_t is pretty trivial; however, mapping * an NT DACL could be impossible to do in a responsible way. - * Similarly, trying to implement the functionality of being able to + * \li Similarly, trying to implement the functionality of being able to * say "add group writability to whatever permissions already exist" * could be tricky on NT because of the order-of-entry issue combined * with possibly having one or more matching ACEs already explicitly @@ -135,23 +135,23 @@ /* * Trustees. */ -#define ISC_FSACCESS_OWNER 0x1 /* User account. */ -#define ISC_FSACCESS_GROUP 0x2 /* Primary group owner. */ -#define ISC_FSACCESS_OTHER 0x4 /* Not the owner or the group owner. */ -#define ISC_FSACCESS_WORLD 0x7 /* User, Group, Other. */ +#define ISC_FSACCESS_OWNER 0x1 /*%< User account. */ +#define ISC_FSACCESS_GROUP 0x2 /*%< Primary group owner. */ +#define ISC_FSACCESS_OTHER 0x4 /*%< Not the owner or the group owner. */ +#define ISC_FSACCESS_WORLD 0x7 /*%< User, Group, Other. */ /* * Types of permission. */ -#define ISC_FSACCESS_READ 0x00000001 /* File only. */ -#define ISC_FSACCESS_WRITE 0x00000002 /* File only. */ -#define ISC_FSACCESS_EXECUTE 0x00000004 /* File only. */ -#define ISC_FSACCESS_CREATECHILD 0x00000008 /* Dir only. */ -#define ISC_FSACCESS_DELETECHILD 0x00000010 /* Dir only. */ -#define ISC_FSACCESS_LISTDIRECTORY 0x00000020 /* Dir only. */ -#define ISC_FSACCESS_ACCESSCHILD 0x00000040 /* Dir only. */ +#define ISC_FSACCESS_READ 0x00000001 /*%< File only. */ +#define ISC_FSACCESS_WRITE 0x00000002 /*%< File only. */ +#define ISC_FSACCESS_EXECUTE 0x00000004 /*%< File only. */ +#define ISC_FSACCESS_CREATECHILD 0x00000008 /*%< Dir only. */ +#define ISC_FSACCESS_DELETECHILD 0x00000010 /*%< Dir only. */ +#define ISC_FSACCESS_LISTDIRECTORY 0x00000020 /*%< Dir only. */ +#define ISC_FSACCESS_ACCESSCHILD 0x00000040 /*%< Dir only. */ -/* +/*% * Adding any permission bits beyond 0x200 would mean typedef'ing * isc_fsaccess_t as isc_uint64_t, and redefining this value to * reflect the new range of permission types, Probably to 21 for diff --git a/lib/isc/include/isc/hash.h b/lib/isc/include/isc/hash.h index 6a179328a5..0172a0c72b 100644 --- a/lib/isc/include/isc/hash.h +++ b/lib/isc/include/isc/hash.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: hash.h,v 1.4 2004/03/05 05:10:57 marka Exp $ */ +/* $Id: hash.h,v 1.5 2005/04/27 04:57:17 sra Exp $ */ #ifndef ISC_HASH_H #define ISC_HASH_H 1 @@ -24,12 +24,10 @@ ***** Module Info *****/ -/* - * Hash +/*! \file * - * The hash API - * - * Provides an unpredictable hash value for variable length data. + * \brief The hash API + * provides an unpredictable hash value for variable length data. * A hash object contains a random vector (which is hidden from clients * of this API) to make the actual hash value unpredictable. * @@ -48,27 +46,27 @@ * it should be typical to have a single context for an entire system. * To support such cases, the API also provides a single-context mode. * - * MP: + * \li MP: * The hash object is almost read-only. Once the internal random vector * is initialized, no write operation will occur, and there will be no * need to lock the object to calculate actual hash values. * - * Reliability: + * \li Reliability: * In some cases this module uses low-level data copy to initialize the * random vector. Errors in this part are likely to crash the server or * corrupt memory. * - * Resources: + * \li Resources: * A buffer, used as a random vector for calculating hash values. * - * Security: + * \li Security: * This module intends to provide unpredictable hash values in * adversarial environments in order to avoid denial of service attacks * to hash buckets. * Its unpredictability relies on the quality of entropy to build the * random vector. * - * Standards: + * \li Standards: * None. */ @@ -88,10 +86,11 @@ isc_hash_ctxcreate(isc_mem_t *mctx, isc_entropy_t *entropy, unsigned int limit, isc_hash_t **hctx); isc_result_t isc_hash_create(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit); -/* - * Create a new hash object. +/*!< + * \brief Create a new hash object. * * isc_hash_ctxcreate() creates a different object. + * * isc_hash_create() creates a module-internal object to support the * single-context mode. It should be called only once. * @@ -105,15 +104,16 @@ isc_hash_create(isc_mem_t *mctx, isc_entropy_t *entropy, size_t limit); void isc_hash_ctxattach(isc_hash_t *hctx, isc_hash_t **hctxp); -/* - * Attach to a hash object. +/*!< + * \brief Attach to a hash object. + * * This function is only necessary for the multiple-context mode. */ void isc_hash_ctxdetach(isc_hash_t **hctxp); -/* - * Detach from a hash object. +/*!< + * \brief Detach from a hash object. * * This function is for the multiple-context mode, and takes a valid * hash object as an argument. @@ -121,19 +121,23 @@ isc_hash_ctxdetach(isc_hash_t **hctxp); void isc_hash_destroy(void); -/* - * This function is for the single-context mode, and is expected to be used +/*!< + * \brief This function is for the single-context mode, and is expected to be used * as a counterpart of isc_hash_create(). + * * A valid module-internal hash object must have been created, and this * function should be called only once. */ +/*@{*/ void isc_hash_ctxinit(isc_hash_t *hctx); void isc_hash_init(void); -/* - * Initialize a hash object. It fills in the random vector with a proper +/*!< + * \brief Initialize a hash object. + * + * It fills in the random vector with a proper * source of entropy, which is typically from the entropy object specified * at the creation. Thus, it is desirable to call these functions after * initializing the entropy object with some good entropy sources. @@ -142,26 +146,31 @@ isc_hash_init(void); * * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash * object as an argument. + * * isc_hash_init() is for the single-context mode. A valid module-internal * hash object must have been created, and this function should be called only * once. */ +/*@}*/ +/*@{*/ unsigned int isc_hash_ctxcalc(isc_hash_t *hctx, const unsigned char *key, unsigned int keylen, isc_boolean_t case_sensitive); unsigned int isc_hash_calc(const unsigned char *key, unsigned int keylen, isc_boolean_t case_sensitive); -/* - * Calculate a hash value. +/*!< + * \brief Calculate a hash value. * * isc_hash_ctxinit() is for the multiple-context mode, and takes a valid hash * object as an argument. + * * isc_hash_init() is for the single-context mode. A valid module-internal * hash object must have been created. * * 'key' is the hash key, which is a variable length buffer. + * * 'keylen' specifies the key length, which must not be larger than the limit * specified for the corresponding hash object. * @@ -169,6 +178,7 @@ isc_hash_calc(const unsigned char *key, unsigned int keylen, * case_sensitive values. It should typically be ISC_FALSE if the hash key * is a DNS name. */ +/*@}*/ ISC_LANG_ENDDECLS diff --git a/lib/isc/include/isc/heap.h b/lib/isc/include/isc/heap.h index 1e2e2cb47d..eeccaf44cd 100644 --- a/lib/isc/include/isc/heap.h +++ b/lib/isc/include/isc/heap.h @@ -15,17 +15,19 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: heap.h,v 1.17 2004/03/05 05:10:57 marka Exp $ */ +/* $Id: heap.h,v 1.18 2005/04/27 04:57:17 sra Exp $ */ #ifndef ISC_HEAP_H #define ISC_HEAP_H 1 +/*! \file */ + #include #include ISC_LANG_BEGINDECLS -/* +/*% * The comparision function returns ISC_TRUE if the first argument has * higher priority than the second argument, and ISC_FALSE otherwise. */ diff --git a/lib/isc/include/isc/hex.h b/lib/isc/include/isc/hex.h index 160ba86be3..ddfcfff8a3 100644 --- a/lib/isc/include/isc/hex.h +++ b/lib/isc/include/isc/hex.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: hex.h,v 1.5 2004/03/05 05:10:57 marka Exp $ */ +/* $Id: hex.h,v 1.6 2005/04/27 04:57:18 sra Exp $ */ #ifndef ISC_HEX_H #define ISC_HEX_H 1 +/*! \file */ + #include #include @@ -32,40 +34,40 @@ ISC_LANG_BEGINDECLS isc_result_t isc_hex_totext(isc_region_t *source, int wordlength, const char *wordbreak, isc_buffer_t *target); -/* - * Convert data into hex encoded text. +/*!< + * \brief Convert data into hex encoded text. * * Notes: - * The hex encoded text in 'target' will be divided into + *\li The hex encoded text in 'target' will be divided into * words of at most 'wordlength' characters, separated by * the 'wordbreak' string. No parentheses will surround * the text. * * Requires: - * 'source' is a region containing binary data - * 'target' is a text buffer containing available space - * 'wordbreak' points to a null-terminated string of + *\li 'source' is a region containing binary data + *\li 'target' is a text buffer containing available space + *\li 'wordbreak' points to a null-terminated string of * zero or more whitespace characters * * Ensures: - * target will contain the hex encoded version of the data + *\li target will contain the hex encoded version of the data * in source. The 'used' pointer in target will be advanced as * necessary. */ isc_result_t isc_hex_decodestring(char *cstr, isc_buffer_t *target); -/* - * Decode a null-terminated hex string. +/*!< + * \brief Decode a null-terminated hex string. * * Requires: - * 'cstr' is non-null. - * 'target' is a valid buffer. + *\li 'cstr' is non-null. + *\li 'target' is a valid buffer. * * Returns: - * ISC_R_SUCCESS -- the entire decoded representation of 'cstring' + *\li #ISC_R_SUCCESS -- the entire decoded representation of 'cstring' * fit in 'target'. - * ISC_R_BADHEX -- 'cstr' is not a valid hex encoding. + *\li #ISC_R_BADHEX -- 'cstr' is not a valid hex encoding. * * Other error returns are any possible error code from: * isc_lex_create(), @@ -75,16 +77,16 @@ isc_hex_decodestring(char *cstr, isc_buffer_t *target); isc_result_t isc_hex_tobuffer(isc_lex_t *lexer, isc_buffer_t *target, int length); -/* - * Convert hex encoded text from a lexer context into data. +/*!< + * \brief Convert hex encoded text from a lexer context into data. * * Requires: - * 'lex' is a valid lexer context - * 'target' is a buffer containing binary data - * 'length' is an integer + *\li 'lex' is a valid lexer context + *\li 'target' is a buffer containing binary data + *\li 'length' is an integer * * Ensures: - * target will contain the data represented by the hex encoded + *\li target will contain the data represented by the hex encoded * string parsed by the lexer. No more than length bytes will be read, * if length is positive. The 'used' pointer in target will be * advanced as necessary. diff --git a/lib/isc/include/isc/hmacmd5.h b/lib/isc/include/isc/hmacmd5.h index 26519ed47f..46c60a20c5 100644 --- a/lib/isc/include/isc/hmacmd5.h +++ b/lib/isc/include/isc/hmacmd5.h @@ -15,11 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: hmacmd5.h,v 1.5 2004/03/05 05:10:57 marka Exp $ */ +/* $Id: hmacmd5.h,v 1.6 2005/04/27 04:57:18 sra Exp $ */ -/* - * This is the header file for the HMAC-MD5 keyed hash algorithm - * described in RFC 2104. +/*! \file + * \brief This is the header file for the HMAC-MD5 keyed hash algorithm + * described in RFC2104. */ #ifndef ISC_HMACMD5_H diff --git a/lib/isc/include/isc/interfaceiter.h b/lib/isc/include/isc/interfaceiter.h index e6e435e8c3..1c2532a6ed 100644 --- a/lib/isc/include/isc/interfaceiter.h +++ b/lib/isc/include/isc/interfaceiter.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: interfaceiter.h,v 1.11 2004/03/05 05:10:58 marka Exp $ */ +/* $Id: interfaceiter.h,v 1.12 2005/04/27 04:57:18 sra Exp $ */ #ifndef ISC_INTERFACEITER_H #define ISC_INTERFACEITER_H 1 @@ -24,10 +24,8 @@ ***** Module Info *****/ -/* - * Interface iterator - * - * Iterate over the list of network interfaces. +/*! \file + * \brief Iterates over the list of network interfaces. * * Interfaces whose address family is not supported are ignored and never * returned by the iterator. Interfaces whose netmask, interface flags, @@ -46,25 +44,26 @@ #include #include -/* - * Public structure describing a network interface. +/*! + * \brief Public structure describing a network interface. */ struct isc_interface { - char name[32]; /* Interface name, null-terminated. */ - unsigned int af; /* Address family. */ - isc_netaddr_t address; /* Local address. */ - isc_netaddr_t netmask; /* Network mask. */ - isc_netaddr_t dstaddress; /* Destination address - (point-to-point only). */ - isc_uint32_t flags; /* Flags; see below. */ + char name[32]; /*%< Interface name, null-terminated. */ + unsigned int af; /*%< Address family. */ + isc_netaddr_t address; /*%< Local address. */ + isc_netaddr_t netmask; /*%< Network mask. */ + isc_netaddr_t dstaddress; /*%< Destination address (point-to-point only). */ + isc_uint32_t flags; /*%< Flags; see INTERFACE flags. */ }; -/* Interface flags. */ +/*@{*/ +/*! Interface flags. */ #define INTERFACE_F_UP 0x00000001U #define INTERFACE_F_POINTTOPOINT 0x00000002U #define INTERFACE_F_LOOPBACK 0x00000004U +/*@}*/ /*** *** Functions @@ -74,59 +73,59 @@ ISC_LANG_BEGINDECLS isc_result_t isc_interfaceiter_create(isc_mem_t *mctx, isc_interfaceiter_t **iterp); -/* - * Create an iterator for traversing the operating system's list +/*!< + * \brief Create an iterator for traversing the operating system's list * of network interfaces. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * Various network-related errors + *\li #ISC_R_SUCCESS + * \li #ISC_R_NOMEMORY + *\li Various network-related errors */ isc_result_t isc_interfaceiter_first(isc_interfaceiter_t *iter); -/* - * Position the iterator on the first interface. +/*!< + * \brief Position the iterator on the first interface. * * Returns: - * ISC_R_SUCCESS Success. - * ISC_R_NOMORE There are no interfaces. + *\li #ISC_R_SUCCESS Success. + *\li #ISC_R_NOMORE There are no interfaces. */ isc_result_t isc_interfaceiter_current(isc_interfaceiter_t *iter, isc_interface_t *ifdata); -/* - * Get information about the interface the iterator is currently +/*!< + * \brief Get information about the interface the iterator is currently * positioned at and store it at *ifdata. * * Requires: - * The iterator has been successfully positioned using + *\li The iterator has been successfully positioned using * isc_interface_iter_first() / isc_interface_iter_next(). * * Returns: - * ISC_R_SUCCESS Success. + *\li #ISC_R_SUCCESS Success. */ isc_result_t isc_interfaceiter_next(isc_interfaceiter_t *iter); -/* - * Position the iterator on the next interface. +/*!< + * \brief Position the iterator on the next interface. * * Requires: - * The iterator has been successfully positioned using + * \li The iterator has been successfully positioned using * isc_interface_iter_first() / isc_interface_iter_next(). * * Returns: - * ISC_R_SUCCESS Success. - * ISC_R_NOMORE There are no more interfaces. + *\li #ISC_R_SUCCESS Success. + *\li #ISC_R_NOMORE There are no more interfaces. */ void isc_interfaceiter_destroy(isc_interfaceiter_t **iterp); -/* - * Destroy the iterator. +/*!< + * \brief Destroy the iterator. */ ISC_LANG_ENDDECLS diff --git a/lib/isc/include/isc/ipv6.h b/lib/isc/include/isc/ipv6.h index 4d7cd9aaac..d80b876a42 100644 --- a/lib/isc/include/isc/ipv6.h +++ b/lib/isc/include/isc/ipv6.h @@ -15,12 +15,12 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ipv6.h,v 1.20 2004/03/05 05:10:58 marka Exp $ */ +/* $Id: ipv6.h,v 1.21 2005/04/27 04:57:18 sra Exp $ */ #ifndef ISC_IPV6_H #define ISC_IPV6_H 1 -/* +/*! * Also define LWRES_IPV6_H to keep it from being included if liblwres is * being used, or redefinition errors will occur. */ @@ -30,23 +30,23 @@ ***** Module Info *****/ -/* - * IPv6 definitions for systems which do not support IPv6. +/*! \file isc/ipv6.h + * \brief IPv6 definitions for systems which do not support IPv6. * - * MP: + * \li MP: * No impact. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: + * \li Resources: * N/A. * - * Security: + * \li Security: * No anticipated impact. * - * Standards: - * RFC 2553. + * \li Standards: + * RFC2553. */ /*** @@ -95,7 +95,7 @@ struct sockaddr_in6 { #define SIN6_LEN 1 #endif -/* +/*% * Unspecified */ #define IN6_IS_ADDR_UNSPECIFIED(a) \ @@ -104,7 +104,7 @@ struct sockaddr_in6 { ((a)->s6_addr32[2] == 0) && \ ((a)->s6_addr32[3] == 0)) -/* +/*% * Loopback */ #define IN6_IS_ADDR_LOOPBACK(a) \ @@ -113,7 +113,7 @@ struct sockaddr_in6 { ((a)->s6_addr32[2] == 0) && \ ((a)->s6_addr32[3] == htonl(1))) -/* +/*% * IPv4 compatible */ #define IN6_IS_ADDR_V4COMPAT(a) \ @@ -123,7 +123,7 @@ struct sockaddr_in6 { ((a)->s6_addr32[3] != 0) && \ ((a)->s6_addr32[3] != htonl(1))) -/* +/*% * Mapped */ #define IN6_IS_ADDR_V4MAPPED(a) \ @@ -131,13 +131,13 @@ struct sockaddr_in6 { ((a)->s6_addr32[1] == 0) && \ ((a)->s6_addr32[2] == htonl(0x0000ffff))) -/* +/*% * Multicast */ #define IN6_IS_ADDR_MULTICAST(a) \ ((a)->s6_addr8[0] == 0xffU) -/* +/*% * Unicast link / site local. */ #define IN6_IS_ADDR_LINKLOCAL(a) \ diff --git a/lib/isc/include/isc/lang.h b/lib/isc/include/isc/lang.h index 2fefc9aabc..0438de1e3a 100644 --- a/lib/isc/include/isc/lang.h +++ b/lib/isc/include/isc/lang.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lang.h,v 1.7 2004/03/05 05:10:58 marka Exp $ */ +/* $Id: lang.h,v 1.8 2005/04/27 04:57:18 sra Exp $ */ #ifndef ISC_LANG_H #define ISC_LANG_H 1 +/*! \file */ + #ifdef __cplusplus #define ISC_LANG_BEGINDECLS extern "C" { #define ISC_LANG_ENDDECLS } diff --git a/lib/isc/include/isc/lex.h b/lib/isc/include/isc/lex.h index e90932130c..d751345c53 100644 --- a/lib/isc/include/isc/lex.h +++ b/lib/isc/include/isc/lex.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lex.h,v 1.30 2004/03/05 05:10:58 marka Exp $ */ +/* $Id: lex.h,v 1.31 2005/04/27 04:57:18 sra Exp $ */ #ifndef ISC_LEX_H #define ISC_LEX_H 1 @@ -24,28 +24,26 @@ ***** Module Info *****/ -/* - * Lex - * - * The "lex" module provides a lightweight tokenizer. It can operate +/*! \file isc/lex.h + * \brief The "lex" module provides a lightweight tokenizer. It can operate * on files or buffers, and can handle "include". It is designed for * parsing of DNS master files and the BIND configuration file, but * should be general enough to tokenize other things, e.g. HTTP. * - * MP: + * \li MP: * No synchronization is provided. Clients must ensure exclusive * access. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: - * + * \li Resources: + * TBS * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ @@ -65,31 +63,35 @@ ISC_LANG_BEGINDECLS *** Options ***/ -/* +/*@{*/ +/*! * Various options for isc_lex_gettoken(). */ -#define ISC_LEXOPT_EOL 0x01 /* Want end-of-line token. */ -#define ISC_LEXOPT_EOF 0x02 /* Want end-of-file token. */ -#define ISC_LEXOPT_INITIALWS 0x04 /* Want initial whitespace. */ -#define ISC_LEXOPT_NUMBER 0x08 /* Recognize numbers. */ -#define ISC_LEXOPT_QSTRING 0x10 /* Recognize qstrings. */ +#define ISC_LEXOPT_EOL 0x01 /*%< Want end-of-line token. */ +#define ISC_LEXOPT_EOF 0x02 /*%< Want end-of-file token. */ +#define ISC_LEXOPT_INITIALWS 0x04 /*%< Want initial whitespace. */ +#define ISC_LEXOPT_NUMBER 0x08 /*%< Recognize numbers. */ +#define ISC_LEXOPT_QSTRING 0x10 /*%< Recognize qstrings. */ +/*@}*/ -/* +/*@{*/ +/*! * The ISC_LEXOPT_DNSMULTILINE option handles the processing of '(' and ')' in * the DNS master file format. If this option is set, then the * ISC_LEXOPT_INITIALWS and ISC_LEXOPT_EOL options will be ignored when * the paren count is > 0. To use this option, '(' and ')' must be special * characters. */ -#define ISC_LEXOPT_DNSMULTILINE 0x20 /* Handle '(' and ')'. */ -#define ISC_LEXOPT_NOMORE 0x40 /* Want "no more" token. */ +#define ISC_LEXOPT_DNSMULTILINE 0x20 /*%< Handle '(' and ')'. */ +#define ISC_LEXOPT_NOMORE 0x40 /*%< Want "no more" token. */ -#define ISC_LEXOPT_CNUMBER 0x80 /* Regognise octal and hex */ -#define ISC_LEXOPT_ESCAPE 0x100 /* Recognize escapes. */ -#define ISC_LEXOPT_QSTRINGMULTILINE 0x200 /* Allow multiline "" strings */ - -/* +#define ISC_LEXOPT_CNUMBER 0x80 /*%< Regognize octal and hex */ +#define ISC_LEXOPT_ESCAPE 0x100 /*%< Recognize escapes. */ +#define ISC_LEXOPT_QSTRINGMULTILINE 0x200 /*%< Allow multiline "" strings */ +/*@}*/ +/*@{*/ +/*! * Various commenting styles, which may be changed at any time with * isc_lex_setcomments(). */ @@ -98,12 +100,13 @@ ISC_LANG_BEGINDECLS #define ISC_LEXCOMMENT_CPLUSPLUS 0x02 #define ISC_LEXCOMMENT_SHELL 0x04 #define ISC_LEXCOMMENT_DNSMASTERFILE 0x08 +/*@}*/ /*** *** Types ***/ -/* Lex */ +/*! Lex */ typedef char isc_lexspecials_t[256]; @@ -140,268 +143,268 @@ typedef struct isc_token { isc_result_t isc_lex_create(isc_mem_t *mctx, size_t max_token, isc_lex_t **lexp); -/* +/*%< * Create a lexer. * * 'max_token' is a hint of the number of bytes in the largest token. * * Requires: - * '*lexp' is a valid lexer. + *\li '*lexp' is a valid lexer. * - * max_token > 0. + *\li max_token > 0. * * Ensures: - * On success, *lexp is attached to the newly created lexer. + *\li On success, *lexp is attached to the newly created lexer. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY */ void isc_lex_destroy(isc_lex_t **lexp); -/* +/*%< * Destroy the lexer. * * Requires: - * '*lexp' is a valid lexer. + *\li '*lexp' is a valid lexer. * * Ensures: - * *lexp == NULL + *\li *lexp == NULL */ unsigned int isc_lex_getcomments(isc_lex_t *lex); -/* +/*%< * Return the current lexer commenting styles. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * * Returns: - * The commenting sytles which are currently allowed. + *\li The commenting sytles which are currently allowed. */ void isc_lex_setcomments(isc_lex_t *lex, unsigned int comments); -/* +/*%< * Set allowed lexer commenting styles. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * - * 'comments' has meaningful values. + *\li 'comments' has meaningful values. */ void isc_lex_getspecials(isc_lex_t *lex, isc_lexspecials_t specials); -/* +/*%< * Put the current list of specials into 'specials'. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. */ void isc_lex_setspecials(isc_lex_t *lex, isc_lexspecials_t specials); -/* +/*!< * The characters in 'specials' are returned as tokens. Along with * whitespace, they delimit strings and numbers. * * Note: - * Comment processing takes precedence over special character + *\li Comment processing takes precedence over special character * recognition. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. */ isc_result_t isc_lex_openfile(isc_lex_t *lex, const char *filename); -/* +/*%< * Open 'filename' and make it the current input source for 'lex'. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * - * filename is a valid C string. + *\li filename is a valid C string. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY Out of memory - * ISC_R_NOTFOUND File not found - * ISC_R_NOPERM No permission to open file - * ISC_R_FAILURE Couldn't open file, not sure why - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY Out of memory + *\li #ISC_R_NOTFOUND File not found + *\li #ISC_R_NOPERM No permission to open file + *\li #ISC_R_FAILURE Couldn't open file, not sure why + *\li #ISC_R_UNEXPECTED */ isc_result_t isc_lex_openstream(isc_lex_t *lex, FILE *stream); -/* +/*%< * Make 'stream' the current input source for 'lex'. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * - * 'stream' is a valid C stream. + *\li 'stream' is a valid C stream. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY Out of memory + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY Out of memory */ isc_result_t isc_lex_openbuffer(isc_lex_t *lex, isc_buffer_t *buffer); -/* +/*%< * Make 'buffer' the current input source for 'lex'. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * - * 'buffer' is a valid buffer. + *\li 'buffer' is a valid buffer. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY Out of memory + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY Out of memory */ isc_result_t isc_lex_close(isc_lex_t *lex); -/* +/*%< * Close the most recently opened object (i.e. file or buffer). * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMORE No more input sources + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMORE No more input sources */ isc_result_t isc_lex_gettoken(isc_lex_t *lex, unsigned int options, isc_token_t *tokenp); -/* +/*%< * Get the next token. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * - * 'lex' has an input source. + *\li 'lex' has an input source. * - * 'options' contains valid options. + *\li 'options' contains valid options. * - * '*tokenp' is a valid pointer. + *\li '*tokenp' is a valid pointer. * * Returns: - * ISC_R_SUCCESS - * ISC_R_UNEXPECTEDEND - * ISC_R_NOMEMORY + *\li #ISC_R_SUCCESS + *\li #ISC_R_UNEXPECTEDEND + *\li #ISC_R_NOMEMORY * * These two results are returned only if their corresponding lexer * options are not set. * - * ISC_R_EOF End of input source - * ISC_R_NOMORE No more input sources + *\li #ISC_R_EOF End of input source + *\li #ISC_R_NOMORE No more input sources */ isc_result_t isc_lex_getmastertoken(isc_lex_t *lex, isc_token_t *token, isc_tokentype_t expect, isc_boolean_t eol); -/* +/*%< * Get the next token from a DNS master file type stream. This is a * convenience function that sets appropriate options and handles quoted * strings and end of line correctly for master files. It also ungets * unexpected tokens. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * - * 'token' is a valid pointer + *\li 'token' is a valid pointer * * Returns: * - * any return code from isc_lex_gettoken. + * \li any return code from isc_lex_gettoken(). */ void isc_lex_ungettoken(isc_lex_t *lex, isc_token_t *tokenp); -/* +/*%< * Unget the current token. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * - * 'lex' has an input source. + *\li 'lex' has an input source. * - * 'tokenp' points to a valid token. + *\li 'tokenp' points to a valid token. * - * There is no ungotten token already. + *\li There is no ungotten token already. */ void isc_lex_getlasttokentext(isc_lex_t *lex, isc_token_t *tokenp, isc_region_t *r); -/* +/*%< * Returns a region containing the text of the last token returned. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * - * 'lex' has an input source. + *\li 'lex' has an input source. * - * 'tokenp' points to a valid token. + *\li 'tokenp' points to a valid token. * - * A token has been gotten and not ungotten. + *\li A token has been gotten and not ungotten. */ char * isc_lex_getsourcename(isc_lex_t *lex); -/* +/*%< * Return the input source name. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * * Returns: - * source name or NULL if no current source. - * result valid while current input source exists. + * \li source name or NULL if no current source. + *\li result valid while current input source exists. */ unsigned long isc_lex_getsourceline(isc_lex_t *lex); -/* +/*%< * Return the input source line number. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * * Returns: - * Current line number or 0 if no current source. + *\li Current line number or 0 if no current source. */ isc_result_t isc_lex_setsourcename(isc_lex_t *lex, const char *name); -/* +/*%< * Assigns a new name to the input source. * * Requires: * - * 'lex' is a valid lexer. + * \li 'lex' is a valid lexer. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_NOTFOUND - there are no sources. + * \li #ISC_R_SUCCESS + * \li #ISC_R_NOMEMORY + * \li #ISC_R_NOTFOUND - there are no sources. */ isc_boolean_t isc_lex_isfile(isc_lex_t *lex); -/* +/*%< * Return whether the current input source is a file. * * Requires: - * 'lex' is a valid lexer. + *\li 'lex' is a valid lexer. * * Returns: - * ISC_TRUE if the current input is a file, - * ISC_FALSE otherwise. + * \li #ISC_TRUE if the current input is a file, + *\li #ISC_FALSE otherwise. */ diff --git a/lib/isc/include/isc/lfsr.h b/lib/isc/include/isc/lfsr.h index e1b5fb23c6..bf0aa876c2 100644 --- a/lib/isc/include/isc/lfsr.h +++ b/lib/isc/include/isc/lfsr.h @@ -15,17 +15,19 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lfsr.h,v 1.11 2004/03/05 05:10:58 marka Exp $ */ +/* $Id: lfsr.h,v 1.12 2005/04/27 04:57:18 sra Exp $ */ #ifndef ISC_LFSR_H #define ISC_LFSR_H 1 +/*! \file */ + #include #include typedef struct isc_lfsr isc_lfsr_t; -/* +/*% * This function is called when reseeding is needed. It is allowed to * modify any state in the LFSR in any way it sees fit OTHER THAN "bits". * @@ -36,96 +38,91 @@ typedef struct isc_lfsr isc_lfsr_t; */ typedef void (*isc_lfsrreseed_t)(isc_lfsr_t *, void *); -/* +/*% * The members of this structure can be used by the application, but care * needs to be taken to not change state once the lfsr is in operation. */ struct isc_lfsr { - isc_uint32_t state; /* previous state */ - unsigned int bits; /* length */ - isc_uint32_t tap; /* bit taps */ - unsigned int count; /* reseed count (in BITS!) */ - isc_lfsrreseed_t reseed; /* reseed function */ - void *arg; /* reseed function argument */ + isc_uint32_t state; /*%< previous state */ + unsigned int bits; /*%< length */ + isc_uint32_t tap; /*%< bit taps */ + unsigned int count; /*%< reseed count (in BITS!) */ + isc_lfsrreseed_t reseed; /*%< reseed function */ + void *arg; /*%< reseed function argument */ }; ISC_LANG_BEGINDECLS -/* - * In all these functions it is important that the caller only use as many - * bits as the LFSR has state. Also, it isn't guaranteed that an LFSR of - * bit length 32 will have 2^32 unique states before repeating. - */ void isc_lfsr_init(isc_lfsr_t *lfsr, isc_uint32_t state, unsigned int bits, isc_uint32_t tap, unsigned int count, isc_lfsrreseed_t reseed, void *arg); -/* +/*%< * Initialize an LFSR. * * Note: * - * Putting untrusted values into this function will cause the LFSR to + *\li Putting untrusted values into this function will cause the LFSR to * generate (perhaps) non-maximal length sequences. * * Requires: * - * lfsr != NULL + *\li lfsr != NULL * - * 8 <= bits <= 32 + *\li 8 <= bits <= 32 * - * tap != 0 + *\li tap != 0 */ void isc_lfsr_generate(isc_lfsr_t *lfsr, void *data, unsigned int count); -/* +/*%< * Returns "count" bytes of data from the LFSR. * * Requires: * - * lfsr be valid. + *\li lfsr be valid. * - * data != NULL. + *\li data != NULL. * - * count > 0. + *\li count > 0. */ void isc_lfsr_skip(isc_lfsr_t *lfsr, unsigned int skip); -/* +/*%< * Skip "skip" states. * * Requires: * - * lfsr be valid. + *\li lfsr be valid. */ isc_uint32_t isc_lfsr_generate32(isc_lfsr_t *lfsr1, isc_lfsr_t *lfsr2); -/* +/*%< * Given two LFSRs, use the current state from each to skip entries in the * other. The next states are then xor'd together and returned. * * WARNING: * - * This function is used only for very, very low security data, such + *\li This function is used only for very, very low security data, such * as DNS message IDs where it is desired to have an unpredictable * stream of bytes that are harder to predict than a simple flooding * attack. * * Notes: * - * Since the current state from each of the LFSRs is used to skip + *\li Since the current state from each of the LFSRs is used to skip * state in the other, it is important that no state be leaked * from either LFSR. * * Requires: * - * lfsr1 and lfsr2 be valid. + *\li lfsr1 and lfsr2 be valid. * - * 1 <= skipbits <= 31 + *\li 1 <= skipbits <= 31 */ ISC_LANG_ENDDECLS diff --git a/lib/isc/include/isc/lib.h b/lib/isc/include/isc/lib.h index 1a478017f9..f3cde4c86c 100644 --- a/lib/isc/include/isc/lib.h +++ b/lib/isc/include/isc/lib.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lib.h,v 1.8 2004/03/05 05:10:58 marka Exp $ */ +/* $Id: lib.h,v 1.9 2005/04/27 04:57:18 sra Exp $ */ #ifndef ISC_LIB_H #define ISC_LIB_H 1 +/*! \file */ + #include #include @@ -29,8 +31,8 @@ LIBISC_EXTERNAL_DATA extern isc_msgcat_t *isc_msgcat; void isc_lib_initmsgcat(void); -/* - * Initialize the ISC library's message catalog, isc_msgcat, if it +/*!< + * \brief Initialize the ISC library's message catalog, isc_msgcat, if it * has not already been initialized. */ diff --git a/lib/isc/include/isc/log.h b/lib/isc/include/isc/log.h index 96bcaf69ba..cf6aaa2495 100644 --- a/lib/isc/include/isc/log.h +++ b/lib/isc/include/isc/log.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: log.h,v 1.48 2004/04/10 04:33:36 marka Exp $ */ +/* $Id: log.h,v 1.49 2005/04/27 04:57:18 sra Exp $ */ #ifndef ISC_LOG_H #define ISC_LOG_H 1 +/*! \file */ + #include #include #include /* XXXDCL NT */ @@ -29,29 +31,36 @@ #include #include -/* - * Severity levels, patterned after Unix's syslog levels. +/*@{*/ +/*! + * \brief Severity levels, patterned after Unix's syslog levels. * - * ISC_LOG_DYNAMIC can only be used for defining channels with - * isc_log_createchannel(), not to specify a level in isc_log_write(). */ #define ISC_LOG_DEBUG(level) (level) +/*! + * #ISC_LOG_DYNAMIC can only be used for defining channels with + * isc_log_createchannel(), not to specify a level in isc_log_write(). + */ #define ISC_LOG_DYNAMIC 0 #define ISC_LOG_INFO (-1) #define ISC_LOG_NOTICE (-2) #define ISC_LOG_WARNING (-3) #define ISC_LOG_ERROR (-4) #define ISC_LOG_CRITICAL (-5) +/*@}*/ -/* - * Destinations. +/*@{*/ +/*! + * \brief Destinations. */ #define ISC_LOG_TONULL 1 #define ISC_LOG_TOSYSLOG 2 #define ISC_LOG_TOFILE 3 #define ISC_LOG_TOFILEDESC 4 +/*@}*/ -/* +/*@{*/ +/*% * Channel flags. */ #define ISC_LOG_PRINTTIME 0x0001 @@ -62,18 +71,24 @@ #define ISC_LOG_PRINTALL 0x001F #define ISC_LOG_DEBUGONLY 0x1000 #define ISC_LOG_OPENERR 0x8000 /* internal */ +/*@}*/ -/* - * Other options. +/*@{*/ +/*! + * \brief Other options. + * * XXXDCL INFINITE doesn't yet work. Arguably it isn't needed, but * since I am intend to make large number of versions work efficiently, * INFINITE is going to be trivial to add to that. */ #define ISC_LOG_ROLLINFINITE (-1) #define ISC_LOG_ROLLNEVER (-2) +/*@}*/ -/* - * Used to name the categories used by a library. An array of isc_logcategory +/*! + * \brief Used to name the categories used by a library. + * + * An array of isc_logcategory * structures names each category, and the id value is initialized by calling * isc_log_registercategories. */ @@ -82,28 +97,30 @@ struct isc_logcategory { unsigned int id; }; -/* - * Similar to isc_logcategory above, but for all the modules a library defines. +/*% + * Similar to isc_logcategory, but for all the modules a library defines. */ struct isc_logmodule { const char *name; unsigned int id; }; -/* +/*% * The isc_logfile structure is initialized as part of an isc_logdestination - * before calling isc_log_createchannel(). When defining an ISC_LOG_TOFILE + * before calling isc_log_createchannel(). + * + * When defining an #ISC_LOG_TOFILE * channel the name, versions and maximum_size should be set before calling - * isc_log_createchannel(). To define an ISC_LOG_TOFILEDESC channel set only + * isc_log_createchannel(). To define an #ISC_LOG_TOFILEDESC channel set only * the stream before the call. * * Setting maximum_size to zero implies no maximum. */ typedef struct isc_logfile { - FILE *stream; /* Initialized to NULL for ISC_LOG_TOFILE. */ - const char *name; /* NULL for ISC_LOG_TOFILEDESC. */ - int versions; /* >= 0, ISC_LOG_ROLLNEVER, ISC_LOG_ROLLINFINITE. */ - /* + FILE *stream; /*%< Initialized to NULL for #ISC_LOG_TOFILE. */ + const char *name; /*%< NULL for #ISC_LOG_TOFILEDESC. */ + int versions; /* >= 0, #ISC_LOG_ROLLNEVER, #ISC_LOG_ROLLINFINITE. */ + /*% * stdio's ftell is standardized to return a long, which may well not * be big enough for the largest file supportable by the operating * system (though it is _probably_ big enough for the largest log @@ -111,10 +128,10 @@ typedef struct isc_logfile { * to a size large enough for the largest possible file on a system. */ isc_offset_t maximum_size; - isc_boolean_t maximum_reached; /* Private. */ + isc_boolean_t maximum_reached; /*%< Private. */ } isc_logfile_t; -/* +/*% * Passed to isc_log_createchannel to define the attributes of either * a stdio or a syslog log. */ @@ -123,7 +140,8 @@ typedef union isc_logdestination { int facility; /* XXXDCL NT */ } isc_logdestination_t; -/* +/*@{*/ +/*% * The built-in categories of libisc. * * Each library registering categories should provide library_LOGCATEGORY_name @@ -133,13 +151,16 @@ typedef union isc_logdestination { LIBISC_EXTERNAL_DATA extern isc_logcategory_t isc_categories[]; LIBISC_EXTERNAL_DATA extern isc_log_t *isc_lctx; LIBISC_EXTERNAL_DATA extern isc_logmodule_t isc_modules[]; +/*@}*/ -/* +/*@{*/ +/*% * Do not log directly to DEFAULT. Use another category. When in doubt, * use GENERAL. */ #define ISC_LOGCATEGORY_DEFAULT (&isc_categories[0]) #define ISC_LOGCATEGORY_GENERAL (&isc_categories[1]) +/*@}*/ #define ISC_LOGMODULE_SOCKET (&isc_modules[0]) #define ISC_LOGMODULE_TIME (&isc_modules[1]) @@ -150,33 +171,33 @@ ISC_LANG_BEGINDECLS isc_result_t isc_log_create(isc_mem_t *mctx, isc_log_t **lctxp, isc_logconfig_t **lcfgp); -/* +/*%< * Establish a new logging context, with default channels. * * Notes: - * isc_log_create calls isc_logconfig_create, so see its comment + *\li isc_log_create() calls isc_logconfig_create(), so see its comment * below for more information. * * Requires: - * mctx is a valid memory context. - * lctxp is not null and *lctxp is null. - * lcfgp is null or lcfgp is not null and *lcfgp is null. + *\li mctx is a valid memory context. + *\li lctxp is not null and *lctxp is null. + *\li lcfgp is null or lcfgp is not null and *lcfgp is null. * * Ensures: - * *lctxp will point to a valid logging context if all of the necessary + *\li *lctxp will point to a valid logging context if all of the necessary * memory was allocated, or NULL otherwise. - * *lcfgp will point to a valid logging configuration if all of the + *\li *lcfgp will point to a valid logging configuration if all of the * necessary memory was allocated, or NULL otherwise. - * On failure, no additional memory is allocated. + *\li On failure, no additional memory is allocated. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_NOMEMORY Resource limit: Out of memory + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_NOMEMORY Resource limit: Out of memory */ isc_result_t isc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp); -/* +/*%< * Create the data structure that holds all of the configurable information * about where messages are actually supposed to be sent -- the information * that could changed based on some configuration file, as opposed to the @@ -184,190 +205,192 @@ isc_logconfig_create(isc_log_t *lctx, isc_logconfig_t **lcfgp); * into a program, or the debug_level which is dynamic state information. * * Notes: - * It is necessary to specify the logging context the configuration + *\li It is necessary to specify the logging context the configuration * will be used with because the number of categories and modules * needs to be known in order to set the configuration. However, * the configuration is not used by the logging context until the * isc_logconfig_use function is called. * - * The memory context used for operations that allocate memory for + *\li The memory context used for operations that allocate memory for * the configuration is that of the logging context, as specified * in the isc_log_create call. * - * Four default channels are established: + *\li Four default channels are established: + *\verbatim * default_syslog - * - log to syslog's daemon facility ISC_LOG_INFO or higher + * - log to syslog's daemon facility #ISC_LOG_INFO or higher * default_stderr - * - log to stderr ISC_LOG_INFO or higher + * - log to stderr #ISC_LOG_INFO or higher * default_debug - * - log to stderr ISC_LOG_DEBUG dynamically + * - log to stderr #ISC_LOG_DEBUG dynamically * null * - log nothing + *\endverbatim * * Requires: - * lctx is a valid logging context. - * lcftp is not null and *lcfgp is null. + *\li lctx is a valid logging context. + *\li lcftp is not null and *lcfgp is null. * * Ensures: - * *lcfgp will point to a valid logging context if all of the necessary + *\li *lcfgp will point to a valid logging context if all of the necessary * memory was allocated, or NULL otherwise. - * On failure, no additional memory is allocated. + *\li On failure, no additional memory is allocated. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_NOMEMORY Resource limit: Out of memory + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_NOMEMORY Resource limit: Out of memory */ isc_logconfig_t * isc_logconfig_get(isc_log_t *lctx); -/* +/*%< * Returns a pointer to the configuration currently in use by the log context. * * Requires: - * lctx is a valid context. + *\li lctx is a valid context. * * Ensures: - * The configuration pointer is non-null. + *\li The configuration pointer is non-null. * * Returns: - * The configuration pointer. + *\li The configuration pointer. */ isc_result_t isc_logconfig_use(isc_log_t *lctx, isc_logconfig_t *lcfg); -/* +/*%< * Associate a new configuration with a logging context. * * Notes: - * This is thread safe. The logging context will lock a mutex + *\li This is thread safe. The logging context will lock a mutex * before attempting to swap in the new configuration, and isc_log_doit * (the internal function used by all of isc_log_[v]write[1]) locks * the same lock for the duration of its use of the configuration. * * Requires: - * lctx is a valid logging context. - * lcfg is a valid logging configuration. - * lctx is the same configuration given to isc_logconfig_create + *\li lctx is a valid logging context. + *\li lcfg is a valid logging configuration. + *\li lctx is the same configuration given to isc_logconfig_create * when the configuration was created. * * Ensures: - * Future calls to isc_log_write will use the new configuration. + *\li Future calls to isc_log_write will use the new configuration. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_NOMEMORY Resource limit: Out of memory + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_NOMEMORY Resource limit: Out of memory */ void isc_log_destroy(isc_log_t **lctxp); -/* +/*%< * Deallocate the memory associated with a logging context. * * Requires: - * *lctx is a valid logging context. + *\li *lctx is a valid logging context. * * Ensures: - * All of the memory associated with the logging context is returned + *\li All of the memory associated with the logging context is returned * to the free memory pool. * - * Any open files are closed. + *\li Any open files are closed. * - * The logging context is marked as invalid. + *\li The logging context is marked as invalid. */ void isc_logconfig_destroy(isc_logconfig_t **lcfgp); -/* +/*%< * Destroy a logging configuration. * * Notes: - * This function cannot be used directly with the return value of + *\li This function cannot be used directly with the return value of * isc_logconfig_get, because a logging context must always have * a valid configuration associated with it. * * Requires: - * lcfgp is not null and *lcfgp is a valid logging configuration. - * The logging configuration is not in use by an existing logging context. + *\li lcfgp is not null and *lcfgp is a valid logging configuration. + *\li The logging configuration is not in use by an existing logging context. * * Ensures: - * All memory allocated for the configuration is freed. + *\li All memory allocated for the configuration is freed. * - * The configuration is marked as invalid. + *\li The configuration is marked as invalid. */ void isc_log_registercategories(isc_log_t *lctx, isc_logcategory_t categories[]); -/* +/*%< * Identify logging categories a library will use. * * Notes: - * A category should only be registered once, but no mechanism enforces + *\li A category should only be registered once, but no mechanism enforces * this rule. * - * The end of the categories array is identified by a NULL name. + *\li The end of the categories array is identified by a NULL name. * - * Because the name is used by ISC_LOG_PRINTCATEGORY, it should not + *\li Because the name is used by #ISC_LOG_PRINTCATEGORY, it should not * be altered or destroyed after isc_log_registercategories(). * - * Because each element of the categories array is used by + *\li Because each element of the categories array is used by * isc_log_categorybyname, it should not be altered or destroyed * after registration. * - * The value of the id integer in each structure is overwritten + *\li The value of the id integer in each structure is overwritten * by this function, and so id need not be initialized to any particular * value prior to the function call. * - * A subsequent call to isc_log_registercategories with the same + *\li A subsequent call to isc_log_registercategories with the same * logging context (but new categories) will cause the last * element of the categories array from the prior call to have * its "name" member changed from NULL to point to the new * categories array, and its "id" member set to UINT_MAX. * * Requires: - * lctx is a valid logging context. - * categories != NULL. - * categories[0].name != NULL. + *\li lctx is a valid logging context. + *\li categories != NULL. + *\li categories[0].name != NULL. * * Ensures: - * There are references to each category in the logging context, + * \li There are references to each category in the logging context, * so they can be used with isc_log_usechannel() and isc_log_write(). */ void isc_log_registermodules(isc_log_t *lctx, isc_logmodule_t modules[]); -/* +/*%< * Identify logging categories a library will use. * * Notes: - * A module should only be registered once, but no mechanism enforces + *\li A module should only be registered once, but no mechanism enforces * this rule. * - * The end of the modules array is identified by a NULL name. + *\li The end of the modules array is identified by a NULL name. * - * Because the name is used by ISC_LOG_PRINTMODULE, it should not + *\li Because the name is used by #ISC_LOG_PRINTMODULE, it should not * be altered or destroyed after isc_log_registermodules(). * - * Because each element of the modules array is used by + *\li Because each element of the modules array is used by * isc_log_modulebyname, it should not be altered or destroyed * after registration. * - * The value of the id integer in each structure is overwritten + *\li The value of the id integer in each structure is overwritten * by this function, and so id need not be initialized to any particular * value prior to the function call. * - * A subsequent call to isc_log_registermodules with the same + *\li A subsequent call to isc_log_registermodules with the same * logging context (but new modules) will cause the last * element of the modules array from the prior call to have * its "name" member changed from NULL to point to the new * modules array, and its "id" member set to UINT_MAX. * * Requires: - * lctx is a valid logging context. - * modules != NULL. - * modules[0].name != NULL; + *\li lctx is a valid logging context. + *\li modules != NULL. + *\li modules[0].name != NULL; * * Ensures: - * Each module has a reference in the logging context, so they can be + *\li Each module has a reference in the logging context, so they can be * used with isc_log_usechannel() and isc_log_write(). */ @@ -376,68 +399,67 @@ isc_log_createchannel(isc_logconfig_t *lcfg, const char *name, unsigned int type, int level, const isc_logdestination_t *destination, unsigned int flags); -/* +/*%< * Specify the parameters of a logging channel. * * Notes: - * The name argument is copied to memory in the logging context, so + *\li The name argument is copied to memory in the logging context, so * it can be altered or destroyed after isc_log_createchannel(). * - * Defining a very large number of channels will have a performance + *\li Defining a very large number of channels will have a performance * impact on isc_log_usechannel(), since the names are searched * linearly until a match is made. This same issue does not affect * isc_log_write, however. * - * Channel names can be redefined; this is primarily useful for programs + *\li Channel names can be redefined; this is primarily useful for programs * that want their own definition of default_syslog, default_debug * and default_stderr. * - * Any channel that is redefined will not affect logging that was + *\li Any channel that is redefined will not affect logging that was * already directed to its original definition, _except_ for the * default_stderr channel. This case is handled specially so that * the default logging category can be changed by redefining * default_stderr. (XXXDCL Though now that I think of it, the default * logging category can be changed with only one additional function * call by defining a new channel and then calling isc_log_usechannel() - * for ISC_LOGCATEGORY_DEFAULT.) + * for #ISC_LOGCATEGORY_DEFAULT.) * - * Specifying ISC_LOG_PRINTTIME or ISC_LOG_PRINTTAG for syslog is allowed, + *\li Specifying #ISC_LOG_PRINTTIME or #ISC_LOG_PRINTTAG for syslog is allowed, * but probably not what you wanted to do. * - * ISC_LOG_DEBUGONLY will mark the channel as usable only when the + * #ISC_LOG_DEBUGONLY will mark the channel as usable only when the * debug level of the logging context (see isc_log_setdebuglevel) * is non-zero. * * Requires: - * lcfg is a valid logging configuration. + *\li lcfg is a valid logging configuration. * - * name is not NULL. + *\li name is not NULL. * - * type is ISC_LOG_TOSYSLOG, ISC_LOG_TOFILE, ISC_LOG_TOFILEDESC or - * ISC_LOG_TONULL. + *\li type is #ISC_LOG_TOSYSLOG, #ISC_LOG_TOFILE, #ISC_LOG_TOFILEDESC or + * #ISC_LOG_TONULL. * - * destination is not NULL unless type is ISC_LOG_TONULL. + *\li destination is not NULL unless type is #ISC_LOG_TONULL. * - * level is >= ISC_LOG_CRITICAL (the most negative logging level). + *\li level is >= #ISC_LOG_CRITICAL (the most negative logging level). * - * flags does not include any bits aside from the ISC_LOG_PRINT* bits - * or ISC_LOG_DEBUGONLY. + *\li flags does not include any bits aside from the ISC_LOG_PRINT* bits + * or #ISC_LOG_DEBUGONLY. * * Ensures: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * A channel with the given name is usable with * isc_log_usechannel(). * - * ISC_R_NOMEMORY or ISC_R_UNEXPECTED + *\li #ISC_R_NOMEMORY or #ISC_R_UNEXPECTED * No additional memory is being used by the logging context. - * * Any channel that previously existed with the given name * is not redefined. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_NOMEMORY Resource limit: Out of memory - * ISC_R_UNEXPECTED type was out of range and REQUIRE() + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_NOMEMORY Resource limit: Out of memory + *\li #ISC_R_UNEXPECTED type was out of range and REQUIRE() * was disabled. */ @@ -445,166 +467,186 @@ isc_result_t isc_log_usechannel(isc_logconfig_t *lcfg, const char *name, const isc_logcategory_t *category, const isc_logmodule_t *module); -/* +/*%< * Associate a named logging channel with a category and module that * will use it. * * Notes: - * The name is searched for linearly in the set of known channel names + *\li The name is searched for linearly in the set of known channel names * until a match is found. (Note the performance impact of a very large * number of named channels.) When multiple channels of the same * name are defined, the most recent definition is found. * - * Specifing a very large number of channels for a category will have + *\li Specifing a very large number of channels for a category will have * a moderate impact on performance in isc_log_write(), as each * call looks up the category for the start of a linked list, which * it follows all the way to the end to find matching modules. The * test for matching modules is integral, though. * - * If category is NULL, then the channel is associated with the indicated + *\li If category is NULL, then the channel is associated with the indicated * module for all known categories (including the "default" category). * - * If module is NULL, then the channel is associated with every module + *\li If module is NULL, then the channel is associated with every module * that uses that category. * - * Passing both category and module as NULL would make every log message + *\li Passing both category and module as NULL would make every log message * use the indicated channel. * - * Specifying a channel that is ISC_LOG_TONULL for a category/module pair + * \li Specifying a channel that is #ISC_LOG_TONULL for a category/module pair * has no effect on any other channels associated with that pair, * regardless of ordering. Thus you cannot use it to "mask out" one * category/module pair when you have specified some other channel that * is also used by that category/module pair. * * Requires: - * lcfg is a valid logging configuration. + *\li lcfg is a valid logging configuration. * - * category is NULL or has an id that is in the range of known ids. + *\li category is NULL or has an id that is in the range of known ids. * * module is NULL or has an id that is in the range of known ids. * * Ensures: - * ISC_R_SUCCESS + *\li #ISC_R_SUCCESS * The channel will be used by the indicated category/module * arguments. * - * ISC_R_NOMEMORY + *\li #ISC_R_NOMEMORY * If assignment for a specific category has been requested, * the channel has not been associated with the indicated * category/module arguments and no additional memory is * used by the logging context. - * * If assignment for all categories has been requested * then _some_ may have succeeded (starting with category * "default" and progressing through the order of categories - * passed to isc_log_registercategories) and additional memory + * passed to isc_log_registercategories()) and additional memory * is being used by whatever assignments succeeded. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_NOMEMORY Resource limit: Out of memory + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_NOMEMORY Resource limit: Out of memory */ -void -isc_log_write(isc_log_t *lctx, isc_logcategory_t *category, - isc_logmodule_t *module, int level, - const char *format, ...) -ISC_FORMAT_PRINTF(5, 6); -/* +/* Attention: next four comments PRECEED code */ +/*! + * \brief * Write a message to the log channels. * * Notes: - * Log messages containing natural language text should be logged with + *\li Log messages containing natural language text should be logged with * isc_log_iwrite() to allow for localization. * - * lctx can be NULL; this is allowed so that programs which use + *\li lctx can be NULL; this is allowed so that programs which use * libraries that use the ISC logging system are not required to * also use it. * - * The format argument is a printf(3) string, with additional arguments + *\li The format argument is a printf(3) string, with additional arguments * as necessary. * * Requires: - * lctx is a valid logging context. + *\li lctx is a valid logging context. * - * The category and module arguments must have ids that are in the + *\li The category and module arguments must have ids that are in the * range of known ids, as estabished by isc_log_registercategories() * and isc_log_registermodules(). * - * level != ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define + *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define * channels, and explicit debugging level must be identified for * isc_log_write() via ISC_LOG_DEBUG(level). * - * format != NULL. + *\li format != NULL. * * Ensures: - * The log message is written to every channel associated with the + *\li The log message is written to every channel associated with the * indicated category/module pair. * * Returns: - * Nothing. Failure to log a message is not construed as a + *\li Nothing. Failure to log a message is not construed as a * meaningful error. */ +void +isc_log_write(isc_log_t *lctx, isc_logcategory_t *category, + isc_logmodule_t *module, int level, + const char *format, ...) +ISC_FORMAT_PRINTF(5, 6); + +/*% + * Write a message to the log channels. + * + * Notes: + *\li lctx can be NULL; this is allowed so that programs which use + * libraries that use the ISC logging system are not required to + * also use it. + * + *\li The format argument is a printf(3) string, with additional arguments + * as necessary. + * + * Requires: + *\li lctx is a valid logging context. + * + *\li The category and module arguments must have ids that are in the + * range of known ids, as estabished by isc_log_registercategories() + * and isc_log_registermodules(). + * + *\li level != #ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define + * channels, and explicit debugging level must be identified for + * isc_log_write() via ISC_LOG_DEBUG(level). + * + *\li format != NULL. + * + * Ensures: + *\li The log message is written to every channel associated with the + * indicated category/module pair. + * + * Returns: + *\li Nothing. Failure to log a message is not construed as a + * meaningful error. + */ void isc_log_vwrite(isc_log_t *lctx, isc_logcategory_t *category, isc_logmodule_t *module, int level, const char *format, va_list args) -ISC_FORMAT_PRINTF(5, 0); -/* - * Write a message to the log channels. - * - * Notes: - * lctx can be NULL; this is allowed so that programs which use - * libraries that use the ISC logging system are not required to - * also use it. - * - * The format argument is a printf(3) string, with additional arguments - * as necessary. - * - * Requires: - * lctx is a valid logging context. - * - * The category and module arguments must have ids that are in the - * range of known ids, as estabished by isc_log_registercategories() - * and isc_log_registermodules(). - * - * level != ISC_LOG_DYNAMIC. ISC_LOG_DYNAMIC is used only to define - * channels, and explicit debugging level must be identified for - * isc_log_write() via ISC_LOG_DEBUG(level). - * - * format != NULL. - * - * Ensures: - * The log message is written to every channel associated with the - * indicated category/module pair. - * - * Returns: - * Nothing. Failure to log a message is not construed as a - * meaningful error. - */ -void -isc_log_write1(isc_log_t *lctx, isc_logcategory_t *category, - isc_logmodule_t *module, int level, const char *format, ...) -ISC_FORMAT_PRINTF(5, 6); -/* +ISC_FORMAT_PRINTF(5, 0); + +/*% * Write a message to the log channels, pruning duplicates that occur within * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval). * This function is otherwise identical to isc_log_write(). */ - void -isc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category, - isc_logmodule_t *module, int level, const char *format, - va_list args) -ISC_FORMAT_PRINTF(5, 0); -/* +isc_log_write1(isc_log_t *lctx, isc_logcategory_t *category, + isc_logmodule_t *module, int level, const char *format, ...) + +ISC_FORMAT_PRINTF(5, 6); + +/*% * Write a message to the log channels, pruning duplicates that occur within * a configurable amount of seconds (see isc_log_[sg]etduplicateinterval). * This function is otherwise identical to isc_log_vwrite(). */ +void +isc_log_vwrite1(isc_log_t *lctx, isc_logcategory_t *category, + isc_logmodule_t *module, int level, const char *format, + va_list args) +ISC_FORMAT_PRINTF(5, 0); + +/*% + * These are four internationalized versions of the the isc_log_[v]write[1] + * functions. + * + * The only difference is that they take arguments for a message + * catalog, message set, and message number, all immediately preceding the + * format argument. The format argument becomes the default text, a la + * isc_msgcat_get. If the message catalog is NULL, no lookup is attempted + * for a message -- which makes the message set and message number irrelevant, + * and the non-internationalized call should have probably been used instead. + * + * Yes, that means there are now *eight* interfaces to logging a message. + * Sheesh. Make the madness stop! + */ +/*@{*/ void isc_log_iwrite(isc_log_t *lctx, isc_logcategory_t *category, isc_logmodule_t *module, int level, @@ -632,72 +674,61 @@ isc_log_ivwrite1(isc_log_t *lctx, isc_logcategory_t *category, isc_msgcat_t *msgcat, int msgset, int message, const char *format, va_list args) ISC_FORMAT_PRINTF(8, 0); -/* - * These are four internationalized versions of the the isc_log_[v]write[1] - * functions. The only difference is that they take arguments for a message - * catalog, message set, and message number, all immediately preceding the - * format argument. The format argument becomes the default text, a la - * isc_msgcat_get. If the message catalog is NULL, no lookup is attempted - * for a message -- which makes the message set and message number irrelevant, - * and the non-internationalized call should have probably been used instead. - * - * Yes, that means there are now *eight* interfaces to logging a message. - * Sheesh. Make the madness stop! - */ +/*@}*/ void isc_log_setdebuglevel(isc_log_t *lctx, unsigned int level); -/* +/*%< * Set the debugging level used for logging. * * Notes: - * Setting the debugging level to 0 disables debugging log messages. + *\li Setting the debugging level to 0 disables debugging log messages. * * Requires: - * lctx is a valid logging context. + *\li lctx is a valid logging context. * * Ensures: - * The debugging level is set to the requested value. + *\li The debugging level is set to the requested value. */ unsigned int isc_log_getdebuglevel(isc_log_t *lctx); -/* +/*%< * Get the current debugging level. * * Notes: - * This is provided so that a program can have a notion of + *\li This is provided so that a program can have a notion of * "increment debugging level" or "decrement debugging level" * without needing to keep track of what the current level is. * - * A return value of 0 indicates that debugging messages are disabled. + *\li A return value of 0 indicates that debugging messages are disabled. * * Requires: - * lctx is a valid logging context. + *\li lctx is a valid logging context. * * Ensures: - * The current logging debugging level is returned. + *\li The current logging debugging level is returned. */ isc_boolean_t isc_log_wouldlog(isc_log_t *lctx, int level); -/* +/*%< * Determine whether logging something to 'lctx' at 'level' would * actually cause something to be logged somewhere. * - * If ISC_FALSE is returned, it is guaranteed that nothing would + * If #ISC_FALSE is returned, it is guaranteed that nothing would * be logged, allowing the caller to omit unnecessary * isc_log_write() calls and possible message preformatting. */ void isc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval); -/* +/*%< * Set the interval over which duplicate log messages will be ignored * by isc_log_[v]write1(), in seconds. * * Notes: - * Increasing the duplicate interval from X to Y will not necessarily + *\li Increasing the duplicate interval from X to Y will not necessarily * filter out duplicates of messages logged in Y - X seconds since the * increase. (Example: Message1 is logged at midnight. Message2 * is logged at 00:01:00, when the interval is only 30 seconds, causing @@ -707,43 +738,43 @@ isc_log_setduplicateinterval(isc_logconfig_t *lcfg, unsigned int interval); * passed since the first occurrence. * * Requires: - * lctx is a valid logging context. + *\li lctx is a valid logging context. */ unsigned int isc_log_getduplicateinterval(isc_logconfig_t *lcfg); -/* +/*%< * Get the current duplicate filtering interval. * * Requires: - * lctx is a valid logging context. + *\li lctx is a valid logging context. * * Returns: - * The current duplicate filtering interval. + *\li The current duplicate filtering interval. */ isc_result_t isc_log_settag(isc_logconfig_t *lcfg, const char *tag); -/* - * Set the program name or other identifier for ISC_LOG_PRINTTAG. +/*%< + * Set the program name or other identifier for #ISC_LOG_PRINTTAG. * * Requires: - * lcfg is a valid logging configuration. + *\li lcfg is a valid logging configuration. * * Notes: - * If this function has not set the tag to a non-NULL, non-empty value, - * then the ISC_LOG_PRINTTAG channel flag will not print anything. + *\li If this function has not set the tag to a non-NULL, non-empty value, + * then the #ISC_LOG_PRINTTAG channel flag will not print anything. * Unlike some implementations of syslog on Unix systems, you *must* set * the tag in order to get it logged. It is not implicitly derived from * the program name (which is pretty impossible to infer portably). * - * Setting the tag to NULL or the empty string will also cause the - * ISC_LOG_PRINTTAG channel flag to not print anything. If tag equals the + *\li Setting the tag to NULL or the empty string will also cause the + * #ISC_LOG_PRINTTAG channel flag to not print anything. If tag equals the * empty string, calls to isc_log_gettag will return NULL. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_NOMEMORY Resource Limit: Out of memory + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_NOMEMORY Resource Limit: Out of memory * * XXXDCL when creating a new isc_logconfig_t, it might be nice if the tag * of the currently active isc_logconfig_t was inherited. this does not @@ -752,33 +783,35 @@ isc_log_settag(isc_logconfig_t *lcfg, const char *tag); char * isc_log_gettag(isc_logconfig_t *lcfg); -/* - * Get the current identifier printed with ISC_LOG_PRINTTAG. +/*%< + * Get the current identifier printed with #ISC_LOG_PRINTTAG. * * Requires: - * lcfg is a valid logging configuration. + *\li lcfg is a valid logging configuration. * * Notes: - * Since isc_log_settag() will not associate a zero-length string + *\li Since isc_log_settag() will not associate a zero-length string * with the logging configuration, attempts to do so will cause * this function to return NULL. However, a determined programmer * will observe that (currently) a tag of length greater than zero * could be set, and then modified to be zero length. * * Returns: - * A pointer to the current identifier, or NULL if none has been set. + *\li A pointer to the current identifier, or NULL if none has been set. */ void isc_log_opensyslog(const char *tag, int options, int facility); -/* +/*%< * Initialize syslog logging. * * Notes: - * XXXDCL NT + *\li XXXDCL NT * This is currently equivalent to openlog(), but is not going to remain * that way. In the meantime, the arguments are all identical to * those used by openlog(3), as follows: + * + * \code * tag: The string to use in the position of the program * name in syslog messages. Most (all?) syslogs * will use basename(argv[0]) if tag is NULL. @@ -789,89 +822,90 @@ isc_log_opensyslog(const char *tag, int options, int facility); * facility: The default syslog facility. This is irrelevant * since isc_log_write will ALWAYS use the channel's * declared facility. + * \endcode * - * Zero effort has been made (yet) to accomodate systems with openlog() + *\li Zero effort has been made (yet) to accomodate systems with openlog() * that only takes two arguments, or to identify valid syslog * facilities or options for any given architecture. * - * It is necessary to call isc_log_opensyslog() to initialize + *\li It is necessary to call isc_log_opensyslog() to initialize * syslogging on machines which do not support network connections to * syslogd because they require a Unix domain socket to be used. Since * this is a chore to determine at run-time, it is suggested that it * always be called by programs using the ISC logging system. * * Requires: - * Nothing. + *\li Nothing. * * Ensures: - * openlog() is called to initialize the syslog system. + *\li openlog() is called to initialize the syslog system. */ void isc_log_closefilelogs(isc_log_t *lctx); -/* - * Close all open files used by ISC_LOG_TOFILE channels. +/*%< + * Close all open files used by #ISC_LOG_TOFILE channels. * * Notes: - * This function is provided for programs that want to use their own + *\li This function is provided for programs that want to use their own * log rolling mechanism rather than the one provided internally. * For example, a program that wanted to keep daily logs would define - * a channel which used ISC_LOG_ROLLNEVER, then once a day would + * a channel which used #ISC_LOG_ROLLNEVER, then once a day would * rename the log file and call isc_log_closefilelogs(). * - * ISC_LOG_TOFILEDESC channels are unaffected. + *\li #ISC_LOG_TOFILEDESC channels are unaffected. * * Requires: - * lctx is a valid context. + *\li lctx is a valid context. * * Ensures: - * The open files are closed and will be reopened when they are + *\li The open files are closed and will be reopened when they are * next needed. */ isc_logcategory_t * isc_log_categorybyname(isc_log_t *lctx, const char *name); -/* +/*%< * Find a category by its name. * * Notes: - * The string name of a category is not required to be unique. + *\li The string name of a category is not required to be unique. * * Requires: - * lctx is a valid context. - * name is not NULL. + *\li lctx is a valid context. + *\li name is not NULL. * * Returns: - * A pointer to the _first_ isc_logcategory_t structure used by "name". + *\li A pointer to the _first_ isc_logcategory_t structure used by "name". * - * NULL if no category exists by that name. + *\li NULL if no category exists by that name. */ isc_logmodule_t * isc_log_modulebyname(isc_log_t *lctx, const char *name); -/* +/*%< * Find a module by its name. * * Notes: - * The string name of a module is not required to be unique. + *\li The string name of a module is not required to be unique. * * Requires: - * lctx is a valid context. - * name is not NULL. + *\li lctx is a valid context. + *\li name is not NULL. * * Returns: - * A pointer to the _first_ isc_logmodule_t structure used by "name". + *\li A pointer to the _first_ isc_logmodule_t structure used by "name". * - * NULL if no module exists by that name. + *\li NULL if no module exists by that name. */ void isc_log_setcontext(isc_log_t *lctx); -/* +/*%< * Sets the context used by the libisc for logging. * * Requires: - * lctx be a valid context. + *\li lctx be a valid context. */ ISC_LANG_ENDDECLS diff --git a/lib/isc/include/isc/magic.h b/lib/isc/include/isc/magic.h index 7c9262ece3..8cd4b137d0 100644 --- a/lib/isc/include/isc/magic.h +++ b/lib/isc/include/isc/magic.h @@ -15,20 +15,21 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: magic.h,v 1.12 2004/03/05 05:10:58 marka Exp $ */ +/* $Id: magic.h,v 1.13 2005/04/27 04:57:18 sra Exp $ */ #ifndef ISC_MAGIC_H #define ISC_MAGIC_H 1 +/*! \file */ + typedef struct { unsigned int magic; } isc__magic_t; -/* +/*% * To use this macro the magic number MUST be the first thing in the * structure, and MUST be of type "unsigned int". - * * The intent of this is to allow magic numbers to be checked even though * the object is otherwise opaque. */ diff --git a/lib/isc/include/isc/md5.h b/lib/isc/include/isc/md5.h index b39e2102a7..ec3c0baf10 100644 --- a/lib/isc/include/isc/md5.h +++ b/lib/isc/include/isc/md5.h @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: md5.h,v 1.9 2004/03/05 05:10:58 marka Exp $ */ +/* $Id: md5.h,v 1.10 2005/04/27 04:57:18 sra Exp $ */ -/* - * This is the header file for the MD5 message-digest algorithm. +/*! \file + * \brief This is the header file for the MD5 message-digest algorithm. + * * The algorithm is due to Ron Rivest. This code was * written by Colin Plumb in 1993, no copyright is claimed. * This code is in the public domain; do with it what you wish. diff --git a/lib/isc/include/isc/mem.h b/lib/isc/include/isc/mem.h index ec676f007c..7c18502c2a 100644 --- a/lib/isc/include/isc/mem.h +++ b/lib/isc/include/isc/mem.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: mem.h,v 1.60 2004/10/11 05:49:29 marka Exp $ */ +/* $Id: mem.h,v 1.61 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_MEM_H #define ISC_MEM_H 1 +/*! \file */ + #include #include @@ -36,7 +38,7 @@ typedef void (*isc_mem_water_t)(void *, int); typedef void * (*isc_memalloc_t)(void *, size_t); typedef void (*isc_memfree_t)(void *, void *); -/* +/*% * Define ISC_MEM_DEBUG=1 to make all functions that free memory * set the pointer being freed to NULL after being freed. * This is the default; set ISC_MEM_DEBUG=0 to disable it. @@ -45,7 +47,7 @@ typedef void (*isc_memfree_t)(void *, void *); #define ISC_MEM_DEBUG 1 #endif -/* +/*% * Define ISC_MEM_TRACKLINES=1 to turn on detailed tracing of memory * allocation and freeing by file and line number. */ @@ -53,7 +55,7 @@ typedef void (*isc_memfree_t)(void *, void *); #define ISC_MEM_TRACKLINES 1 #endif -/* +/*% * Define ISC_MEM_CHECKOVERRUN=1 to turn on checks for using memory outside * the requested space. This will increase the size of each allocation. */ @@ -61,7 +63,7 @@ typedef void (*isc_memfree_t)(void *, void *); #define ISC_MEM_CHECKOVERRUN 1 #endif -/* +/*% * Define ISC_MEM_FILL=1 to fill each block of memory returned to the system * with the byte string '0xbe'. This helps track down uninitialized pointers * and the like. On freeing memory, the space is filled with '0xde' for @@ -71,7 +73,7 @@ typedef void (*isc_memfree_t)(void *, void *); #define ISC_MEM_FILL 1 #endif -/* +/*% * Define ISC_MEMPOOL_NAMES=1 to make memory pools store a symbolic * name so that the leaking pool can be more readily identified in * case of a memory leak. @@ -81,27 +83,29 @@ typedef void (*isc_memfree_t)(void *, void *); #endif LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging; +/*@{*/ #define ISC_MEM_DEBUGTRACE 0x00000001U #define ISC_MEM_DEBUGRECORD 0x00000002U #define ISC_MEM_DEBUGUSAGE 0x00000004U -/* +/*!< * The variable isc_mem_debugging holds a set of flags for * turning certain memory debugging options on or off at * runtime. Its is intialized to the value ISC_MEM_DEGBUGGING, * which is 0 by default but may be overridden at compile time. * The following flags can be specified: * - * ISC_MEM_DEBUGTRACE + * \li #ISC_MEM_DEBUGTRACE * Log each allocation and free to isc_lctx. * - * ISC_MEM_DEBUGRECORD + * \li #ISC_MEM_DEBUGRECORD * Remember each allocation, and match them up on free. * Crash if a free doesn't match an allocation. * - * ISC_MEM_DEBUGUSAGE + * \li #ISC_MEM_DEBUGUSAGE * If a hi_water mark is set, print the maximium inuse memory * every time it is raised once it exceeds the hi_water mark. */ +/*@}*/ #if ISC_MEM_TRACKLINES #define _ISC_MEM_FILELINE , __FILE__, __LINE__ @@ -116,12 +120,13 @@ LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging; #define isc_mem_strdup(c, p) isc__mem_strdup((c), (p) _ISC_MEM_FILELINE) #define isc_mempool_get(c) isc__mempool_get((c) _ISC_MEM_FILELINE) -/* +/*% * isc_mem_putanddetach() is a convienence function for use where you * have a structure with an attached memory context. * * Given: * + * \code * struct { * ... * isc_mem_t *mctx; @@ -131,14 +136,17 @@ LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging; * isc_mem_t *mctx; * * isc_mem_putanddetach(&ptr->mctx, ptr, sizeof(*ptr)); + * \endcode * * is the equivalent of: * + * \code * mctx = NULL; * isc_mem_attach(ptr->mctx, &mctx); * isc_mem_detach(&ptr->mctx); * isc_mem_put(mctx, ptr, sizeof(*ptr)); * isc_mem_detach(&mctx); + * \endcode */ #if ISC_MEM_DEBUG @@ -170,6 +178,7 @@ LIBISC_EXTERNAL_DATA extern unsigned int isc_mem_debugging; #define isc_mempool_put(c, p) isc__mempool_put((c), (p) _ISC_MEM_FILELINE) #endif +/*@{*/ isc_result_t isc_mem_create(size_t max_size, size_t target_size, isc_mem_t **mctxp); @@ -178,8 +187,8 @@ isc_result_t isc_mem_createx(size_t max_size, size_t target_size, isc_memalloc_t memalloc, isc_memfree_t memfree, void *arg, isc_mem_t **mctxp); -/* - * Create a memory context. +/*!< + * \brief Create a memory context. * * 'max_size' and 'target_size' are tuning parameters. When * ISC_MEM_USE_INTERNAL_MALLOC is true, allocations smaller than @@ -202,13 +211,15 @@ isc_mem_createx(size_t max_size, size_t target_size, * * Requires: * mctxp != NULL && *mctxp == NULL */ +/*@}*/ +/*@{*/ void isc_mem_attach(isc_mem_t *, isc_mem_t **); void isc_mem_detach(isc_mem_t **); -/* - * Attach to / detach from a memory context. +/*!< + * \brief Attach to / detach from a memory context. * * This is intended for applications that use multiple memory contexts * in such a way that it is not obvious when the last allocations from @@ -219,10 +230,11 @@ isc_mem_detach(isc_mem_t **); * and destroy it at the end of main(), thereby guaranteeing that it * is not destroyed while there are outstanding allocations. */ +/*@}*/ void isc_mem_destroy(isc_mem_t **); -/* +/*%< * Destroy a memory context. */ @@ -230,38 +242,40 @@ isc_result_t isc_mem_ondestroy(isc_mem_t *ctx, isc_task_t *task, isc_event_t **event); -/* +/*%< * Request to be notified with an event when a memory context has * been successfully destroyed. */ void isc_mem_stats(isc_mem_t *mctx, FILE *out); -/* +/*%< * Print memory usage statistics for 'mctx' on the stream 'out'. */ void isc_mem_setdestroycheck(isc_mem_t *mctx, isc_boolean_t on); -/* - * Iff 'on' is ISC_TRUE, 'mctx' will check for memory leaks when +/*%< + * If 'on' is ISC_TRUE, 'mctx' will check for memory leaks when * destroyed and abort the program if any are present. */ +/*@{*/ void isc_mem_setquota(isc_mem_t *, size_t); size_t isc_mem_getquota(isc_mem_t *); -/* +/*%< * Set/get the memory quota of 'mctx'. This is a hard limit * on the amount of memory that may be allocated from mctx; * if it is exceeded, allocations will fail. */ +/*@}*/ size_t isc_mem_inuse(isc_mem_t *mctx); -/* +/*%< * Get an estimate of the number of memory in use in 'mctx', in bytes. * This includes quantization overhead, but does not include memory * allocated from the system but not yet used. @@ -270,11 +284,13 @@ isc_mem_inuse(isc_mem_t *mctx); void isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg, size_t hiwater, size_t lowater); -/* - * Set high and low water marks for this memory context. When the memory - * usage of 'mctx' exceeds 'hiwater', '(water)(water_arg, ISC_MEM_HIWATER)' +/*%< + * Set high and low water marks for this memory context. + * + * When the memory + * usage of 'mctx' exceeds 'hiwater', '(water)(water_arg, #ISC_MEM_HIWATER)' * will be called. When the usage drops below 'lowater', 'water' will - * again be called, this time with ISC_MEM_LOWATER. + * again be called, this time with #ISC_MEM_LOWATER. * * If 'water' is NULL then 'water_arg', 'hi_water' and 'lo_water' are * ignored and the state is reset. @@ -291,47 +307,47 @@ isc_mem_setwater(isc_mem_t *mctx, isc_mem_water_t water, void *water_arg, isc_result_t isc_mempool_create(isc_mem_t *mctx, size_t size, isc_mempool_t **mpctxp); -/* +/*%< * Create a memory pool. * * Requires: - * mctx is a valid memory context. - * size > 0 - * mpctxp != NULL and *mpctxp == NULL + *\li mctx is a valid memory context. + *\li size > 0 + *\li mpctxp != NULL and *mpctxp == NULL * * Defaults: - * maxalloc = UINT_MAX - * freemax = 1 - * fillcount = 1 + *\li maxalloc = UINT_MAX + *\li freemax = 1 + *\li fillcount = 1 * * Returns: - * ISC_R_NOMEMORY -- not enough memory to create pool - * ISC_R_SUCCESS -- all is well. + *\li #ISC_R_NOMEMORY -- not enough memory to create pool + *\li #ISC_R_SUCCESS -- all is well. */ void isc_mempool_destroy(isc_mempool_t **mpctxp); -/* +/*%< * Destroy a memory pool. * * Requires: - * mpctxp != NULL && *mpctxp is a valid pool. - * The pool has no un"put" allocations outstanding + *\li mpctxp != NULL && *mpctxp is a valid pool. + *\li The pool has no un"put" allocations outstanding */ void isc_mempool_setname(isc_mempool_t *mpctx, const char *name); -/* +/*%< * Associate a name with a memory pool. At most 15 characters may be used. * * Requires: - * mpctx is a valid pool. - * name != NULL; + *\li mpctx is a valid pool. + *\li name != NULL; */ void isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock); -/* +/*%< * Associate a lock with this memory pool. * * This lock is used when getting or putting items using this memory pool, @@ -346,13 +362,13 @@ isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock); * * Requires: * - * mpctpx is a valid pool. + *\li mpctpx is a valid pool. * - * lock != NULL. + *\li lock != NULL. * - * No previous lock is assigned to this pool. + *\li No previous lock is assigned to this pool. * - * The lock is initialized before calling this function via the normal + *\li The lock is initialized before calling this function via the normal * means of doing that. */ @@ -372,57 +388,57 @@ isc_mempool_associatelock(isc_mempool_t *mpctx, isc_mutex_t *lock); unsigned int isc_mempool_getfreemax(isc_mempool_t *mpctx); -/* +/*%< * Returns the maximum allowed size of the free list. */ void isc_mempool_setfreemax(isc_mempool_t *mpctx, unsigned int limit); -/* +/*%< * Sets the maximum allowed size of the free list. */ unsigned int isc_mempool_getfreecount(isc_mempool_t *mpctx); -/* +/*%< * Returns current size of the free list. */ unsigned int isc_mempool_getmaxalloc(isc_mempool_t *mpctx); -/* +/*!< * Returns the maximum allowed number of allocations. */ void isc_mempool_setmaxalloc(isc_mempool_t *mpctx, unsigned int limit); -/* +/*%< * Sets the maximum allowed number of allocations. * * Additional requirements: - * limit > 0 + *\li limit > 0 */ unsigned int isc_mempool_getallocated(isc_mempool_t *mpctx); -/* +/*%< * Returns the number of items allocated from this pool. */ unsigned int isc_mempool_getfillcount(isc_mempool_t *mpctx); -/* +/*%< * Returns the number of items allocated as a block from the parent memory * context when the free list is empty. */ void isc_mempool_setfillcount(isc_mempool_t *mpctx, unsigned int limit); -/* +/*%< * Sets the fillcount. * * Additional requirements: - * limit > 0 + *\li limit > 0 */ diff --git a/lib/isc/include/isc/msgcat.h b/lib/isc/include/isc/msgcat.h index a6837aaf03..870955adc4 100644 --- a/lib/isc/include/isc/msgcat.h +++ b/lib/isc/include/isc/msgcat.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: msgcat.h,v 1.9 2004/03/05 05:10:59 marka Exp $ */ +/* $Id: msgcat.h,v 1.10 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_MSGCAT_H #define ISC_MSGCAT_H 1 @@ -24,34 +24,33 @@ ***** Module Info *****/ -/* - * ISC Message Catalog - * - * Message catalogs aid internationalization of applications by allowing +/*! \file isc/msgcat.h + * \brief The ISC Message Catalog + * aids internationalization of applications by allowing * messages to be retrieved from locale-specific files instead of * hardwiring them into the application. This allows translations of * messages appropriate to the locale to be supplied without recompiling * the application. * * Notes: - * It's very important that message catalogs work, even if only the + *\li It's very important that message catalogs work, even if only the * default_text can be used. * * MP: - * The caller must ensure appropriate synchronization of + *\li The caller must ensure appropriate synchronization of * isc_msgcat_open() and isc_msgcat_close(). isc_msgcat_get() * ensures appropriate synchronization. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * + *\li TBS * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ @@ -70,61 +69,61 @@ ISC_LANG_BEGINDECLS void isc_msgcat_open(const char *name, isc_msgcat_t **msgcatp); -/* +/*%< * Open a message catalog. * * Notes: * - * If memory cannot be allocated or other failures occur, *msgcatp + *\li If memory cannot be allocated or other failures occur, *msgcatp * will be set to NULL. If a NULL msgcat is given to isc_msgcat_get(), * the default_text will be returned, ensuring that some message text * will be available, no matter what's going wrong. * * Requires: * - * 'name' is a valid string. + *\li 'name' is a valid string. * - * msgcatp != NULL && *msgcatp == NULL + *\li msgcatp != NULL && *msgcatp == NULL */ void isc_msgcat_close(isc_msgcat_t **msgcatp); -/* +/*%< * Close a message catalog. * * Notes: * - * Any string pointers returned by prior calls to isc_msgcat_get() are + *\li Any string pointers returned by prior calls to isc_msgcat_get() are * invalid after isc_msgcat_close() has been called and must not be * used. * * Requires: * - * *msgcatp is a valid message catalog or is NULL. + *\li *msgcatp is a valid message catalog or is NULL. * * Ensures: * - * All resources associated with the message catalog are released. + *\li All resources associated with the message catalog are released. * - * *msgcatp == NULL + *\li *msgcatp == NULL */ const char * isc_msgcat_get(isc_msgcat_t *msgcat, int set, int message, const char *default_text); -/* +/*%< * Get message 'message' from message set 'set' in 'msgcat'. If it * is not available, use 'default_text'. * * Requires: * - * 'msgcat' is a valid message catalog or is NULL. + *\li 'msgcat' is a valid message catalog or is NULL. * - * set > 0 + *\li set > 0 * - * message > 0 + *\li message > 0 * - * 'default_text' is a valid string. + *\li 'default_text' is a valid string. */ ISC_LANG_ENDDECLS diff --git a/lib/isc/include/isc/msgs.h b/lib/isc/include/isc/msgs.h index 222efa3f95..22e8bb1ef3 100644 --- a/lib/isc/include/isc/msgs.h +++ b/lib/isc/include/isc/msgs.h @@ -15,16 +15,20 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: msgs.h,v 1.9 2004/03/05 05:10:59 marka Exp $ */ +/* $Id: msgs.h,v 1.10 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_MSGS_H #define ISC_MSGS_H 1 +/*! \file */ + #include /* Provide isc_msgcat global variable. */ #include /* Provide isc_msgcat_*() functions. */ -/* - * Message sets, named per source file, excepting "GENERAL". +/*@{*/ +/*! + * \brief Message sets, named per source file, excepting "GENERAL". + * * IMPORTANT: The original list is alphabetical, but any new sets must * be added to the end. */ @@ -49,135 +53,139 @@ #define ISC_MSGSET_TIMER 19 #define ISC_MSGSET_UTIL 20 #define ISC_MSGSET_IFITERGETIFADDRS 21 +/*@}*/ -/* - * Message numbers. They are only required to be unique per message set, +/*@{*/ +/*! + * Message numbers + * are only required to be unique per message set, * but are unique throughout the entire catalog to not be as confusing when * debugging. * * The initial numbering was done by multiply by 100 the set number the * message appears in then adding the incremental message number. */ -#define ISC_MSG_FAILED 101 /* "failed" */ -#define ISC_MSG_SUCCEEDED 102 /* Compatible with "failed" */ -#define ISC_MSG_SUCCESS 103 /* More usual way to say "success" */ -#define ISC_MSG_STARTING 104 /* As in "daemon: starting" */ -#define ISC_MSG_STOPING 105 /* As in "daemon: stopping" */ -#define ISC_MSG_ENTERING 106 /* As in "some_subr: entering" */ -#define ISC_MSG_EXITING 107 /* As in "some_subr: exiting" */ -#define ISC_MSG_CALLING 108 /* As in "calling some_subr()" */ -#define ISC_MSG_RETURNED 109 /* As in "some_subr: returned " */ -#define ISC_MSG_FATALERROR 110 /* "fatal error" */ -#define ISC_MSG_SHUTTINGDOWN 111 /* "shutting down" */ -#define ISC_MSG_RUNNING 112 /* "running" */ -#define ISC_MSG_WAIT 113 /* "wait" */ -#define ISC_MSG_WAITUNTIL 114 /* "waituntil" */ +#define ISC_MSG_FAILED 101 /*%< "failed" */ +#define ISC_MSG_SUCCEEDED 102 /*%< Compatible with "failed" */ +#define ISC_MSG_SUCCESS 103 /*%< More usual way to say "success" */ +#define ISC_MSG_STARTING 104 /*%< As in "daemon: starting" */ +#define ISC_MSG_STOPING 105 /*%< As in "daemon: stopping" */ +#define ISC_MSG_ENTERING 106 /*%< As in "some_subr: entering" */ +#define ISC_MSG_EXITING 107 /*%< As in "some_subr: exiting" */ +#define ISC_MSG_CALLING 108 /*%< As in "calling some_subr()" */ +#define ISC_MSG_RETURNED 109 /*%< As in "some_subr: returned " */ +#define ISC_MSG_FATALERROR 110 /*%< "fatal error" */ +#define ISC_MSG_SHUTTINGDOWN 111 /*%< "shutting down" */ +#define ISC_MSG_RUNNING 112 /*%< "running" */ +#define ISC_MSG_WAIT 113 /*%< "wait" */ +#define ISC_MSG_WAITUNTIL 114 /*%< "waituntil" */ -#define ISC_MSG_SIGNALSETUP 201 /* "handle_signal() %d setup: %s" */ +#define ISC_MSG_SIGNALSETUP 201 /*%< "handle_signal() %d setup: %s" */ -#define ISC_MSG_ILLEGALOPT 301 /* "illegal option" */ -#define ISC_MSG_OPTNEEDARG 302 /* "option requires an argument" */ +#define ISC_MSG_ILLEGALOPT 301 /*%< "illegal option" */ +#define ISC_MSG_OPTNEEDARG 302 /*%< "option requires an argument" */ -#define ISC_MSG_ENTROPYSTATS 401 /* "Entropy pool %p: refcnt %u ..." */ +#define ISC_MSG_ENTROPYSTATS 401 /*%< "Entropy pool %p: refcnt %u ..." */ -#define ISC_MSG_MAKESCANSOCKET 501 /* "making interface scan socket: %s" */ -#define ISC_MSG_GETIFCONFIG 502 /* "get interface configuration: %s" */ -#define ISC_MSG_BUFFERMAX 503 /* "... maximum buffer size exceeded" */ -#define ISC_MSG_GETDESTADDR 504 /* "%s: getting destination address: %s" */ -#define ISC_MSG_GETNETMASK 505 /* "%s: getting netmask: %s" */ +#define ISC_MSG_MAKESCANSOCKET 501 /*%< "making interface scan socket: %s" */ +#define ISC_MSG_GETIFCONFIG 502 /*%< "get interface configuration: %s" */ +#define ISC_MSG_BUFFERMAX 503 /*%< "... maximum buffer size exceeded" */ +#define ISC_MSG_GETDESTADDR 504 /*%< "%s: getting destination address: %s" */ +#define ISC_MSG_GETNETMASK 505 /*%< "%s: getting netmask: %s" */ -#define ISC_MSG_GETIFLISTSIZE 601 /* "getting interface list size: ..." */ -#define ISC_MSG_GETIFLIST 602 /* "getting interface list: ..." */ -#define ISC_MSG_UNEXPECTEDTYPE 603 /* "... unexpected ... message type" */ +#define ISC_MSG_GETIFLISTSIZE 601 /*%< "getting interface list size: ..." */ +#define ISC_MSG_GETIFLIST 602 /*%< "getting interface list: ..." */ +#define ISC_MSG_UNEXPECTEDTYPE 603 /*%< "... unexpected ... message type" */ -#define ISC_MSG_UNEXPECTEDSTATE 701 /* "Unexpected state %d" */ +#define ISC_MSG_UNEXPECTEDSTATE 701 /*%< "Unexpected state %d" */ -#define ISC_MSG_BADTIME 801 /* "Bad 00 99:99:99.999 " */ -#define ISC_MSG_LEVEL 802 /* "level %d: " */ +#define ISC_MSG_BADTIME 801 /*%< "Bad 00 99:99:99.999 " */ +#define ISC_MSG_LEVEL 802 /*%< "level %d: " */ -#define ISC_MSG_ADDTRACE 901 /* "add %p size %u " */ -#define ISC_MSG_DELTRACE 902 /* "del %p size %u " */ -#define ISC_MSG_POOLSTATS 903 /* "[Pool statistics]\n" */ -#define ISC_MSG_POOLNAME 904 /* "name" */ -#define ISC_MSG_POOLSIZE 905 /* "size" */ -#define ISC_MSG_POOLMAXALLOC 906 /* "maxalloc" */ -#define ISC_MSG_POOLALLOCATED 907 /* "allocated" */ -#define ISC_MSG_POOLFREECOUNT 908 /* "freecount" */ -#define ISC_MSG_POOLFREEMAX 909 /* "freemax" */ -#define ISC_MSG_POOLFILLCOUNT 910 /* "fillcount" */ -#define ISC_MSG_POOLGETS 911 /* "gets" */ -#define ISC_MSG_DUMPALLOC 912 /* "DUMP OF ALL OUTSTANDING MEMORY ..." */ -#define ISC_MSG_NONE 913 /* "\tNone.\n" */ -#define ISC_MSG_PTRFILELINE 914 /* "\tptr %p file %s line %u\n" */ +#define ISC_MSG_ADDTRACE 901 /*%< "add %p size %u " */ +#define ISC_MSG_DELTRACE 902 /*%< "del %p size %u " */ +#define ISC_MSG_POOLSTATS 903 /*%< "[Pool statistics]\n" */ +#define ISC_MSG_POOLNAME 904 /*%< "name" */ +#define ISC_MSG_POOLSIZE 905 /*%< "size" */ +#define ISC_MSG_POOLMAXALLOC 906 /*%< "maxalloc" */ +#define ISC_MSG_POOLALLOCATED 907 /*%< "allocated" */ +#define ISC_MSG_POOLFREECOUNT 908 /*%< "freecount" */ +#define ISC_MSG_POOLFREEMAX 909 /*%< "freemax" */ +#define ISC_MSG_POOLFILLCOUNT 910 /*%< "fillcount" */ +#define ISC_MSG_POOLGETS 911 /*%< "gets" */ +#define ISC_MSG_DUMPALLOC 912 /*%< "DUMP OF ALL OUTSTANDING MEMORY ..." */ +#define ISC_MSG_NONE 913 /*%< "\tNone.\n" */ +#define ISC_MSG_PTRFILELINE 914 /*%< "\tptr %p file %s line %u\n" */ -#define ISC_MSG_UNKNOWNADDR 1001 /* "" */ +#define ISC_MSG_UNKNOWNADDR 1001 /*%< "" */ -#define ISC_MSG_NOLONGDBL 1104 /* "long doubles are not supported" */ +#define ISC_MSG_NOLONGDBL 1104 /*%< "long doubles are not supported" */ -#define ISC_MSG_PRINTLOCK 1201 /* "rwlock %p thread %lu ..." */ -#define ISC_MSG_READ 1202 /* "read" */ -#define ISC_MSG_WRITE 1203 /* "write" */ -#define ISC_MSG_READING 1204 /* "reading" */ -#define ISC_MSG_WRITING 1205 /* "writing" */ -#define ISC_MSG_PRELOCK 1206 /* "prelock" */ -#define ISC_MSG_POSTLOCK 1207 /* "postlock" */ -#define ISC_MSG_PREUNLOCK 1208 /* "preunlock" */ -#define ISC_MSG_POSTUNLOCK 1209 /* "postunlock" */ +#define ISC_MSG_PRINTLOCK 1201 /*%< "rwlock %p thread %lu ..." */ +#define ISC_MSG_READ 1202 /*%< "read" */ +#define ISC_MSG_WRITE 1203 /*%< "write" */ +#define ISC_MSG_READING 1204 /*%< "reading" */ +#define ISC_MSG_WRITING 1205 /*%< "writing" */ +#define ISC_MSG_PRELOCK 1206 /*%< "prelock" */ +#define ISC_MSG_POSTLOCK 1207 /*%< "postlock" */ +#define ISC_MSG_PREUNLOCK 1208 /*%< "preunlock" */ +#define ISC_MSG_POSTUNLOCK 1209 /*%< "postunlock" */ -#define ISC_MSG_UNKNOWNFAMILY 1301 /* "unknown address family: %d" */ +#define ISC_MSG_UNKNOWNFAMILY 1301 /*%< "unknown address family: %d" */ -#define ISC_MSG_WRITEFAILED 1401 /* "write() failed during watcher ..." */ -#define ISC_MSG_READFAILED 1402 /* "read() failed during watcher ... " */ -#define ISC_MSG_PROCESSCMSG 1403 /* "processing cmsg %p" */ -#define ISC_MSG_IFRECEIVED 1404 /* "interface received on ifindex %u" */ -#define ISC_MSG_SENDTODATA 1405 /* "sendto pktinfo data, ifindex %u" */ -#define ISC_MSG_DOIORECV 1406 /* "doio_recv: recvmsg(%d) %d bytes ..." */ -#define ISC_MSG_PKTRECV 1407 /* "packet received correctly" */ -#define ISC_MSG_DESTROYING 1408 /* "destroying" */ -#define ISC_MSG_CREATED 1409 /* "created" */ -#define ISC_MSG_ACCEPTLOCK 1410 /* "internal_accept called, locked ..." */ -#define ISC_MSG_ACCEPTEDCXN 1411 /* "accepted connection, new socket %p" */ -#define ISC_MSG_INTERNALRECV 1412 /* "internal_recv: task %p got event %p" */ -#define ISC_MSG_INTERNALSEND 1413 /* "internal_send: task %p got event %p" */ -#define ISC_MSG_WATCHERMSG 1414 /* "watcher got message %d" */ -#define ISC_MSG_SOCKETSREMAIN 1415 /* "sockets exist" */ -#define ISC_MSG_PKTINFOPROVIDED 1416 /* "pktinfo structure provided, ..." */ -#define ISC_MSG_BOUND 1417 /* "bound" */ -#define ISC_MSG_ACCEPTRETURNED 1418 /* accept() returned %d/%s */ -#define ISC_MSG_TOOMANYFDS 1419 /* %s: too many open file descriptors */ -#define ISC_MSG_ZEROPORT 1420 /* dropping source port zero packet */ -#define ISC_MSG_FILTER 1420 /* setsockopt(SO_ACCEPTFILTER): %s */ +#define ISC_MSG_WRITEFAILED 1401 /*%< "write() failed during watcher ..." */ +#define ISC_MSG_READFAILED 1402 /*%< "read() failed during watcher ... " */ +#define ISC_MSG_PROCESSCMSG 1403 /*%< "processing cmsg %p" */ +#define ISC_MSG_IFRECEIVED 1404 /*%< "interface received on ifindex %u" */ +#define ISC_MSG_SENDTODATA 1405 /*%< "sendto pktinfo data, ifindex %u" */ +#define ISC_MSG_DOIORECV 1406 /*%< "doio_recv: recvmsg(%d) %d bytes ..." */ +#define ISC_MSG_PKTRECV 1407 /*%< "packet received correctly" */ +#define ISC_MSG_DESTROYING 1408 /*%< "destroying" */ +#define ISC_MSG_CREATED 1409 /*%< "created" */ +#define ISC_MSG_ACCEPTLOCK 1410 /*%< "internal_accept called, locked ..." */ +#define ISC_MSG_ACCEPTEDCXN 1411 /*%< "accepted connection, new socket %p" */ +#define ISC_MSG_INTERNALRECV 1412 /*%< "internal_recv: task %p got event %p" */ +#define ISC_MSG_INTERNALSEND 1413 /*%< "internal_send: task %p got event %p" */ +#define ISC_MSG_WATCHERMSG 1414 /*%< "watcher got message %d" */ +#define ISC_MSG_SOCKETSREMAIN 1415 /*%< "sockets exist" */ +#define ISC_MSG_PKTINFOPROVIDED 1416 /*%< "pktinfo structure provided, ..." */ +#define ISC_MSG_BOUND 1417 /*%< "bound" */ +#define ISC_MSG_ACCEPTRETURNED 1418 /*%< accept() returned %d/%s */ +#define ISC_MSG_TOOMANYFDS 1419 /*%< %s: too many open file descriptors */ +#define ISC_MSG_ZEROPORT 1420 /*%< dropping source port zero packet */ +#define ISC_MSG_FILTER 1420 /*%< setsockopt(SO_ACCEPTFILTER): %s */ -#define ISC_MSG_AWAKE 1502 /* "awake" */ -#define ISC_MSG_WORKING 1503 /* "working" */ -#define ISC_MSG_EXECUTE 1504 /* "execute action" */ -#define ISC_MSG_EMPTY 1505 /* "empty" */ -#define ISC_MSG_DONE 1506 /* "done" */ -#define ISC_MSG_QUANTUM 1507 /* "quantum" */ +#define ISC_MSG_AWAKE 1502 /*%< "awake" */ +#define ISC_MSG_WORKING 1503 /*%< "working" */ +#define ISC_MSG_EXECUTE 1504 /*%< "execute action" */ +#define ISC_MSG_EMPTY 1505 /*%< "empty" */ +#define ISC_MSG_DONE 1506 /*%< "done" */ +#define ISC_MSG_QUANTUM 1507 /*%< "quantum" */ -#define ISC_MSG_SCHEDULE 1601 /* "schedule" */ -#define ISC_MSG_SIGNALSCHED 1602 /* "signal (schedule)" */ -#define ISC_MSG_SIGNALDESCHED 1603 /* "signal (deschedule)" */ -#define ISC_MSG_SIGNALDESTROY 1604 /* "signal (destroy)" */ -#define ISC_MSG_IDLERESCHED 1605 /* "idle reschedule" */ -#define ISC_MSG_EVENTNOTALLOC 1606 /* "couldn't allocate event" */ -#define ISC_MSG_SCHEDFAIL 1607 /* "couldn't schedule timer: %u" */ -#define ISC_MSG_POSTING 1608 /* "posting" */ -#define ISC_MSG_WAKEUP 1609 /* "wakeup" */ +#define ISC_MSG_SCHEDULE 1601 /*%< "schedule" */ +#define ISC_MSG_SIGNALSCHED 1602 /*%< "signal (schedule)" */ +#define ISC_MSG_SIGNALDESCHED 1603 /*%< "signal (deschedule)" */ +#define ISC_MSG_SIGNALDESTROY 1604 /*%< "signal (destroy)" */ +#define ISC_MSG_IDLERESCHED 1605 /*%< "idle reschedule" */ +#define ISC_MSG_EVENTNOTALLOC 1606 /*%< "couldn't allocate event" */ +#define ISC_MSG_SCHEDFAIL 1607 /*%< "couldn't schedule timer: %u" */ +#define ISC_MSG_POSTING 1608 /*%< "posting" */ +#define ISC_MSG_WAKEUP 1609 /*%< "wakeup" */ -#define ISC_MSG_LOCK 1701 /* "LOCK" */ -#define ISC_MSG_LOCKING 1702 /* "LOCKING" */ -#define ISC_MSG_LOCKED 1703 /* "LOCKED" */ -#define ISC_MSG_UNLOCKED 1704 /* "UNLOCKED" */ -#define ISC_MSG_RWLOCK 1705 /* "RWLOCK" */ -#define ISC_MSG_RWLOCKED 1706 /* "RWLOCKED" */ -#define ISC_MSG_RWUNLOCK 1707 /* "RWUNLOCK" */ -#define ISC_MSG_BROADCAST 1708 /* "BROADCAST" */ -#define ISC_MSG_SIGNAL 1709 /* "SIGNAL" */ -#define ISC_MSG_UTILWAIT 1710 /* "WAIT" */ -#define ISC_MSG_WAITED 1711 /* "WAITED" */ +#define ISC_MSG_LOCK 1701 /*%< "LOCK" */ +#define ISC_MSG_LOCKING 1702 /*%< "LOCKING" */ +#define ISC_MSG_LOCKED 1703 /*%< "LOCKED" */ +#define ISC_MSG_UNLOCKED 1704 /*%< "UNLOCKED" */ +#define ISC_MSG_RWLOCK 1705 /*%< "RWLOCK" */ +#define ISC_MSG_RWLOCKED 1706 /*%< "RWLOCKED" */ +#define ISC_MSG_RWUNLOCK 1707 /*%< "RWUNLOCK" */ +#define ISC_MSG_BROADCAST 1708 /*%< "BROADCAST" */ +#define ISC_MSG_SIGNAL 1709 /*%< "SIGNAL" */ +#define ISC_MSG_UTILWAIT 1710 /*%< "WAIT" */ +#define ISC_MSG_WAITED 1711 /*%< "WAITED" */ -#define ISC_MSG_GETIFADDRS 1801 /* "getting interface addresses: ..." */ +#define ISC_MSG_GETIFADDRS 1801 /*%< "getting interface addresses: ..." */ +/*@}*/ #endif /* ISC_MSGS_H */ diff --git a/lib/isc/include/isc/mutexblock.h b/lib/isc/include/isc/mutexblock.h index aef41991ad..64b065a508 100644 --- a/lib/isc/include/isc/mutexblock.h +++ b/lib/isc/include/isc/mutexblock.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: mutexblock.h,v 1.11 2004/03/05 05:10:59 marka Exp $ */ +/* $Id: mutexblock.h,v 1.12 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_MUTEXBLOCK_H #define ISC_MUTEXBLOCK_H 1 +/*! \file */ + #include #include #include @@ -28,39 +30,39 @@ ISC_LANG_BEGINDECLS isc_result_t isc_mutexblock_init(isc_mutex_t *block, unsigned int count); -/* +/*%< * Initialize a block of locks. If an error occurs all initialized locks * will be destroyed, if possible. * * Requires: * - * block != NULL + *\li block != NULL * - * count > 0 + *\li count > 0 * * Returns: * - * Any code isc_mutex_init() can return is a valid return for this + *\li Any code isc_mutex_init() can return is a valid return for this * function. */ isc_result_t isc_mutexblock_destroy(isc_mutex_t *block, unsigned int count); -/* +/*%< * Destroy a block of locks. * * Requires: * - * block != NULL + *\li block != NULL * - * count > 0 + *\li count > 0 * - * Each lock in the block be initialized via isc_mutex_init() or + *\li Each lock in the block be initialized via isc_mutex_init() or * the whole block was initialized via isc_mutex_initblock(). * * Returns: * - * Any code isc_mutex_init() can return is a valid return for this + *\li Any code isc_mutex_init() can return is a valid return for this * function. */ diff --git a/lib/isc/include/isc/netaddr.h b/lib/isc/include/isc/netaddr.h index 07c81a5d87..0a102ad844 100644 --- a/lib/isc/include/isc/netaddr.h +++ b/lib/isc/include/isc/netaddr.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: netaddr.h,v 1.28 2005/02/23 01:06:38 marka Exp $ */ +/* $Id: netaddr.h,v 1.29 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_NETADDR_H #define ISC_NETADDR_H 1 +/*! \file */ + #include #include #include @@ -49,40 +51,40 @@ isc_netaddr_equal(const isc_netaddr_t *a, const isc_netaddr_t *b); isc_boolean_t isc_netaddr_eqprefix(const isc_netaddr_t *a, const isc_netaddr_t *b, unsigned int prefixlen); -/* +/*%< * Compare the 'prefixlen' most significant bits of the network - * addresses 'a' and 'b'. Return ISC_TRUE if they are equal, - * ISC_FALSE if not. + * addresses 'a' and 'b'. Return #ISC_TRUE if they are equal, + * #ISC_FALSE if not. */ isc_result_t isc_netaddr_masktoprefixlen(const isc_netaddr_t *s, unsigned int *lenp); -/* +/*%< * Convert a netmask in 's' into a prefix length in '*lenp'. * The mask should consist of zero or more '1' bits in the most * most significant part of the address, followed by '0' bits. - * If this is not the case, ISC_R_MASKNONCONTIG is returned. + * If this is not the case, #ISC_R_MASKNONCONTIG is returned. * * Returns: - * ISC_R_SUCCESS - * ISC_R_MASKNONCONTIG + *\li #ISC_R_SUCCESS + *\li #ISC_R_MASKNONCONTIG */ isc_result_t isc_netaddr_totext(const isc_netaddr_t *netaddr, isc_buffer_t *target); -/* +/*%< * Append a text representation of 'sockaddr' to the buffer 'target'. * The text is NOT null terminated. Handles IPv4 and IPv6 addresses. * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOSPACE The text or the null termination did not fit. - * ISC_R_FAILURE Unspecified failure + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOSPACE The text or the null termination did not fit. + *\li #ISC_R_FAILURE Unspecified failure */ void isc_netaddr_format(const isc_netaddr_t *na, char *array, unsigned int size); -/* +/*%< * Format a human-readable representation of the network address '*na' * into the character array 'array', which is of size 'size'. * The resulting string is guaranteed to be null-terminated. @@ -90,7 +92,7 @@ isc_netaddr_format(const isc_netaddr_t *na, char *array, unsigned int size); #define ISC_NETADDR_FORMATSIZE \ sizeof("xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:XXX.XXX.XXX.XXX") -/* +/*%< * Minimum size of array to pass to isc_netaddr_format(). */ @@ -114,43 +116,43 @@ isc_netaddr_getzone(const isc_netaddr_t *netaddr); void isc_netaddr_any(isc_netaddr_t *netaddr); -/* +/*%< * Return the IPv4 wildcard address. */ void isc_netaddr_any6(isc_netaddr_t *netaddr); -/* +/*%< * Return the IPv6 wildcard address. */ isc_boolean_t isc_netaddr_ismulticast(isc_netaddr_t *na); -/* +/*%< * Returns ISC_TRUE if the address is a multicast address. */ isc_boolean_t isc_netaddr_isexperimental(isc_netaddr_t *na); -/* +/*%< * Returns ISC_TRUE if the address is a experimental (CLASS E) address. */ isc_boolean_t isc_netaddr_islinklocal(isc_netaddr_t *na); -/* - * Returns ISC_TRUE if the address is a link local address. +/*%< + * Returns #ISC_TRUE if the address is a link local address. */ isc_boolean_t isc_netaddr_issitelocal(isc_netaddr_t *na); -/* - * Returns ISC_TRUE if the address is a site local address. +/*%< + * Returns #ISC_TRUE if the address is a site local address. */ void isc_netaddr_fromv4mapped(isc_netaddr_t *t, const isc_netaddr_t *s); -/* +/*%< * Convert an IPv6 v4mapped address into an IPv4 address. */ diff --git a/lib/isc/include/isc/netscope.h b/lib/isc/include/isc/netscope.h index 6b593f7946..410d9d630f 100644 --- a/lib/isc/include/isc/netscope.h +++ b/lib/isc/include/isc/netscope.h @@ -15,22 +15,25 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: netscope.h,v 1.5 2004/03/05 05:10:59 marka Exp $ */ +/* $Id: netscope.h,v 1.6 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_NETSCOPE_H #define ISC_NETSCOPE_H 1 +/*! \file */ + ISC_LANG_BEGINDECLS -/* +/*% * Convert a string of an IPv6 scope zone to zone index. If the conversion * succeeds, 'zoneid' will store the index value. + * * XXXJT: when a standard interface for this purpose is defined, * we should use it. * * Returns: - * ISC_R_SUCCESS: conversion succeeds - * ISC_R_FAILURE: conversion fails + * \li ISC_R_SUCCESS: conversion succeeds + * \li ISC_R_FAILURE: conversion fails */ isc_result_t isc_netscope_pton(int af, char *scopename, void *addr, isc_uint32_t *zoneid); diff --git a/lib/isc/include/isc/ondestroy.h b/lib/isc/include/isc/ondestroy.h index 9991f8daa1..077f55e389 100644 --- a/lib/isc/include/isc/ondestroy.h +++ b/lib/isc/include/isc/ondestroy.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ondestroy.h,v 1.8 2004/03/05 05:10:59 marka Exp $ */ +/* $Id: ondestroy.h,v 1.9 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_ONDESTROY_H #define ISC_ONDESTROY_H 1 @@ -25,33 +25,39 @@ ISC_LANG_BEGINDECLS -/* +/*! \file * ondestroy handling. * * Any class ``X'' of objects that wants to send out notifications * on its destruction should declare a field of type isc_ondestroy_t * (call it 'ondest'). * + * \code * typedef struct { * ... * isc_ondestroy_t ondest; * ... * } X; + * \endcode * * When an object ``A'' of type X is created * it must initialize the field ondest with a call to * + * \code * isc_ondestroy_init(&A->ondest). + * \endcode * * X should also provide a registration function for third-party * objects to call to register their interest in being told about * the destruction of a particular instance of X. * + * \code * isc_result_t * X_ondestroy(X *instance, isc_task_t *task, * isc_event_t **eventp) { * return(isc_ondestroy_register(&instance->ondest, task,eventp)); * } + * \endcode * * Note: locking of the ondestory structure embedded inside of X, is * X's responsibility. @@ -59,15 +65,17 @@ ISC_LANG_BEGINDECLS * When an instance of X is destroyed, a call to isc_ondestroy_notify() * sends the notifications: * + * \code * X *instance; * isc_ondestroy_t ondest = instance->ondest; * * ... completely cleanup 'instance' here... * * isc_ondestroy_notify(&ondest, instance); + * \endcode * * - * see dns/zone.c for an ifdef'd-out example. + * see lib/dns/zone.c for an ifdef'd-out example. */ struct isc_ondestroy { @@ -77,7 +85,7 @@ struct isc_ondestroy { void isc_ondestroy_init(isc_ondestroy_t *ondest); -/* +/*%< * Initialize the on ondest structure. *must* be called before first call * to isc_ondestroy_register(). */ @@ -86,7 +94,7 @@ isc_result_t isc_ondestroy_register(isc_ondestroy_t *ondest, isc_task_t *task, isc_event_t **eventp); -/* +/*%< * Stores task and *eventp away inside *ondest. Ownership of **event is * taken from the caller (and *eventp is set to NULL). The task is attached * to. @@ -94,7 +102,7 @@ isc_ondestroy_register(isc_ondestroy_t *ondest, isc_task_t *task, void isc_ondestroy_notify(isc_ondestroy_t *ondest, void *sender); -/* +/*%< * Dispatches the event(s) to the task(s) that were given in * isc_ondestroy_register call(s) (done via calls to * isc_task_sendanddetach()). Before dispatch, the sender value of each diff --git a/lib/isc/include/isc/os.h b/lib/isc/include/isc/os.h index 83343bcb26..9b714cb9c6 100644 --- a/lib/isc/include/isc/os.h +++ b/lib/isc/include/isc/os.h @@ -15,18 +15,20 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: os.h,v 1.6 2004/03/05 05:10:59 marka Exp $ */ +/* $Id: os.h,v 1.7 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_OS_H #define ISC_OS_H 1 +/*! \file */ + #include ISC_LANG_BEGINDECLS unsigned int isc_os_ncpus(void); -/* +/*%< * Return the number of CPUs available on the system, or 1 if this cannot * be determined. */ diff --git a/lib/isc/include/isc/parseint.h b/lib/isc/include/isc/parseint.h index 6b0f9b217c..5ba6edd50d 100644 --- a/lib/isc/include/isc/parseint.h +++ b/lib/isc/include/isc/parseint.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: parseint.h,v 1.3 2004/03/05 05:10:59 marka Exp $ */ +/* $Id: parseint.h,v 1.4 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_PARSEINT_H #define ISC_PARSEINT_H 1 @@ -23,8 +23,8 @@ #include #include -/* - * Parse integers, in a saner way than atoi() or strtoul() do. +/*! \file + * \brief Parse integers, in a saner way than atoi() or strtoul() do. */ /*** @@ -41,21 +41,22 @@ isc_parse_uint16(isc_uint16_t *uip, const char *string, int base); isc_result_t isc_parse_uint8(isc_uint8_t *uip, const char *string, int base); -/* +/*%< * Parse the null-terminated string 'string' containing a base 'base' - * integer, storing the result in '*uip'. The base is interpreted + * integer, storing the result in '*uip'. + * The base is interpreted * as in strtoul(). Unlike strtoul(), leading whitespace, minus or * plus signs are not accepted, and all errors (including overflow) * are reported uniformly through the return value. * * Requires: - * 'string' points to a null-terminated string - * 0 <= 'base' <= 36 + *\li 'string' points to a null-terminated string + *\li 0 <= 'base' <= 36 * * Returns: - * ISC_R_SUCCESS - * ISC_R_BADNUMBER The string is not numeric (in the given base) - * ISC_R_RANGE The number is not representable as the requested type. + *\li #ISC_R_SUCCESS + *\li #ISC_R_BADNUMBER The string is not numeric (in the given base) + *\li #ISC_R_RANGE The number is not representable as the requested type. */ ISC_LANG_ENDDECLS diff --git a/lib/isc/include/isc/platform.h.in b/lib/isc/include/isc/platform.h.in index 200d897a78..48277a1d29 100644 --- a/lib/isc/include/isc/platform.h.in +++ b/lib/isc/include/isc/platform.h.in @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: platform.h.in,v 1.36 2005/02/24 00:33:34 marka Exp $ */ +/* $Id: platform.h.in,v 1.37 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_PLATFORM_H #define ISC_PLATFORM_H 1 +/*! \file */ + /***** ***** Platform-dependent defines. *****/ @@ -28,184 +30,184 @@ *** Network. ***/ -/* +/*! \brief * Define if this system needs the header file included * for full IPv6 support (pretty much only UnixWare). */ @ISC_PLATFORM_NEEDNETINETIN6H@ -/* +/*! \brief * Define if this system needs the header file included * to support in6_pkinfo (pretty much only BSD/OS). */ @ISC_PLATFORM_NEEDNETINET6IN6H@ -/* +/*! \brief * If sockaddrs on this system have an sa_len field, ISC_PLATFORM_HAVESALEN * will be defined. */ @ISC_PLATFORM_HAVESALEN@ -/* +/*! \brief * If this system has the IPv6 structure definitions, ISC_PLATFORM_HAVEIPV6 * will be defined. */ @ISC_PLATFORM_HAVEIPV6@ -/* +/*! \brief * If this system is missing in6addr_any, ISC_PLATFORM_NEEDIN6ADDRANY will * be defined. */ @ISC_PLATFORM_NEEDIN6ADDRANY@ -/* +/*! \brief * If this system is missing in6addr_loopback, ISC_PLATFORM_NEEDIN6ADDRLOOPBACK * will be defined. */ @ISC_PLATFORM_NEEDIN6ADDRLOOPBACK@ -/* +/*! \brief * If this system has in6_pktinfo, ISC_PLATFORM_HAVEIN6PKTINFO will be * defined. */ @ISC_PLATFORM_HAVEIN6PKTINFO@ -/* +/*! \brief * If this system has in_addr6, rather than in6_addr, ISC_PLATFORM_HAVEINADDR6 * will be defined. */ @ISC_PLATFORM_HAVEINADDR6@ -/* +/*! \brief * If this system has sin6_scope_id, ISC_PLATFORM_HAVESCOPEID will be defined. */ @ISC_PLATFORM_HAVESCOPEID@ -/* +/*! \brief * If this system needs inet_ntop(), ISC_PLATFORM_NEEDNTOP will be defined. */ @ISC_PLATFORM_NEEDNTOP@ -/* +/*! \brief * If this system needs inet_pton(), ISC_PLATFORM_NEEDPTON will be defined. */ @ISC_PLATFORM_NEEDPTON@ -/* +/*! \brief * If this system needs inet_aton(), ISC_PLATFORM_NEEDATON will be defined. */ @ISC_PLATFORM_NEEDATON@ -/* +/*! \brief * If this system needs in_port_t, ISC_PLATFORM_NEEDPORTT will be defined. */ @ISC_PLATFORM_NEEDPORTT@ -/* +/*! \brief * If the system needs strsep(), ISC_PLATFORM_NEEDSTRSEP will be defined. */ @ISC_PLATFORM_NEEDSTRSEP@ -/* +/*! \brief * If the system needs strlcpy(), ISC_PLATFORM_NEEDSTRLCPY will be defined. */ @ISC_PLATFORM_NEEDSTRLCPY@ -/* +/*! \brief * If the system needs strlcat(), ISC_PLATFORM_NEEDSTRLCAT will be defined. */ @ISC_PLATFORM_NEEDSTRLCAT@ -/* +/*! \brief * Define either ISC_PLATFORM_BSD44MSGHDR or ISC_PLATFORM_BSD43MSGHDR. */ @ISC_PLATFORM_MSGHDRFLAVOR@ -/* +/*! \brief * Define if PTHREAD_ONCE_INIT should be surrounded by braces to * prevent compiler warnings (such as with gcc on Solaris 2.8). */ @ISC_PLATFORM_BRACEPTHREADONCEINIT@ -/* +/*! \brief * Define on some UnixWare systems to fix erroneous definitions of various * IN6_IS_ADDR_* macros. */ @ISC_PLATFORM_FIXIN6ISADDR@ -/*** +/* *** Printing. ***/ -/* +/*! \brief * If this system needs vsnprintf() and snprintf(), ISC_PLATFORM_NEEDVSNPRINTF * will be defined. */ @ISC_PLATFORM_NEEDVSNPRINTF@ -/* +/*! \brief * If this system need a modern sprintf() that returns (int) not (char*). */ @ISC_PLATFORM_NEEDSPRINTF@ -/* +/*! \brief * The printf format string modifier to use with isc_uint64_t values. */ @ISC_PLATFORM_QUADFORMAT@ -/* +/*! \brief * Defined if we are using threads. */ @ISC_PLATFORM_USETHREADS@ -/* +/*! \brief * Defined if unistd.h does not cause fd_set to be delared. */ @ISC_PLATFORM_NEEDSYSSELECTH@ -/* +/*! \brief * Type used for resource limits. */ @ISC_PLATFORM_RLIMITTYPE@ -/* +/*! \brief * Define if your compiler supports "long long int". */ @ISC_PLATFORM_HAVELONGLONG@ -/* +/*! \brief * Define if the system has struct lifconf which is a extended struct ifconf * for IPv6. */ @ISC_PLATFORM_HAVELIFCONF@ -/* +/*! \brief * Define if the system has struct if_laddrconf which is a extended struct * ifconf for IPv6. */ @ISC_PLATFORM_HAVEIF_LADDRCONF@ -/* +/*! \brief * Define if the system has struct if_laddrreq. */ @ISC_PLATFORM_HAVEIF_LADDRREQ@ -/* +/*! \brief * Used to control how extern data is linked; needed for Win32 platforms. */ @ISC_PLATFORM_USEDECLSPEC@ -/* +/*! \brief * Define if the system supports if_nametoindex. */ @ISC_PLATFORM_HAVEIFNAMETOINDEX@ -/* +/*! \brief * Define if this system needs strtoul. */ @ISC_PLATFORM_NEEDSTRTOUL@ -/* +/*! \brief * Define if this system needs memmove. */ @ISC_PLATFORM_NEEDMEMMOVE@ @@ -221,7 +223,7 @@ #define LIBISCCC_EXTERNAL_DATA #define LIBISCCFG_EXTERNAL_DATA #define LIBBIND9_EXTERNAL_DATA -#else /* ISC_PLATFORM_USEDECLSPEC */ +#else /*! \brief ISC_PLATFORM_USEDECLSPEC */ #ifdef LIBISC_EXPORTS #define LIBISC_EXTERNAL_DATA __declspec(dllexport) #else @@ -247,7 +249,7 @@ #else #define LIBBIND9_EXTERNAL_DATA __declspec(dllimport) #endif -#endif /* ISC_PLATFORM_USEDECLSPEC */ +#endif /*! \brief ISC_PLATFORM_USEDECLSPEC */ /* * Tell emacs to use C mode for this file. diff --git a/lib/isc/include/isc/print.h b/lib/isc/include/isc/print.h index ec7cef890f..1dba7f4f89 100644 --- a/lib/isc/include/isc/print.h +++ b/lib/isc/include/isc/print.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: print.h,v 1.19 2004/03/05 05:10:59 marka Exp $ */ +/* $Id: print.h,v 1.20 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_PRINT_H #define ISC_PRINT_H 1 +/*! \file */ + /*** *** Imports ***/ @@ -28,7 +30,7 @@ #include #include -/* +/*! * This block allows lib/isc/print.c to be cleanly compiled even if * the platform does not need it. The standard Makefile will still * not compile print.c or archive print.o, so this is just to make test diff --git a/lib/isc/include/isc/quota.h b/lib/isc/include/isc/quota.h index 6d705fb361..51aa9df29b 100644 --- a/lib/isc/include/isc/quota.h +++ b/lib/isc/include/isc/quota.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: quota.h,v 1.10 2004/03/05 05:11:00 marka Exp $ */ +/* $Id: quota.h,v 1.11 2005/04/27 04:57:19 sra Exp $ */ #ifndef ISC_QUOTA_H #define ISC_QUOTA_H 1 @@ -24,10 +24,9 @@ ***** Module Info *****/ -/* - * Quota +/*! \file isc/quota.h * - * The isc_quota_t object is a simple helper object for implementing + * \brief The isc_quota_t object is a simple helper object for implementing * quotas on things like the number of simultaneous connections to * a server. It keeps track of the amount of quota in use, and * encapsulates the locking necessary to allow multiple tasks to @@ -48,9 +47,9 @@ ISC_LANG_BEGINDECLS +/*% isc_quota structure */ struct isc_quota { - isc_mutex_t lock; - /* Locked by lock. */ + isc_mutex_t lock; /*%< Locked by lock. */ int max; int used; isc_boolean_t soft; @@ -58,7 +57,7 @@ struct isc_quota { isc_result_t isc_quota_init(isc_quota_t *quota, int max); -/* +/*%< * Initialize a quota object. * * Returns: @@ -68,43 +67,43 @@ isc_quota_init(isc_quota_t *quota, int max); void isc_quota_destroy(isc_quota_t *quota); -/* +/*%< * Destroy a quota object. */ void isc_quota_soft(isc_quota_t *quota, isc_boolean_t soft); -/* +/*%< * Turn on/off soft quotas. */ isc_result_t isc_quota_reserve(isc_quota_t *quota); -/* +/*%< * Attempt to reserve one unit of 'quota'. * * Returns: - * ISC_R_SUCCESS Success - * ISC_R_SOFTQUOTA Success soft quota reached - * ISC_R_QUOTA Quota is full + *\li #ISC_R_SUCCESS Success + *\li #ISC_R_SOFTQUOTA Success soft quota reached + *\li #ISC_R_QUOTA Quota is full */ void isc_quota_release(isc_quota_t *quota); -/* +/*%< * Release one unit of quota. */ isc_result_t isc_quota_attach(isc_quota_t *quota, isc_quota_t **p); -/* +/*%< * Like isc_quota_reserve, and also attaches '*p' to the * quota if successful (ISC_R_SUCCESS or ISC_R_SOFTQUOTA). */ void isc_quota_detach(isc_quota_t **p); -/* +/*%< * Like isc_quota_release, and also detaches '*p' from the * quota. */ diff --git a/lib/isc/include/isc/random.h b/lib/isc/include/isc/random.h index c2df5c67df..79b3f2d972 100644 --- a/lib/isc/include/isc/random.h +++ b/lib/isc/include/isc/random.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: random.h,v 1.12 2004/03/05 05:11:00 marka Exp $ */ +/* $Id: random.h,v 1.13 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_RANDOM_H #define ISC_RANDOM_H 1 @@ -23,9 +23,11 @@ #include #include -/* - * Implements a random state pool which will let the caller return a - * series of possibly non-reproducable random values. Note that the +/*! \file + * \brief Implements a random state pool which will let the caller return a + * series of possibly non-reproducable random values. + * + * Note that the * strength of these numbers is not all that high, and should not be * used in cryptography functions. It is useful for jittering values * a bit here and there, such as timeouts, etc. @@ -35,13 +37,13 @@ ISC_LANG_BEGINDECLS void isc_random_seed(isc_uint32_t seed); -/* +/*%< * Set the initial seed of the random state. */ void isc_random_get(isc_uint32_t *val); -/* +/*%< * Get a random value. * * Requires: @@ -50,7 +52,7 @@ isc_random_get(isc_uint32_t *val); isc_uint32_t isc_random_jitter(isc_uint32_t max, isc_uint32_t jitter); -/* +/*%< * Get a random value between (max - jitter) and (max). * This is useful for jittering timer values. */ diff --git a/lib/isc/include/isc/ratelimiter.h b/lib/isc/include/isc/ratelimiter.h index eaebe91336..a31bab4abe 100644 --- a/lib/isc/include/isc/ratelimiter.h +++ b/lib/isc/include/isc/ratelimiter.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ratelimiter.h,v 1.15 2004/03/05 05:11:00 marka Exp $ */ +/* $Id: ratelimiter.h,v 1.16 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_RATELIMITER_H #define ISC_RATELIMITER_H 1 @@ -24,8 +24,8 @@ ***** Module Info *****/ -/* - * A rate limiter is a mechanism for dispatching events at a limited +/*! \file + * \brief A rate limiter is a mechanism for dispatching events at a limited * rate. This is intended to be used when sending zone maintenance * SOA queries, NOTIFY messages, etc. */ @@ -46,13 +46,13 @@ ISC_LANG_BEGINDECLS isc_result_t isc_ratelimiter_create(isc_mem_t *mctx, isc_timermgr_t *timermgr, isc_task_t *task, isc_ratelimiter_t **ratelimiterp); -/* +/*%< * Create a rate limiter. The execution interval is initially undefined. */ isc_result_t isc_ratelimiter_setinterval(isc_ratelimiter_t *rl, isc_interval_t *interval); -/* +/*!< * Set the mininum interval between event executions. * The interval value is copied, so the caller need not preserve it. * @@ -62,7 +62,7 @@ isc_ratelimiter_setinterval(isc_ratelimiter_t *rl, isc_interval_t *interval); void isc_ratelimiter_setpertic(isc_ratelimiter_t *rl, isc_uint32_t perint); -/* +/*%< * Set the number of events processed per interval timer tick. * If 'perint' is zero it is treated as 1. */ @@ -70,8 +70,10 @@ isc_ratelimiter_setpertic(isc_ratelimiter_t *rl, isc_uint32_t perint); isc_result_t isc_ratelimiter_enqueue(isc_ratelimiter_t *rl, isc_task_t *task, isc_event_t **eventp); -/* - * Queue an event for rate-limited execution. This is similar +/*%< + * Queue an event for rate-limited execution. + * + * This is similar * to doing an isc_task_send() to the 'task', except that the * execution may be delayed to achieve the desired rate of * execution. @@ -80,50 +82,50 @@ isc_ratelimiter_enqueue(isc_ratelimiter_t *rl, isc_task_t *task, * must ensure that the task exists until the event is delivered. * * Requires: - * An interval has been set by calling + *\li An interval has been set by calling * isc_ratelimiter_setinterval(). * - * 'task' to be non NULL. - * '(*eventp)->ev_sender' to be NULL. + *\li 'task' to be non NULL. + *\li '(*eventp)->ev_sender' to be NULL. */ void isc_ratelimiter_shutdown(isc_ratelimiter_t *ratelimiter); -/* +/*%< * Shut down a rate limiter. * * Ensures: - * All events that have not yet been + *\li All events that have not yet been * dispatched to the task are dispatched immediately with - * the ISC_EVENTATTR_CANCELED bit set in ev_attributes. + * the #ISC_EVENTATTR_CANCELED bit set in ev_attributes. * - * Further attempts to enqueue events will fail with - * ISC_R_SHUTTINGDOWN. + *\li Further attempts to enqueue events will fail with + * #ISC_R_SHUTTINGDOWN. * - * The reatelimiter is no longer attached to its task. + *\li The reatelimiter is no longer attached to its task. */ void isc_ratelimiter_attach(isc_ratelimiter_t *source, isc_ratelimiter_t **target); -/* +/*%< * Attach to a rate limiter. */ void isc_ratelimiter_detach(isc_ratelimiter_t **ratelimiterp); -/* +/*%< * Detach from a rate limiter. */ isc_result_t isc_ratelimiter_stall(isc_ratelimiter_t *rl); -/* +/*%< * Stall event processing. */ isc_result_t isc_ratelimiter_release(isc_ratelimiter_t *rl); -/* +/*%< * Release a stalled rate limiter. */ diff --git a/lib/isc/include/isc/refcount.h b/lib/isc/include/isc/refcount.h index 0aa76c5606..fbb6de578f 100644 --- a/lib/isc/include/isc/refcount.h +++ b/lib/isc/include/isc/refcount.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: refcount.h,v 1.7 2004/04/14 05:09:43 marka Exp $ */ +/* $Id: refcount.h,v 1.8 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_REFCOUNT_H #define ISC_REFCOUNT_H 1 @@ -26,8 +26,10 @@ #include #include -/* - * Implements a locked reference counter. These functions may actually be +/*! \file + * \brief Implements a locked reference counter. + * + * These functions may actually be * implemented using macros, and implementations of these macros are below. * The isc_refcount_t type should not be accessed directly, as its contents * depend on the implementation. @@ -39,9 +41,7 @@ ISC_LANG_BEGINDECLS * Function prototypes */ -/* - * void - * isc_refcount_init(isc_refcount_t *ref, unsigned int n); +/* void isc_refcount_init(isc_refcount_t *ref, unsigned int n); * * Initialize the reference counter. There will be 'n' initial references. * @@ -93,6 +93,7 @@ typedef struct isc_refcount { isc_mutex_t lock; } isc_refcount_t; +/*% Initialize the reference counter. There will be 'n' initial references. */ #define isc_refcount_init(rp, n) \ do { \ isc_result_t _r; \ @@ -101,6 +102,7 @@ typedef struct isc_refcount { RUNTIME_CHECK(_r == ISC_R_SUCCESS); \ } while (0) +/*% Destroys a reference counter. */ #define isc_refcount_destroy(rp) \ do { \ REQUIRE((rp)->refs == 0); \ @@ -109,6 +111,7 @@ typedef struct isc_refcount { #define isc_refcount_current(rp) ((unsigned int)((rp)->refs)) +/*% Increments the reference count, returning the new value in targetp if it's not NULL. */ #define isc_refcount_increment(rp, tp) \ do { \ unsigned int *_tmp = (unsigned int *)(tp); \ @@ -120,6 +123,7 @@ typedef struct isc_refcount { UNLOCK(&(rp)->lock); \ } while (0) +/*% Decrements the reference count, returning the new value in targetp if it's not NULL. */ #define isc_refcount_decrement(rp, tp) \ do { \ unsigned int *_tmp = (unsigned int *)(tp); \ diff --git a/lib/isc/include/isc/region.h b/lib/isc/include/isc/region.h index 0ffe5a7d32..38bea108ce 100644 --- a/lib/isc/include/isc/region.h +++ b/lib/isc/include/isc/region.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: region.h,v 1.19 2004/03/05 05:11:00 marka Exp $ */ +/* $Id: region.h,v 1.20 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_REGION_H #define ISC_REGION_H 1 +/*! \file */ + #include struct isc_region { @@ -45,7 +47,8 @@ struct isc_consttextregion { unsigned int length; }; -/* +/*@{*/ +/*! * The region structure is not opaque, and is usually directly manipulated. * Some macros are defined below for convenience. */ @@ -76,20 +79,21 @@ struct isc_consttextregion { _r->base += _l; \ _r->length -= _l; \ } while (0) +/*@}*/ int isc_region_compare(isc_region_t *r1, isc_region_t *r2); -/* +/*%< * Compares the contents of two regions * * Requires: - * 'r1' is a valid region - * 'r2' is a valid region + *\li 'r1' is a valid region + *\li 'r2' is a valid region * * Returns: - * < 0 if r1 is lexicographically less than r2 - * = 0 if r1 is lexicographically identical to r2 - * > 0 if r1 is lexicographically greater than r2 + *\li < 0 if r1 is lexicographically less than r2 + *\li = 0 if r1 is lexicographically identical to r2 + *\li > 0 if r1 is lexicographically greater than r2 */ #endif /* ISC_REGION_H */ diff --git a/lib/isc/include/isc/resource.h b/lib/isc/include/isc/resource.h index 271ab9f7dc..cf6ecda6c9 100644 --- a/lib/isc/include/isc/resource.h +++ b/lib/isc/include/isc/resource.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: resource.h,v 1.5 2004/03/05 05:11:00 marka Exp $ */ +/* $Id: resource.h,v 1.6 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_RESOURCE_H #define ISC_RESOURCE_H 1 +/*! \file */ + #include #include @@ -29,40 +31,40 @@ ISC_LANG_BEGINDECLS isc_result_t isc_resource_setlimit(isc_resource_t resource, isc_resourcevalue_t value); -/* +/*%< * Set the maximum limit for a system resource. * * Notes: - * If 'value' exceeds the maximum possible on the operating system, + *\li If 'value' exceeds the maximum possible on the operating system, * it is silently limited to that maximum -- or to "infinity", if - * the operating system has that concept. ISC_RESOURCE_UNLIMITED + * the operating system has that concept. #ISC_RESOURCE_UNLIMITED * can be used to explicitly ask for the maximum. * * Requires: - * 'resource' is a valid member of the isc_resource_t enumeration. + *\li 'resource' is a valid member of the isc_resource_t enumeration. * * Returns: - * ISC_R_SUCCESS Success. - * ISC_R_NOTIMPLEMENTED 'resource' is not a type known by the OS. - * ISC_R_NOPERM The calling process did not have adequate permission + *\li #ISC_R_SUCCESS Success. + *\li #ISC_R_NOTIMPLEMENTED 'resource' is not a type known by the OS. + *\li #ISC_R_NOPERM The calling process did not have adequate permission * to change the resource limit. */ isc_result_t isc_resource_getlimit(isc_resource_t resource, isc_resourcevalue_t *value); -/* +/*%< * Get the maximum limit for a system resource. * * Notes: - * 'value' is set to the maximum limit. + *\li 'value' is set to the maximum limit. * - * ISC_RESOURCE_UNLIMITED is the maximum value of isc_resourcevalue_t. + *\li #ISC_RESOURCE_UNLIMITED is the maximum value of isc_resourcevalue_t. * - * On many (all?) Unix systems, RLIM_INFINITY is a valid value that is - * significantly less than ISC_RESOURCE_UNLIMITED, but which in practice + *\li On many (all?) Unix systems, RLIM_INFINITY is a valid value that is + * significantly less than #ISC_RESOURCE_UNLIMITED, but which in practice * behaves the same. * - * The current ISC libdns configuration file parser assigns a value + *\li The current ISC libdns configuration file parser assigns a value * of ISC_UINT32_MAX for a size_spec of "unlimited" and ISC_UNIT32_MAX - 1 * for "default", the latter of which is supposed to represent "the * limit that was in force when the server started". Since these are @@ -72,11 +74,11 @@ isc_resource_getlimit(isc_resource_t resource, isc_resourcevalue_t *value); * discrete integral values or generalized concepts. * * Requires: - * 'resource' is a valid member of the isc_resource_t enumeration. + *\li 'resource' is a valid member of the isc_resource_t enumeration. * * Returns: - * ISC_R_SUCCESS Success. - * ISC_R_NOTIMPLEMENTED 'resource' is not a type known by the OS. + *\li #ISC_R_SUCCESS Success. + *\li #ISC_R_NOTIMPLEMENTED 'resource' is not a type known by the OS. */ ISC_LANG_ENDDECLS diff --git a/lib/isc/include/isc/result.h b/lib/isc/include/isc/result.h index d3bfb49a74..7348997e8c 100644 --- a/lib/isc/include/isc/result.h +++ b/lib/isc/include/isc/result.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: result.h,v 1.63 2004/05/15 03:37:34 jinmei Exp $ */ +/* $Id: result.h,v 1.64 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_RESULT_H #define ISC_RESULT_H 1 @@ -23,77 +23,75 @@ #include #include -#define ISC_R_SUCCESS 0 /* success */ -#define ISC_R_NOMEMORY 1 /* out of memory */ -#define ISC_R_TIMEDOUT 2 /* timed out */ -#define ISC_R_NOTHREADS 3 /* no available threads */ -#define ISC_R_ADDRNOTAVAIL 4 /* address not available */ -#define ISC_R_ADDRINUSE 5 /* address in use */ -#define ISC_R_NOPERM 6 /* permission denied */ -#define ISC_R_NOCONN 7 /* no pending connections */ -#define ISC_R_NETUNREACH 8 /* network unreachable */ -#define ISC_R_HOSTUNREACH 9 /* host unreachable */ -#define ISC_R_NETDOWN 10 /* network down */ -#define ISC_R_HOSTDOWN 11 /* host down */ -#define ISC_R_CONNREFUSED 12 /* connection refused */ -#define ISC_R_NORESOURCES 13 /* not enough free resources */ -#define ISC_R_EOF 14 /* end of file */ -#define ISC_R_BOUND 15 /* socket already bound */ -#define ISC_R_RELOAD 16 /* reload */ -#define ISC_R_LOCKBUSY 17 /* lock busy */ -#define ISC_R_EXISTS 18 /* already exists */ -#define ISC_R_NOSPACE 19 /* ran out of space */ -#define ISC_R_CANCELED 20 /* operation canceled */ -#define ISC_R_NOTBOUND 21 /* socket is not bound */ -#define ISC_R_SHUTTINGDOWN 22 /* shutting down */ -#define ISC_R_NOTFOUND 23 /* not found */ -#define ISC_R_UNEXPECTEDEND 24 /* unexpected end of input */ -#define ISC_R_FAILURE 25 /* generic failure */ -#define ISC_R_IOERROR 26 /* I/O error */ -#define ISC_R_NOTIMPLEMENTED 27 /* not implemented */ -#define ISC_R_UNBALANCED 28 /* unbalanced parentheses */ -#define ISC_R_NOMORE 29 /* no more */ -#define ISC_R_INVALIDFILE 30 /* invalid file */ -#define ISC_R_BADBASE64 31 /* bad base64 encoding */ -#define ISC_R_UNEXPECTEDTOKEN 32 /* unexpected token */ -#define ISC_R_QUOTA 33 /* quota reached */ -#define ISC_R_UNEXPECTED 34 /* unexpected error */ -#define ISC_R_ALREADYRUNNING 35 /* already running */ -#define ISC_R_IGNORE 36 /* ignore */ -#define ISC_R_MASKNONCONTIG 37 /* addr mask not contiguous */ -#define ISC_R_FILENOTFOUND 38 /* file not found */ -#define ISC_R_FILEEXISTS 39 /* file already exists */ -#define ISC_R_NOTCONNECTED 40 /* socket is not connected */ -#define ISC_R_RANGE 41 /* out of range */ -#define ISC_R_NOENTROPY 42 /* out of entropy */ -#define ISC_R_MULTICAST 43 /* invalid use of multicast */ -#define ISC_R_NOTFILE 44 /* not a file */ -#define ISC_R_NOTDIRECTORY 45 /* not a directory */ -#define ISC_R_QUEUEFULL 46 /* queue is full */ -#define ISC_R_FAMILYMISMATCH 47 /* address family mismatch */ -#define ISC_R_FAMILYNOSUPPORT 48 /* AF not supported */ -#define ISC_R_BADHEX 49 /* bad hex encoding */ -#define ISC_R_TOOMANYOPENFILES 50 /* too many open files */ -#define ISC_R_NOTBLOCKING 51 /* not blocking */ -#define ISC_R_UNBALANCEDQUOTES 52 /* unbalanced quotes */ -#define ISC_R_INPROGRESS 53 /* operation in progress */ -#define ISC_R_CONNECTIONRESET 54 /* connection reset */ -#define ISC_R_SOFTQUOTA 55 /* soft quota reached */ -#define ISC_R_BADNUMBER 56 /* not a valid number */ -#define ISC_R_DISABLED 57 /* disabled */ -#define ISC_R_MAXSIZE 58 /* max size */ -#define ISC_R_BADADDRESSFORM 59 /* invalid address format */ +#define ISC_R_SUCCESS 0 /*%< success */ +#define ISC_R_NOMEMORY 1 /*%< out of memory */ +#define ISC_R_TIMEDOUT 2 /*%< timed out */ +#define ISC_R_NOTHREADS 3 /*%< no available threads */ +#define ISC_R_ADDRNOTAVAIL 4 /*%< address not available */ +#define ISC_R_ADDRINUSE 5 /*%< address in use */ +#define ISC_R_NOPERM 6 /*%< permission denied */ +#define ISC_R_NOCONN 7 /*%< no pending connections */ +#define ISC_R_NETUNREACH 8 /*%< network unreachable */ +#define ISC_R_HOSTUNREACH 9 /*%< host unreachable */ +#define ISC_R_NETDOWN 10 /*%< network down */ +#define ISC_R_HOSTDOWN 11 /*%< host down */ +#define ISC_R_CONNREFUSED 12 /*%< connection refused */ +#define ISC_R_NORESOURCES 13 /*%< not enough free resources */ +#define ISC_R_EOF 14 /*%< end of file */ +#define ISC_R_BOUND 15 /*%< socket already bound */ +#define ISC_R_RELOAD 16 /*%< reload */ +#define ISC_R_LOCKBUSY 17 /*%< lock busy */ +#define ISC_R_EXISTS 18 /*%< already exists */ +#define ISC_R_NOSPACE 19 /*%< ran out of space */ +#define ISC_R_CANCELED 20 /*%< operation canceled */ +#define ISC_R_NOTBOUND 21 /*%< socket is not bound */ +#define ISC_R_SHUTTINGDOWN 22 /*%< shutting down */ +#define ISC_R_NOTFOUND 23 /*%< not found */ +#define ISC_R_UNEXPECTEDEND 24 /*%< unexpected end of input */ +#define ISC_R_FAILURE 25 /*%< generic failure */ +#define ISC_R_IOERROR 26 /*%< I/O error */ +#define ISC_R_NOTIMPLEMENTED 27 /*%< not implemented */ +#define ISC_R_UNBALANCED 28 /*%< unbalanced parentheses */ +#define ISC_R_NOMORE 29 /*%< no more */ +#define ISC_R_INVALIDFILE 30 /*%< invalid file */ +#define ISC_R_BADBASE64 31 /*%< bad base64 encoding */ +#define ISC_R_UNEXPECTEDTOKEN 32 /*%< unexpected token */ +#define ISC_R_QUOTA 33 /*%< quota reached */ +#define ISC_R_UNEXPECTED 34 /*%< unexpected error */ +#define ISC_R_ALREADYRUNNING 35 /*%< already running */ +#define ISC_R_IGNORE 36 /*%< ignore */ +#define ISC_R_MASKNONCONTIG 37 /*%< addr mask not contiguous */ +#define ISC_R_FILENOTFOUND 38 /*%< file not found */ +#define ISC_R_FILEEXISTS 39 /*%< file already exists */ +#define ISC_R_NOTCONNECTED 40 /*%< socket is not connected */ +#define ISC_R_RANGE 41 /*%< out of range */ +#define ISC_R_NOENTROPY 42 /*%< out of entropy */ +#define ISC_R_MULTICAST 43 /*%< invalid use of multicast */ +#define ISC_R_NOTFILE 44 /*%< not a file */ +#define ISC_R_NOTDIRECTORY 45 /*%< not a directory */ +#define ISC_R_QUEUEFULL 46 /*%< queue is full */ +#define ISC_R_FAMILYMISMATCH 47 /*%< address family mismatch */ +#define ISC_R_FAMILYNOSUPPORT 48 /*%< AF not supported */ +#define ISC_R_BADHEX 49 /*%< bad hex encoding */ +#define ISC_R_TOOMANYOPENFILES 50 /*%< too many open files */ +#define ISC_R_NOTBLOCKING 51 /*%< not blocking */ +#define ISC_R_UNBALANCEDQUOTES 52 /*%< unbalanced quotes */ +#define ISC_R_INPROGRESS 53 /*%< operation in progress */ +#define ISC_R_CONNECTIONRESET 54 /*%< connection reset */ +#define ISC_R_SOFTQUOTA 55 /*%< soft quota reached */ +#define ISC_R_BADNUMBER 56 /*%< not a valid number */ +#define ISC_R_DISABLED 57 /*%< disabled */ +#define ISC_R_MAXSIZE 58 /*%< max size */ +#define ISC_R_BADADDRESSFORM 59 /*%< invalid address format */ -/* - * Not a result code: the number of results. - */ +/*% Not a result code: the number of results. */ #define ISC_R_NRESULTS 60 ISC_LANG_BEGINDECLS const char * isc_result_totext(isc_result_t); -/* +/*%< * Convert an isc_result_t into a string message describing the result. */ diff --git a/lib/isc/include/isc/resultclass.h b/lib/isc/include/isc/resultclass.h index 128cebb315..4791151990 100644 --- a/lib/isc/include/isc/resultclass.h +++ b/lib/isc/include/isc/resultclass.h @@ -15,19 +15,21 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: resultclass.h,v 1.12 2004/03/05 05:11:00 marka Exp $ */ +/* $Id: resultclass.h,v 1.13 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_RESULTCLASS_H #define ISC_RESULTCLASS_H 1 -/***** - ***** Registry of Predefined Result Type Classes - *****/ -/* +/*! \file + * \brief Registry of Predefined Result Type Classes + * * A result class number is an unsigned 16 bit number. Each class may * contain up to 65536 results. A result code is formed by adding the * result number within the class to the class number multiplied by 65536. + * + * Classes < 1024 are reserved for ISC use. + * Result classes >= 1024 and <= 65535 are reserved for application use. */ #define ISC_RESULTCLASS_FROMNUM(num) ((num) << 16) @@ -36,9 +38,6 @@ #define ISC_RESULTCLASS_INCLASS(rclass, result) \ ((rclass) == ((result) & 0xFFFF0000)) -/* - * Classes < 1024 are reserved for ISC use. - */ #define ISC_RESULTCLASS_ISC ISC_RESULTCLASS_FROMNUM(0) #define ISC_RESULTCLASS_DNS ISC_RESULTCLASS_FROMNUM(1) @@ -47,8 +46,5 @@ #define ISC_RESULTCLASS_OMAPI ISC_RESULTCLASS_FROMNUM(4) #define ISC_RESULTCLASS_ISCCC ISC_RESULTCLASS_FROMNUM(5) -/* - * Result classes >= 1024 and <= 65535 are reserved for application use. - */ #endif /* ISC_RESULTCLASS_H */ diff --git a/lib/isc/include/isc/rwlock.h b/lib/isc/include/isc/rwlock.h index ca775d791b..ec8961bd2d 100644 --- a/lib/isc/include/isc/rwlock.h +++ b/lib/isc/include/isc/rwlock.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rwlock.h,v 1.21 2004/03/05 05:11:00 marka Exp $ */ +/* $Id: rwlock.h,v 1.22 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_RWLOCK_H #define ISC_RWLOCK_H 1 +/*! \file */ + #include #include #include @@ -38,15 +40,15 @@ struct isc_rwlock { /* Unlocked. */ unsigned int magic; isc_mutex_t lock; - /* Locked by lock. */ + /*%< Locked by lock. */ isc_condition_t readable; isc_condition_t writeable; isc_rwlocktype_t type; - /* The number of threads that have the lock. */ + /*% The number of threads that have the lock. */ unsigned int active; - /* + /*% * The number of lock grants made since the lock was last switched * from reading to writing or vice versa; used in determining * when the quota is reached and it is time to switch. diff --git a/lib/isc/include/isc/serial.h b/lib/isc/include/isc/serial.h index f57f98183f..614cc7d96c 100644 --- a/lib/isc/include/isc/serial.h +++ b/lib/isc/include/isc/serial.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: serial.h,v 1.10 2004/03/05 05:11:00 marka Exp $ */ +/* $Id: serial.h,v 1.11 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_SERIAL_H #define ISC_SERIAL_H 1 @@ -23,9 +23,8 @@ #include #include -/* - * Implement 32 bit serial space arithmetic comparision functions. - * +/*! \file + * \brief Implement 32 bit serial space arithmetic comparision functions. * Note: Undefined results are returned as ISC_FALSE. */ @@ -37,37 +36,37 @@ ISC_LANG_BEGINDECLS isc_boolean_t isc_serial_lt(isc_uint32_t a, isc_uint32_t b); -/* +/*%< * Return true if 'a' < 'b' otherwise false. */ isc_boolean_t isc_serial_gt(isc_uint32_t a, isc_uint32_t b); -/* +/*%< * Return true if 'a' > 'b' otherwise false. */ isc_boolean_t isc_serial_le(isc_uint32_t a, isc_uint32_t b); -/* +/*%< * Return true if 'a' <= 'b' otherwise false. */ isc_boolean_t isc_serial_ge(isc_uint32_t a, isc_uint32_t b); -/* +/*%< * Return true if 'a' >= 'b' otherwise false. */ isc_boolean_t isc_serial_eq(isc_uint32_t a, isc_uint32_t b); -/* +/*%< * Return true if 'a' == 'b' otherwise false. */ isc_boolean_t isc_serial_ne(isc_uint32_t a, isc_uint32_t b); -/* +/*%< * Return true if 'a' != 'b' otherwise false. */ diff --git a/lib/isc/include/isc/sha1.h b/lib/isc/include/isc/sha1.h index 9466fedcc8..104d7a7007 100644 --- a/lib/isc/include/isc/sha1.h +++ b/lib/isc/include/isc/sha1.h @@ -18,14 +18,14 @@ #ifndef ISC_SHA1_H #define ISC_SHA1_H 1 -/* $Id: sha1.h,v 1.9 2004/03/05 05:11:00 marka Exp $ */ +/* $Id: sha1.h,v 1.10 2005/04/27 04:57:20 sra Exp $ */ /* $NetBSD: sha1.h,v 1.2 1998/05/29 22:55:44 thorpej Exp $ */ -/* - * SHA-1 in C - * By Steve Reid - * 100% Public Domain +/*! \file + * \brief SHA-1 in C + * \author By Steve Reid + * \note 100% Public Domain */ #include diff --git a/lib/isc/include/isc/sockaddr.h b/lib/isc/include/isc/sockaddr.h index a5dd7499ba..374decc876 100644 --- a/lib/isc/include/isc/sockaddr.h +++ b/lib/isc/include/isc/sockaddr.h @@ -15,7 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sockaddr.h,v 1.46 2005/03/16 23:39:06 marka Exp $ */ +/* $Id: sockaddr.h,v 1.47 2005/04/27 04:57:20 sra Exp $ */ + +/*! \file + */ #ifndef ISC_SOCKADDR_H #define ISC_SOCKADDR_H 1 @@ -65,13 +68,13 @@ isc_sockaddr_compare(const isc_sockaddr_t *a, const isc_sockaddr_t *b, isc_boolean_t isc_sockaddr_equal(const isc_sockaddr_t *a, const isc_sockaddr_t *b); -/* +/*%< * Return ISC_TRUE iff the socket addresses 'a' and 'b' are equal. */ isc_boolean_t isc_sockaddr_eqaddr(const isc_sockaddr_t *a, const isc_sockaddr_t *b); -/* +/*%< * Return ISC_TRUE iff the address parts of the socket addresses * 'a' and 'b' are equal, ignoring the ports. */ @@ -79,14 +82,14 @@ isc_sockaddr_eqaddr(const isc_sockaddr_t *a, const isc_sockaddr_t *b); isc_boolean_t isc_sockaddr_eqaddrprefix(const isc_sockaddr_t *a, const isc_sockaddr_t *b, unsigned int prefixlen); -/* +/*%< * Return ISC_TRUE iff the most significant 'prefixlen' bits of the * socket addresses 'a' and 'b' are equal, ignoring the ports. */ unsigned int isc_sockaddr_hash(const isc_sockaddr_t *sockaddr, isc_boolean_t address_only); -/* +/*%< * Return a hash value for the socket address 'sockaddr'. If 'address_only' * is ISC_TRUE, the hash value will not depend on the port. * @@ -96,19 +99,19 @@ isc_sockaddr_hash(const isc_sockaddr_t *sockaddr, isc_boolean_t address_only); void isc_sockaddr_any(isc_sockaddr_t *sockaddr); -/* +/*%< * Return the IPv4 wildcard address. */ void isc_sockaddr_any6(isc_sockaddr_t *sockaddr); -/* +/*%< * Return the IPv6 wildcard address. */ void isc_sockaddr_anyofpf(isc_sockaddr_t *sockaddr, int family); -/* +/*%< * Set '*sockaddr' to the wildcard address of protocol family * 'family'. * @@ -119,61 +122,61 @@ isc_sockaddr_anyofpf(isc_sockaddr_t *sockaddr, int family); void isc_sockaddr_fromin(isc_sockaddr_t *sockaddr, const struct in_addr *ina, in_port_t port); -/* +/*%< * Construct an isc_sockaddr_t from an IPv4 address and port. */ void isc_sockaddr_fromin6(isc_sockaddr_t *sockaddr, const struct in6_addr *ina6, in_port_t port); -/* +/*%< * Construct an isc_sockaddr_t from an IPv6 address and port. */ void isc_sockaddr_v6fromin(isc_sockaddr_t *sockaddr, const struct in_addr *ina, in_port_t port); -/* +/*%< * Construct an IPv6 isc_sockaddr_t representing a mapped IPv4 address. */ void isc_sockaddr_fromnetaddr(isc_sockaddr_t *sockaddr, const isc_netaddr_t *na, in_port_t port); -/* +/*%< * Construct an isc_sockaddr_t from an isc_netaddr_t and port. */ int isc_sockaddr_pf(const isc_sockaddr_t *sockaddr); -/* +/*%< * Get the protocol family of 'sockaddr'. * * Requires: * - * 'sockaddr' is a valid sockaddr with an address family of AF_INET + *\li 'sockaddr' is a valid sockaddr with an address family of AF_INET * or AF_INET6. * * Returns: * - * The protocol family of 'sockaddr', e.g. PF_INET or PF_INET6. + *\li The protocol family of 'sockaddr', e.g. PF_INET or PF_INET6. */ void isc_sockaddr_setport(isc_sockaddr_t *sockaddr, in_port_t port); -/* +/*%< * Set the port of 'sockaddr' to 'port'. */ in_port_t isc_sockaddr_getport(isc_sockaddr_t *sockaddr); -/* +/*%< * Get the port stored in 'sockaddr'. */ isc_result_t isc_sockaddr_totext(const isc_sockaddr_t *sockaddr, isc_buffer_t *target); -/* +/*%< * Append a text representation of 'sockaddr' to the buffer 'target'. * The text will include both the IP address (v4 or v6) and the port. * The text is null terminated, but the terminating null is not @@ -186,7 +189,7 @@ isc_sockaddr_totext(const isc_sockaddr_t *sockaddr, isc_buffer_t *target); void isc_sockaddr_format(const isc_sockaddr_t *sa, char *array, unsigned int size); -/* +/*%< * Format a human-readable representation of the socket address '*sa' * into the character array 'array', which is of size 'size'. * The resulting string is guaranteed to be null-terminated. @@ -194,8 +197,8 @@ isc_sockaddr_format(const isc_sockaddr_t *sa, char *array, unsigned int size); isc_boolean_t isc_sockaddr_ismulticast(isc_sockaddr_t *sa); -/* - * Returns ISC_TRUE if the address is a multicast address. +/*%< + * Returns #ISC_TRUE if the address is a multicast address. */ isc_boolean_t @@ -206,19 +209,19 @@ isc_sockaddr_isexperimental(isc_sockaddr_t *sa); isc_boolean_t isc_sockaddr_islinklocal(isc_sockaddr_t *sa); -/* +/*%< * Returns ISC_TRUE if the address is a link local addresss. */ isc_boolean_t isc_sockaddr_issitelocal(isc_sockaddr_t *sa); -/* +/*%< * Returns ISC_TRUE if the address is a sitelocal address. */ isc_result_t isc_sockaddr_frompath(isc_sockaddr_t *sockaddr, const char *path); -/* +/*%< * Create a UNIX domain sockaddr that refers to path. * * Returns: @@ -229,7 +232,7 @@ isc_sockaddr_frompath(isc_sockaddr_t *sockaddr, const char *path); #define ISC_SOCKADDR_FORMATSIZE \ sizeof("xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:XXX.XXX.XXX.XXX#YYYYY") -/* +/*%< * Minimum size of array to pass to isc_sockaddr_format(). */ diff --git a/lib/isc/include/isc/socket.h b/lib/isc/include/isc/socket.h index 575aa009d5..422d1b5bf8 100644 --- a/lib/isc/include/isc/socket.h +++ b/lib/isc/include/isc/socket.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: socket.h,v 1.59 2005/02/24 00:33:34 marka Exp $ */ +/* $Id: socket.h,v 1.60 2005/04/27 04:57:20 sra Exp $ */ #ifndef ISC_SOCKET_H #define ISC_SOCKET_H 1 @@ -24,36 +24,32 @@ ***** Module Info *****/ -/* - * Sockets - * - * Provides TCP and UDP sockets for network I/O. The sockets are event +/*! \file + * \brief Provides TCP and UDP sockets for network I/O. The sockets are event * sources in the task system. * * When I/O completes, a completion event for the socket is posted to the * event queue of the task which requested the I/O. * - * MP: + * \li MP: * The module ensures appropriate synchronization of data structures it * creates and manipulates. - * * Clients of this module must not be holding a socket's task's lock when * making a call that affects that socket. Failure to follow this rule * can result in deadlock. - * * The caller must ensure that isc_socketmgr_destroy() is called only * once for a given manager. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: - * + * \li Resources: + * TBS * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ @@ -75,7 +71,7 @@ ISC_LANG_BEGINDECLS *** Constants ***/ -/* +/*% * Maximum number of buffers in a scatter/gather read/write. The operating * system in use must support at least this number (plus one on some.) */ @@ -87,33 +83,34 @@ ISC_LANG_BEGINDECLS struct isc_socketevent { ISC_EVENT_COMMON(isc_socketevent_t); - isc_result_t result; /* OK, EOF, whatever else */ - unsigned int minimum; /* minimum i/o for event */ - unsigned int n; /* bytes read or written */ - unsigned int offset; /* offset into buffer list */ - isc_region_t region; /* for single-buffer i/o */ - isc_bufferlist_t bufferlist; /* list of buffers */ - isc_sockaddr_t address; /* source address */ - isc_time_t timestamp; /* timestamp of packet recv */ - struct in6_pktinfo pktinfo; /* ipv6 pktinfo */ - isc_uint32_t attributes; /* see below */ + isc_result_t result; /*%< OK, EOF, whatever else */ + unsigned int minimum; /*%< minimum i/o for event */ + unsigned int n; /*%< bytes read or written */ + unsigned int offset; /*%< offset into buffer list */ + isc_region_t region; /*%< for single-buffer i/o */ + isc_bufferlist_t bufferlist; /*%< list of buffers */ + isc_sockaddr_t address; /*%< source address */ + isc_time_t timestamp; /*%< timestamp of packet recv */ + struct in6_pktinfo pktinfo; /*%< ipv6 pktinfo */ + isc_uint32_t attributes; /*%< see below */ }; typedef struct isc_socket_newconnev isc_socket_newconnev_t; struct isc_socket_newconnev { ISC_EVENT_COMMON(isc_socket_newconnev_t); isc_socket_t * newsocket; - isc_result_t result; /* OK, EOF, whatever else */ - isc_sockaddr_t address; /* source address */ + isc_result_t result; /*%< OK, EOF, whatever else */ + isc_sockaddr_t address; /*%< source address */ }; typedef struct isc_socket_connev isc_socket_connev_t; struct isc_socket_connev { ISC_EVENT_COMMON(isc_socket_connev_t); - isc_result_t result; /* OK, EOF, whatever else */ + isc_result_t result; /*%< OK, EOF, whatever else */ }; -/* +/*@{*/ +/*! * _ATTACHED: Internal use only. * _TRUNC: Packet was truncated on receive. * _CTRUNC: Packet control information was truncated. This can @@ -129,6 +126,7 @@ struct isc_socket_connev { #define ISC_SOCKEVENTATTR_TIMESTAMP 0x00200000U /* public */ #define ISC_SOCKEVENTATTR_PKTINFO 0x00100000U /* public */ #define ISC_SOCKEVENTATTR_MULTICAST 0x00080000U /* public */ +/*@}*/ #define ISC_SOCKEVENT_ANYEVENT (0) #define ISC_SOCKEVENT_RECVDONE (ISC_EVENTCLASS_SOCKET + 1) @@ -148,27 +146,33 @@ typedef enum { isc_sockettype_unix = 3 } isc_sockettype_t; -/* +/*@{*/ +/*! * How a socket should be shutdown in isc_socket_shutdown() calls. */ -#define ISC_SOCKSHUT_RECV 0x00000001 /* close read side */ -#define ISC_SOCKSHUT_SEND 0x00000002 /* close write side */ -#define ISC_SOCKSHUT_ALL 0x00000003 /* close them all */ +#define ISC_SOCKSHUT_RECV 0x00000001 /*%< close read side */ +#define ISC_SOCKSHUT_SEND 0x00000002 /*%< close write side */ +#define ISC_SOCKSHUT_ALL 0x00000003 /*%< close them all */ +/*@}*/ -/* +/*@{*/ +/*! * What I/O events to cancel in isc_socket_cancel() calls. */ -#define ISC_SOCKCANCEL_RECV 0x00000001 /* cancel recv */ -#define ISC_SOCKCANCEL_SEND 0x00000002 /* cancel send */ -#define ISC_SOCKCANCEL_ACCEPT 0x00000004 /* cancel accept */ -#define ISC_SOCKCANCEL_CONNECT 0x00000008 /* cancel connect */ -#define ISC_SOCKCANCEL_ALL 0x0000000f /* cancel everything */ +#define ISC_SOCKCANCEL_RECV 0x00000001 /*%< cancel recv */ +#define ISC_SOCKCANCEL_SEND 0x00000002 /*%< cancel send */ +#define ISC_SOCKCANCEL_ACCEPT 0x00000004 /*%< cancel accept */ +#define ISC_SOCKCANCEL_CONNECT 0x00000008 /*%< cancel connect */ +#define ISC_SOCKCANCEL_ALL 0x0000000f /*%< cancel everything */ +/*@}*/ -/* +/*@{*/ +/*! * Flags for isc_socket_send() and isc_socket_recv() calls. */ -#define ISC_SOCKFLAG_IMMEDIATE 0x00000001 /* send event only if needed */ -#define ISC_SOCKFLAG_NORETRY 0x00000002 /* drop failed UDP sends */ +#define ISC_SOCKFLAG_IMMEDIATE 0x00000001 /*%< send event only if needed */ +#define ISC_SOCKFLAG_NORETRY 0x00000002 /*%< drop failed UDP sends */ +/*@}*/ /*** *** Socket and Socket Manager Functions @@ -182,18 +186,18 @@ isc_socket_create(isc_socketmgr_t *manager, int pf, isc_sockettype_t type, isc_socket_t **socketp); -/* +/*%< * Create a new 'type' socket managed by 'manager'. * * Note: * - * 'pf' is the desired protocol family, e.g. PF_INET or PF_INET6. + *\li 'pf' is the desired protocol family, e.g. PF_INET or PF_INET6. * * Requires: * - * 'manager' is a valid manager + *\li 'manager' is a valid manager * - * 'socketp' is a valid pointer, and *socketp == NULL + *\li 'socketp' is a valid pointer, and *socketp == NULL * * Ensures: * @@ -201,16 +205,16 @@ isc_socket_create(isc_socketmgr_t *manager, * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_NORESOURCES - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_NORESOURCES + *\li #ISC_R_UNEXPECTED */ void isc_socket_cancel(isc_socket_t *sock, isc_task_t *task, unsigned int how); -/* +/*%< * Cancel pending I/O of the type specified by "how". * * Note: if "task" is NULL, then the cancel applies to all tasks using the @@ -218,45 +222,45 @@ isc_socket_cancel(isc_socket_t *sock, isc_task_t *task, * * Requires: * - * "socket" is a valid socket + * \li "socket" is a valid socket * - * "task" is NULL or a valid task + * \li "task" is NULL or a valid task * * "how" is a bitmask describing the type of cancelation to perform. * The type ISC_SOCKCANCEL_ALL will cancel all pending I/O on this * socket. * - * ISC_SOCKCANCEL_RECV: + * \li ISC_SOCKCANCEL_RECV: * Cancel pending isc_socket_recv() calls. * - * ISC_SOCKCANCEL_SEND: + * \li ISC_SOCKCANCEL_SEND: * Cancel pending isc_socket_send() and isc_socket_sendto() calls. * - * ISC_SOCKCANCEL_ACCEPT: + * \li ISC_SOCKCANCEL_ACCEPT: * Cancel pending isc_socket_accept() calls. * - * ISC_SOCKCANCEL_CONNECT: + * \li ISC_SOCKCANCEL_CONNECT: * Cancel pending isc_socket_connect() call. */ void isc_socket_shutdown(isc_socket_t *sock, unsigned int how); -/* +/*%< * Shutdown 'socket' according to 'how'. * * Requires: * - * 'socket' is a valid socket. + * \li 'socket' is a valid socket. * - * 'task' is NULL or is a valid task. + * \li 'task' is NULL or is a valid task. * - * If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then + * \li If 'how' is 'ISC_SOCKSHUT_RECV' or 'ISC_SOCKSHUT_ALL' then * * The read queue must be empty. * * No further read requests may be made. * - * If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then + * \li If 'how' is 'ISC_SOCKSHUT_SEND' or 'ISC_SOCKSHUT_ALL' then * * The write queue must be empty. * @@ -265,39 +269,39 @@ isc_socket_shutdown(isc_socket_t *sock, unsigned int how); void isc_socket_attach(isc_socket_t *sock, isc_socket_t **socketp); -/* +/*%< * Attach *socketp to socket. * * Requires: * - * 'socket' is a valid socket. + * \li 'socket' is a valid socket. * - * 'socketp' points to a NULL socket. + * \li 'socketp' points to a NULL socket. * * Ensures: * - * *socketp is attached to socket. + * \li *socketp is attached to socket. */ void isc_socket_detach(isc_socket_t **socketp); -/* +/*%< * Detach *socketp from its socket. * * Requires: * - * 'socketp' points to a valid socket. + * \li 'socketp' points to a valid socket. * - * If '*socketp' is the last reference to the socket, + * \li If '*socketp' is the last reference to the socket, * then: * * There must be no pending I/O requests. * * Ensures: * - * *socketp is NULL. + * \li *socketp is NULL. * - * If '*socketp' is the last reference to the socket, + * \li If '*socketp' is the last reference to the socket, * then: * * The socket will be shutdown (both reading and writing) @@ -308,145 +312,146 @@ isc_socket_detach(isc_socket_t **socketp); isc_result_t isc_socket_bind(isc_socket_t *sock, isc_sockaddr_t *addressp); -/* +/*%< * Bind 'socket' to '*addressp'. * * Requires: * - * 'socket' is a valid socket + * \li 'socket' is a valid socket * - * 'addressp' points to a valid isc_sockaddr. + * \li 'addressp' points to a valid isc_sockaddr. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOPERM - * ISC_R_ADDRNOTAVAIL - * ISC_R_ADDRINUSE - * ISC_R_BOUND - * ISC_R_UNEXPECTED + * \li ISC_R_SUCCESS + * \li ISC_R_NOPERM + * \li ISC_R_ADDRNOTAVAIL + * \li ISC_R_ADDRINUSE + * \li ISC_R_BOUND + * \li ISC_R_UNEXPECTED */ isc_result_t isc_socket_filter(isc_socket_t *sock, const char *filter); -/* +/*%< * Inform the kernel that it should perform accept filtering. * If filter is NULL the current filter will be removed.:w */ isc_result_t isc_socket_listen(isc_socket_t *sock, unsigned int backlog); -/* +/*%< * Set listen mode on the socket. After this call, the only function that * can be used (other than attach and detach) is isc_socket_accept(). * * Notes: * - * 'backlog' is as in the UNIX system call listen() and may be + * \li 'backlog' is as in the UNIX system call listen() and may be * ignored by non-UNIX implementations. * - * If 'backlog' is zero, a reasonable system default is used, usually + * \li If 'backlog' is zero, a reasonable system default is used, usually * SOMAXCONN. * * Requires: * - * 'socket' is a valid, bound TCP socket or a valid, bound UNIX socket. + * \li 'socket' is a valid, bound TCP socket or a valid, bound UNIX socket. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_UNEXPECTED + * \li ISC_R_SUCCESS + * \li ISC_R_UNEXPECTED */ isc_result_t isc_socket_accept(isc_socket_t *sock, isc_task_t *task, isc_taskaction_t action, const void *arg); -/* +/*%< * Queue accept event. When a new connection is received, the task will * get an ISC_SOCKEVENT_NEWCONN event with the sender set to the listen * socket. The new socket structure is sent inside the isc_socket_newconnev_t * event type, and is attached to the task 'task'. * * REQUIRES: - * 'socket' is a valid TCP socket that isc_socket_listen() was called + * \li 'socket' is a valid TCP socket that isc_socket_listen() was called * on. * - * 'task' is a valid task + * \li 'task' is a valid task * - * 'action' is a valid action + * \li 'action' is a valid action * * RETURNS: - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED + * \li ISC_R_SUCCESS + * \li ISC_R_NOMEMORY + * \li ISC_R_UNEXPECTED */ isc_result_t isc_socket_connect(isc_socket_t *sock, isc_sockaddr_t *addressp, isc_task_t *task, isc_taskaction_t action, const void *arg); -/* +/*%< * Connect 'socket' to peer with address *saddr. When the connection * succeeds, or when an error occurs, a CONNECT event with action 'action' * and arg 'arg' will be posted to the event queue for 'task'. * * Requires: * - * 'socket' is a valid TCP socket + * \li 'socket' is a valid TCP socket * - * 'addressp' points to a valid isc_sockaddr + * \li 'addressp' points to a valid isc_sockaddr * - * 'task' is a valid task + * \li 'task' is a valid task * - * 'action' is a valid action + * \li 'action' is a valid action * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED + * \li ISC_R_SUCCESS + * \li ISC_R_NOMEMORY + * \li ISC_R_UNEXPECTED * * Posted event's result code: * - * ISC_R_SUCCESS - * ISC_R_TIMEDOUT - * ISC_R_CONNREFUSED - * ISC_R_NETUNREACH - * ISC_R_UNEXPECTED + * \li ISC_R_SUCCESS + * \li ISC_R_TIMEDOUT + * \li ISC_R_CONNREFUSED + * \li ISC_R_NETUNREACH + * \li ISC_R_UNEXPECTED */ isc_result_t isc_socket_getpeername(isc_socket_t *sock, isc_sockaddr_t *addressp); -/* +/*%< * Get the name of the peer connected to 'socket'. * * Requires: * - * 'socket' is a valid TCP socket. + * \li 'socket' is a valid TCP socket. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_TOOSMALL - * ISC_R_UNEXPECTED + * \li ISC_R_SUCCESS + * \li ISC_R_TOOSMALL + * \li ISC_R_UNEXPECTED */ isc_result_t isc_socket_getsockname(isc_socket_t *sock, isc_sockaddr_t *addressp); -/* +/*%< * Get the name of 'socket'. * * Requires: * - * 'socket' is a valid socket. + * \li 'socket' is a valid socket. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_TOOSMALL - * ISC_R_UNEXPECTED + * \li ISC_R_SUCCESS + * \li ISC_R_TOOSMALL + * \li ISC_R_UNEXPECTED */ +/*@{*/ isc_result_t isc_socket_recv(isc_socket_t *sock, isc_region_t *region, unsigned int minimum, @@ -461,39 +466,39 @@ isc_socket_recv2(isc_socket_t *sock, isc_region_t *region, unsigned int minimum, isc_task_t *task, isc_socketevent_t *event, unsigned int flags); -/* +/*! * Receive from 'socket', storing the results in region. * * Notes: * - * Let 'length' refer to the length of 'region' or to the sum of all + *\li Let 'length' refer to the length of 'region' or to the sum of all * available regions in the list of buffers '*buflist'. * - * If 'minimum' is non-zero and at least that many bytes are read, + *\li If 'minimum' is non-zero and at least that many bytes are read, * the completion event will be posted to the task 'task.' If minimum * is zero, the exact number of bytes requested in the region must * be read for an event to be posted. This only makes sense for TCP * connections, and is always set to 1 byte for UDP. * - * The read will complete when the desired number of bytes have been + *\li The read will complete when the desired number of bytes have been * read, if end-of-input occurs, or if an error occurs. A read done * event with the given 'action' and 'arg' will be posted to the * event queue of 'task'. * - * The caller may not modify 'region', the buffers which are passed + *\li The caller may not modify 'region', the buffers which are passed * into this function, or any data they refer to until the completion * event is received. * - * For isc_socket_recvv(): + *\li For isc_socket_recvv(): * On successful completion, '*buflist' will be empty, and the list of * all buffers will be returned in the done event's 'bufferlist' * member. On error return, '*buflist' will be unchanged. * - * For isc_socket_recv2(): + *\li For isc_socket_recv2(): * 'event' is not NULL, and the non-socket specific fields are * expected to be initialized. * - * For isc_socket_recv2(): + *\li For isc_socket_recv2(): * The only defined value for 'flags' is ISC_SOCKFLAG_IMMEDIATE. If * set and the operation completes, the return value will be * ISC_R_SUCCESS and the event will be filled in and not sent. If the @@ -503,36 +508,38 @@ isc_socket_recv2(isc_socket_t *sock, isc_region_t *region, * * Requires: * - * 'socket' is a valid, bound socket. + *\li 'socket' is a valid, bound socket. * - * For isc_socket_recv(): + *\li For isc_socket_recv(): * 'region' is a valid region * - * For isc_socket_recvv(): + *\li For isc_socket_recvv(): * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. * - * 'task' is a valid task + *\li 'task' is a valid task * - * For isc_socket_recv() and isc_socket_recvv(): + *\li For isc_socket_recv() and isc_socket_recvv(): * action != NULL and is a valid action * - * For isc_socket_recv2(): + *\li For isc_socket_recv2(): * event != NULL * * Returns: * - * ISC_R_SUCCESS - * ISC_R_INPROGRESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li #ISC_R_INPROGRESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED * * Event results: * - * ISC_R_SUCCESS - * ISC_R_UNEXPECTED - * XXX needs other net-type errors + *\li #ISC_R_SUCCESS + *\li #ISC_R_UNEXPECTED + *\li XXX needs other net-type errors */ +/*@}*/ +/*@{*/ isc_result_t isc_socket_send(isc_socket_t *sock, isc_region_t *region, isc_task_t *task, isc_taskaction_t action, const void *arg); @@ -553,41 +560,41 @@ isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region, isc_sockaddr_t *address, struct in6_pktinfo *pktinfo, isc_socketevent_t *event, unsigned int flags); -/* +/*! * Send the contents of 'region' to the socket's peer. * * Notes: * - * Shutting down the requestor's task *may* result in any + *\li Shutting down the requestor's task *may* result in any * still pending writes being dropped or completed, depending on the * underlying OS implementation. * - * If 'action' is NULL, then no completion event will be posted. + *\li If 'action' is NULL, then no completion event will be posted. * - * The caller may not modify 'region', the buffers which are passed + *\li The caller may not modify 'region', the buffers which are passed * into this function, or any data they refer to until the completion * event is received. * - * For isc_socket_sendv() and isc_socket_sendtov(): + *\li For isc_socket_sendv() and isc_socket_sendtov(): * On successful completion, '*buflist' will be empty, and the list of * all buffers will be returned in the done event's 'bufferlist' * member. On error return, '*buflist' will be unchanged. * - * For isc_socket_sendto2(): + *\li For isc_socket_sendto2(): * 'event' is not NULL, and the non-socket specific fields are * expected to be initialized. * - * For isc_socket_sendto2(): + *\li For isc_socket_sendto2(): * The only defined values for 'flags' are ISC_SOCKFLAG_IMMEDIATE * and ISC_SOCKFLAG_NORETRY. * - * If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the + *\li If ISC_SOCKFLAG_IMMEDIATE is set and the operation completes, the * return value will be ISC_R_SUCCESS and the event will be filled * in and not sent. If the operation does not complete, the return * value will be ISC_R_INPROGRESS and the event will be sent when * the operation completes. * - * ISC_SOCKFLAG_NORETRY can only be set for UDP sockets. If set + *\li ISC_SOCKFLAG_NORETRY can only be set for UDP sockets. If set * and the send operation fails due to a transient error, the send * will not be retried and the error will be indicated in the event. * Using this option along with ISC_SOCKFLAG_IMMEDIATE allows the caller @@ -595,110 +602,113 @@ isc_socket_sendto2(isc_socket_t *sock, isc_region_t *region, * * Requires: * - * 'socket' is a valid, bound socket. + *\li 'socket' is a valid, bound socket. * - * For isc_socket_send(): + *\li For isc_socket_send(): * 'region' is a valid region * - * For isc_socket_sendv() and isc_socket_sendtov(): + *\li For isc_socket_sendv() and isc_socket_sendtov(): * 'buflist' is non-NULL, and '*buflist' contain at least one buffer. * - * 'task' is a valid task + *\li 'task' is a valid task * - * For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and + *\li For isc_socket_sendv(), isc_socket_sendtov(), isc_socket_send(), and * isc_socket_sendto(): * action == NULL or is a valid action * - * For isc_socket_sendto2(): + *\li For isc_socket_sendto2(): * event != NULL * * Returns: * - * ISC_R_SUCCESS - * ISC_R_INPROGRESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li #ISC_R_INPROGRESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED * * Event results: * - * ISC_R_SUCCESS - * ISC_R_UNEXPECTED - * XXX needs other net-type errors + *\li #ISC_R_SUCCESS + *\li #ISC_R_UNEXPECTED + *\li XXX needs other net-type errors */ +/*@}*/ isc_result_t isc_socketmgr_create(isc_mem_t *mctx, isc_socketmgr_t **managerp); -/* +/*%< * Create a socket manager. * * Notes: * - * All memory will be allocated in memory context 'mctx'. + *\li All memory will be allocated in memory context 'mctx'. * * Requires: * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. * - * 'managerp' points to a NULL isc_socketmgr_t. + *\li 'managerp' points to a NULL isc_socketmgr_t. * * Ensures: * - * '*managerp' is a valid isc_socketmgr_t. + *\li '*managerp' is a valid isc_socketmgr_t. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED */ void isc_socketmgr_destroy(isc_socketmgr_t **managerp); -/* +/*%< * Destroy a socket manager. * * Notes: * - * This routine blocks until there are no sockets left in the manager, + *\li This routine blocks until there are no sockets left in the manager, * so if the caller holds any socket references using the manager, it * must detach them before calling isc_socketmgr_destroy() or it will * block forever. * * Requires: * - * '*managerp' is a valid isc_socketmgr_t. + *\li '*managerp' is a valid isc_socketmgr_t. * - * All sockets managed by this manager are fully detached. + *\li All sockets managed by this manager are fully detached. * * Ensures: * - * *managerp == NULL + *\li *managerp == NULL * - * All resources used by the manager have been freed. + *\li All resources used by the manager have been freed. */ isc_sockettype_t isc_socket_gettype(isc_socket_t *sock); -/* +/*%< * Returns the socket type for "sock." * * Requires: * - * "sock" is a valid socket. + *\li "sock" is a valid socket. */ +/*@{*/ isc_boolean_t isc_socket_isbound(isc_socket_t *sock); void isc_socket_ipv6only(isc_socket_t *sock, isc_boolean_t yes); -/* +/*%< * If the socket is an IPv6 socket set/clear the IPV6_IPV6ONLY socket * option if the host OS supports this option. * * Requires: - * 'sock' is a valid socket. + *\li 'sock' is a valid socket. */ +/*@}*/ void isc_socket_cleanunix(isc_sockaddr_t *addr, isc_boolean_t active); diff --git a/lib/isc/include/isc/stdio.h b/lib/isc/include/isc/stdio.h index 5a01a882c5..6e3b686e43 100644 --- a/lib/isc/include/isc/stdio.h +++ b/lib/isc/include/isc/stdio.h @@ -15,11 +15,22 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: stdio.h,v 1.7 2004/03/05 05:11:01 marka Exp $ */ +/* $Id: stdio.h,v 1.8 2005/04/27 04:57:21 sra Exp $ */ #ifndef ISC_STDIO_H #define ISC_STDIO_H 1 +/*! \file */ + +/*% + * These functions are wrappers around the corresponding stdio functions. + * + * They return a detailed error code in the form of an an isc_result_t. ANSI C + * does not guarantee that stdio functions set errno, hence these functions + * must use platform dependent methods (e.g., the POSIX errno) to construct the + * error code. + */ + #include #include @@ -27,36 +38,35 @@ ISC_LANG_BEGINDECLS +/*% Open */ isc_result_t isc_stdio_open(const char *filename, const char *mode, FILE **fp); +/*% Close */ isc_result_t isc_stdio_close(FILE *f); +/*% Seek */ isc_result_t isc_stdio_seek(FILE *f, long offset, int whence); +/*% Read */ isc_result_t isc_stdio_read(void *ptr, size_t size, size_t nmemb, FILE *f, size_t *nret); +/*% Write */ isc_result_t isc_stdio_write(const void *ptr, size_t size, size_t nmemb, FILE *f, size_t *nret); +/*% Flush */ isc_result_t isc_stdio_flush(FILE *f); -/* - * These functions are wrappers around the corresponding stdio functions, - * returning a detailed error code in the form of an an isc_result_t. ANSI C - * does not guarantee that stdio functions set errno, hence these functions - * must use platform dependent methods (e.g., the POSIX errno) to construct the - * error code. - */ isc_result_t isc_stdio_sync(FILE *f); -/* +/*%< * Invoke fsync() on the file descriptor underlying an stdio stream, or an * equivalent system-dependent operation. Note that this function has no * direct counterpart in the stdio library. diff --git a/lib/isc/include/isc/stdlib.h b/lib/isc/include/isc/stdlib.h index 350a185269..2613535165 100644 --- a/lib/isc/include/isc/stdlib.h +++ b/lib/isc/include/isc/stdlib.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: stdlib.h,v 1.2 2004/03/05 05:11:01 marka Exp $ */ +/* $Id: stdlib.h,v 1.3 2005/04/27 04:57:21 sra Exp $ */ #ifndef ISC_STDLIB_H #define ISC_STDLIB_H 1 +/*! \file */ + #include #include diff --git a/lib/isc/include/isc/string.h b/lib/isc/include/isc/string.h index 4a64144bcc..41507e9fdf 100644 --- a/lib/isc/include/isc/string.h +++ b/lib/isc/include/isc/string.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: string.h,v 1.12 2004/03/05 05:11:01 marka Exp $ */ +/* $Id: string.h,v 1.13 2005/04/27 04:57:21 sra Exp $ */ #ifndef ISC_STRING_H #define ISC_STRING_H 1 +/*! \file */ + #include #include @@ -30,7 +32,7 @@ ISC_LANG_BEGINDECLS isc_uint64_t isc_string_touint64(char *source, char **endp, int base); -/* +/*%< * Convert the string pointed to by 'source' to isc_uint64_t. * * On successful conversion 'endp' points to the first character diff --git a/lib/isc/include/isc/symtab.h b/lib/isc/include/isc/symtab.h index 7ac51eb5b8..45e92f8b14 100644 --- a/lib/isc/include/isc/symtab.h +++ b/lib/isc/include/isc/symtab.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: symtab.h,v 1.17 2004/03/05 05:11:01 marka Exp $ */ +/* $Id: symtab.h,v 1.18 2005/04/27 04:57:21 sra Exp $ */ #ifndef ISC_SYMTAB_H #define ISC_SYMTAB_H 1 @@ -24,10 +24,8 @@ ***** Module Info *****/ -/* - * Symbol Table - * - * Provides a simple memory-based symbol table. +/*! \file + * \brief Provides a simple memory-based symbol table. * * Keys are C strings, and key comparisons are case-insenstive. A type may * be specified when looking up, defining, or undefining. A type value of @@ -38,11 +36,11 @@ * tuple when a tuple with the given key and type already exists in the table. * What to do in this case is specified by the client. Possible policies are: * - * isc_symexists_reject Disallow the define, returning ISC_R_EXISTS - * isc_symexists_replace Replace the old value with the new. The + *\li #isc_symexists_reject Disallow the define, returning #ISC_R_EXISTS + *\li #isc_symexists_replace Replace the old value with the new. The * undefine action (if provided) will be called * with the old tuple. - * isc_symexists_add Add the new tuple, leaving the old tuple in + *\li #isc_symexists_add Add the new tuple, leaving the old tuple in * the table. Subsequent lookups will retrieve * the most-recently-defined tuple. * @@ -59,19 +57,19 @@ * undefined. It can be used to free memory associated with keys and/or * values. * - * MP: + * \li MP: * The callers of this module must ensure any required synchronization. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: - * + * \li Resources: + * TBS * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ @@ -82,10 +80,10 @@ #include #include -/*** +/* *** Symbol Tables. ***/ - +/*% Symbol table value. */ typedef union isc_symvalue { void * as_pointer; int as_integer; @@ -94,31 +92,36 @@ typedef union isc_symvalue { typedef void (*isc_symtabaction_t)(char *key, unsigned int type, isc_symvalue_t value, void *userarg); - +/*% Symbol table exists. */ typedef enum { - isc_symexists_reject = 0, - isc_symexists_replace = 1, - isc_symexists_add = 2 + isc_symexists_reject = 0, /*%< Disallow the define */ + isc_symexists_replace = 1, /*%< Replace the old value with the new */ + isc_symexists_add = 2 /*%< Add the new tuple */ } isc_symexists_t; ISC_LANG_BEGINDECLS +/*% Create a symbol table. */ isc_result_t isc_symtab_create(isc_mem_t *mctx, unsigned int size, isc_symtabaction_t undefine_action, void *undefine_arg, isc_boolean_t case_sensitive, isc_symtab_t **symtabp); +/*% Destroy a symbol table. */ void isc_symtab_destroy(isc_symtab_t **symtabp); +/*% Lookup a symbol table. */ isc_result_t isc_symtab_lookup(isc_symtab_t *symtab, const char *key, unsigned int type, isc_symvalue_t *value); +/*% Define a symbol table. */ isc_result_t isc_symtab_define(isc_symtab_t *symtab, const char *key, unsigned int type, isc_symvalue_t value, isc_symexists_t exists_policy); +/*% Undefine a symbol table. */ isc_result_t isc_symtab_undefine(isc_symtab_t *symtab, const char *key, unsigned int type); diff --git a/lib/isc/include/isc/task.h b/lib/isc/include/isc/task.h index 2cd1c5e800..cd1c163d50 100644 --- a/lib/isc/include/isc/task.h +++ b/lib/isc/include/isc/task.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: task.h,v 1.51 2004/03/05 05:11:01 marka Exp $ */ +/* $Id: task.h,v 1.52 2005/04/27 04:57:21 sra Exp $ */ #ifndef ISC_TASK_H #define ISC_TASK_H 1 @@ -24,33 +24,55 @@ ***** Module Info *****/ -/* - * Task System - * - * The task system provides a lightweight execution context, which is - * basically an event queue. When a task's event queue is non-empty, the +/*! \file + * \brief The task system provides a lightweight execution context, which is + * basically an event queue. + + * When a task's event queue is non-empty, the * task is runnable. A small work crew of threads, typically one per CPU, * execute runnable tasks by dispatching the events on the tasks' event * queues. Context switching between tasks is fast. * - * MP: + * \li MP: * The module ensures appropriate synchronization of data structures it * creates and manipulates. - * * The caller must ensure that isc_taskmgr_destroy() is called only * once for a given manager. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: - * + * \li Resources: + * TBS * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. + * + * \section purge Purging and Unsending + * + * Events which have been queued for a task but not delivered may be removed + * from the task's event queue by purging or unsending. + * + * With both types, the caller specifies a matching pattern that selects + * events based upon their sender, type, and tag. + * + * Purging calls isc_event_free() on the matching events. + * + * Unsending returns a list of events that matched the pattern. + * The caller is then responsible for them. + * + * Consumers of events should purge, not unsend. + * + * Producers of events often want to remove events when the caller indicates + * it is no longer interested in the object, e.g. by cancelling a timer. + * Sometimes this can be done by purging, but for some event types, the + * calls to isc_event_free() cause deadlock because the event free routine + * wants to acquire a lock the caller is already holding. Unsending instead + * of purging solves this problem. As a general rule, producers should only + * unsend events which they have sent. */ @@ -76,355 +98,335 @@ ISC_LANG_BEGINDECLS isc_result_t isc_task_create(isc_taskmgr_t *manager, unsigned int quantum, isc_task_t **taskp); -/* +/*%< * Create a task. * * Notes: * - * If 'quantum' is non-zero, then only that many events can be dispatched + *\li If 'quantum' is non-zero, then only that many events can be dispatched * before the task must yield to other tasks waiting to execute. If * quantum is zero, then the default quantum of the task manager will * be used. * - * The 'quantum' option may be removed from isc_task_create() in the + *\li The 'quantum' option may be removed from isc_task_create() in the * future. If this happens, isc_task_getquantum() and * isc_task_setquantum() will be provided. * * Requires: * - * 'manager' is a valid task manager. + *\li 'manager' is a valid task manager. * - * taskp != NULL && *taskp == NULL + *\li taskp != NULL && *taskp == NULL * * Ensures: * - * On success, '*taskp' is bound to the new task. + *\li On success, '*taskp' is bound to the new task. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED - * ISC_R_SHUTTINGDOWN + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED + *\li #ISC_R_SHUTTINGDOWN */ void isc_task_attach(isc_task_t *source, isc_task_t **targetp); -/* +/*%< * Attach *targetp to source. * * Requires: * - * 'source' is a valid task. + *\li 'source' is a valid task. * - * 'targetp' points to a NULL isc_task_t *. + *\li 'targetp' points to a NULL isc_task_t *. * * Ensures: * - * *targetp is attached to source. + *\li *targetp is attached to source. */ void isc_task_detach(isc_task_t **taskp); -/* +/*%< * Detach *taskp from its task. * * Requires: * - * '*taskp' is a valid task. + *\li '*taskp' is a valid task. * * Ensures: * - * *taskp is NULL. + *\li *taskp is NULL. * - * If '*taskp' is the last reference to the task, the task is idle (has + *\li If '*taskp' is the last reference to the task, the task is idle (has * an empty event queue), and has not been shutdown, the task will be * shutdown. * - * If '*taskp' is the last reference to the task and + *\li If '*taskp' is the last reference to the task and * the task has been shutdown, - * - * All resources used by the task will be freed. + * all resources used by the task will be freed. */ void isc_task_send(isc_task_t *task, isc_event_t **eventp); -/* +/*%< * Send '*event' to 'task'. * * Requires: * - * 'task' is a valid task. - * eventp != NULL && *eventp != NULL. + *\li 'task' is a valid task. + *\li eventp != NULL && *eventp != NULL. * * Ensures: * - * *eventp == NULL. + *\li *eventp == NULL. */ void isc_task_sendanddetach(isc_task_t **taskp, isc_event_t **eventp); -/* +/*%< * Send '*event' to '*taskp' and then detach '*taskp' from its * task. * * Requires: * - * '*taskp' is a valid task. - * eventp != NULL && *eventp != NULL. + *\li '*taskp' is a valid task. + *\li eventp != NULL && *eventp != NULL. * * Ensures: * - * *eventp == NULL. + *\li *eventp == NULL. * - * *taskp == NULL. + *\li *taskp == NULL. * - * If '*taskp' is the last reference to the task, the task is + *\li If '*taskp' is the last reference to the task, the task is * idle (has an empty event queue), and has not been shutdown, * the task will be shutdown. * - * If '*taskp' is the last reference to the task and + *\li If '*taskp' is the last reference to the task and * the task has been shutdown, - * - * All resources used by the task will be freed. + * all resources used by the task will be freed. */ -/* - * Purging and Unsending - * - * Events which have been queued for a task but not delivered may be removed - * from the task's event queue by purging or unsending. - * - * With both types, the caller specifies a matching pattern that selects - * events based upon their sender, type, and tag. - * - * Purging calls isc_event_free() on the matching events. - * - * Unsending returns a list of events that matched the pattern. - * The caller is then responsible for them. - * - * Consumers of events should purge, not unsend. - * - * Producers of events often want to remove events when the caller indicates - * it is no longer interested in the object, e.g. by cancelling a timer. - * Sometimes this can be done by purging, but for some event types, the - * calls to isc_event_free() cause deadlock because the event free routine - * wants to acquire a lock the caller is already holding. Unsending instead - * of purging solves this problem. As a general rule, producers should only - * unsend events which they have sent. - */ unsigned int isc_task_purgerange(isc_task_t *task, void *sender, isc_eventtype_t first, isc_eventtype_t last, void *tag); -/* +/*%< * Purge events from a task's event queue. * * Requires: * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * last >= first + *\li last >= first * * Ensures: * - * Events in the event queue of 'task' whose sender is 'sender', whose + *\li Events in the event queue of 'task' whose sender is 'sender', whose * type is >= first and <= last, and whose tag is 'tag' will be purged, * unless they are marked as unpurgable. * - * A sender of NULL will match any sender. A NULL tag matches any + *\li A sender of NULL will match any sender. A NULL tag matches any * tag. * * Returns: * - * The number of events purged. + *\li The number of events purged. */ unsigned int isc_task_purge(isc_task_t *task, void *sender, isc_eventtype_t type, void *tag); -/* +/*%< * Purge events from a task's event queue. * * Notes: * - * This function is equivalent to + *\li This function is equivalent to * + *\code * isc_task_purgerange(task, sender, type, type, tag); + *\endcode * * Requires: * - * 'task' is a valid task. + *\li 'task' is a valid task. * * Ensures: * - * Events in the event queue of 'task' whose sender is 'sender', whose + *\li Events in the event queue of 'task' whose sender is 'sender', whose * type is 'type', and whose tag is 'tag' will be purged, unless they * are marked as unpurgable. * - * A sender of NULL will match any sender. A NULL tag matches any + *\li A sender of NULL will match any sender. A NULL tag matches any * tag. * * Returns: * - * The number of events purged. + *\li The number of events purged. */ isc_boolean_t isc_task_purgeevent(isc_task_t *task, isc_event_t *event); -/* +/*%< * Purge 'event' from a task's event queue. * * XXXRTH: WARNING: This method may be removed before beta. * * Notes: * - * If 'event' is on the task's event queue, it will be purged, + *\li If 'event' is on the task's event queue, it will be purged, * unless it is marked as unpurgeable. 'event' does not have to be * on the task's event queue; in fact, it can even be an invalid * pointer. Purging only occurs if the event is actually on the task's * event queue. * - * Purging never changes the state of the task. + * \li Purging never changes the state of the task. * * Requires: * - * 'task' is a valid task. + *\li 'task' is a valid task. * * Ensures: * - * 'event' is not in the event queue for 'task'. + *\li 'event' is not in the event queue for 'task'. * * Returns: * - * ISC_TRUE The event was purged. - * ISC_FALSE The event was not in the event queue, + *\li #ISC_TRUE The event was purged. + *\li #ISC_FALSE The event was not in the event queue, * or was marked unpurgeable. */ unsigned int isc_task_unsendrange(isc_task_t *task, void *sender, isc_eventtype_t first, isc_eventtype_t last, void *tag, isc_eventlist_t *events); -/* +/*%< * Remove events from a task's event queue. * * Requires: * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * last >= first. + *\li last >= first. * - * *events is a valid list. + *\li *events is a valid list. * * Ensures: * - * Events in the event queue of 'task' whose sender is 'sender', whose + *\li Events in the event queue of 'task' whose sender is 'sender', whose * type is >= first and <= last, and whose tag is 'tag' will be dequeued * and appended to *events. * - * A sender of NULL will match any sender. A NULL tag matches any + *\li A sender of NULL will match any sender. A NULL tag matches any * tag. * * Returns: * - * The number of events unsent. + *\li The number of events unsent. */ unsigned int isc_task_unsend(isc_task_t *task, void *sender, isc_eventtype_t type, void *tag, isc_eventlist_t *events); -/* +/*%< * Remove events from a task's event queue. * * Notes: * - * This function is equivalent to + *\li This function is equivalent to * + *\code * isc_task_unsendrange(task, sender, type, type, tag, events); + *\endcode * * Requires: * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * *events is a valid list. + *\li *events is a valid list. * * Ensures: * - * Events in the event queue of 'task' whose sender is 'sender', whose + *\li Events in the event queue of 'task' whose sender is 'sender', whose * type is 'type', and whose tag is 'tag' will be dequeued and appended * to *events. * * Returns: * - * The number of events unsent. + *\li The number of events unsent. */ isc_result_t isc_task_onshutdown(isc_task_t *task, isc_taskaction_t action, const void *arg); -/* +/*%< * Send a shutdown event with action 'action' and argument 'arg' when * 'task' is shutdown. * * Notes: * - * Shutdown events are posted in LIFO order. + *\li Shutdown events are posted in LIFO order. * * Requires: * - * 'task' is a valid task. + *\li 'task' is a valid task. * - * 'action' is a valid task action. + *\li 'action' is a valid task action. * * Ensures: * - * When the task is shutdown, shutdown events requested with + *\li When the task is shutdown, shutdown events requested with * isc_task_onshutdown() will be appended to the task's event queue. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_TASKSHUTTINGDOWN Task is shutting down. + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_TASKSHUTTINGDOWN Task is shutting down. */ void isc_task_shutdown(isc_task_t *task); -/* +/*%< * Shutdown 'task'. * * Notes: * - * Shutting down a task causes any shutdown events requested with + *\li Shutting down a task causes any shutdown events requested with * isc_task_onshutdown() to be posted (in LIFO order). The task * moves into a "shutting down" mode which prevents further calls * to isc_task_onshutdown(). * - * Trying to shutdown a task that has already been shutdown has no + *\li Trying to shutdown a task that has already been shutdown has no * effect. * * Requires: * - * 'task' is a valid task. + *\li 'task' is a valid task. * * Ensures: * - * Any shutdown events requested with isc_task_onshutdown() have been + *\li Any shutdown events requested with isc_task_onshutdown() have been * posted (in LIFO order). */ void isc_task_destroy(isc_task_t **taskp); -/* +/*%< * Destroy '*taskp'. * * Notes: * - * This call is equivalent to: + *\li This call is equivalent to: * + *\code * isc_task_shutdown(*taskp); * isc_task_detach(taskp); + *\endcode * * Requires: * @@ -432,45 +434,44 @@ isc_task_destroy(isc_task_t **taskp); * * Ensures: * - * Any shutdown events requested with isc_task_onshutdown() have been + *\li Any shutdown events requested with isc_task_onshutdown() have been * posted (in LIFO order). * - * *taskp == NULL + *\li *taskp == NULL * - * If '*taskp' is the last reference to the task, - * - * All resources used by the task will be freed. + *\li If '*taskp' is the last reference to the task, + * all resources used by the task will be freed. */ void isc_task_setname(isc_task_t *task, const char *name, void *tag); -/* +/*%< * Name 'task'. * * Notes: * - * Only the first 15 characters of 'name' will be copied. + *\li Only the first 15 characters of 'name' will be copied. * - * Naming a task is currently only useful for debugging purposes. + *\li Naming a task is currently only useful for debugging purposes. * * Requires: * - * 'task' is a valid task. + *\li 'task' is a valid task. */ const char * isc_task_getname(isc_task_t *task); -/* +/*%< * Get the name of 'task', as previously set using isc_task_setname(). * * Notes: - * This function is for debugging purposes only. + *\li This function is for debugging purposes only. * * Requires: - * 'task' is a valid task. + *\li 'task' is a valid task. * * Returns: - * A non-NULL pointer to a null-terminated string. + *\li A non-NULL pointer to a null-terminated string. * If the task has not been named, the string is * empty. * @@ -478,19 +479,19 @@ isc_task_getname(isc_task_t *task); void * isc_task_gettag(isc_task_t *task); -/* +/*%< * Get the tag value for 'task', as previously set using isc_task_settag(). * * Notes: - * This function is for debugging purposes only. + *\li This function is for debugging purposes only. * * Requires: - * 'task' is a valid task. + *\li 'task' is a valid task. */ isc_result_t isc_task_beginexclusive(isc_task_t *task); -/* +/*%< * Request exclusive access for 'task', which must be the calling * task. Waits for any other concurrently executing tasks to finish their * current event, and prevents any new events from executing in any of the @@ -500,37 +501,37 @@ isc_task_beginexclusive(isc_task_t *task); * isc_task_endexclusive() before returning from the current event handler. * * Requires: - * 'task' is the calling task. + *\li 'task' is the calling task. * * Returns: - * ISC_R_SUCCESS The current task now has exclusive access. - * ISC_R_LOCKBUSY Another task has already requested exclusive + *\li #ISC_R_SUCCESS The current task now has exclusive access. + *\li #ISC_R_LOCKBUSY Another task has already requested exclusive * access. */ void isc_task_endexclusive(isc_task_t *task); -/* +/*%< * Relinquish the exclusive access obtained by isc_task_beginexclusive(), * allowing other tasks to execute. * * Requires: - * 'task' is the calling task, and has obtained + *\li 'task' is the calling task, and has obtained * exclusive access by calling isc_task_spl(). */ void isc_task_getcurrenttime(isc_task_t *task, isc_stdtime_t *t); -/* +/*%< * Provide the most recent timestamp on the task. The timestamp is considered * as the "current time" in the second-order granularity. * * Requires: - * 'task' is a valid task. - * 't' is a valid non NULL pointer. + *\li 'task' is a valid task. + *\li 't' is a valid non NULL pointer. * * Ensures: - * '*t' has the "current time". + *\li '*t' has the "current time". */ /***** @@ -540,73 +541,73 @@ isc_task_getcurrenttime(isc_task_t *task, isc_stdtime_t *t); isc_result_t isc_taskmgr_create(isc_mem_t *mctx, unsigned int workers, unsigned int default_quantum, isc_taskmgr_t **managerp); -/* +/*%< * Create a new task manager. * * Notes: * - * 'workers' in the number of worker threads to create. In general, + *\li 'workers' in the number of worker threads to create. In general, * the value should be close to the number of processors in the system. * The 'workers' value is advisory only. An attempt will be made to * create 'workers' threads, but if at least one thread creation * succeeds, isc_taskmgr_create() may return ISC_R_SUCCESS. * - * If 'default_quantum' is non-zero, then it will be used as the default + *\li If 'default_quantum' is non-zero, then it will be used as the default * quantum value when tasks are created. If zero, then an implementation * defined default quantum will be used. * * Requires: * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. * - * workers > 0 + *\li workers > 0 * - * managerp != NULL && *managerp == NULL + *\li managerp != NULL && *managerp == NULL * * Ensures: * - * On success, '*managerp' will be attached to the newly created task + *\li On success, '*managerp' will be attached to the newly created task * manager. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_NOTHREADS No threads could be created. - * ISC_R_UNEXPECTED An unexpected error occurred. + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_NOTHREADS No threads could be created. + *\li #ISC_R_UNEXPECTED An unexpected error occurred. */ void isc_taskmgr_destroy(isc_taskmgr_t **managerp); -/* +/*%< * Destroy '*managerp'. * * Notes: * - * Calling isc_taskmgr_destroy() will shutdown all tasks managed by + *\li Calling isc_taskmgr_destroy() will shutdown all tasks managed by * *managerp that haven't already been shutdown. The call will block * until all tasks have entered the done state. * - * isc_taskmgr_destroy() must not be called by a task event action, + *\li isc_taskmgr_destroy() must not be called by a task event action, * because it would block forever waiting for the event action to * complete. An event action that wants to cause task manager shutdown * should request some non-event action thread of execution to do the * shutdown, e.g. by signalling a condition variable or using * isc_app_shutdown(). * - * Task manager references are not reference counted, so the caller + *\li Task manager references are not reference counted, so the caller * must ensure that no attempt will be made to use the manager after * isc_taskmgr_destroy() returns. * * Requires: * - * '*managerp' is a valid task manager. + *\li '*managerp' is a valid task manager. * - * isc_taskmgr_destroy() has not be called previously on '*managerp'. + *\li isc_taskmgr_destroy() has not be called previously on '*managerp'. * * Ensures: * - * All resources used by the task manager, and any tasks it managed, + *\li All resources used by the task manager, and any tasks it managed, * have been freed. */ diff --git a/lib/isc/include/isc/taskpool.h b/lib/isc/include/isc/taskpool.h index 343620bc30..feec5a286c 100644 --- a/lib/isc/include/isc/taskpool.h +++ b/lib/isc/include/isc/taskpool.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: taskpool.h,v 1.9 2004/03/05 05:11:01 marka Exp $ */ +/* $Id: taskpool.h,v 1.10 2005/04/27 04:57:21 sra Exp $ */ #ifndef ISC_TASKPOOL_H #define ISC_TASKPOOL_H 1 @@ -24,10 +24,8 @@ ***** Module Info *****/ -/* - * Task Pool - * - * A task pool is a mechanism for sharing a small number of tasks +/*! \file + * \brief A task pool is a mechanism for sharing a small number of tasks * among a large number of objects such that each object is * assigned a unique task, but each task may be shared by several * objects. @@ -62,44 +60,44 @@ isc_result_t isc_taskpool_create(isc_taskmgr_t *tmgr, isc_mem_t *mctx, unsigned int ntasks, unsigned int quantum, isc_taskpool_t **poolp); -/* +/*%< * Create a task pool of "ntasks" tasks, each with quantum * "quantum". * * Requires: * - * 'tmgr' is a valid task manager. + *\li 'tmgr' is a valid task manager. * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. * - * poolp != NULL && *poolp == NULL + *\li poolp != NULL && *poolp == NULL * * Ensures: * - * On success, '*taskp' points to the new task pool. + *\li On success, '*taskp' points to the new task pool. * * Returns: * - * ISC_R_SUCCESS - * ISC_R_NOMEMORY - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS + *\li #ISC_R_NOMEMORY + *\li #ISC_R_UNEXPECTED */ void isc_taskpool_gettask(isc_taskpool_t *pool, unsigned int hash, isc_task_t **targetp); -/* +/*%< * Attach to the task corresponding to the hash value "hash". */ void isc_taskpool_destroy(isc_taskpool_t **poolp); -/* +/*%< * Destroy a task pool. The tasks in the pool are detached but not * shut down. * * Requires: - * '*poolp' is a valid task pool. + * \li '*poolp' is a valid task pool. */ ISC_LANG_ENDDECLS diff --git a/lib/isc/include/isc/timer.h b/lib/isc/include/isc/timer.h index c96b5de8e9..8f3a7429f4 100644 --- a/lib/isc/include/isc/timer.h +++ b/lib/isc/include/isc/timer.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: timer.h,v 1.31 2004/03/05 05:11:02 marka Exp $ */ +/* $Id: timer.h,v 1.32 2005/04/27 04:57:21 sra Exp $ */ #ifndef ISC_TIMER_H #define ISC_TIMER_H 1 @@ -24,50 +24,46 @@ ***** Module Info *****/ -/* - * Timers - * - * Provides timers which are event sources in the task system. +/*! \file + * \brief Provides timers which are event sources in the task system. * * Three types of timers are supported: * - * 'ticker' timers generate a periodic tick event. + *\li 'ticker' timers generate a periodic tick event. * - * 'once' timers generate an idle timeout event if they are idle for too + *\li 'once' timers generate an idle timeout event if they are idle for too * long, and generate a life timeout event if their lifetime expires. * They are used to implement both (possibly expiring) idle timers and * 'one-shot' timers. * - * 'limited' timers generate a periodic tick event until they reach + *\li 'limited' timers generate a periodic tick event until they reach * their lifetime when they generate a life timeout event. * - * 'inactive' timers generate no events. + *\li 'inactive' timers generate no events. * * Timers can change type. It is typical to create a timer as * an 'inactive' timer and then change it into a 'ticker' or * 'once' timer. * - * MP: + *\li MP: * The module ensures appropriate synchronization of data structures it * creates and manipulates. - * * Clients of this module must not be holding a timer's task's lock when * making a call that affects that timer. Failure to follow this rule * can result in deadlock. - * * The caller must ensure that isc_timermgr_destroy() is called only * once for a given manager. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: - * + * \li Resources: + * TBS * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ @@ -87,11 +83,12 @@ ISC_LANG_BEGINDECLS *** Types ***/ +/*% Timer Type */ typedef enum { - isc_timertype_ticker = 0, - isc_timertype_once = 1, - isc_timertype_limited = 2, - isc_timertype_inactive = 3 + isc_timertype_ticker = 0, /*%< Ticker */ + isc_timertype_once = 1, /*%< Once */ + isc_timertype_limited = 2, /*%< Limited */ + isc_timertype_inactive = 3 /*%< Inactive */ } isc_timertype_t; typedef struct isc_timerevent { @@ -120,7 +117,7 @@ isc_timer_create(isc_timermgr_t *manager, isc_taskaction_t action, const void *arg, isc_timer_t **timerp); -/* +/*%< * Create a new 'type' timer managed by 'manager'. The timers parameters * are specified by 'expires' and 'interval'. Events will be posted to * 'task' and when dispatched 'action' will be called with 'arg' as the @@ -128,51 +125,51 @@ isc_timer_create(isc_timermgr_t *manager, * * Notes: * - * For ticker timers, the timer will generate a 'tick' event every + *\li For ticker timers, the timer will generate a 'tick' event every * 'interval' seconds. The value of 'expires' is ignored. * - * For once timers, 'expires' specifies the time when a life timeout + *\li For once timers, 'expires' specifies the time when a life timeout * event should be generated. If 'expires' is 0 (the epoch), then no life * timeout will be generated. 'interval' specifies how long the timer * can be idle before it generates an idle timeout. If 0, then no * idle timeout will be generated. * - * If 'expires' is NULL, the epoch will be used. + *\li If 'expires' is NULL, the epoch will be used. * * If 'interval' is NULL, the zero interval will be used. * * Requires: * - * 'manager' is a valid manager + *\li 'manager' is a valid manager * - * 'task' is a valid task + *\li 'task' is a valid task * - * 'action' is a valid action + *\li 'action' is a valid action * - * 'expires' points to a valid time, or is NULL. + *\li 'expires' points to a valid time, or is NULL. * - * 'interval' points to a valid interval, or is NULL. + *\li 'interval' points to a valid interval, or is NULL. * - * type == isc_timertype_inactive || + *\li type == isc_timertype_inactive || * ('expires' and 'interval' are not both 0) * - * 'timerp' is a valid pointer, and *timerp == NULL + *\li 'timerp' is a valid pointer, and *timerp == NULL * * Ensures: * - * '*timerp' is attached to the newly created timer + *\li '*timerp' is attached to the newly created timer * - * The timer is attached to the task + *\li The timer is attached to the task * - * An idle timeout will not be generated until at least Now + the + *\li An idle timeout will not be generated until at least Now + the * timer's interval if 'timer' is a once timer with a non-zero * interval. * * Returns: * - * Success - * No memory - * Unexpected error + *\li Success + *\li No memory + *\li Unexpected error */ isc_result_t @@ -181,90 +178,91 @@ isc_timer_reset(isc_timer_t *timer, isc_time_t *expires, isc_interval_t *interval, isc_boolean_t purge); -/* +/*%< * Change the timer's type, expires, and interval values to the given * values. If 'purge' is TRUE, any pending events from this timer * are purged from its task's event queue. * * Notes: * - * If 'expires' is NULL, the epoch will be used. + *\li If 'expires' is NULL, the epoch will be used. * - * If 'interval' is NULL, the zero interval will be used. + *\li If 'interval' is NULL, the zero interval will be used. * * Requires: * - * 'timer' is a valid timer + *\li 'timer' is a valid timer * - * The same requirements that isc_timer_create() imposes on 'type', + *\li The same requirements that isc_timer_create() imposes on 'type', * 'expires' and 'interval' apply. * * Ensures: * - * An idle timeout will not be generated until at least Now + the + *\li An idle timeout will not be generated until at least Now + the * timer's interval if 'timer' is a once timer with a non-zero * interval. * * Returns: * - * Success - * No memory - * Unexpected error + *\li Success + *\li No memory + *\li Unexpected error */ isc_result_t isc_timer_touch(isc_timer_t *timer); -/* +/*%< * Set the last-touched time of 'timer' to the current time. * * Requires: * - * 'timer' is a valid once timer. + *\li 'timer' is a valid once timer. * * Ensures: * - * An idle timeout will not be generated until at least Now + the + *\li An idle timeout will not be generated until at least Now + the * timer's interval if 'timer' is a once timer with a non-zero * interval. * * Returns: * - * Success - * Unexpected error + *\li Success + *\li Unexpected error */ void isc_timer_attach(isc_timer_t *timer, isc_timer_t **timerp); -/* +/*%< * Attach *timerp to timer. * * Requires: * - * 'timer' is a valid timer. + *\li 'timer' is a valid timer. * - * 'timerp' points to a NULL timer. + *\li 'timerp' points to a NULL timer. * * Ensures: * - * *timerp is attached to timer. + *\li *timerp is attached to timer. */ void isc_timer_detach(isc_timer_t **timerp); -/* +/*%< * Detach *timerp from its timer. * * Requires: * - * 'timerp' points to a valid timer. + *\li 'timerp' points to a valid timer. * * Ensures: * - * *timerp is NULL. + *\li *timerp is NULL. * - * If '*timerp' is the last reference to the timer, + *\li If '*timerp' is the last reference to the timer, * then: * + *\code * The timer will be shutdown * * The timer will detach from its task @@ -275,6 +273,7 @@ isc_timer_detach(isc_timer_t **timerp); * Therefore, if isc_timer_detach() is called in the context * of the timer's task, it is guaranteed that no more * timer event callbacks will run after the call. + *\endcode */ isc_result_t @@ -282,51 +281,51 @@ isc_timer_gettype(isc_timer_t *timer); isc_result_t isc_timermgr_create(isc_mem_t *mctx, isc_timermgr_t **managerp); -/* +/*%< * Create a timer manager. * * Notes: * - * All memory will be allocated in memory context 'mctx'. + *\li All memory will be allocated in memory context 'mctx'. * * Requires: * - * 'mctx' is a valid memory context. + *\li 'mctx' is a valid memory context. * - * 'managerp' points to a NULL isc_timermgr_t. + *\li 'managerp' points to a NULL isc_timermgr_t. * * Ensures: * - * '*managerp' is a valid isc_timermgr_t. + *\li '*managerp' is a valid isc_timermgr_t. * * Returns: * - * Success - * No memory - * Unexpected error + *\li Success + *\li No memory + *\li Unexpected error */ void isc_timermgr_destroy(isc_timermgr_t **managerp); -/* +/*%< * Destroy a timer manager. * * Notes: * - * This routine blocks until there are no timers left in the manager, + *\li This routine blocks until there are no timers left in the manager, * so if the caller holds any timer references using the manager, it * must detach them before calling isc_timermgr_destroy() or it will * block forever. * * Requires: * - * '*managerp' is a valid isc_timermgr_t. + *\li '*managerp' is a valid isc_timermgr_t. * * Ensures: * - * *managerp == NULL + *\li *managerp == NULL * - * All resources used by the manager have been freed. + *\li All resources used by the manager have been freed. */ void isc_timermgr_poke(isc_timermgr_t *m); diff --git a/lib/isc/include/isc/types.h b/lib/isc/include/isc/types.h index 72638919d7..1872d0555b 100644 --- a/lib/isc/include/isc/types.h +++ b/lib/isc/include/isc/types.h @@ -15,12 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: types.h,v 1.35 2004/03/05 05:11:02 marka Exp $ */ +/* $Id: types.h,v 1.36 2005/04/27 04:57:21 sra Exp $ */ #ifndef ISC_TYPES_H #define ISC_TYPES_H 1 -/* +/*! \file + * \brief * OS-specific types, from the OS-specific include directories. */ #include @@ -37,57 +38,56 @@ */ #include -/*** - *** Core Types. Alphabetized by defined type. - ***/ +/* Core Types. Alphabetized by defined type. */ -typedef struct isc_bitstring isc_bitstring_t; -typedef struct isc_buffer isc_buffer_t; -typedef ISC_LIST(isc_buffer_t) isc_bufferlist_t; -typedef struct isc_constregion isc_constregion_t; -typedef struct isc_consttextregion isc_consttextregion_t; -typedef struct isc_entropy isc_entropy_t; -typedef struct isc_entropysource isc_entropysource_t; -typedef struct isc_event isc_event_t; -typedef ISC_LIST(isc_event_t) isc_eventlist_t; -typedef unsigned int isc_eventtype_t; -typedef isc_uint32_t isc_fsaccess_t; -typedef struct isc_hash isc_hash_t; -typedef struct isc_interface isc_interface_t; -typedef struct isc_interfaceiter isc_interfaceiter_t; -typedef struct isc_interval isc_interval_t; -typedef struct isc_lex isc_lex_t; -typedef struct isc_log isc_log_t; -typedef struct isc_logcategory isc_logcategory_t; -typedef struct isc_logconfig isc_logconfig_t; -typedef struct isc_logmodule isc_logmodule_t; -typedef struct isc_mem isc_mem_t; -typedef struct isc_mempool isc_mempool_t; -typedef struct isc_msgcat isc_msgcat_t; -typedef struct isc_ondestroy isc_ondestroy_t; -typedef struct isc_netaddr isc_netaddr_t; -typedef struct isc_quota isc_quota_t; -typedef struct isc_random isc_random_t; -typedef struct isc_ratelimiter isc_ratelimiter_t; -typedef struct isc_region isc_region_t; -typedef isc_uint64_t isc_resourcevalue_t; -typedef unsigned int isc_result_t; -typedef struct isc_rwlock isc_rwlock_t; -typedef struct isc_sockaddr isc_sockaddr_t; -typedef struct isc_socket isc_socket_t; -typedef struct isc_socketevent isc_socketevent_t; -typedef struct isc_socketmgr isc_socketmgr_t; -typedef struct isc_symtab isc_symtab_t; -typedef struct isc_task isc_task_t; -typedef ISC_LIST(isc_task_t) isc_tasklist_t; -typedef struct isc_taskmgr isc_taskmgr_t; -typedef struct isc_textregion isc_textregion_t; -typedef struct isc_time isc_time_t; -typedef struct isc_timer isc_timer_t; -typedef struct isc_timermgr isc_timermgr_t; +typedef struct isc_bitstring isc_bitstring_t; /*%< Bitstring */ +typedef struct isc_buffer isc_buffer_t; /*%< Buffer */ +typedef ISC_LIST(isc_buffer_t) isc_bufferlist_t; /*%< Buffer List */ +typedef struct isc_constregion isc_constregion_t; /*%< Const region */ +typedef struct isc_consttextregion isc_consttextregion_t; /*%< Const Text Region */ +typedef struct isc_entropy isc_entropy_t; /*%< Entropy */ +typedef struct isc_entropysource isc_entropysource_t; /*%< Entropy Source */ +typedef struct isc_event isc_event_t; /*%< Event */ +typedef ISC_LIST(isc_event_t) isc_eventlist_t; /*%< Event List */ +typedef unsigned int isc_eventtype_t; /*%< Event Type */ +typedef isc_uint32_t isc_fsaccess_t; /*%< FS Access */ +typedef struct isc_hash isc_hash_t; /*%< Hash */ +typedef struct isc_interface isc_interface_t; /*%< Interface */ +typedef struct isc_interfaceiter isc_interfaceiter_t; /*%< Interface Iterator */ +typedef struct isc_interval isc_interval_t; /*%< Interval */ +typedef struct isc_lex isc_lex_t; /*%< Lex */ +typedef struct isc_log isc_log_t; /*%< Log */ +typedef struct isc_logcategory isc_logcategory_t; /*%< Log Category */ +typedef struct isc_logconfig isc_logconfig_t; /*%< Log Configuration */ +typedef struct isc_logmodule isc_logmodule_t; /*%< Log Module */ +typedef struct isc_mem isc_mem_t; /*%< Memory */ +typedef struct isc_mempool isc_mempool_t; /*%< Memory Pool */ +typedef struct isc_msgcat isc_msgcat_t; /*%< Message Catalog */ +typedef struct isc_ondestroy isc_ondestroy_t; /*%< On Destroy */ +typedef struct isc_netaddr isc_netaddr_t; /*%< Net Address */ +typedef struct isc_quota isc_quota_t; /*%< Quota */ +typedef struct isc_random isc_random_t; /*%< Random */ +typedef struct isc_ratelimiter isc_ratelimiter_t; /*%< Rate Limiter */ +typedef struct isc_region isc_region_t; /*%< Region */ +typedef isc_uint64_t isc_resourcevalue_t; /*%< Resource Value */ +typedef unsigned int isc_result_t; /*%< Result */ +typedef struct isc_rwlock isc_rwlock_t; /*%< Read Write Lock */ +typedef struct isc_sockaddr isc_sockaddr_t; /*%< Socket Address */ +typedef struct isc_socket isc_socket_t; /*%< Socket */ +typedef struct isc_socketevent isc_socketevent_t; /*%< Socket Event */ +typedef struct isc_socketmgr isc_socketmgr_t; /*%< Socket Manager */ +typedef struct isc_symtab isc_symtab_t; /*%< Symbol Table */ +typedef struct isc_task isc_task_t; /*%< Task */ +typedef ISC_LIST(isc_task_t) isc_tasklist_t; /*%< Task List */ +typedef struct isc_taskmgr isc_taskmgr_t; /*%< Task Manager */ +typedef struct isc_textregion isc_textregion_t; /*%< Text Region */ +typedef struct isc_time isc_time_t; /*%< Time */ +typedef struct isc_timer isc_timer_t; /*%< Timer */ +typedef struct isc_timermgr isc_timermgr_t; /*%< Timer Manager */ typedef void (*isc_taskaction_t)(isc_task_t *, isc_event_t *); +/*% Resource */ typedef enum { isc_resource_coresize = 1, isc_resource_cputime, diff --git a/lib/isc/include/isc/util.h b/lib/isc/include/isc/util.h index 438a6ce00e..00a50a61e5 100644 --- a/lib/isc/include/isc/util.h +++ b/lib/isc/include/isc/util.h @@ -15,17 +15,18 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: util.h,v 1.24 2004/03/05 05:11:02 marka Exp $ */ +/* $Id: util.h,v 1.25 2005/04/27 04:57:21 sra Exp $ */ #ifndef ISC_UTIL_H #define ISC_UTIL_H 1 -/* +/*! \file util.h * NOTE: * * This file is not to be included from any (or other) library * files. * + * \brief * Including this file puts several macros in your name space that are * not protected (as all the other ISC functions/macros do) by prepending * ISC_ or isc_ to the name. @@ -35,21 +36,22 @@ *** General Macros. ***/ -/* +/*% * Use this to hide unused function arguments. - * + * \code * int * foo(char *bar) * { * UNUSED(bar); * } + * \endcode */ #define UNUSED(x) (void)(x) #define ISC_MAX(a, b) ((a) > (b) ? (a) : (b)) #define ISC_MIN(a, b) ((a) < (b) ? (a) : (b)) -/* +/*% * Use this to remove the const qualifier of a variable to assign it to * a non-const variable or pass it as a non-const function argument ... * but only when you are sure it won't then be changed! @@ -64,16 +66,15 @@ var = _u.v; \ } while (0) -/* +/*% * Use this in translation units that would otherwise be empty, to * suppress compiler warnings. */ #define EMPTY_TRANSLATION_UNIT static void isc__empty(void) { isc__empty(); } -/* +/*% * We use macros instead of calling the routines directly because * the capital letters make the locking stand out. - * * We RUNTIME_CHECK for success since in general there's no way * for us to continue if they fail. */ @@ -203,9 +204,13 @@ */ #include /* Contractual promise. */ +/*% Require Assertion */ #define REQUIRE(e) ISC_REQUIRE(e) +/*% Ensure Assertion */ #define ENSURE(e) ISC_ENSURE(e) +/*% Insist Assertion */ #define INSIST(e) ISC_INSIST(e) +/*% Invariant Assertion */ #define INVARIANT(e) ISC_INVARIANT(e) /* @@ -213,11 +218,14 @@ */ #include /* Contractual promise. */ +/*% Unexpected Error */ #define UNEXPECTED_ERROR isc_error_unexpected +/*% Fatal Error */ #define FATAL_ERROR isc_error_fatal +/*% Runtime Check */ #define RUNTIME_CHECK(cond) ISC_ERROR_RUNTIMECHECK(cond) -/* +/*% * Time */ #define TIME_NOW(tp) RUNTIME_CHECK(isc_time_now((tp)) == ISC_R_SUCCESS) diff --git a/lib/isc/include/isc/version.h b/lib/isc/include/isc/version.h index 7d928cfbf0..742bd00d91 100644 --- a/lib/isc/include/isc/version.h +++ b/lib/isc/include/isc/version.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.h,v 1.3 2004/03/05 05:11:02 marka Exp $ */ +/* $Id: version.h,v 1.4 2005/04/27 04:57:21 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/inet_aton.c b/lib/isc/inet_aton.c index efb078c90b..5ea60abe59 100644 --- a/lib/isc/inet_aton.c +++ b/lib/isc/inet_aton.c @@ -67,10 +67,11 @@ * ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS * SOFTWARE. */ +/*! \file */ #if defined(LIBC_SCCS) && !defined(lint) static char sccsid[] = "@(#)inet_addr.c 8.1 (Berkeley) 6/17/93"; -static char rcsid[] = "$Id: inet_aton.c,v 1.17 2004/03/05 05:10:45 marka Exp $"; +static char rcsid[] = "$Id: inet_aton.c,v 1.18 2005/04/27 04:57:12 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -81,7 +82,7 @@ static char rcsid[] = "$Id: inet_aton.c,v 1.17 2004/03/05 05:10:45 marka Exp $"; #include #include -/* +/*% * Check whether "cp" is a valid ascii representation * of an Internet address and convert to a binary address. * Returns 1 if the address is valid, 0 if not. diff --git a/lib/isc/inet_ntop.c b/lib/isc/inet_ntop.c index 827fd52a28..9d5f1b4c78 100644 --- a/lib/isc/inet_ntop.c +++ b/lib/isc/inet_ntop.c @@ -14,10 +14,11 @@ * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR * PERFORMANCE OF THIS SOFTWARE. */ +/*! \file */ #if defined(LIBC_SCCS) && !defined(lint) static char rcsid[] = - "$Id: inet_ntop.c,v 1.15 2004/08/28 06:16:57 marka Exp $"; + "$Id: inet_ntop.c,v 1.16 2005/04/27 04:57:12 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -45,12 +46,12 @@ static const char *inet_ntop6(const unsigned char *src, char *dst, size_t size); #endif -/* char * +/*! char * * isc_net_ntop(af, src, dst, size) * convert a network format address to presentation format. - * return: + * \return * pointer to presentation format address (`dst'), or NULL (see errno). - * author: + * \author * Paul Vixie, 1996. */ const char * @@ -70,15 +71,16 @@ isc_net_ntop(int af, const void *src, char *dst, size_t size) /* NOTREACHED */ } -/* const char * +/*! const char * * inet_ntop4(src, dst, size) * format an IPv4 address - * return: + * \return * `dst' (as a const) - * notes: + * \note * (1) uses no statics + * \note * (2) takes a unsigned char* not an in_addr as input - * author: + * \author * Paul Vixie, 1996. */ static const char * @@ -97,10 +99,10 @@ inet_ntop4(const unsigned char *src, char *dst, size_t size) return (dst); } -/* const char * +/*! const char * * isc_inet_ntop6(src, dst, size) * convert IPv6 binary address into presentation (printable) format - * author: + * \author * Paul Vixie, 1996. */ #ifdef AF_INET6 diff --git a/lib/isc/inet_pton.c b/lib/isc/inet_pton.c index c758ed9080..ce2e4c5e42 100644 --- a/lib/isc/inet_pton.c +++ b/lib/isc/inet_pton.c @@ -14,10 +14,11 @@ * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR * PERFORMANCE OF THIS SOFTWARE. */ +/*! \file */ #if defined(LIBC_SCCS) && !defined(lint) static char rcsid[] = - "$Id: inet_pton.c,v 1.15 2005/03/31 23:54:45 marka Exp $"; + "$Id: inet_pton.c,v 1.16 2005/04/27 04:57:12 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -27,8 +28,11 @@ static char rcsid[] = #include +/*% INT16 Size */ #define NS_INT16SZ 2 +/*% IPv4 Address Size */ #define NS_INADDRSZ 4 +/*% IPv6 Address Size */ #define NS_IN6ADDRSZ 16 /* @@ -39,15 +43,14 @@ static char rcsid[] = static int inet_pton4(const char *src, unsigned char *dst); static int inet_pton6(const char *src, unsigned char *dst); -/* int - * isc_net_pton(af, src, dst) +/*% * convert from presentation format (which usually means ASCII printable) * to network format (which is usually some kind of binary format). - * return: + * \return * 1 if the address was valid for the specified address family * 0 if the address wasn't valid (`dst' is untouched in this case) * -1 if some other error occurred (`dst' is untouched in this case, too) - * author: + * \author * Paul Vixie, 1996. */ int @@ -64,14 +67,14 @@ isc_net_pton(int af, const char *src, void *dst) { /* NOTREACHED */ } -/* int - * inet_pton4(src, dst) +/*!\fn static int inet_pton4(const char *src, unsigned char *dst) + * \brief * like inet_aton() but without all the hexadecimal and shorthand. - * return: + * \return * 1 if `src' is a valid dotted quad, else 0. - * notice: + * \note * does not touch `dst' unless it's returning 1. - * author: + * \author * Paul Vixie, 1996. */ static int @@ -113,17 +116,17 @@ inet_pton4(const char *src, unsigned char *dst) { return (1); } -/* int - * inet_pton6(src, dst) +/*% * convert presentation level address to network order binary form. - * return: + * \return * 1 if `src' is a valid [RFC1884 2.2] address, else 0. - * notice: + * \note * (1) does not touch `dst' unless it's returning 1. + * \note * (2) :: in a full address is silently ignored. - * credit: + * \author * inspired by Mark Andrews. - * author: + * \author * Paul Vixie, 1996. */ static int diff --git a/lib/isc/lex.c b/lib/isc/lex.c index 337f609550..ea5d3d10ec 100644 --- a/lib/isc/lex.c +++ b/lib/isc/lex.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lex.c,v 1.79 2004/08/28 06:16:57 marka Exp $ */ +/* $Id: lex.c,v 1.80 2005/04/27 04:57:12 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/lfsr.c b/lib/isc/lfsr.c index 10446b63ae..c7810b91f9 100644 --- a/lib/isc/lfsr.c +++ b/lib/isc/lfsr.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lfsr.c,v 1.14 2004/03/05 05:10:46 marka Exp $ */ +/* $Id: lfsr.c,v 1.15 2005/04/27 04:57:13 sra Exp $ */ + +/*! \file */ #include @@ -49,7 +51,7 @@ isc_lfsr_init(isc_lfsr_t *lfsr, isc_uint32_t state, unsigned int bits, lfsr->state = 0xffffffffU >> (32 - lfsr->bits); } -/* +/*! * Return the next state of the lfsr. */ static inline isc_uint32_t diff --git a/lib/isc/lib.c b/lib/isc/lib.c index 3a18e5c4d3..3e60b38ccf 100644 --- a/lib/isc/lib.c +++ b/lib/isc/lib.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lib.c,v 1.10 2004/03/05 05:10:46 marka Exp $ */ +/* $Id: lib.c,v 1.11 2005/04/27 04:57:13 sra Exp $ */ + +/*! \file */ #include @@ -53,7 +55,7 @@ void isc_lib_initmsgcat(void) { isc_result_t result; - /* + /*! * Initialize the ISC library's message catalog, isc_msgcat, if it * has not already been initialized. */ diff --git a/lib/isc/log.c b/lib/isc/log.c index 031ade33c5..4eda8c7b4f 100644 --- a/lib/isc/log.c +++ b/lib/isc/log.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: log.c,v 1.87 2004/06/11 00:36:30 marka Exp $ */ +/* $Id: log.c,v 1.88 2005/04/27 04:57:13 sra Exp $ */ -/* Principal Authors: DCL */ +/*! \file + * \author Principal Authors: DCL */ #include @@ -56,7 +57,7 @@ #define PATH_MAX 1024 /* AIX and others don't define this. */ #endif -/* +/*! * This is the structure that holds each named channel. A simple linked * list chains all of the channels together, so an individual channel is * found by doing strcmp()s with the names down the list. Their should @@ -76,7 +77,7 @@ struct isc_logchannel { ISC_LINK(isc_logchannel_t) link; }; -/* +/*! * The logchannellist structure associates categories and modules with * channels. First the appropriate channellist is found based on the * category, and then each structure in the linked list is checked for @@ -92,7 +93,7 @@ struct isc_logchannellist { ISC_LINK(isc_logchannellist_t) link; }; -/* +/*! * This structure is used to remember messages for pruning via * isc_log_[v]write1(). */ @@ -104,7 +105,7 @@ struct isc_logmessage { ISC_LINK(isc_logmessage_t) link; }; -/* +/*! * The isc_logconfig structure is used to store the configurable information * about where messages are actually supposed to be sent -- the information * that could changed based on some configuration file, as opposed to the @@ -123,7 +124,7 @@ struct isc_logconfig { isc_boolean_t dynamic; }; -/* +/*! * This isc_log structure provides the context for the isc_log functions. * The log context locks itself in isc_log_doit, the internal backend to * isc_log_write. The locking is necessary both to provide exclusive access @@ -156,7 +157,7 @@ struct isc_log { ISC_LIST(isc_logmessage_t) messages; }; -/* +/*! * Used when ISC_LOG_PRINTLEVEL is enabled for a channel. */ static const char *log_level_strings[] = { @@ -168,7 +169,7 @@ static const char *log_level_strings[] = { "critical" }; -/* +/*! * Used to convert ISC_LOG_* priorities into syslog priorities. * XXXDCL This will need modification for NT. */ @@ -181,7 +182,7 @@ static const int syslog_map[] = { LOG_CRIT }; -/* +/*! * When adding new categories, a corresponding ISC_LOGCATEGORY_foo * definition needs to be added to . * @@ -195,8 +196,8 @@ LIBISC_EXTERNAL_DATA isc_logcategory_t isc_categories[] = { { NULL, 0 } }; -/* - * See above comment for categories, and apply it to modules. +/*! + * See above comment for categories on LIBISC_EXTERNAL_DATA, and apply it to modules. */ LIBISC_EXTERNAL_DATA isc_logmodule_t isc_modules[] = { { "socket", 0 }, @@ -206,19 +207,19 @@ LIBISC_EXTERNAL_DATA isc_logmodule_t isc_modules[] = { { NULL, 0 } }; -/* +/*! * This essentially constant structure must be filled in at run time, * because its channel member is pointed to a channel that is created * dynamically with isc_log_createchannel. */ static isc_logchannellist_t default_channel; -/* +/*! * libisc logs to this context. */ LIBISC_EXTERNAL_DATA isc_log_t *isc_lctx = NULL; -/* +/*! * Forward declarations. */ static isc_result_t @@ -241,7 +242,8 @@ isc_log_doit(isc_log_t *lctx, isc_logcategory_t *category, const char *format, va_list args) ISC_FORMAT_PRINTF(9, 0); -/* +/*@{*/ +/*! * Convenience macros. */ @@ -252,6 +254,7 @@ isc_log_doit(isc_log_t *lctx, isc_logcategory_t *category, #define FILE_MAXSIZE(channel) (channel->destination.file.maximum_size) #define FILE_MAXREACHED(channel) (channel->destination.file.maximum_reached) +/*@}*/ /**** **** Public interfaces. ****/ diff --git a/lib/isc/md5.c b/lib/isc/md5.c index a67237c377..a9454297b7 100644 --- a/lib/isc/md5.c +++ b/lib/isc/md5.c @@ -15,9 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: md5.c,v 1.10 2004/03/05 05:10:46 marka Exp $ */ +/* $Id: md5.c,v 1.11 2005/04/27 04:57:13 sra Exp $ */ -/* +/*! \file * This code implements the MD5 message-digest algorithm. * The algorithm is due to Ron Rivest. This code was * written by Colin Plumb in 1993, no copyright is claimed. @@ -54,7 +54,7 @@ byteSwap(isc_uint32_t *buf, unsigned words) } while (--words); } -/* +/*! * Start MD5 accumulation. Set bit count to 0 and buffer to mysterious * initialization constants. */ @@ -74,19 +74,21 @@ isc_md5_invalidate(isc_md5_t *ctx) { memset(ctx, 0, sizeof(isc_md5_t)); } -/* The four core functions - F1 is optimized somewhat */ +/*@{*/ +/*! The four core functions - F1 is optimized somewhat */ /* #define F1(x, y, z) (x & y | ~x & z) */ #define F1(x, y, z) (z ^ (x & (y ^ z))) #define F2(x, y, z) F1(z, x, y) #define F3(x, y, z) (x ^ y ^ z) #define F4(x, y, z) (y ^ (x | ~z)) +/*@}*/ -/* This is the central step in the MD5 algorithm. */ +/*! This is the central step in the MD5 algorithm. */ #define MD5STEP(f,w,x,y,z,in,s) \ (w += f(x,y,z) + in, w = (w<>(32-s)) + x) -/* +/*! * The core of the MD5 algorithm, this alters an existing MD5 hash to * reflect the addition of 16 longwords of new data. MD5Update blocks * the data and converts bytes into longwords for this routine. @@ -174,7 +176,7 @@ transform(isc_uint32_t buf[4], isc_uint32_t const in[16]) { buf[3] += d; } -/* +/*! * Update context to reflect the concatenation of another buffer full * of bytes. */ @@ -213,7 +215,7 @@ isc_md5_update(isc_md5_t *ctx, const unsigned char *buf, unsigned int len) { memcpy(ctx->in, buf, len); } -/* +/*! * Final wrapup - pad to 64-byte boundary with the bit pattern * 1 0* (64-bit count of bits processed, MSB-first) */ diff --git a/lib/isc/mem.c b/lib/isc/mem.c index 20337a3e9d..dac37f10ef 100644 --- a/lib/isc/mem.c +++ b/lib/isc/mem.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: mem.c,v 1.118 2005/03/16 00:55:19 marka Exp $ */ +/* $Id: mem.c,v 1.119 2005/04/27 04:57:13 sra Exp $ */ + +/*! \file */ #include @@ -39,7 +41,7 @@ #endif LIBISC_EXTERNAL_DATA unsigned int isc_mem_debugging = ISC_MEM_DEBUGGING; -/* +/*! * Define ISC_MEM_USE_INTERNAL_MALLOC=1 to use the internal malloc() * implementation in preference to the system one. The internal malloc() * is very space-efficient, and quite fast on uniprocessor systems. It @@ -55,8 +57,8 @@ LIBISC_EXTERNAL_DATA unsigned int isc_mem_debugging = ISC_MEM_DEBUGGING; #define DEF_MAX_SIZE 1100 #define DEF_MEM_TARGET 4096 -#define ALIGNMENT_SIZE 8 /* must be a power of 2 */ -#define NUM_BASIC_BLOCKS 64 /* must be > 1 */ +#define ALIGNMENT_SIZE 8 /*%< must be a power of 2 */ +#define NUM_BASIC_BLOCKS 64 /*%< must be > 1 */ #define TABLE_INCREMENT 1024 #define DEBUGLIST_COUNT 1024 @@ -87,7 +89,7 @@ struct element { }; typedef struct { - /* + /*! * This structure must be ALIGNMENT_SIZE bytes. */ union { @@ -157,24 +159,24 @@ struct isc_mem { struct isc_mempool { /* always unlocked */ - unsigned int magic; /* magic number */ - isc_mutex_t *lock; /* optional lock */ - isc_mem_t *mctx; /* our memory context */ - /* locked via the memory context's lock */ - ISC_LINK(isc_mempool_t) link; /* next pool in this mem context */ - /* optionally locked from here down */ - element *items; /* low water item list */ - size_t size; /* size of each item on this pool */ - unsigned int maxalloc; /* max number of items allowed */ - unsigned int allocated; /* # of items currently given out */ - unsigned int freecount; /* # of items on reserved list */ - unsigned int freemax; /* # of items allowed on free list */ - unsigned int fillcount; /* # of items to fetch on each fill */ - /* Stats only. */ - unsigned int gets; /* # of requests to this pool */ - /* Debugging only. */ + unsigned int magic; /*%< magic number */ + isc_mutex_t *lock; /*%< optional lock */ + isc_mem_t *mctx; /*%< our memory context */ + /*%< locked via the memory context's lock */ + ISC_LINK(isc_mempool_t) link; /*%< next pool in this mem context */ + /*%< optionally locked from here down */ + element *items; /*%< low water item list */ + size_t size; /*%< size of each item on this pool */ + unsigned int maxalloc; /*%< max number of items allowed */ + unsigned int allocated; /*%< # of items currently given out */ + unsigned int freecount; /*%< # of items on reserved list */ + unsigned int freemax; /*%< # of items allowed on free list */ + unsigned int fillcount; /*%< # of items to fetch on each fill */ + /*%< Stats only. */ + unsigned int gets; /*%< # of requests to this pool */ + /*%< Debugging only. */ #if ISC_MEMPOOL_NAMES - char name[16]; /* printed name in stats reports */ + char name[16]; /*%< printed name in stats reports */ #endif }; @@ -198,7 +200,7 @@ struct isc_mempool { static void print_active(isc_mem_t *ctx, FILE *out); -/* +/*! * mctx must be locked. */ static inline void @@ -320,7 +322,7 @@ rmsize(size_t size) { static inline size_t quantize(size_t size) { - /* + /*! * Round up the result in order to get a size big * enough to satisfy the request and be aligned on ALIGNMENT_SIZE * byte boundaries. @@ -408,7 +410,7 @@ more_frags(isc_mem_t *ctx, size_t new_size) { void *new; unsigned char *curr, *next; - /* + /*! * Try to get more fragments by chopping up a basic block. */ @@ -591,7 +593,7 @@ mem_putunlocked(isc_mem_t *ctx, void *mem, size_t size) { #else /* ISC_MEM_USE_INTERNAL_MALLOC */ -/* +/*! * Perform a malloc, doing memory filling and overrun detection as necessary. */ static inline void * @@ -619,7 +621,7 @@ mem_get(isc_mem_t *ctx, size_t size) { return (ret); } -/* +/*! * Perform a free, doing memory filling and overrun detection as necessary. */ static inline void @@ -635,7 +637,7 @@ mem_put(isc_mem_t *ctx, void *mem, size_t size) { (ctx->memfree)(ctx->arg, mem); } -/* +/*! * Update internal counters after a memory get. */ static inline void @@ -652,7 +654,7 @@ mem_getstats(isc_mem_t *ctx, size_t size) { } } -/* +/*! * Update internal counters after a memory put. */ static inline void diff --git a/lib/isc/mutexblock.c b/lib/isc/mutexblock.c index e3f122787b..2e00a45a59 100644 --- a/lib/isc/mutexblock.c +++ b/lib/isc/mutexblock.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: mutexblock.c,v 1.16 2004/03/05 05:10:47 marka Exp $ */ +/* $Id: mutexblock.c,v 1.17 2005/04/27 04:57:13 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/netaddr.c b/lib/isc/netaddr.c index 99f7a2f334..f92dd035fb 100644 --- a/lib/isc/netaddr.c +++ b/lib/isc/netaddr.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: netaddr.c,v 1.34 2005/03/16 23:39:05 marka Exp $ */ +/* $Id: netaddr.c,v 1.35 2005/04/27 04:57:13 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/netscope.c b/lib/isc/netscope.c index 701999077d..6b8db25844 100644 --- a/lib/isc/netscope.c +++ b/lib/isc/netscope.c @@ -14,10 +14,11 @@ * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR * PERFORMANCE OF THIS SOFTWARE. */ +/*! \file */ #if defined(LIBC_SCCS) && !defined(lint) static char rcsid[] = - "$Id: netscope.c,v 1.7 2004/03/16 05:52:20 marka Exp $"; + "$Id: netscope.c,v 1.8 2005/04/27 04:57:13 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include diff --git a/lib/isc/nls/msgcat.c b/lib/isc/nls/msgcat.c index 2f1ab30670..635afce03b 100644 --- a/lib/isc/nls/msgcat.c +++ b/lib/isc/nls/msgcat.c @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: msgcat.c,v 1.13 2004/03/05 05:11:06 marka Exp $ */ +/* $Id: msgcat.c,v 1.14 2005/04/27 04:57:22 sra Exp $ */ -/* - * Principal Author: Bob Halley +/*! \file msgcat.c + * + * \author Principal Author: Bob Halley */ #include diff --git a/lib/isc/ondestroy.c b/lib/isc/ondestroy.c index e0836ef11a..684e7a7262 100644 --- a/lib/isc/ondestroy.c +++ b/lib/isc/ondestroy.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ondestroy.c,v 1.12 2004/03/05 05:10:47 marka Exp $ */ +/* $Id: ondestroy.c,v 1.13 2005/04/27 04:57:13 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/parseint.c b/lib/isc/parseint.c index 1d8518bd4e..9ceba957e7 100644 --- a/lib/isc/parseint.c +++ b/lib/isc/parseint.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: parseint.c,v 1.4 2004/03/05 05:10:48 marka Exp $ */ +/* $Id: parseint.c,v 1.5 2005/04/27 04:57:14 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/print.c b/lib/isc/print.c index a4406ebc55..8707d0b3bf 100644 --- a/lib/isc/print.c +++ b/lib/isc/print.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: print.c,v 1.27 2004/03/05 05:10:48 marka Exp $ */ +/* $Id: print.c,v 1.28 2005/04/27 04:57:14 sra Exp $ */ + +/*! \file */ #include @@ -41,7 +43,7 @@ isc_print_sprintf(char *str, const char *format, ...) { return (strlen(str)); } -/* +/*! * Return length of string that would have been written if not truncated. */ @@ -57,7 +59,7 @@ isc_print_snprintf(char *str, size_t size, const char *format, ...) { } -/* +/*! * Return length of string that would have been written if not truncated. */ diff --git a/lib/isc/pthreads/condition.c b/lib/isc/pthreads/condition.c index 1a5b9327dd..856b0155da 100644 --- a/lib/isc/pthreads/condition.c +++ b/lib/isc/pthreads/condition.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: condition.c,v 1.32 2004/03/05 05:11:16 marka Exp $ */ +/* $Id: condition.c,v 1.33 2005/04/27 04:57:22 sra Exp $ */ + +/*! \file */ #include @@ -44,7 +46,7 @@ isc_condition_waituntil(isc_condition_t *c, isc_mutex_t *m, isc_time_t *t) { if (result != ISC_R_SUCCESS) return (result); - /* + /*! * POSIX defines a timespec's tv_nsec as long. isc_time_nanoseconds * ensures its return value is < 1 billion, which will fit in a long. */ diff --git a/lib/isc/pthreads/include/isc/condition.h b/lib/isc/pthreads/include/isc/condition.h index 8676e42309..fdfbf341c6 100644 --- a/lib/isc/pthreads/include/isc/condition.h +++ b/lib/isc/pthreads/include/isc/condition.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: condition.h,v 1.22 2004/03/05 05:11:40 marka Exp $ */ +/* $Id: condition.h,v 1.23 2005/04/27 04:57:22 sra Exp $ */ #ifndef ISC_CONDITION_H #define ISC_CONDITION_H 1 +/*! \file */ + #include #include #include diff --git a/lib/isc/pthreads/include/isc/mutex.h b/lib/isc/pthreads/include/isc/mutex.h index 5fb0eb49e5..8350e495ea 100644 --- a/lib/isc/pthreads/include/isc/mutex.h +++ b/lib/isc/pthreads/include/isc/mutex.h @@ -15,17 +15,19 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: mutex.h,v 1.25 2004/03/05 05:11:41 marka Exp $ */ +/* $Id: mutex.h,v 1.26 2005/04/27 04:57:22 sra Exp $ */ #ifndef ISC_MUTEX_H #define ISC_MUTEX_H 1 +/*! \file */ + #include #include #include /* for ISC_R_ codes */ -/* +/*! * Supply mutex attributes that enable deadlock detection * (helpful when debugging). This is system dependent and * currently only supported on NetBSD. @@ -39,7 +41,7 @@ extern pthread_mutexattr_t isc__mutex_attrs; /* XXX We could do fancier error handling... */ -/* +/*! * Define ISC_MUTEX_PROFILE to turn on profiling of mutexes by line. When * enabled, isc_mutex_stats() can be used to print a table showing the * number of times each type of mutex was locked and the amount of time @@ -53,8 +55,8 @@ extern pthread_mutexattr_t isc__mutex_attrs; typedef struct isc_mutexstats isc_mutexstats_t; typedef struct { - pthread_mutex_t mutex; /* The actual mutex. */ - isc_mutexstats_t * stats; /* Mutex statistics. */ + pthread_mutex_t mutex; /*%< The actual mutex. */ + isc_mutexstats_t * stats; /*%< Mutex statistics. */ } isc_mutex_t; #else typedef pthread_mutex_t isc_mutex_t; diff --git a/lib/isc/pthreads/include/isc/once.h b/lib/isc/pthreads/include/isc/once.h index 45bf56ffc4..f5f69e1ada 100644 --- a/lib/isc/pthreads/include/isc/once.h +++ b/lib/isc/pthreads/include/isc/once.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: once.h,v 1.9 2004/03/05 05:11:41 marka Exp $ */ +/* $Id: once.h,v 1.10 2005/04/27 04:57:22 sra Exp $ */ #ifndef ISC_ONCE_H #define ISC_ONCE_H 1 +/*! \file */ + #include #include @@ -28,12 +30,12 @@ typedef pthread_once_t isc_once_t; #ifdef ISC_PLATFORM_BRACEPTHREADONCEINIT -/* +/*! * This accomodates systems that define PTHRAD_ONCE_INIT improperly. */ #define ISC_ONCE_INIT { PTHREAD_ONCE_INIT } #else -/* +/*! * This is the usual case. */ #define ISC_ONCE_INIT PTHREAD_ONCE_INIT diff --git a/lib/isc/pthreads/include/isc/thread.h b/lib/isc/pthreads/include/isc/thread.h index ab1d0e5cbb..ea0b2c1bc6 100644 --- a/lib/isc/pthreads/include/isc/thread.h +++ b/lib/isc/pthreads/include/isc/thread.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: thread.h,v 1.20 2004/03/05 05:11:41 marka Exp $ */ +/* $Id: thread.h,v 1.21 2005/04/27 04:57:22 sra Exp $ */ #ifndef ISC_THREAD_H #define ISC_THREAD_H 1 +/*! \file */ + #include #include diff --git a/lib/isc/pthreads/mutex.c b/lib/isc/pthreads/mutex.c index 40ea201de8..3c830cbf84 100644 --- a/lib/isc/pthreads/mutex.c +++ b/lib/isc/pthreads/mutex.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: mutex.c,v 1.10 2005/03/17 03:56:12 marka Exp $ */ +/* $Id: mutex.c,v 1.11 2005/04/27 04:57:22 sra Exp $ */ + +/*! \file */ #include @@ -28,7 +30,8 @@ #if ISC_MUTEX_PROFILE -/* Operations on timevals; adapted from FreeBSD's sys/time.h */ +/*@{*/ +/*% Operations on timevals; adapted from FreeBSD's sys/time.h */ #define timevalclear(tvp) ((tvp)->tv_sec = (tvp)->tv_usec = 0) #define timevaladd(vvp, uvp) \ do { \ @@ -49,6 +52,8 @@ } \ } while (0) +/*@}*/ + #define ISC_MUTEX_MAX_LOCKERS 32 typedef struct { @@ -60,8 +65,8 @@ typedef struct { } isc_mutexlocker_t; struct isc_mutexstats { - const char * file; /* File mutex was created in. */ - int line; /* Line mutex was created on. */ + const char * file; /*%< File mutex was created in. */ + int line; /*%< Line mutex was created on. */ unsigned count; struct timeval lock_t; struct timeval locked_total; diff --git a/lib/isc/pthreads/thread.c b/lib/isc/pthreads/thread.c index d5a1533c62..adc08aa063 100644 --- a/lib/isc/pthreads/thread.c +++ b/lib/isc/pthreads/thread.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: thread.c,v 1.13 2004/12/04 06:47:03 marka Exp $ */ +/* $Id: thread.c,v 1.14 2005/04/27 04:57:22 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/quota.c b/lib/isc/quota.c index 971be2a354..3bc599d2f3 100644 --- a/lib/isc/quota.c +++ b/lib/isc/quota.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: quota.c,v 1.13 2004/03/05 05:10:48 marka Exp $ */ +/* $Id: quota.c,v 1.14 2005/04/27 04:57:14 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/random.c b/lib/isc/random.c index e4f68b211c..a1ecc89f5f 100644 --- a/lib/isc/random.c +++ b/lib/isc/random.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: random.c,v 1.21 2004/03/05 05:10:48 marka Exp $ */ +/* $Id: random.c,v 1.22 2005/04/27 04:57:14 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/ratelimiter.c b/lib/isc/ratelimiter.c index 6843b17183..4f33d59e7e 100644 --- a/lib/isc/ratelimiter.c +++ b/lib/isc/ratelimiter.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ratelimiter.c,v 1.21 2004/03/05 05:10:48 marka Exp $ */ +/* $Id: ratelimiter.c,v 1.22 2005/04/27 04:57:14 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/region.c b/lib/isc/region.c index 524532d807..8805c2d6ff 100644 --- a/lib/isc/region.c +++ b/lib/isc/region.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: region.c,v 1.3 2004/03/05 05:10:48 marka Exp $ */ +/* $Id: region.c,v 1.4 2005/04/27 04:57:14 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/result.c b/lib/isc/result.c index aa47d32580..7121b07e5d 100644 --- a/lib/isc/result.c +++ b/lib/isc/result.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: result.c,v 1.64 2004/06/11 00:27:02 marka Exp $ */ +/* $Id: result.c,v 1.65 2005/04/27 04:57:14 sra Exp $ */ + +/*! \file */ #include @@ -38,66 +40,66 @@ typedef struct resulttable { } resulttable; static const char *text[ISC_R_NRESULTS] = { - "success", /* 0 */ - "out of memory", /* 1 */ - "timed out", /* 2 */ - "no available threads", /* 3 */ - "address not available", /* 4 */ - "address in use", /* 5 */ - "permission denied", /* 6 */ - "no pending connections", /* 7 */ - "network unreachable", /* 8 */ - "host unreachable", /* 9 */ - "network down", /* 10 */ - "host down", /* 11 */ - "connection refused", /* 12 */ - "not enough free resources", /* 13 */ - "end of file", /* 14 */ - "socket already bound", /* 15 */ - "reload", /* 16 */ - "lock busy", /* 17 */ - "already exists", /* 18 */ - "ran out of space", /* 19 */ - "operation canceled", /* 20 */ - "socket is not bound", /* 21 */ - "shutting down", /* 22 */ - "not found", /* 23 */ - "unexpected end of input", /* 24 */ - "failure", /* 25 */ - "I/O error", /* 26 */ - "not implemented", /* 27 */ - "unbalanced parentheses", /* 28 */ - "no more", /* 29 */ - "invalid file", /* 30 */ - "bad base64 encoding", /* 31 */ - "unexpected token", /* 32 */ - "quota reached", /* 33 */ - "unexpected error", /* 34 */ - "already running", /* 35 */ - "ignore", /* 36 */ - "address mask not contiguous", /* 37 */ - "file not found", /* 38 */ - "file already exists", /* 39 */ - "socket is not connected", /* 40 */ - "out of range", /* 41 */ - "out of entropy", /* 42 */ - "invalid use of multicast address", /* 43 */ - "not a file", /* 44 */ - "not a directory", /* 45 */ - "queue is full", /* 46 */ - "address family mismatch", /* 47 */ - "address family not supported", /* 48 */ - "bad hex encoding", /* 49 */ - "too many open files", /* 50 */ - "not blocking", /* 51 */ - "unbalanced quotes", /* 52 */ - "operation in progress", /* 53 */ - "connection reset", /* 54 */ - "soft quota reached", /* 55 */ - "not a valid number", /* 56 */ - "disabled", /* 57 */ - "max size", /* 58 */ - "invalid address format" /* 59 */ + "success", /*%< 0 */ + "out of memory", /*%< 1 */ + "timed out", /*%< 2 */ + "no available threads", /*%< 3 */ + "address not available", /*%< 4 */ + "address in use", /*%< 5 */ + "permission denied", /*%< 6 */ + "no pending connections", /*%< 7 */ + "network unreachable", /*%< 8 */ + "host unreachable", /*%< 9 */ + "network down", /*%< 10 */ + "host down", /*%< 11 */ + "connection refused", /*%< 12 */ + "not enough free resources", /*%< 13 */ + "end of file", /*%< 14 */ + "socket already bound", /*%< 15 */ + "reload", /*%< 16 */ + "lock busy", /*%< 17 */ + "already exists", /*%< 18 */ + "ran out of space", /*%< 19 */ + "operation canceled", /*%< 20 */ + "socket is not bound", /*%< 21 */ + "shutting down", /*%< 22 */ + "not found", /*%< 23 */ + "unexpected end of input", /*%< 24 */ + "failure", /*%< 25 */ + "I/O error", /*%< 26 */ + "not implemented", /*%< 27 */ + "unbalanced parentheses", /*%< 28 */ + "no more", /*%< 29 */ + "invalid file", /*%< 30 */ + "bad base64 encoding", /*%< 31 */ + "unexpected token", /*%< 32 */ + "quota reached", /*%< 33 */ + "unexpected error", /*%< 34 */ + "already running", /*%< 35 */ + "ignore", /*%< 36 */ + "address mask not contiguous", /*%< 37 */ + "file not found", /*%< 38 */ + "file already exists", /*%< 39 */ + "socket is not connected", /*%< 40 */ + "out of range", /*%< 41 */ + "out of entropy", /*%< 42 */ + "invalid use of multicast address", /*%< 43 */ + "not a file", /*%< 44 */ + "not a directory", /*%< 45 */ + "queue is full", /*%< 46 */ + "address family mismatch", /*%< 47 */ + "address family not supported", /*%< 48 */ + "bad hex encoding", /*%< 49 */ + "too many open files", /*%< 50 */ + "not blocking", /*%< 51 */ + "unbalanced quotes", /*%< 52 */ + "operation in progress", /*%< 53 */ + "connection reset", /*%< 54 */ + "soft quota reached", /*%< 55 */ + "not a valid number", /*%< 56 */ + "disabled", /*%< 57 */ + "max size", /*%< 58 */ + "invalid address format" /*%< 59 */ }; #define ISC_RESULT_RESULTSET 2 diff --git a/lib/isc/rwlock.c b/lib/isc/rwlock.c index 3e21e9fc6c..3e6fd2f261 100644 --- a/lib/isc/rwlock.c +++ b/lib/isc/rwlock.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: rwlock.c,v 1.39 2005/03/16 00:55:19 marka Exp $ */ +/* $Id: rwlock.c,v 1.40 2005/04/27 04:57:14 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/serial.c b/lib/isc/serial.c index 8aca0c024c..0434e49513 100644 --- a/lib/isc/serial.c +++ b/lib/isc/serial.c @@ -15,7 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: serial.c,v 1.8 2004/03/05 05:10:49 marka Exp $ */ +/* $Id: serial.c,v 1.9 2005/04/27 04:57:14 sra Exp $ */ + +/*! \file */ + #include #include diff --git a/lib/isc/sha1.c b/lib/isc/sha1.c index 50a17dea48..7629b0c340 100644 --- a/lib/isc/sha1.c +++ b/lib/isc/sha1.c @@ -15,16 +15,16 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sha1.c,v 1.14 2004/03/05 05:10:49 marka Exp $ */ +/* $Id: sha1.c,v 1.15 2005/04/27 04:57:14 sra Exp $ */ /* $NetBSD: sha1.c,v 1.5 2000/01/22 22:19:14 mycroft Exp $ */ /* $OpenBSD: sha1.c,v 1.9 1997/07/23 21:12:32 kstailey Exp $ */ -/* +/*! \file * SHA-1 in C - * By Steve Reid + * \author By Steve Reid * 100% Public Domain - * + * \verbatim * Test Vectors (from FIPS PUB 180-1) * "abc" * A9993E36 4706816A BA3E2571 7850C26C 9CD0D89D @@ -32,6 +32,7 @@ * 84983E44 1C3BD26E BAAE4AA1 F95129E5 E54670F1 * A million repetitions of "a" * 34AA973C D4C4DAA4 F61EEB2B DBAD2731 6534016F + * \endverbatim */ #include "config.h" @@ -44,7 +45,8 @@ #define rol(value, bits) (((value) << (bits)) | ((value) >> (32 - (bits)))) -/* +/*@{*/ +/*! * blk0() and blk() perform the initial expand. * I got the idea of expanding during the round function from SSLeay */ @@ -61,7 +63,9 @@ ^ block->l[(i + 2) & 15] \ ^ block->l[i & 15], 1)) -/* +/*@}*/ +/*@{*/ +/*! * (R0+R1), R2, R3, R4 are the different operations (rounds) used in SHA1 */ #define R0(v,w,x,y,z,i) \ @@ -80,6 +84,8 @@ z += (w ^ x ^ y) + blk(i) + 0xCA62C1D6 + rol(v, 5); \ w = rol(w, 30); +/*@}*/ + typedef union { unsigned char c[64]; unsigned int l[16]; @@ -154,7 +160,7 @@ do_R4(isc_uint32_t *a, isc_uint32_t *b, isc_uint32_t *c, isc_uint32_t *d, } #endif -/* +/*! * Hash a single 512-bit block. This is the core of the algorithm. */ static void @@ -217,7 +223,7 @@ transform(isc_uint32_t state[5], const unsigned char buffer[64]) { } -/* +/*! * isc_sha1_init - Initialize new context */ void @@ -240,7 +246,7 @@ isc_sha1_invalidate(isc_sha1_t *context) { memset(context, 0, sizeof(isc_sha1_t)); } -/* +/*! * Run your data through this. */ void @@ -270,7 +276,7 @@ isc_sha1_update(isc_sha1_t *context, const unsigned char *data, } -/* +/*! * Add padding and return the message digest. */ diff --git a/lib/isc/sockaddr.c b/lib/isc/sockaddr.c index 51e24f8002..c4fb408ca0 100644 --- a/lib/isc/sockaddr.c +++ b/lib/isc/sockaddr.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sockaddr.c,v 1.64 2005/03/16 23:39:05 marka Exp $ */ +/* $Id: sockaddr.c,v 1.65 2005/04/27 04:57:15 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/string.c b/lib/isc/string.c index 8895a8e143..98c4175946 100644 --- a/lib/isc/string.c +++ b/lib/isc/string.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: string.c,v 1.11 2004/09/16 01:01:26 marka Exp $ */ +/* $Id: string.c,v 1.12 2005/04/27 04:57:15 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/strtoul.c b/lib/isc/strtoul.c index f4f47c2d2f..f692fe1841 100644 --- a/lib/isc/strtoul.c +++ b/lib/isc/strtoul.c @@ -48,11 +48,12 @@ * SUCH DAMAGE. */ +/*! \file */ #if defined(LIBC_SCCS) && !defined(lint) static char sccsid[] = "@(#)strtoul.c 8.1 (Berkeley) 6/4/93"; #endif /* LIBC_SCCS and not lint */ -/* $Id: strtoul.c,v 1.3 2004/03/05 05:10:49 marka Exp $ */ +/* $Id: strtoul.c,v 1.4 2005/04/27 04:57:15 sra Exp $ */ #include @@ -63,7 +64,7 @@ static char sccsid[] = "@(#)strtoul.c 8.1 (Berkeley) 6/4/93"; #include #include -/* +/*! * Convert a string to an unsigned long integer. * * Ignores `locale' stuff. Assumes that the upper and lower case diff --git a/lib/isc/symtab.c b/lib/isc/symtab.c index 0679473755..39b122e35a 100644 --- a/lib/isc/symtab.c +++ b/lib/isc/symtab.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: symtab.c,v 1.26 2004/03/05 05:10:49 marka Exp $ */ +/* $Id: symtab.c,v 1.27 2005/04/27 04:57:15 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/task.c b/lib/isc/task.c index 44f77b69f6..801834ea83 100644 --- a/lib/isc/task.c +++ b/lib/isc/task.c @@ -15,10 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: task.c,v 1.92 2004/10/15 00:45:34 marka Exp $ */ +/* $Id: task.c,v 1.93 2005/04/27 04:57:15 sra Exp $ */ -/* - * Principal Author: Bob Halley +/*! \file + * \author Principal Author: Bob Halley */ /* diff --git a/lib/isc/task_p.h b/lib/isc/task_p.h index 6d792bff17..b8efb4e393 100644 --- a/lib/isc/task_p.h +++ b/lib/isc/task_p.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: task_p.h,v 1.7 2004/03/05 05:10:50 marka Exp $ */ +/* $Id: task_p.h,v 1.8 2005/04/27 04:57:15 sra Exp $ */ #ifndef ISC_TASK_P_H #define ISC_TASK_P_H +/*! \file */ + isc_boolean_t isc__taskmgr_ready(void); diff --git a/lib/isc/taskpool.c b/lib/isc/taskpool.c index db99ad63fc..7b1509e13e 100644 --- a/lib/isc/taskpool.c +++ b/lib/isc/taskpool.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: taskpool.c,v 1.12 2004/03/05 05:10:50 marka Exp $ */ +/* $Id: taskpool.c,v 1.13 2005/04/27 04:57:15 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/timer.c b/lib/isc/timer.c index 8520e1950d..f489790a71 100644 --- a/lib/isc/timer.c +++ b/lib/isc/timer.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: timer.c,v 1.73 2004/03/05 05:10:50 marka Exp $ */ +/* $Id: timer.c,v 1.74 2005/04/27 04:57:15 sra Exp $ */ + +/*! \file */ #include @@ -57,14 +59,14 @@ #define VALID_TIMER(t) ISC_MAGIC_VALID(t, TIMER_MAGIC) struct isc_timer { - /* Not locked. */ + /*! Not locked. */ unsigned int magic; isc_timermgr_t * manager; isc_mutex_t lock; - /* Locked by timer lock. */ + /*! Locked by timer lock. */ unsigned int references; isc_time_t idle; - /* Locked by manager lock. */ + /*! Locked by manager lock. */ isc_timertype_t type; isc_time_t expires; isc_interval_t interval; @@ -99,7 +101,7 @@ struct isc_timermgr { }; #ifndef ISC_PLATFORM_USETHREADS -/* +/*! * If threads are not in use, there can be only one. */ static isc_timermgr_t *timermgr = NULL; @@ -115,7 +117,7 @@ schedule(isc_timer_t *timer, isc_time_t *now, isc_boolean_t signal_ok) { isc_boolean_t timedwait; #endif - /* + /*! * Note: the caller must ensure locking. */ @@ -128,7 +130,7 @@ schedule(isc_timer_t *timer, isc_time_t *now, isc_boolean_t signal_ok) { manager = timer->manager; #ifdef ISC_PLATFORM_USETHREADS - /* + /*! * If the manager was timed wait, we may need to signal the * manager to force a wakeup. */ @@ -580,7 +582,7 @@ dispatch(isc_timermgr_t *manager, isc_time_t *now) { isc_timer_t *timer; isc_result_t result; - /* + /*! * The caller must be holding the manager lock. */ diff --git a/lib/isc/timer_p.h b/lib/isc/timer_p.h index 30ea8e63c0..9341b83578 100644 --- a/lib/isc/timer_p.h +++ b/lib/isc/timer_p.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: timer_p.h,v 1.6 2004/03/05 05:10:50 marka Exp $ */ +/* $Id: timer_p.h,v 1.7 2005/04/27 04:57:15 sra Exp $ */ #ifndef ISC_TIMER_P_H #define ISC_TIMER_P_H +/*! \file */ + isc_result_t isc__timermgr_nextevent(isc_time_t *when); diff --git a/lib/isc/unix/app.c b/lib/isc/unix/app.c index aa7f5c30a5..f062da1541 100644 --- a/lib/isc/unix/app.c +++ b/lib/isc/unix/app.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: app.c,v 1.50 2004/03/05 05:11:43 marka Exp $ */ +/* $Id: app.c,v 1.51 2005/04/27 04:57:23 sra Exp $ */ + +/*! \file */ #include @@ -54,7 +56,7 @@ static isc_eventlist_t on_run; static isc_mutex_t lock; static isc_boolean_t shutdown_requested = ISC_FALSE; static isc_boolean_t running = ISC_FALSE; -/* +/*! * We assume that 'want_shutdown' can be read and written atomically. */ static isc_boolean_t want_shutdown = ISC_FALSE; @@ -69,14 +71,14 @@ static pthread_t blockedthread; #endif /* ISC_PLATFORM_USETHREADS */ #ifdef HAVE_LINUXTHREADS -/* +/*! * Linux has sigwait(), but it appears to prevent signal handlers from * running, even if they're not in the set being waited for. This makes * it impossible to get the default actions for SIGILL, SIGSEGV, etc. * Instead of messing with it, we just use sigsuspend() instead. */ #undef HAVE_SIGWAIT -/* +/*! * We need to remember which thread is the main thread... */ static pthread_t main_thread; @@ -291,7 +293,7 @@ isc_app_onrun(isc_mem_t *mctx, isc_task_t *task, isc_taskaction_t action, } #ifndef ISC_PLATFORM_USETHREADS -/* +/*! * Event loop for nonthreaded programs. */ static isc_result_t @@ -371,14 +373,14 @@ evloop() { * is set by isc_condition_signal(). */ -/* - * True iff we are currently executing in the recursive +/*! + * \brief True if we are currently executing in the recursive * event loop. */ static isc_boolean_t in_recursive_evloop = ISC_FALSE; -/* - * True iff we are exiting the event loop as the result of +/*! + * \brief True if we are exiting the event loop as the result of * a call to isc_condition_signal() rather than a shutdown * or reload. */ diff --git a/lib/isc/unix/dir.c b/lib/isc/unix/dir.c index ec6c61611f..8683c6ccba 100644 --- a/lib/isc/unix/dir.c +++ b/lib/isc/unix/dir.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dir.c,v 1.20 2004/03/05 05:11:43 marka Exp $ */ +/* $Id: dir.c,v 1.21 2005/04/27 04:57:23 sra Exp $ */ -/* Principal Authors: DCL */ +/*! \file + * \author Principal Authors: DCL */ #include @@ -50,8 +51,8 @@ isc_dir_init(isc_dir_t *dir) { dir->magic = ISC_DIR_MAGIC; } -/* - * Allocate workspace and open directory stream. If either one fails, +/*! + * \brief Allocate workspace and open directory stream. If either one fails, * NULL will be returned. */ isc_result_t @@ -72,8 +73,10 @@ isc_dir_open(isc_dir_t *dir, const char *dirname) { return (result); } -/* - * Return previously retrieved file or get next one. Unix's dirent has +/*! + * \brief Return previously retrieved file or get next one. + + * Unix's dirent has * separate open and read functions, but the Win32 and DOS interfaces open * the dir stream and reads the first file in one operation. */ @@ -107,8 +110,8 @@ isc_dir_read(isc_dir_t *dir) { return (ISC_R_SUCCESS); } -/* - * Close directory stream. +/*! + * \brief Close directory stream. */ void isc_dir_close(isc_dir_t *dir) { @@ -118,8 +121,8 @@ isc_dir_close(isc_dir_t *dir) { dir->handle = NULL; } -/* - * Reposition directory stream at start. +/*! + * \brief Reposition directory stream at start. */ isc_result_t isc_dir_reset(isc_dir_t *dir) { @@ -132,8 +135,8 @@ isc_dir_reset(isc_dir_t *dir) { isc_result_t isc_dir_chdir(const char *dirname) { - /* - * Change the current directory to 'dirname'. + /*! + * \brief Change the current directory to 'dirname'. */ REQUIRE(dirname != NULL); @@ -165,8 +168,8 @@ isc_dir_createunique(char *templet) { REQUIRE(templet != NULL); - /* - * mkdtemp is not portable, so this emulates it. + /*! + * \brief mkdtemp is not portable, so this emulates it. */ pid = getpid(); diff --git a/lib/isc/unix/entropy.c b/lib/isc/unix/entropy.c index 3ae3bd3a51..aebca37033 100644 --- a/lib/isc/unix/entropy.c +++ b/lib/isc/unix/entropy.c @@ -15,10 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: entropy.c,v 1.71 2004/03/16 05:52:21 marka Exp $ */ +/* $Id: entropy.c,v 1.72 2005/04/27 04:57:23 sra Exp $ */ -/* - * This is the system depenedent part of the ISC entropy API. +/* \file unix/entropy.c + * \brief + * This is the system dependent part of the ISC entropy API. */ #include @@ -41,7 +42,7 @@ #include "errno2result.h" -/* +/*% * There is only one variable in the entropy data structures that is not * system independent, but pulling the structure that uses it into this file * ultimately means pulling several other independent structures here also to diff --git a/lib/isc/unix/errno2result.c b/lib/isc/unix/errno2result.c index 6ec7e9a3ff..c32b8e1827 100644 --- a/lib/isc/unix/errno2result.c +++ b/lib/isc/unix/errno2result.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: errno2result.c,v 1.13 2004/03/05 05:11:44 marka Exp $ */ +/* $Id: errno2result.c,v 1.14 2005/04/27 04:57:23 sra Exp $ */ + +/*! \file */ #include @@ -25,7 +27,7 @@ #include "errno2result.h" -/* +/*% * Convert a POSIX errno value into an isc_result_t. The * list of supported errno values is not complete; new users * of this function should add any expected errors that are diff --git a/lib/isc/unix/errno2result.h b/lib/isc/unix/errno2result.h index cd150f0e94..393385a966 100644 --- a/lib/isc/unix/errno2result.h +++ b/lib/isc/unix/errno2result.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: errno2result.h,v 1.8 2004/03/05 05:11:44 marka Exp $ */ +/* $Id: errno2result.h,v 1.9 2005/04/27 04:57:23 sra Exp $ */ #ifndef UNIX_ERRNO2RESULT_H #define UNIX_ERRNO2RESULT_H 1 +/*! \file */ + /* XXXDCL this should be moved to lib/isc/include/isc/errno2result.h. */ #include /* Provides errno. */ diff --git a/lib/isc/unix/file.c b/lib/isc/unix/file.c index 64c34e7c25..1c77171c7f 100644 --- a/lib/isc/unix/file.c +++ b/lib/isc/unix/file.c @@ -48,7 +48,9 @@ * SUCH DAMAGE. */ -/* $Id: file.c,v 1.47 2004/03/18 02:58:06 marka Exp $ */ +/* $Id: file.c,v 1.48 2005/04/27 04:57:23 sra Exp $ */ + +/*! \file */ #include @@ -154,7 +156,7 @@ isc_file_settime(const char *file, isc_time_t *time) { } #undef TEMPLATE -#define TEMPLATE "tmp-XXXXXXXXXX" /* 14 characters. */ +#define TEMPLATE "tmp-XXXXXXXXXX" /*%< 14 characters. */ isc_result_t isc_file_mktemplate(const char *path, char *buf, size_t buflen) { diff --git a/lib/isc/unix/fsaccess.c b/lib/isc/unix/fsaccess.c index ada7ea3c0f..e189b96a82 100644 --- a/lib/isc/unix/fsaccess.c +++ b/lib/isc/unix/fsaccess.c @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: fsaccess.c,v 1.7 2004/03/05 05:11:44 marka Exp $ */ +/* $Id: fsaccess.c,v 1.8 2005/04/27 04:57:23 sra Exp $ */ #include #include @@ -24,7 +24,8 @@ #include "errno2result.h" -/* +/*! \file + * \brief * The OS-independent part of the API is in lib/isc. */ #include "../fsaccess.c" diff --git a/lib/isc/unix/ifiter_getifaddrs.c b/lib/isc/unix/ifiter_getifaddrs.c index 7e14192b7e..55534ca37e 100644 --- a/lib/isc/unix/ifiter_getifaddrs.c +++ b/lib/isc/unix/ifiter_getifaddrs.c @@ -15,28 +15,33 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ifiter_getifaddrs.c,v 1.4 2004/03/05 05:11:45 marka Exp $ */ +/* $Id: ifiter_getifaddrs.c,v 1.5 2005/04/27 04:57:23 sra Exp $ */ -/* +/*! \file + * \brief * Obtain the list of network interfaces using the getifaddrs(3) library. */ #include +/*% Iterator Magic */ #define IFITER_MAGIC ISC_MAGIC('I', 'F', 'I', 'G') +/*% Valid Iterator */ #define VALID_IFITER(t) ISC_MAGIC_VALID(t, IFITER_MAGIC) +/*% Iterator structure */ struct isc_interfaceiter { - unsigned int magic; /* Magic number. */ + unsigned int magic; /*%< Magic number. */ isc_mem_t *mctx; - void *buf; /* (unused) */ - unsigned int bufsize; /* (always 0) */ - struct ifaddrs *ifaddrs; /* List of ifaddrs */ - struct ifaddrs *pos; /* Ptr to current ifaddr */ - isc_interface_t current; /* Current interface data. */ - isc_result_t result; /* Last result code. */ + void *buf; /*%< (unused) */ + unsigned int bufsize; /*%< (always 0) */ + struct ifaddrs *ifaddrs; /*%< List of ifaddrs */ + struct ifaddrs *pos; /*%< Ptr to current ifaddr */ + isc_interface_t current; /*%< Current interface data. */ + isc_result_t result; /*%< Last result code. */ }; + isc_result_t isc_interfaceiter_create(isc_mem_t *mctx, isc_interfaceiter_t **iterp) { isc_interfaceiter_t *iter; diff --git a/lib/isc/unix/ifiter_ioctl.c b/lib/isc/unix/ifiter_ioctl.c index ba73204389..722cfc6ca9 100644 --- a/lib/isc/unix/ifiter_ioctl.c +++ b/lib/isc/unix/ifiter_ioctl.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ifiter_ioctl.c,v 1.50 2004/11/10 22:22:10 marka Exp $ */ +/* $Id: ifiter_ioctl.c,v 1.51 2005/04/27 04:57:23 sra Exp $ */ -/* +/*! \file + * \brief * Obtain the list of network interfaces using the SIOCGLIFCONF ioctl. * See netintro(4). */ @@ -93,7 +94,7 @@ struct isc_interfaceiter { #endif -/* +/*% * Size of buffer for SIOCGLIFCONF, in bytes. We assume no sane system * will have more than a megabyte of interface configuration data. */ diff --git a/lib/isc/unix/ifiter_sysctl.c b/lib/isc/unix/ifiter_sysctl.c index e46526b12a..11bb036a91 100644 --- a/lib/isc/unix/ifiter_sysctl.c +++ b/lib/isc/unix/ifiter_sysctl.c @@ -15,9 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ifiter_sysctl.c,v 1.22 2005/03/16 00:55:19 marka Exp $ */ +/* $Id: ifiter_sysctl.c,v 1.23 2005/04/27 04:57:23 sra Exp $ */ -/* +/*! \file + * \brief * Obtain the list of network interfaces using sysctl. * See TCP/IP Illustrated Volume 2, sections 19.8, 19.14, * and 19.16. diff --git a/lib/isc/unix/include/isc/dir.h b/lib/isc/unix/include/isc/dir.h index 307f43fe78..e46798eb3e 100644 --- a/lib/isc/unix/include/isc/dir.h +++ b/lib/isc/unix/include/isc/dir.h @@ -15,13 +15,15 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: dir.h,v 1.17 2004/03/05 05:11:52 marka Exp $ */ +/* $Id: dir.h,v 1.18 2005/04/27 04:57:24 sra Exp $ */ /* Principal Authors: DCL */ #ifndef ISC_DIR_H #define ISC_DIR_H 1 +/*! \file */ + #include /* Required on some systems. */ #include @@ -31,8 +33,9 @@ #define ISC_DIR_NAMEMAX 256 #define ISC_DIR_PATHMAX 1024 +/*% Directory Entry */ typedef struct isc_direntry { - /* + /*! * Ideally, this should be NAME_MAX, but AIX does not define it by * default and dynamically allocating the space based on pathconf() * complicates things undesirably, as does adding special conditionals @@ -42,9 +45,10 @@ typedef struct isc_direntry { unsigned int length; } isc_direntry_t; +/*% Directory */ typedef struct isc_dir { unsigned int magic; - /* + /*! * As with isc_direntry_t->name, making this "right" for all systems * is slightly problematic because AIX does not define PATH_MAX. */ @@ -78,7 +82,7 @@ isc_dir_chroot(const char *dirname); isc_result_t isc_dir_createunique(char *templet); -/* +/*!< * Use a templet (such as from isc_file_mktemplate()) to create a uniquely * named, empty directory. The templet string is modified in place. * If result == ISC_R_SUCCESS, it is the name of the directory that was diff --git a/lib/isc/unix/include/isc/int.h b/lib/isc/unix/include/isc/int.h index 96e29a13d8..e91d6f1398 100644 --- a/lib/isc/unix/include/isc/int.h +++ b/lib/isc/unix/include/isc/int.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: int.h,v 1.12 2004/03/05 05:11:52 marka Exp $ */ +/* $Id: int.h,v 1.13 2005/04/27 04:57:24 sra Exp $ */ #ifndef ISC_INT_H #define ISC_INT_H 1 +/*! \file */ + typedef char isc_int8_t; typedef unsigned char isc_uint8_t; typedef short isc_int16_t; @@ -37,7 +39,7 @@ typedef unsigned long long isc_uint64_t; #define ISC_INT16_MAX 32767 #define ISC_UINT16_MAX 65535 -/* +/*% * Note that "int" is 32 bits on all currently supported Unix-like operating * systems, but "long" can be either 32 bits or 64 bits, thus the 32 bit * constants are not qualified with "L". diff --git a/lib/isc/unix/include/isc/keyboard.h b/lib/isc/unix/include/isc/keyboard.h index 8a21409e60..75d9911ac9 100644 --- a/lib/isc/unix/include/isc/keyboard.h +++ b/lib/isc/unix/include/isc/keyboard.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: keyboard.h,v 1.7 2004/03/05 05:11:52 marka Exp $ */ +/* $Id: keyboard.h,v 1.8 2005/04/27 04:57:24 sra Exp $ */ #ifndef ISC_KEYBOARD_H #define ISC_KEYBOARD_H 1 +/*! \file */ + #include #include diff --git a/lib/isc/unix/include/isc/net.h b/lib/isc/unix/include/isc/net.h index c56537fe14..89e2207545 100644 --- a/lib/isc/unix/include/isc/net.h +++ b/lib/isc/unix/include/isc/net.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: net.h,v 1.42 2005/02/24 00:33:34 marka Exp $ */ +/* $Id: net.h,v 1.43 2005/04/27 04:57:24 sra Exp $ */ #ifndef ISC_NET_H #define ISC_NET_H 1 @@ -24,19 +24,20 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * Basic Networking Types * * This module is responsible for defining the following basic networking * types: * - * struct in_addr - * struct in6_addr - * struct in6_pktinfo - * struct sockaddr - * struct sockaddr_in - * struct sockaddr_in6 - * in_port_t + *\li struct in_addr + *\li struct in6_addr + *\li struct in6_pktinfo + *\li struct sockaddr + *\li struct sockaddr_in + *\li struct sockaddr_in6 + *\li in_port_t * * It ensures that the AF_ and PF_ macros are defined. * @@ -44,27 +45,27 @@ * * It declares inet_aton(), inet_ntop(), and inet_pton(). * - * It ensures that INADDR_LOOPBACK, INADDR_ANY, IN6ADDR_ANY_INIT, + * It ensures that #INADDR_LOOPBACK, #INADDR_ANY, #IN6ADDR_ANY_INIT, * in6addr_any, and in6addr_loopback are available. * * It ensures that IN_MULTICAST() is available to check for multicast * addresses. * * MP: - * No impact. + *\li No impact. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * N/A. + *\li N/A. * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * BSD Socket API - * RFC 2553 + *\li BSD Socket API + *\li RFC2553 */ /*** @@ -94,19 +95,19 @@ #include #ifdef ISC_PLATFORM_HAVEINADDR6 -#define in6_addr in_addr6 /* Required for pre RFC2133 implementations. */ +#define in6_addr in_addr6 /*%< Required for pre RFC2133 implementations. */ #endif #ifdef ISC_PLATFORM_HAVEIPV6 -/* +#ifndef IN6ADDR_ANY_INIT +#ifdef s6_addr +/*% * Required for some pre RFC2133 implementations. * IN6ADDR_ANY_INIT and IN6ADDR_LOOPBACK_INIT were added in * draft-ietf-ipngwg-bsd-api-04.txt or draft-ietf-ipngwg-bsd-api-05.txt. * If 's6_addr' is defined then assume that there is a union and three * levels otherwise assume two levels required. */ -#ifndef IN6ADDR_ANY_INIT -#ifdef s6_addr #define IN6ADDR_ANY_INIT { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } } } #else #define IN6ADDR_ANY_INIT { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } } @@ -115,6 +116,7 @@ #ifndef IN6ADDR_LOOPBACK_INIT #ifdef s6_addr +/*% IPv6 address loopback init */ #define IN6ADDR_LOOPBACK_INIT { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 } } } #else #define IN6ADDR_LOOPBACK_INIT { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 } } @@ -122,12 +124,14 @@ #endif #ifndef IN6_IS_ADDR_V4MAPPED +/*% Is IPv6 address V4 mapped? */ #define IN6_IS_ADDR_V4MAPPED(x) \ (memcmp((x)->s6_addr, in6addr_any.s6_addr, 10) == 0 && \ (x)->s6_addr[10] == 0xff && (x)->s6_addr[11] == 0xff) #endif #ifndef IN6_IS_ADDR_V4COMPAT +/*% Is IPv6 address V4 compatible? */ #define IN6_IS_ADDR_V4COMPAT(x) \ (memcmp((x)->s6_addr, in6addr_any.s6_addr, 12) == 0 && \ ((x)->s6_addr[12] != 0 || (x)->s6_addr[13] != 0 || \ @@ -136,50 +140,58 @@ #endif #ifndef IN6_IS_ADDR_MULTICAST +/*% Is IPv6 address multicast? */ #define IN6_IS_ADDR_MULTICAST(a) ((a)->s6_addr[0] == 0xff) #endif #ifndef IN6_IS_ADDR_LINKLOCAL +/*% Is IPv6 address linklocal? */ #define IN6_IS_ADDR_LINKLOCAL(a) \ (((a)->s6_addr[0] == 0xfe) && (((a)->s6_addr[1] & 0xc0) == 0x80)) #endif #ifndef IN6_IS_ADDR_SITELOCAL +/*% is IPv6 address sitelocal? */ #define IN6_IS_ADDR_SITELOCAL(a) \ (((a)->s6_addr[0] == 0xfe) && (((a)->s6_addr[1] & 0xc0) == 0xc0)) #endif #ifndef IN6_IS_ADDR_LOOPBACK +/*% is IPv6 address loopback? */ #define IN6_IS_ADDR_LOOPBACK(x) \ (memcmp((x)->s6_addr, in6addr_loopback.s6_addr, 16) == 0) #endif #endif #ifndef AF_INET6 +/*% IPv6 */ #define AF_INET6 99 #endif #ifndef PF_INET6 +/*% IPv6 */ #define PF_INET6 AF_INET6 #endif #ifndef INADDR_LOOPBACK +/*% inaddr loopback */ #define INADDR_LOOPBACK 0x7f000001UL #endif #ifndef ISC_PLATFORM_HAVEIN6PKTINFO +/*% IPv6 packet info */ struct in6_pktinfo { - struct in6_addr ipi6_addr; /* src/dst IPv6 address */ - unsigned int ipi6_ifindex; /* send/recv interface index */ + struct in6_addr ipi6_addr; /*%< src/dst IPv6 address */ + unsigned int ipi6_ifindex; /*%< send/recv interface index */ }; #endif -/* - * Cope with a missing in6addr_any and in6addr_loopback. - */ #if defined(ISC_PLATFORM_HAVEIPV6) && defined(ISC_PLATFORM_NEEDIN6ADDRANY) extern const struct in6_addr isc_net_in6addrany; +/*% + * Cope with a missing in6addr_any and in6addr_loopback. + */ #define in6addr_any isc_net_in6addrany #endif @@ -188,11 +200,12 @@ extern const struct in6_addr isc_net_in6addrloop; #define in6addr_loopback isc_net_in6addrloop #endif -/* - * Fix UnixWare 7.1.1's broken IN6_IS_ADDR_* definitions. - */ #ifdef ISC_PLATFORM_FIXIN6ISADDR #undef IN6_IS_ADDR_GEOGRAPHIC +/*! + * \brief + * Fix UnixWare 7.1.1's broken IN6_IS_ADDR_* definitions. + */ #define IN6_IS_ADDR_GEOGRAPHIC(a) (((a)->S6_un.S6_l[0] & 0xE0) == 0x80) #undef IN6_IS_ADDR_IPX #define IN6_IS_ADDR_IPX(a) (((a)->S6_un.S6_l[0] & 0xFE) == 0x04) @@ -208,24 +221,26 @@ extern const struct in6_addr isc_net_in6addrloop; #define IN6_IS_ADDR_SITELOCAL(a) (((a)->S6_un.S6_l[0] & 0xC0FF) == 0xC0FE) #endif /* ISC_PLATFORM_FIXIN6ISADDR */ -/* +#ifdef ISC_PLATFORM_NEEDPORTT +/*% * Ensure type in_port_t is defined. */ -#ifdef ISC_PLATFORM_NEEDPORTT typedef isc_uint16_t in_port_t; #endif -/* +#ifndef MSG_TRUNC +/*% * If this system does not have MSG_TRUNC (as returned from recvmsg()) * ISC_PLATFORM_RECVOVERFLOW will be defined. This will enable the MSG_TRUNC * faking code in socket.c. */ -#ifndef MSG_TRUNC #define ISC_PLATFORM_RECVOVERFLOW #endif +/*% IP address. */ #define ISC__IPADDR(x) ((isc_uint32_t)htonl((isc_uint32_t)(x))) +/*% Is IP address multicast? */ #define ISC_IPADDR_ISMULTICAST(i) \ (((isc_uint32_t)(i) & ISC__IPADDR(0xf0000000)) \ == ISC__IPADDR(0xe0000000)) @@ -242,40 +257,40 @@ ISC_LANG_BEGINDECLS isc_result_t isc_net_probeipv4(void); -/* +/*%< * Check if the system's kernel supports IPv4. * * Returns: * - * ISC_R_SUCCESS IPv4 is supported. - * ISC_R_NOTFOUND IPv4 is not supported. - * ISC_R_DISABLED IPv4 is disabled. - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS IPv4 is supported. + *\li #ISC_R_NOTFOUND IPv4 is not supported. + *\li #ISC_R_DISABLED IPv4 is disabled. + *\li #ISC_R_UNEXPECTED */ isc_result_t isc_net_probeipv6(void); -/* +/*%< * Check if the system's kernel supports IPv6. * * Returns: * - * ISC_R_SUCCESS IPv6 is supported. - * ISC_R_NOTFOUND IPv6 is not supported. - * ISC_R_DISABLED IPv6 is disabled. - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS IPv6 is supported. + *\li #ISC_R_NOTFOUND IPv6 is not supported. + *\li #ISC_R_DISABLED IPv6 is disabled. + *\li #ISC_R_UNEXPECTED */ isc_result_t isc_net_probe_ipv6only(void); -/* +/*%< * Check if the system's kernel supports the IPV6_V6ONLY socket option. * * Returns: * - * ISC_R_SUCCESS the option is supported for both TCP and UDP. - * ISC_R_NOTFOUND IPv6 itself or the option is not supported. - * ISC_R_UNEXPECTED + *\li #ISC_R_SUCCESS the option is supported for both TCP and UDP. + *\li #ISC_R_NOTFOUND IPv6 itself or the option is not supported. + *\li #ISC_R_UNEXPECTED */ isc_result_t diff --git a/lib/isc/unix/include/isc/netdb.h b/lib/isc/unix/include/isc/netdb.h index 8805021648..49da53f064 100644 --- a/lib/isc/unix/include/isc/netdb.h +++ b/lib/isc/unix/include/isc/netdb.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: netdb.h,v 1.7 2004/03/05 05:11:53 marka Exp $ */ +/* $Id: netdb.h,v 1.8 2005/04/27 04:57:24 sra Exp $ */ #ifndef ISC_NETDB_H #define ISC_NETDB_H 1 @@ -24,25 +24,26 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * Portable netdb.h support. * * This module is responsible for defining the getby APIs. * * MP: - * No impact. + *\li No impact. * * Reliability: - * No anticipated impact. + *\li No anticipated impact. * * Resources: - * N/A. + *\li N/A. * * Security: - * No anticipated impact. + *\li No anticipated impact. * * Standards: - * BSD API + *\li BSD API */ /*** diff --git a/lib/isc/unix/include/isc/offset.h b/lib/isc/unix/include/isc/offset.h index bf692ea35e..d6aba41023 100644 --- a/lib/isc/unix/include/isc/offset.h +++ b/lib/isc/unix/include/isc/offset.h @@ -15,12 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: offset.h,v 1.11 2004/03/05 05:11:53 marka Exp $ */ +/* $Id: offset.h,v 1.12 2005/04/27 04:57:24 sra Exp $ */ #ifndef ISC_OFFSET_H #define ISC_OFFSET_H 1 -/* +/*! \file + * \brief * File offsets are operating-system dependent. */ #include /* Required for CHAR_BIT. */ @@ -28,7 +29,7 @@ typedef off_t isc_offset_t; -/* +/*% * POSIX says "Additionally, blkcnt_t and off_t are extended signed integral * types", so the maximum value is all 1s except for the high bit. * This definition is more complex than it really needs to be because it was diff --git a/lib/isc/unix/include/isc/stdtime.h b/lib/isc/unix/include/isc/stdtime.h index d9b8b9a98f..aa437a7af8 100644 --- a/lib/isc/unix/include/isc/stdtime.h +++ b/lib/isc/unix/include/isc/stdtime.h @@ -15,15 +15,17 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: stdtime.h,v 1.9 2004/03/05 05:11:53 marka Exp $ */ +/* $Id: stdtime.h,v 1.10 2005/04/27 04:57:24 sra Exp $ */ #ifndef ISC_STDTIME_H #define ISC_STDTIME_H 1 +/*! \file */ + #include #include -/* +/*% * It's public information that 'isc_stdtime_t' is an unsigned integral type. * Applications that want maximum portability should not assume anything * about its size. @@ -31,15 +33,15 @@ typedef isc_uint32_t isc_stdtime_t; ISC_LANG_BEGINDECLS - +/* */ void isc_stdtime_get(isc_stdtime_t *t); -/* +/*%< * Set 't' to the number of seconds since 00:00:00 UTC, January 1, 1970. * * Requires: * - * 't' is a valid pointer. + *\li 't' is a valid pointer. */ ISC_LANG_ENDDECLS diff --git a/lib/isc/unix/include/isc/strerror.h b/lib/isc/unix/include/isc/strerror.h index a579b652cb..b606d883fd 100644 --- a/lib/isc/unix/include/isc/strerror.h +++ b/lib/isc/unix/include/isc/strerror.h @@ -15,20 +15,23 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: strerror.h,v 1.4 2004/03/05 05:11:53 marka Exp $ */ +/* $Id: strerror.h,v 1.5 2005/04/27 04:57:24 sra Exp $ */ #ifndef ISC_STRERROR_H #define ISC_STRERROR_H +/*! \file */ + #include #include ISC_LANG_BEGINDECLS +/*% String Error Size */ #define ISC_STRERRORSIZE 128 -/* +/*% * Provide a thread safe wrapper to strerrror(). * * Requires: diff --git a/lib/isc/unix/include/isc/syslog.h b/lib/isc/unix/include/isc/syslog.h index d357a42a01..ed515daebe 100644 --- a/lib/isc/unix/include/isc/syslog.h +++ b/lib/isc/unix/include/isc/syslog.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: syslog.h,v 1.3 2004/03/05 05:11:53 marka Exp $ */ +/* $Id: syslog.h,v 1.4 2005/04/27 04:57:24 sra Exp $ */ #ifndef ISC_SYSLOG_H #define ISC_SYSLOG_H 1 +/*! \file */ + #include #include @@ -27,17 +29,17 @@ ISC_LANG_BEGINDECLS isc_result_t isc_syslog_facilityfromstring(const char *str, int *facilityp); -/* +/*%< * Convert 'str' to the appropriate syslog facility constant. * * Requires: * - * 'str' is not NULL - * 'facilityp' is not NULL + *\li 'str' is not NULL + *\li 'facilityp' is not NULL * * Returns: - * ISC_R_SUCCESS - * ISC_R_NOTFOUND + * \li #ISC_R_SUCCESS + * \li #ISC_R_NOTFOUND */ ISC_LANG_ENDDECLS diff --git a/lib/isc/unix/include/isc/time.h b/lib/isc/unix/include/isc/time.h index f69f455e38..556d629cb1 100644 --- a/lib/isc/unix/include/isc/time.h +++ b/lib/isc/unix/include/isc/time.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: time.h,v 1.30 2004/03/05 05:11:53 marka Exp $ */ +/* $Id: time.h,v 1.31 2005/04/27 04:57:25 sra Exp $ */ #ifndef ISC_TIME_H #define ISC_TIME_H 1 +/*! \file */ + #include #include @@ -27,7 +29,8 @@ *** Intervals ***/ -/* +/*! + * \brief * The contents of this structure are private, and MUST NOT be accessed * directly by callers. * @@ -45,32 +48,32 @@ ISC_LANG_BEGINDECLS void isc_interval_set(isc_interval_t *i, unsigned int seconds, unsigned int nanoseconds); -/* +/*%< * Set 'i' to a value representing an interval of 'seconds' seconds and * 'nanoseconds' nanoseconds, suitable for use in isc_time_add() and * isc_time_subtract(). * * Requires: * - * 't' is a valid pointer. - * nanoseconds < 1000000000. + *\li 't' is a valid pointer. + *\li nanoseconds < 1000000000. */ isc_boolean_t isc_interval_iszero(const isc_interval_t *i); -/* +/*%< * Returns ISC_TRUE iff. 'i' is the zero interval. * * Requires: * - * 'i' is a valid pointer. + *\li 'i' is a valid pointer. */ /*** *** Absolute Times ***/ -/* +/*% * The contents of this structure are private, and MUST NOT be accessed * directly by callers. * @@ -86,116 +89,118 @@ extern isc_time_t *isc_time_epoch; void isc_time_set(isc_time_t *t, unsigned int seconds, unsigned int nanoseconds); -/* +/*%< * Set 't' to a particular number of seconds + nanoseconds since the epoch. * * Notes: - * This call is equivalent to: - * + *\li This call is equivalent to: + *\code * isc_time_settoepoch(t); * isc_interval_set(i, seconds, nanoseconds); * isc_time_add(t, i, t); - * + *\endcode * Requires: - * 't' is a valid pointer. - * nanoseconds < 1000000000. + *\li 't' is a valid pointer. + *\li nanoseconds < 1000000000. */ void isc_time_settoepoch(isc_time_t *t); -/* +/*%< * Set 't' to the time of the epoch. * * Notes: - * The date of the epoch is platform-dependent. + * \li The date of the epoch is platform-dependent. * * Requires: * - * 't' is a valid pointer. + *\li 't' is a valid pointer. */ isc_boolean_t isc_time_isepoch(const isc_time_t *t); -/* +/*%< * Returns ISC_TRUE iff. 't' is the epoch ("time zero"). * * Requires: * - * 't' is a valid pointer. + *\li 't' is a valid pointer. */ isc_result_t isc_time_now(isc_time_t *t); -/* +/*%< * Set 't' to the current absolute time. * * Requires: * - * 't' is a valid pointer. + *\li 't' is a valid pointer. * * Returns: * - * Success - * Unexpected error + *\li Success + *\li Unexpected error * Getting the time from the system failed. - * Out of range + *\li Out of range * The time from the system is too large to be represented * in the current definition of isc_time_t. */ isc_result_t isc_time_nowplusinterval(isc_time_t *t, const isc_interval_t *i); -/* +/*%< * Set *t to the current absolute time + i. * * Note: - * This call is equivalent to: + *\li This call is equivalent to: * + *\code * isc_time_now(t); * isc_time_add(t, i, t); + *\endcode * * Requires: * - * 't' and 'i' are valid pointers. + *\li 't' and 'i' are valid pointers. * * Returns: * - * Success - * Unexpected error + *\li Success + *\li Unexpected error * Getting the time from the system failed. - * Out of range + *\li Out of range * The interval added to the time from the system is too large to * be represented in the current definition of isc_time_t. */ int isc_time_compare(const isc_time_t *t1, const isc_time_t *t2); -/* +/*%< * Compare the times referenced by 't1' and 't2' * * Requires: * - * 't1' and 't2' are valid pointers. + *\li 't1' and 't2' are valid pointers. * * Returns: * - * -1 t1 < t2 (comparing times, not pointers) - * 0 t1 = t2 - * 1 t1 > t2 + *\li -1 t1 < t2 (comparing times, not pointers) + *\li 0 t1 = t2 + *\li 1 t1 > t2 */ isc_result_t isc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result); -/* +/*%< * Add 'i' to 't', storing the result in 'result'. * * Requires: * - * 't', 'i', and 'result' are valid pointers. + *\li 't', 'i', and 'result' are valid pointers. * * Returns: - * Success - * Out of range + * \li Success + *\li Out of range * The interval added to the time is too large to * be represented in the current definition of isc_time_t. */ @@ -203,50 +208,50 @@ isc_time_add(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result); isc_result_t isc_time_subtract(const isc_time_t *t, const isc_interval_t *i, isc_time_t *result); -/* +/*%< * Subtract 'i' from 't', storing the result in 'result'. * * Requires: * - * 't', 'i', and 'result' are valid pointers. + *\li 't', 'i', and 'result' are valid pointers. * * Returns: - * Success - * Out of range + *\li Success + *\li Out of range * The interval is larger than the time since the epoch. */ isc_uint64_t isc_time_microdiff(const isc_time_t *t1, const isc_time_t *t2); -/* +/*%< * Find the difference in microseconds between time t1 and time t2. * t2 is the subtrahend of t1; ie, difference = t1 - t2. * * Requires: * - * 't1' and 't2' are valid pointers. + *\li 't1' and 't2' are valid pointers. * * Returns: - * The difference of t1 - t2, or 0 if t1 <= t2. + *\li The difference of t1 - t2, or 0 if t1 <= t2. */ isc_uint32_t isc_time_seconds(const isc_time_t *t); -/* +/*%< * Return the number of seconds since the epoch stored in a time structure. * * Requires: * - * 't' is a valid pointer. + *\li 't' is a valid pointer. */ isc_result_t isc_time_secondsastimet(const isc_time_t *t, time_t *secondsp); -/* +/*%< * Ensure the number of seconds in an isc_time_t is representable by a time_t. * * Notes: - * The number of seconds stored in an isc_time_t might be larger + *\li The number of seconds stored in an isc_time_t might be larger * than the number of seconds a time_t is able to handle. Since * time_t is mostly opaque according to the ANSI/ISO standard * (essentially, all you can be sure of is that it is an arithmetic type, @@ -256,41 +261,41 @@ isc_time_secondsastimet(const isc_time_t *t, time_t *secondsp); * time_t from an isc_time_t. * * Requires: - * 't' is a valid pointer. + *\li 't' is a valid pointer. * * Returns: - * Success - * Out of range + *\li Success + *\li Out of range */ isc_uint32_t isc_time_nanoseconds(const isc_time_t *t); -/* +/*%< * Return the number of nanoseconds stored in a time structure. * * Notes: - * This is the number of nanoseconds in excess of the the number + *\li This is the number of nanoseconds in excess of the the number * of seconds since the epoch; it will always be less than one * full second. * * Requires: - * 't' is a valid pointer. + *\li 't' is a valid pointer. * * Ensures: - * The returned value is less than 1*10^9. + *\li The returned value is less than 1*10^9. */ void isc_time_formattimestamp(const isc_time_t *t, char *buf, unsigned int len); -/* +/*%< * Format the time 't' into the buffer 'buf' of length 'len', * using a format like "30-Aug-2000 04:06:47.997" and the local time zone. * If the text does not fit in the buffer, the result is indeterminate, * but is always guaranteed to be null terminated. * * Requires: - * 'len' > 0 - * 'buf' points to an array of at least len chars + *\li 'len' > 0 + * \li 'buf' points to an array of at least len chars * */ diff --git a/lib/isc/unix/interfaceiter.c b/lib/isc/unix/interfaceiter.c index 66fffecbda..a4d01a4ddf 100644 --- a/lib/isc/unix/interfaceiter.c +++ b/lib/isc/unix/interfaceiter.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: interfaceiter.c,v 1.38 2004/08/28 06:16:57 marka Exp $ */ +/* $Id: interfaceiter.c,v 1.39 2005/04/27 04:57:23 sra Exp $ */ + +/*! \file */ #include @@ -51,9 +53,9 @@ /* Common utility functions */ -/* +/*% * Extract the network address part from a "struct sockaddr". - * + * \brief * The address family is given explicitly * instead of using src->sa_family, because the latter does not work * for copying a network mask obtained by SIOCGIFNETMASK (it does diff --git a/lib/isc/unix/ipv6.c b/lib/isc/unix/ipv6.c index 0ad61fd670..ceb510a93c 100644 --- a/lib/isc/unix/ipv6.c +++ b/lib/isc/unix/ipv6.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ipv6.c,v 1.8 2004/03/05 05:11:45 marka Exp $ */ +/* $Id: ipv6.c,v 1.9 2005/04/27 04:57:23 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/unix/socket.c b/lib/isc/unix/socket.c index 9c895e84f2..2651502770 100644 --- a/lib/isc/unix/socket.c +++ b/lib/isc/unix/socket.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: socket.c,v 1.248 2005/03/30 05:37:08 marka Exp $ */ +/* $Id: socket.c,v 1.249 2005/04/27 04:57:23 sra Exp $ */ + +/*! \file */ #include @@ -61,7 +63,7 @@ #include "socket_p.h" #endif /* ISC_PLATFORM_USETHREADS */ -/* +/*% * Some systems define the socket length argument as an int, some as size_t, * some as socklen_t. This is here so it can be easily changed if needed. */ @@ -69,7 +71,7 @@ #define ISC_SOCKADDR_LEN_T unsigned int #endif -/* +/*% * Define what the possible "soft" errors can be. These are non-fatal returns * of various network related functions, like recv() and so on. * @@ -84,7 +86,7 @@ #define DLVL(x) ISC_LOGCATEGORY_GENERAL, ISC_LOGMODULE_SOCKET, ISC_LOG_DEBUG(x) -/* +/*!< * DLVL(90) -- Function entry/exit and other tracing. * DLVL(70) -- Socket "correctness" -- including returning of events, etc. * DLVL(60) -- Socket data send/receive @@ -108,7 +110,7 @@ typedef isc_event_t intev_t; #define SOCKET_MAGIC ISC_MAGIC('I', 'O', 'i', 'o') #define VALID_SOCKET(t) ISC_MAGIC_VALID(t, SOCKET_MAGIC) -/* +/*! * IPv6 control information. If the socket is an IPv6 socket we want * to collect the destination address and interface so the client can * set them on outgoing packets. @@ -119,7 +121,7 @@ typedef isc_event_t intev_t; #endif #endif -/* +/*% * NetBSD and FreeBSD can timestamp packets. XXXMLG Should we have * a setsockopt() like interface to request timestamps, and if the OS * doesn't do it for us, call gettimeofday() on every UDP receive? @@ -130,7 +132,7 @@ typedef isc_event_t intev_t; #endif #endif -/* +/*% * The number of times a send operation is repeated if the result is EINTR. */ #define NRETRIES 10 @@ -242,9 +244,9 @@ static void build_msghdr_recv(isc_socket_t *, isc_socketevent_t *, #define SELECT_POKE_SHUTDOWN (-1) #define SELECT_POKE_NOTHING (-2) #define SELECT_POKE_READ (-3) -#define SELECT_POKE_ACCEPT (-3) /* Same as _READ */ +#define SELECT_POKE_ACCEPT (-3) /*%< Same as _READ */ #define SELECT_POKE_WRITE (-4) -#define SELECT_POKE_CONNECT (-4) /* Same as _WRITE */ +#define SELECT_POKE_CONNECT (-4) /*%< Same as _WRITE */ #define SELECT_POKE_CLOSE (-5) #define SOCK_DEAD(s) ((s)->references == 0) diff --git a/lib/isc/unix/socket_p.h b/lib/isc/unix/socket_p.h index 11b9695cae..8f4f5c9891 100644 --- a/lib/isc/unix/socket_p.h +++ b/lib/isc/unix/socket_p.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: socket_p.h,v 1.7 2004/03/05 05:11:47 marka Exp $ */ +/* $Id: socket_p.h,v 1.8 2005/04/27 04:57:24 sra Exp $ */ #ifndef ISC_SOCKET_P_H #define ISC_SOCKET_P_H +/*! \file */ + #ifdef ISC_PLATFORM_NEEDSYSSELECTH #include #endif diff --git a/lib/isc/unix/stdtime.c b/lib/isc/unix/stdtime.c index 7e497ac202..8c224ea555 100644 --- a/lib/isc/unix/stdtime.c +++ b/lib/isc/unix/stdtime.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: stdtime.c,v 1.14 2004/03/05 05:11:47 marka Exp $ */ +/* $Id: stdtime.c,v 1.15 2005/04/27 04:57:24 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/unix/strerror.c b/lib/isc/unix/strerror.c index 4c33d0c10e..29365a7d02 100644 --- a/lib/isc/unix/strerror.c +++ b/lib/isc/unix/strerror.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: strerror.c,v 1.4 2004/03/05 05:11:47 marka Exp $ */ +/* $Id: strerror.c,v 1.5 2005/04/27 04:57:24 sra Exp $ */ + +/*! \file */ #include @@ -29,7 +31,7 @@ #include #ifdef HAVE_STRERROR -/* +/*% * We need to do this this way for profiled locks. */ static isc_mutex_t isc_strerror_lock; diff --git a/lib/isc/unix/syslog.c b/lib/isc/unix/syslog.c index ae407d9f6d..7cc2287ac7 100644 --- a/lib/isc/unix/syslog.c +++ b/lib/isc/unix/syslog.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: syslog.c,v 1.3 2004/03/05 05:11:47 marka Exp $ */ +/* $Id: syslog.c,v 1.4 2005/04/27 04:57:24 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/unix/time.c b/lib/isc/unix/time.c index a8a157acac..65668702a4 100644 --- a/lib/isc/unix/time.c +++ b/lib/isc/unix/time.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: time.c,v 1.47 2004/03/05 05:11:48 marka Exp $ */ +/* $Id: time.c,v 1.48 2005/04/27 04:57:24 sra Exp $ */ + +/*! \file */ #include @@ -33,9 +35,9 @@ #include #include -#define NS_PER_S 1000000000 /* Nanoseconds per second. */ -#define NS_PER_US 1000 /* Nanoseconds per microsecond. */ -#define US_PER_S 1000000 /* Microseconds per second. */ +#define NS_PER_S 1000000000 /*%< Nanoseconds per second. */ +#define NS_PER_US 1000 /*%< Nanoseconds per microsecond. */ +#define US_PER_S 1000000 /*%< Microseconds per second. */ /* * All of the INSIST()s checks of nanoseconds < NS_PER_S are for @@ -48,7 +50,7 @@ #define ISC_FIX_TV_USEC 1 #endif -/*** +/*% *** Intervals ***/ diff --git a/lib/isc/version.c b/lib/isc/version.c index 30a1630da3..e96383bd60 100644 --- a/lib/isc/version.c +++ b/lib/isc/version.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.c,v 1.11 2004/03/05 05:10:50 marka Exp $ */ +/* $Id: version.c,v 1.12 2005/04/27 04:57:15 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isc/win32/include/isc/ipv6.h b/lib/isc/win32/include/isc/ipv6.h index 3f63b97d72..26abaf31e4 100644 --- a/lib/isc/win32/include/isc/ipv6.h +++ b/lib/isc/win32/include/isc/ipv6.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ipv6.h,v 1.15 2005/02/09 05:19:30 marka Exp $ */ +/* $Id: ipv6.h,v 1.16 2005/04/27 04:57:25 sra Exp $ */ #ifndef ISC_IPV6_H #define ISC_IPV6_H 1 @@ -40,7 +40,7 @@ * No anticipated impact. * * Standards: - * RFC 2553. + * RFC2553. */ #if _MSC_VER < 1300 diff --git a/lib/isc/win32/include/isc/net.h b/lib/isc/win32/include/isc/net.h index 13c99b177a..7b7c7c876c 100644 --- a/lib/isc/win32/include/isc/net.h +++ b/lib/isc/win32/include/isc/net.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: net.h,v 1.25 2005/02/24 00:33:35 marka Exp $ */ +/* $Id: net.h,v 1.26 2005/04/27 04:57:25 sra Exp $ */ #ifndef ISC_NET_H #define ISC_NET_H 1 @@ -72,7 +72,7 @@ * * Standards: * BSD Socket API - * RFC 2553 + * RFC2553 */ /*** diff --git a/lib/isccc/alist.c b/lib/isccc/alist.c index ee293c7488..45ea75bad4 100644 --- a/lib/isccc/alist.c +++ b/lib/isccc/alist.c @@ -16,7 +16,9 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: alist.c,v 1.3 2004/03/05 05:12:08 marka Exp $ */ +/* $Id: alist.c,v 1.4 2005/04/27 04:57:25 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccc/base64.c b/lib/isccc/base64.c index 67160e6bc7..5a29b31c2f 100644 --- a/lib/isccc/base64.c +++ b/lib/isccc/base64.c @@ -16,7 +16,9 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: base64.c,v 1.3 2004/03/05 05:12:09 marka Exp $ */ +/* $Id: base64.c,v 1.4 2005/04/27 04:57:25 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccc/cc.c b/lib/isccc/cc.c index 5c72311608..4a81a84eef 100644 --- a/lib/isccc/cc.c +++ b/lib/isccc/cc.c @@ -16,7 +16,9 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: cc.c,v 1.11 2004/08/28 06:16:58 marka Exp $ */ +/* $Id: cc.c,v 1.12 2005/04/27 04:57:25 sra Exp $ */ + +/*! \file */ #include @@ -44,12 +46,12 @@ typedef isccc_sexpr_t *sexpr_ptr; static unsigned char auth_hmd5[] = { - 0x05, 0x5f, 0x61, 0x75, 0x74, 0x68, /* len + _auth */ - ISCCC_CCMSGTYPE_TABLE, /* message type */ - 0x00, 0x00, 0x00, 0x20, /* length == 32 */ - 0x04, 0x68, 0x6d, 0x64, 0x35, /* len + hmd5 */ - ISCCC_CCMSGTYPE_BINARYDATA, /* message type */ - 0x00, 0x00, 0x00, 0x16, /* length == 22 */ + 0x05, 0x5f, 0x61, 0x75, 0x74, 0x68, /*%< len + _auth */ + ISCCC_CCMSGTYPE_TABLE, /*%< message type */ + 0x00, 0x00, 0x00, 0x20, /*%< length == 32 */ + 0x04, 0x68, 0x6d, 0x64, 0x35, /*%< len + hmd5 */ + ISCCC_CCMSGTYPE_BINARYDATA, /*%< message type */ + 0x00, 0x00, 0x00, 0x16, /*%< length == 22 */ /* * The base64 encoding of one of our HMAC-MD5 signatures is * 22 bytes. @@ -59,7 +61,7 @@ static unsigned char auth_hmd5[] = { 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 }; -#define HMD5_OFFSET 21 /* 6 + 1 + 4 + 5 + 1 + 4 */ +#define HMD5_OFFSET 21 /*%< 21 = 6 + 1 + 4 + 5 + 1 + 4 */ #define HMD5_LENGTH 22 static isc_result_t diff --git a/lib/isccc/ccmsg.c b/lib/isccc/ccmsg.c index 29cc2d4a16..3adeb577cd 100644 --- a/lib/isccc/ccmsg.c +++ b/lib/isccc/ccmsg.c @@ -16,7 +16,9 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ccmsg.c,v 1.5 2004/03/05 05:12:09 marka Exp $ */ +/* $Id: ccmsg.c,v 1.6 2005/04/27 04:57:25 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccc/include/isccc/alist.h b/lib/isccc/include/isccc/alist.h index 18b78062f5..13586cde1c 100644 --- a/lib/isccc/include/isccc/alist.h +++ b/lib/isccc/include/isccc/alist.h @@ -16,11 +16,13 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: alist.h,v 1.3 2004/03/05 05:12:15 marka Exp $ */ +/* $Id: alist.h,v 1.4 2005/04/27 04:57:26 sra Exp $ */ #ifndef ISCCC_ALIST_H #define ISCCC_ALIST_H 1 +/*! \file */ + #include #include diff --git a/lib/isccc/include/isccc/base64.h b/lib/isccc/include/isccc/base64.h index e6da3ee78e..fadc4a7740 100644 --- a/lib/isccc/include/isccc/base64.h +++ b/lib/isccc/include/isccc/base64.h @@ -16,11 +16,13 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: base64.h,v 1.3 2004/03/05 05:12:15 marka Exp $ */ +/* $Id: base64.h,v 1.4 2005/04/27 04:57:26 sra Exp $ */ #ifndef ISCCC_BASE64_H #define ISCCC_BASE64_H 1 +/*! \file */ + #include #include @@ -33,36 +35,36 @@ ISC_LANG_BEGINDECLS isc_result_t isccc_base64_encode(isccc_region_t *source, int wordlength, const char *wordbreak, isccc_region_t *target); -/* +/*%< * Convert data into base64 encoded text. * * Notes: - * The base64 encoded text in 'target' will be divided into + *\li The base64 encoded text in 'target' will be divided into * words of at most 'wordlength' characters, separated by * the 'wordbreak' string. No parentheses will surround * the text. * * Requires: - * 'source' is a region containing binary data. - * 'target' is a text region containing available space. - * 'wordbreak' points to a null-terminated string of + *\li 'source' is a region containing binary data. + *\li 'target' is a text region containing available space. + *\li 'wordbreak' points to a null-terminated string of * zero or more whitespace characters. */ isc_result_t isccc_base64_decode(const char *cstr, isccc_region_t *target); -/* +/*%< * Decode a null-terminated base64 string. * * Requires: - * 'cstr' is non-null. - * 'target' is a valid region. + *\li 'cstr' is non-null. + *\li 'target' is a valid region. * * Returns: - * ISC_R_SUCCESS -- the entire decoded representation of 'cstring' + *\li #ISC_R_SUCCESS -- the entire decoded representation of 'cstring' * fit in 'target'. - * ISC_R_BADBASE64 -- 'cstr' is not a valid base64 encoding. - * ISC_R_NOSPACE -- 'target' is not big enough. + *\li #ISC_R_BADBASE64 -- 'cstr' is not a valid base64 encoding. + *\li #ISC_R_NOSPACE -- 'target' is not big enough. */ ISC_LANG_ENDDECLS diff --git a/lib/isccc/include/isccc/cc.h b/lib/isccc/include/isccc/cc.h index fa96b8c329..c1bba8f4b5 100644 --- a/lib/isccc/include/isccc/cc.h +++ b/lib/isccc/include/isccc/cc.h @@ -16,69 +16,90 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: cc.h,v 1.4 2004/03/05 05:12:15 marka Exp $ */ +/* $Id: cc.h,v 1.5 2005/04/27 04:57:26 sra Exp $ */ #ifndef ISCCC_CC_H #define ISCCC_CC_H 1 +/*! \file */ + #include #include ISC_LANG_BEGINDECLS +/*% Maximum Datagram Package */ #define ISCCC_CC_MAXDGRAMPACKET 4096 +/*% Message Type String */ #define ISCCC_CCMSGTYPE_STRING 0x00 +/*% Message Type Binary Data */ #define ISCCC_CCMSGTYPE_BINARYDATA 0x01 +/*% Message Type Table */ #define ISCCC_CCMSGTYPE_TABLE 0x02 +/*% Message Type List */ #define ISCCC_CCMSGTYPE_LIST 0x03 +/*% Send to Wire */ isc_result_t isccc_cc_towire(isccc_sexpr_t *alist, isccc_region_t *target, isccc_region_t *secret); +/*% Get From Wire */ isc_result_t isccc_cc_fromwire(isccc_region_t *source, isccc_sexpr_t **alistp, isccc_region_t *secret); +/*% Create Message */ isc_result_t isccc_cc_createmessage(isc_uint32_t version, const char *from, const char *to, isc_uint32_t serial, isccc_time_t now, isccc_time_t expires, isccc_sexpr_t **alistp); +/*% Create Acknowledgment */ isc_result_t isccc_cc_createack(isccc_sexpr_t *message, isc_boolean_t ok, isccc_sexpr_t **ackp); +/*% Is Ack? */ isc_boolean_t isccc_cc_isack(isccc_sexpr_t *message); +/*% Is Reply? */ isc_boolean_t isccc_cc_isreply(isccc_sexpr_t *message); +/*% Create Response */ isc_result_t isccc_cc_createresponse(isccc_sexpr_t *message, isccc_time_t now, isccc_time_t expires, isccc_sexpr_t **alistp); +/*% Define String */ isccc_sexpr_t * isccc_cc_definestring(isccc_sexpr_t *alist, const char *key, const char *str); +/*% Define uint 32 */ isccc_sexpr_t * isccc_cc_defineuint32(isccc_sexpr_t *alist, const char *key, isc_uint32_t i); +/*% Lookup String */ isc_result_t isccc_cc_lookupstring(isccc_sexpr_t *alist, const char *key, char **strp); +/*% Lookup uint 32 */ isc_result_t isccc_cc_lookupuint32(isccc_sexpr_t *alist, const char *key, isc_uint32_t *uintp); +/*% Create Symbol Table */ isc_result_t isccc_cc_createsymtab(isccc_symtab_t **symtabp); +/*% Clean up Symbol Table */ void isccc_cc_cleansymtab(isccc_symtab_t *symtab, isccc_time_t now); +/*% Check for Duplicates */ isc_result_t isccc_cc_checkdup(isccc_symtab_t *symtab, isccc_sexpr_t *message, isccc_time_t now); diff --git a/lib/isccc/include/isccc/ccmsg.h b/lib/isccc/include/isccc/ccmsg.h index ea640924a8..610c777fe2 100644 --- a/lib/isccc/include/isccc/ccmsg.h +++ b/lib/isccc/include/isccc/ccmsg.h @@ -16,15 +16,18 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ccmsg.h,v 1.4 2004/03/05 05:12:15 marka Exp $ */ +/* $Id: ccmsg.h,v 1.5 2005/04/27 04:57:26 sra Exp $ */ #ifndef ISCCC_CCMSG_H #define ISCCC_CCMSG_H 1 +/*! \file */ + #include #include #include +/*% ISCCC Message Structure */ typedef struct isccc_ccmsg { /* private (don't touch!) */ unsigned int magic; @@ -46,56 +49,56 @@ ISC_LANG_BEGINDECLS void isccc_ccmsg_init(isc_mem_t *mctx, isc_socket_t *sock, isccc_ccmsg_t *ccmsg); -/* +/*% * Associate a cc message state with a given memory context and * TCP socket. * * Requires: * - * "mctx" and "sock" be non-NULL and valid types. + *\li "mctx" and "sock" be non-NULL and valid types. * - * "sock" be a read/write TCP socket. + *\li "sock" be a read/write TCP socket. * - * "ccmsg" be non-NULL and an uninitialized or invalidated structure. + *\li "ccmsg" be non-NULL and an uninitialized or invalidated structure. * * Ensures: * - * "ccmsg" is a valid structure. + *\li "ccmsg" is a valid structure. */ void isccc_ccmsg_setmaxsize(isccc_ccmsg_t *ccmsg, unsigned int maxsize); -/* +/*% * Set the maximum packet size to "maxsize" * * Requires: * - * "ccmsg" be valid. + *\li "ccmsg" be valid. * - * 512 <= "maxsize" <= 4294967296 + *\li 512 <= "maxsize" <= 4294967296 */ isc_result_t isccc_ccmsg_readmessage(isccc_ccmsg_t *ccmsg, isc_task_t *task, isc_taskaction_t action, void *arg); -/* +/*% * Schedule an event to be delivered when a command channel message is * readable, or when an error occurs on the socket. * * Requires: * - * "ccmsg" be valid. + *\li "ccmsg" be valid. * - * "task", "taskaction", and "arg" be valid. + *\li "task", "taskaction", and "arg" be valid. * * Returns: * - * ISC_R_SUCCESS -- no error - * Anything that the isc_socket_recv() call can return. XXXMLG + *\li #ISC_R_SUCCESS -- no error + *\li Anything that the isc_socket_recv() call can return. XXXMLG * * Notes: * - * The event delivered is a fully generic event. It will contain no + *\li The event delivered is a fully generic event. It will contain no * actual data. The sender will be a pointer to the isccc_ccmsg_t. * The result code inside that structure should be checked to see * what the final result was. @@ -103,27 +106,27 @@ isccc_ccmsg_readmessage(isccc_ccmsg_t *ccmsg, void isccc_ccmsg_cancelread(isccc_ccmsg_t *ccmsg); -/* +/*% * Cancel a readmessage() call. The event will still be posted with a * CANCELED result code. * * Requires: * - * "ccmsg" be valid. + *\li "ccmsg" be valid. */ void isccc_ccmsg_invalidate(isccc_ccmsg_t *ccmsg); -/* +/*% * Clean up all allocated state, and invalidate the structure. * * Requires: * - * "ccmsg" be valid. + *\li "ccmsg" be valid. * * Ensures: * - * "ccmsg" is invalidated and disassociated with all memory contexts, + *\li "ccmsg" is invalidated and disassociated with all memory contexts, * sockets, etc. */ diff --git a/lib/isccc/include/isccc/events.h b/lib/isccc/include/isccc/events.h index 4612265d54..b9b3fef6e9 100644 --- a/lib/isccc/include/isccc/events.h +++ b/lib/isccc/include/isccc/events.h @@ -16,14 +16,16 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: events.h,v 1.3 2004/03/05 05:12:15 marka Exp $ */ +/* $Id: events.h,v 1.4 2005/04/27 04:57:26 sra Exp $ */ #ifndef ISCCC_EVENTS_H #define ISCCC_EVENTS_H 1 +/*! \file */ + #include -/* +/*% * Registry of ISCCC event numbers. */ diff --git a/lib/isccc/include/isccc/lib.h b/lib/isccc/include/isccc/lib.h index 67ac7ea4f3..ae1eefa206 100644 --- a/lib/isccc/include/isccc/lib.h +++ b/lib/isccc/include/isccc/lib.h @@ -16,11 +16,13 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lib.h,v 1.4 2004/03/05 05:12:15 marka Exp $ */ +/* $Id: lib.h,v 1.5 2005/04/27 04:57:27 sra Exp $ */ #ifndef ISCCC_LIB_H #define ISCCC_LIB_H 1 +/*! \file */ + #include #include @@ -30,7 +32,7 @@ LIBISCCC_EXTERNAL_DATA extern isc_msgcat_t *isccc_msgcat; void isccc_lib_initmsgcat(void); -/* +/*% * Initialize the ISCCC library's message catalog, isccc_msgcat, if it * has not already been initialized. */ diff --git a/lib/isccc/include/isccc/result.h b/lib/isccc/include/isccc/result.h index fae665c150..1567103866 100644 --- a/lib/isccc/include/isccc/result.h +++ b/lib/isccc/include/isccc/result.h @@ -16,31 +16,39 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: result.h,v 1.5 2004/03/05 05:12:15 marka Exp $ */ +/* $Id: result.h,v 1.6 2005/04/27 04:57:27 sra Exp $ */ #ifndef ISCCC_RESULT_H #define ISCCC_RESULT_H 1 +/*! \file */ + #include #include #include #include +/*% Unknown Version */ #define ISCCC_R_UNKNOWNVERSION (ISC_RESULTCLASS_ISCCC + 0) +/*% Syntax Error */ #define ISCCC_R_SYNTAX (ISC_RESULTCLASS_ISCCC + 1) +/*% Bad Authorization */ #define ISCCC_R_BADAUTH (ISC_RESULTCLASS_ISCCC + 2) +/*% Expired */ #define ISCCC_R_EXPIRED (ISC_RESULTCLASS_ISCCC + 3) +/*% Clock Skew */ #define ISCCC_R_CLOCKSKEW (ISC_RESULTCLASS_ISCCC + 4) +/*% Duplicate */ #define ISCCC_R_DUPLICATE (ISC_RESULTCLASS_ISCCC + 5) -#define ISCCC_R_NRESULTS 6 /* Number of results */ +#define ISCCC_R_NRESULTS 6 /*%< Number of results */ ISC_LANG_BEGINDECLS const char * isccc_result_totext(isc_result_t result); -/* +/*% * Convert a isccc_result_t into a string message describing the result. */ diff --git a/lib/isccc/include/isccc/sexpr.h b/lib/isccc/include/isccc/sexpr.h index 0aa42402fa..00c62402f0 100644 --- a/lib/isccc/include/isccc/sexpr.h +++ b/lib/isccc/include/isccc/sexpr.h @@ -16,11 +16,13 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sexpr.h,v 1.4 2004/03/05 05:12:16 marka Exp $ */ +/* $Id: sexpr.h,v 1.5 2005/04/27 04:57:27 sra Exp $ */ #ifndef ISCCC_SEXPR_H #define ISCCC_SEXPR_H 1 +/*! \file */ + #include #include @@ -28,11 +30,13 @@ ISC_LANG_BEGINDECLS +/*% dotted pair structure */ struct isccc_dottedpair { isccc_sexpr_t *car; isccc_sexpr_t *cdr; }; +/*% iscc_sexpr structure */ struct isccc_sexpr { unsigned int type; union { @@ -42,7 +46,7 @@ struct isccc_sexpr { } value; }; -#define ISCCC_SEXPRTYPE_NONE 0x00 /* Illegal. */ +#define ISCCC_SEXPRTYPE_NONE 0x00 /*%< Illegal. */ #define ISCCC_SEXPRTYPE_T 0x01 #define ISCCC_SEXPRTYPE_STRING 0x02 #define ISCCC_SEXPRTYPE_DOTTEDPAIR 0x03 diff --git a/lib/isccc/include/isccc/symtab.h b/lib/isccc/include/isccc/symtab.h index ea0aedaebf..78852b02ed 100644 --- a/lib/isccc/include/isccc/symtab.h +++ b/lib/isccc/include/isccc/symtab.h @@ -16,7 +16,7 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: symtab.h,v 1.3 2004/03/05 05:12:16 marka Exp $ */ +/* $Id: symtab.h,v 1.4 2005/04/27 04:57:27 sra Exp $ */ #ifndef ISCCC_SYMTAB_H #define ISCCC_SYMTAB_H 1 @@ -25,9 +25,8 @@ ***** Module Info *****/ -/* - * Symbol Table - * +/*! \file + * \brief * Provides a simple memory-based symbol table. * * Keys are C strings. A type may be specified when looking up, @@ -39,11 +38,11 @@ * exists in the table. What to do in this case is specified by the * client. Possible policies are: * - * isccc_symexists_reject Disallow the define, returning ISC_R_EXISTS - * isccc_symexists_replace Replace the old value with the new. The + *\li isccc_symexists_reject Disallow the define, returning #ISC_R_EXISTS + *\li isccc_symexists_replace Replace the old value with the new. The * undefine action (if provided) will be called * with the old tuple. - * isccc_symexists_add Add the new tuple, leaving the old tuple in + *\li isccc_symexists_add Add the new tuple, leaving the old tuple in * the table. Subsequent lookups will retrieve * the most-recently-defined tuple. * diff --git a/lib/isccc/include/isccc/symtype.h b/lib/isccc/include/isccc/symtype.h index 9f5b63aa5b..10a73d4e21 100644 --- a/lib/isccc/include/isccc/symtype.h +++ b/lib/isccc/include/isccc/symtype.h @@ -16,11 +16,13 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: symtype.h,v 1.3 2004/03/05 05:12:16 marka Exp $ */ +/* $Id: symtype.h,v 1.4 2005/04/27 04:57:27 sra Exp $ */ #ifndef ISCCC_SYMTYPE_H #define ISCCC_SYMTYPE_H 1 +/*! \file */ + #define ISCCC_SYMTYPE_ZONESTATS 0x0001 #define ISCCC_SYMTYPE_CCDUP 0x0002 #define ISCCC_SYMTYPE_TELLSERVICE 0x0003 diff --git a/lib/isccc/include/isccc/types.h b/lib/isccc/include/isccc/types.h index 8a17d6ae9b..a1ab757cc7 100644 --- a/lib/isccc/include/isccc/types.h +++ b/lib/isccc/include/isccc/types.h @@ -16,20 +16,28 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: types.h,v 1.3 2004/03/05 05:12:16 marka Exp $ */ +/* $Id: types.h,v 1.4 2005/04/27 04:57:27 sra Exp $ */ #ifndef ISCCC_TYPES_H #define ISCCC_TYPES_H 1 +/*! \file */ + #include #include #include +/*% isccc_time_t typedef */ typedef isc_uint32_t isccc_time_t; + +/*% isccc_sexpr_t typedef */ typedef struct isccc_sexpr isccc_sexpr_t; +/*% isccc_dottedpair_t typedef */ typedef struct isccc_dottedpair isccc_dottedpair_t; +/*% isccc_symtab_t typedef */ typedef struct isccc_symtab isccc_symtab_t; +/*% iscc region structure */ typedef struct isccc_region { unsigned char * rstart; unsigned char * rend; diff --git a/lib/isccc/include/isccc/util.h b/lib/isccc/include/isccc/util.h index c8b4d103ec..ef4b398e7b 100644 --- a/lib/isccc/include/isccc/util.h +++ b/lib/isccc/include/isccc/util.h @@ -16,17 +16,18 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: util.h,v 1.4 2004/03/05 05:12:16 marka Exp $ */ +/* $Id: util.h,v 1.5 2005/04/27 04:57:27 sra Exp $ */ #ifndef ISCCC_UTIL_H #define ISCCC_UTIL_H 1 #include -/* +/*! \file + * \brief * Macros for dealing with unaligned numbers. * - * Note: no side effects are allowed when invoking these macros! + * \note no side effects are allowed when invoking these macros! */ #define GET8(v, w) \ @@ -193,7 +194,7 @@ (r).rend = (r).rstart + strlen(s); \ } while (0) -/* +/*% * Use this to remove the const qualifier of a variable to assign it to * a non-const variable or pass it as a non-const function argument ... * but only when you are sure it won't then be changed! diff --git a/lib/isccc/include/isccc/version.h b/lib/isccc/include/isccc/version.h index 782294399a..9ec7a7817d 100644 --- a/lib/isccc/include/isccc/version.h +++ b/lib/isccc/include/isccc/version.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.h,v 1.3 2004/03/05 05:12:16 marka Exp $ */ +/* $Id: version.h,v 1.4 2005/04/27 04:57:27 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccc/lib.c b/lib/isccc/lib.c index ec7fdde46f..f0d7bdaa20 100644 --- a/lib/isccc/lib.c +++ b/lib/isccc/lib.c @@ -16,7 +16,9 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lib.c,v 1.4 2004/03/05 05:12:10 marka Exp $ */ +/* $Id: lib.c,v 1.5 2005/04/27 04:57:25 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccc/result.c b/lib/isccc/result.c index 8137421c58..e28a7fee5a 100644 --- a/lib/isccc/result.c +++ b/lib/isccc/result.c @@ -16,7 +16,9 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: result.c,v 1.5 2004/03/05 05:12:10 marka Exp $ */ +/* $Id: result.c,v 1.6 2005/04/27 04:57:25 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccc/sexpr.c b/lib/isccc/sexpr.c index 43cd36b3e1..ebd4f44862 100644 --- a/lib/isccc/sexpr.c +++ b/lib/isccc/sexpr.c @@ -16,7 +16,9 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: sexpr.c,v 1.4 2004/03/05 05:12:10 marka Exp $ */ +/* $Id: sexpr.c,v 1.5 2005/04/27 04:57:25 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccc/symtab.c b/lib/isccc/symtab.c index 6f0dcde572..bb415fdb39 100644 --- a/lib/isccc/symtab.c +++ b/lib/isccc/symtab.c @@ -16,7 +16,9 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: symtab.c,v 1.5 2004/03/05 05:12:11 marka Exp $ */ +/* $Id: symtab.c,v 1.6 2005/04/27 04:57:25 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccc/version.c b/lib/isccc/version.c index c4e998d7d6..5a5d880ec8 100644 --- a/lib/isccc/version.c +++ b/lib/isccc/version.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.c,v 1.3 2004/03/05 05:12:11 marka Exp $ */ +/* $Id: version.c,v 1.4 2005/04/27 04:57:25 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccfg/include/isccfg/cfg.h b/lib/isccfg/include/isccfg/cfg.h index a13567f544..398b208f7f 100644 --- a/lib/isccfg/include/isccfg/cfg.h +++ b/lib/isccfg/include/isccfg/cfg.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: cfg.h,v 1.34 2004/03/05 05:12:26 marka Exp $ */ +/* $Id: cfg.h,v 1.35 2005/04/27 04:57:28 sra Exp $ */ #ifndef ISCCFG_CFG_H #define ISCCFG_CFG_H 1 @@ -24,7 +24,8 @@ ***** Module Info *****/ -/* +/*! \file + * \brief * This is the new, table-driven, YACC-free configuration file parser. */ @@ -42,19 +43,19 @@ *** Types ***/ -typedef struct cfg_parser cfg_parser_t; -/* +/*% * A configuration parser. */ +typedef struct cfg_parser cfg_parser_t; -/* +/*% * A configuration type definition object. There is a single * static cfg_type_t object for each data type supported by * the configuration parser. */ typedef struct cfg_type cfg_type_t; -/* +/*% * A configuration object. This is the basic building block of the * configuration parse tree. It contains a value (which may be * of one of several types) and information identifying the file @@ -63,12 +64,12 @@ typedef struct cfg_type cfg_type_t; */ typedef struct cfg_obj cfg_obj_t; -/* +/*% * A configuration object list element. */ typedef struct cfg_listelt cfg_listelt_t; -/* +/*% * A callback function to be called when parsing an option * that needs to be interpreted at parsing time, like * "directory". @@ -84,7 +85,7 @@ ISC_LANG_BEGINDECLS isc_result_t cfg_parser_create(isc_mem_t *mctx, isc_log_t *lctx, cfg_parser_t **ret); -/* +/*%< * Create a configuration file parser. Any warning and error * messages will be logged to 'lctx'. * @@ -97,7 +98,7 @@ void cfg_parser_setcallback(cfg_parser_t *pctx, cfg_parsecallback_t callback, void *arg); -/* +/*%< * Make the parser call 'callback' whenever it encounters * a configuration clause with the callback attribute, * passing it the clause name, the clause value, @@ -113,7 +114,7 @@ cfg_parse_file(cfg_parser_t *pctx, const char *filename, isc_result_t cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer, const cfg_type_t *type, cfg_obj_t **ret); -/* +/*%< * Read a configuration containing data of type 'type' * and make '*ret' point to its parse tree. * @@ -124,246 +125,246 @@ cfg_parse_buffer(cfg_parser_t *pctx, isc_buffer_t *buffer, * Returns an error if the file does not parse correctly. * * Requires: - * "filename" is valid. - * "mem" is valid. - * "type" is valid. - * "cfg" is non-NULL and "*cfg" is NULL. + *\li "filename" is valid. + *\li "mem" is valid. + *\li "type" is valid. + *\li "cfg" is non-NULL and "*cfg" is NULL. * * Returns: - * ISC_R_SUCCESS - success - * ISC_R_NOMEMORY - no memory available - * ISC_R_INVALIDFILE - file doesn't exist or is unreadable - * others - file contains errors + * \li #ISC_R_SUCCESS - success + *\li #ISC_R_NOMEMORY - no memory available + *\li #ISC_R_INVALIDFILE - file doesn't exist or is unreadable + *\li others - file contains errors */ void cfg_parser_destroy(cfg_parser_t **pctxp); -/* +/*%< * Destroy a configuration parser. */ isc_boolean_t cfg_obj_isvoid(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is of void type (e.g., an optional * value not specified). */ isc_boolean_t cfg_obj_ismap(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is of a map type. */ isc_result_t cfg_map_get(cfg_obj_t *mapobj, const char* name, cfg_obj_t **obj); -/* +/*%< * Extract an element from a configuration object, which * must be of a map type. * * Requires: - * 'mapobj' points to a valid configuration object of a map type. - * 'name' points to a null-terminated string. - * 'obj' is non-NULL and '*obj' is NULL. + * \li 'mapobj' points to a valid configuration object of a map type. + * \li 'name' points to a null-terminated string. + * \li 'obj' is non-NULL and '*obj' is NULL. * * Returns: - * ISC_R_SUCCESS - success - * ISC_R_NOTFOUND - name not found in map + * \li #ISC_R_SUCCESS - success + * \li #ISC_R_NOTFOUND - name not found in map */ cfg_obj_t * cfg_map_getname(cfg_obj_t *mapobj); -/* +/*%< * Get the name of a named map object, like a server "key" clause. * * Requires: - * 'mapobj' points to a valid configuration object of a map type. + * \li 'mapobj' points to a valid configuration object of a map type. * * Returns: - * A pointer to a configuration object naming the map object, + * \li A pointer to a configuration object naming the map object, * or NULL if the map object does not have a name. */ isc_boolean_t cfg_obj_istuple(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is of a map type. */ cfg_obj_t * cfg_tuple_get(cfg_obj_t *tupleobj, const char *name); -/* +/*%< * Extract an element from a configuration object, which * must be of a tuple type. * * Requires: - * 'tupleobj' points to a valid configuration object of a tuple type. - * 'name' points to a null-terminated string naming one of the - * fields of said tuple type. + * \li 'tupleobj' points to a valid configuration object of a tuple type. + * \li 'name' points to a null-terminated string naming one of the + *\li fields of said tuple type. */ isc_boolean_t cfg_obj_isuint32(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is of integer type. */ isc_uint32_t cfg_obj_asuint32(cfg_obj_t *obj); -/* +/*%< * Returns the value of a configuration object of 32-bit integer type. * * Requires: - * 'obj' points to a valid configuration object of 32-bit integer type. + * \li 'obj' points to a valid configuration object of 32-bit integer type. * * Returns: - * A 32-bit unsigned integer. + * \li A 32-bit unsigned integer. */ isc_boolean_t cfg_obj_isuint64(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is of integer type. */ isc_uint64_t cfg_obj_asuint64(cfg_obj_t *obj); -/* +/*%< * Returns the value of a configuration object of 64-bit integer type. * * Requires: - * 'obj' points to a valid configuration object of 64-bit integer type. + * \li 'obj' points to a valid configuration object of 64-bit integer type. * * Returns: - * A 64-bit unsigned integer. + * \li A 64-bit unsigned integer. */ isc_boolean_t cfg_obj_isstring(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is of string type. */ char * cfg_obj_asstring(cfg_obj_t *obj); -/* +/*%< * Returns the value of a configuration object of a string type * as a null-terminated string. * * Requires: - * 'obj' points to a valid configuration object of a string type. + * \li 'obj' points to a valid configuration object of a string type. * * Returns: - * A pointer to a null terminated string. + * \li A pointer to a null terminated string. */ isc_boolean_t cfg_obj_isboolean(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is of a boolean type. */ isc_boolean_t cfg_obj_asboolean(cfg_obj_t *obj); -/* +/*%< * Returns the value of a configuration object of a boolean type. * * Requires: - * 'obj' points to a valid configuration object of a boolean type. + * \li 'obj' points to a valid configuration object of a boolean type. * * Returns: - * A boolean value. + * \li A boolean value. */ isc_boolean_t cfg_obj_issockaddr(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is a socket address. */ isc_sockaddr_t * cfg_obj_assockaddr(cfg_obj_t *obj); -/* +/*%< * Returns the value of a configuration object representing a socket address. * * Requires: - * 'obj' points to a valid configuration object of a socket address type. + * \li 'obj' points to a valid configuration object of a socket address type. * * Returns: - * A pointer to a sockaddr. The sockaddr must be copied by the caller + * \li A pointer to a sockaddr. The sockaddr must be copied by the caller * if necessary. */ isc_boolean_t cfg_obj_isnetprefix(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is a network prefix. */ void cfg_obj_asnetprefix(cfg_obj_t *obj, isc_netaddr_t *netaddr, unsigned int *prefixlen); -/* +/*%< * Gets the value of a configuration object representing a network * prefix. The network address is returned through 'netaddr' and the * prefix length in bits through 'prefixlen'. * * Requires: - * 'obj' points to a valid configuration object of network prefix type. - * 'netaddr' and 'prefixlen' are non-NULL. + * \li 'obj' points to a valid configuration object of network prefix type. + *\li 'netaddr' and 'prefixlen' are non-NULL. */ isc_boolean_t cfg_obj_islist(cfg_obj_t *obj); -/* +/*%< * Return true iff 'obj' is of list type. */ cfg_listelt_t * cfg_list_first(cfg_obj_t *obj); -/* +/*%< * Returns the first list element in a configuration object of a list type. * * Requires: - * 'obj' points to a valid configuration object of a list type or NULL. + * \li 'obj' points to a valid configuration object of a list type or NULL. * * Returns: - * A pointer to a cfg_listelt_t representing the first list element, + * \li A pointer to a cfg_listelt_t representing the first list element, * or NULL if the list is empty or nonexistent. */ cfg_listelt_t * cfg_list_next(cfg_listelt_t *elt); -/* +/*%< * Returns the next element of a list of configuration objects. * * Requires: - * 'elt' points to cfg_listelt_t obtained from cfg_list_first() or + * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or * a previous call to cfg_list_next(). * * Returns: - * A pointer to a cfg_listelt_t representing the next element, + * \li A pointer to a cfg_listelt_t representing the next element, * or NULL if there are no more elements. */ cfg_obj_t * cfg_listelt_value(cfg_listelt_t *elt); -/* +/*%< * Returns the configuration object associated with cfg_listelt_t. * * Requires: - * 'elt' points to cfg_listelt_t obtained from cfg_list_first() or + * \li 'elt' points to cfg_listelt_t obtained from cfg_list_first() or * cfg_list_next(). * * Returns: - * A non-NULL pointer to a configuration object. + * \li A non-NULL pointer to a configuration object. */ void cfg_print(cfg_obj_t *obj, void (*f)(void *closure, const char *text, int textlen), void *closure); -/* +/*%< * Print the configuration object 'obj' by repeatedly calling the * function 'f', passing 'closure' and a region of text starting * at 'text' and comprising 'textlen' characters. @@ -373,25 +374,25 @@ void cfg_print_grammar(const cfg_type_t *type, void (*f)(void *closure, const char *text, int textlen), void *closure); -/* +/*%< * Print a summary of the grammar of the configuration type 'type'. */ isc_boolean_t cfg_obj_istype(cfg_obj_t *obj, const cfg_type_t *type); -/* +/*%< * Return true iff 'obj' is of type 'type'. */ void cfg_obj_destroy(cfg_parser_t *pctx, cfg_obj_t **obj); -/* +/*%< * Destroy a configuration object. */ void cfg_obj_log(cfg_obj_t *obj, isc_log_t *lctx, int level, const char *fmt, ...) ISC_FORMAT_PRINTF(4, 5); -/* +/*%< * Log a message concerning configuration object 'obj' to the logging * channel of 'pctx', at log level 'level'. The message will be prefixed * with the file name(s) and line number where 'obj' was defined. @@ -399,13 +400,13 @@ cfg_obj_log(cfg_obj_t *obj, isc_log_t *lctx, int level, const char *fmt, ...) const char * cfg_obj_file(cfg_obj_t *obj); -/* +/*%< * Return the file that defined this object. */ unsigned int cfg_obj_line(cfg_obj_t *obj); -/* +/*%< * Return the line in file where this object was defined. */ diff --git a/lib/isccfg/include/isccfg/grammar.h b/lib/isccfg/include/isccfg/grammar.h index 0c54acaa89..64e638ba7c 100644 --- a/lib/isccfg/include/isccfg/grammar.h +++ b/lib/isccfg/include/isccfg/grammar.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: grammar.h,v 1.8 2005/01/17 23:58:33 marka Exp $ */ +/* $Id: grammar.h,v 1.9 2005/04/27 04:57:28 sra Exp $ */ #ifndef ISCCFG_GRAMMAR_H #define ISCCFG_GRAMMAR_H 1 +/*! \file */ + #include #include #include @@ -33,17 +35,17 @@ * and the grammars; not visible to users of the parser. */ -/* Clause may occur multiple times (e.g., "zone") */ +/*% Clause may occur multiple times (e.g., "zone") */ #define CFG_CLAUSEFLAG_MULTI 0x00000001 -/* Clause is obsolete */ +/*% Clause is obsolete */ #define CFG_CLAUSEFLAG_OBSOLETE 0x00000002 -/* Clause is not implemented, and may never be */ +/*% Clause is not implemented, and may never be */ #define CFG_CLAUSEFLAG_NOTIMP 0x00000004 -/* Clause is not implemented yet */ +/*% Clause is not implemented yet */ #define CFG_CLAUSEFLAG_NYI 0x00000008 -/* Default value has changed since earlier release */ +/*% Default value has changed since earlier release */ #define CFG_CLAUSEFLAG_NEWDEFAULT 0x00000010 -/* +/*% * Clause needs to be interpreted during parsing * by calling a callback function, like the * "directory" option. @@ -71,7 +73,7 @@ typedef void (*cfg_freefunc_t)(cfg_parser_t *, cfg_obj_t *); * Structure definitions */ -/* +/*% * A configuration printer object. This is an abstract * interface to a destination to which text can be printed * by calling the function 'f'. @@ -82,42 +84,39 @@ struct cfg_printer { int indent; }; -/* A clause definition. */ - +/*% A clause definition. */ struct cfg_clausedef { const char *name; cfg_type_t *type; unsigned int flags; }; -/* A tuple field definition. */ - +/*% A tuple field definition. */ struct cfg_tuplefielddef { const char *name; cfg_type_t *type; unsigned int flags; }; -/* A configuration object type definition. */ +/*% A configuration object type definition. */ struct cfg_type { - const char *name; /* For debugging purposes only */ + const char *name; /*%< For debugging purposes only */ cfg_parsefunc_t parse; cfg_printfunc_t print; - cfg_docfunc_t doc; /* Print grammar description */ - cfg_rep_t * rep; /* Data representation */ - const void * of; /* Additional data for meta-types */ + cfg_docfunc_t doc; /*%< Print grammar description */ + cfg_rep_t * rep; /*%< Data representation */ + const void * of; /*%< Additional data for meta-types */ }; -/* A keyword-type definition, for things like "port ". */ - +/*% A keyword-type definition, for things like "port ". */ typedef struct { const char *name; const cfg_type_t *type; } keyword_type_t; struct cfg_map { - cfg_obj_t *id; /* Used for 'named maps' like keys, zones, &c */ - const cfg_clausedef_t * const *clausesets; /* The clauses that + cfg_obj_t *id; /*%< Used for 'named maps' like keys, zones, &c */ + const cfg_clausedef_t * const *clausesets; /*%< The clauses that can occur in this map; used for printing */ isc_symtab_t *symtab; @@ -130,15 +129,15 @@ struct cfg_netprefix { unsigned int prefixlen; }; -/* +/*% * A configuration data representation. */ struct cfg_rep { - const char * name; /* For debugging only */ - cfg_freefunc_t free; /* How to free this kind of data. */ + const char * name; /*%< For debugging only */ + cfg_freefunc_t free; /*%< How to free this kind of data. */ }; -/* +/*% * A configuration object. This is the main building block * of the configuration parse tree. */ @@ -148,7 +147,7 @@ struct cfg_obj { union { isc_uint32_t uint32; isc_uint64_t uint64; - isc_textregion_t string; /* null terminated, too */ + isc_textregion_t string; /*%< null terminated, too */ isc_boolean_t boolean; cfg_map_t map; cfg_list_t list; @@ -161,14 +160,13 @@ struct cfg_obj { }; -/* A list element. */ - +/*% A list element. */ struct cfg_listelt { cfg_obj_t *obj; ISC_LINK(cfg_listelt_t) link; }; -/* The parser object. */ +/*% The parser object. */ struct cfg_parser { isc_mem_t * mctx; isc_log_t * lctx; @@ -177,13 +175,13 @@ struct cfg_parser { unsigned int warnings; isc_token_t token; - /* We are at the end of all input. */ + /*% We are at the end of all input. */ isc_boolean_t seen_eof; - /* The current token has been pushed back. */ + /*% The current token has been pushed back. */ isc_boolean_t ungotten; - /* + /*% * The stack of currently active files, represented * as a configuration list of configuration strings. * The head is the top-level file, subsequent elements @@ -192,7 +190,7 @@ struct cfg_parser { */ cfg_obj_t * open_files; - /* + /*% * Names of files that we have parsed and closed * and were previously on the open_file list. * We keep these objects around after closing @@ -203,7 +201,7 @@ struct cfg_parser { */ cfg_obj_t * closed_files; - /* + /*% * Current line number. We maintain our own * copy of this so that it is available even * when a file has just been closed. @@ -215,15 +213,18 @@ struct cfg_parser { }; -/* +/*@{*/ +/*% * Flags defining whether to accept certain types of network addresses. */ #define CFG_ADDR_V4OK 0x00000001 #define CFG_ADDR_V4PREFIXOK 0x00000002 #define CFG_ADDR_V6OK 0x00000004 #define CFG_ADDR_WILDOK 0x00000008 +/*@}*/ -/* +/*@{*/ +/*% * Predefined data representation types. */ LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_uint32; @@ -236,8 +237,10 @@ LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_tuple; LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_sockaddr; LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_netprefix; LIBISCCFG_EXTERNAL_DATA extern cfg_rep_t cfg_rep_void; +/*@}*/ -/* +/*@{*/ +/*% * Predefined configuration object types. */ LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_boolean; @@ -256,6 +259,7 @@ LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_netprefix; LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_void; LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_token; LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_unsupported; +/*@}*/ isc_result_t cfg_gettoken(cfg_parser_t *pctx, int options); @@ -318,7 +322,7 @@ cfg_parse_netprefix(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) isc_result_t cfg_parse_special(cfg_parser_t *pctx, int special); -/* Parse a required special character 'special'. */ +/*%< Parse a required special character 'special'. */ isc_result_t cfg_create_tuple(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **objp); @@ -362,11 +366,11 @@ cfg_doc_enum(cfg_printer_t *pctx, const cfg_type_t *type); void cfg_print_chars(cfg_printer_t *pctx, const char *text, int len); -/* Print 'len' characters at 'text' */ +/*%< Print 'len' characters at 'text' */ void cfg_print_cstr(cfg_printer_t *pctx, const char *s); -/* Print the null-terminated string 's' */ +/*%< Print the null-terminated string 's' */ isc_result_t cfg_parse_map(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret); @@ -413,28 +417,28 @@ cfg_print_obj(cfg_printer_t *pctx, cfg_obj_t *obj); void cfg_doc_obj(cfg_printer_t *pctx, const cfg_type_t *type); -/* +/*%< * Print a description of the grammar of an arbitrary configuration * type 'type' */ void cfg_doc_terminal(cfg_printer_t *pctx, const cfg_type_t *type); -/* +/*%< * Document the type 'type' as a terminal by printing its - * name in angle brackets, e.g., . + * name in angle brackets, e.g., <uint32>. */ void cfg_parser_error(cfg_parser_t *pctx, unsigned int flags, const char *fmt, ...) ISC_FORMAT_PRINTF(3, 4); -/* +/*! * Pass one of these flags to cfg_parser_error() to include the * token text in log message. */ -#define CFG_LOG_NEAR 0x00000001 /* Say "near " */ -#define CFG_LOG_BEFORE 0x00000002 /* Say "before " */ -#define CFG_LOG_NOPREP 0x00000004 /* Say just "" */ +#define CFG_LOG_NEAR 0x00000001 /*%< Say "near " */ +#define CFG_LOG_BEFORE 0x00000002 /*%< Say "before " */ +#define CFG_LOG_NOPREP 0x00000004 /*%< Say just "" */ void cfg_parser_warning(cfg_parser_t *pctx, unsigned int flags, @@ -442,6 +446,6 @@ cfg_parser_warning(cfg_parser_t *pctx, unsigned int flags, isc_boolean_t cfg_is_enum(const char *s, const char *const *enums); -/* Return true iff the string 's' is one of the strings in 'enums' */ +/*%< Return true iff the string 's' is one of the strings in 'enums' */ #endif /* ISCCFG_GRAMMAR_H */ diff --git a/lib/isccfg/include/isccfg/log.h b/lib/isccfg/include/isccfg/log.h index ae43e4e7ee..7d36ce9fc9 100644 --- a/lib/isccfg/include/isccfg/log.h +++ b/lib/isccfg/include/isccfg/log.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: log.h,v 1.6 2004/03/05 05:12:27 marka Exp $ */ +/* $Id: log.h,v 1.7 2005/04/27 04:57:28 sra Exp $ */ #ifndef ISCCFG_LOG_H #define ISCCFG_LOG_H 1 +/*! \file */ + #include #include @@ -34,17 +36,17 @@ ISC_LANG_BEGINDECLS void cfg_log_init(isc_log_t *lctx); -/* +/*%< * Make the libisccfg categories and modules available for use with the * ISC logging library. * * Requires: - * lctx is a valid logging context. + *\li lctx is a valid logging context. * - * cfg_log_init() is called only once. + *\li cfg_log_init() is called only once. * * Ensures: - * The catgories and modules defined above are available for + * \li The catgories and modules defined above are available for * use by isc_log_usechannnel() and isc_log_write(). */ diff --git a/lib/isccfg/include/isccfg/namedconf.h b/lib/isccfg/include/isccfg/namedconf.h index 40d4ed49ae..6b9be22164 100644 --- a/lib/isccfg/include/isccfg/namedconf.h +++ b/lib/isccfg/include/isccfg/namedconf.h @@ -15,12 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: namedconf.h,v 1.3 2004/03/05 05:12:27 marka Exp $ */ +/* $Id: namedconf.h,v 1.4 2005/04/27 04:57:28 sra Exp $ */ #ifndef ISCCFG_NAMEDCONF_H #define ISCCFG_NAMEDCONF_H 1 -/* +/*! \file + * \brief * This module defines the named.conf, rndc.conf, and rndc.key grammars. */ @@ -30,15 +31,15 @@ * Configuration object types. */ LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_namedconf; -/* A complete named.conf file. */ +/*%< A complete named.conf file. */ LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_rndcconf; -/* A complete rndc.conf file. */ +/*%< A complete rndc.conf file. */ LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_rndckey; -/* A complete rndc.key file. */ +/*%< A complete rndc.key file. */ LIBISCCFG_EXTERNAL_DATA extern cfg_type_t cfg_type_keyref; -/* A key reference, used as an ACL element */ +/*%< A key reference, used as an ACL element */ #endif /* ISCCFG_CFG_H */ diff --git a/lib/isccfg/include/isccfg/version.h b/lib/isccfg/include/isccfg/version.h index 9acec1003b..7d5e460a2c 100644 --- a/lib/isccfg/include/isccfg/version.h +++ b/lib/isccfg/include/isccfg/version.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.h,v 1.3 2004/03/05 05:12:27 marka Exp $ */ +/* $Id: version.h,v 1.4 2005/04/27 04:57:28 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/isccfg/log.c b/lib/isccfg/log.c index 296158b5fa..8edc001144 100644 --- a/lib/isccfg/log.c +++ b/lib/isccfg/log.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: log.c,v 1.5 2004/03/05 05:12:22 marka Exp $ */ +/* $Id: log.c,v 1.6 2005/04/27 04:57:27 sra Exp $ */ + +/*! \file */ #include @@ -23,7 +25,7 @@ #include -/* +/*% * When adding a new category, be sure to add the appropriate * #define to . */ @@ -32,7 +34,7 @@ LIBISCCFG_EXTERNAL_DATA isc_logcategory_t cfg_categories[] = { { NULL, 0 } }; -/* +/*% * When adding a new module, be sure to add the appropriate * #define to . */ diff --git a/lib/isccfg/namedconf.c b/lib/isccfg/namedconf.c index 4b49a134b0..76ac427acf 100644 --- a/lib/isccfg/namedconf.c +++ b/lib/isccfg/namedconf.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: namedconf.c,v 1.47 2005/02/23 01:06:41 marka Exp $ */ +/* $Id: namedconf.c,v 1.48 2005/04/27 04:57:27 sra Exp $ */ + +/*! \file */ #include @@ -32,18 +34,18 @@ #define TOKEN_STRING(pctx) (pctx->token.value.as_textregion.base) -/* Check a return value. */ +/*% Check a return value. */ #define CHECK(op) \ do { result = (op); \ if (result != ISC_R_SUCCESS) goto cleanup; \ } while (0) -/* Clean up a configuration object if non-NULL. */ +/*% Clean up a configuration object if non-NULL. */ #define CLEANUP_OBJ(obj) \ do { if ((obj) != NULL) cfg_obj_destroy(pctx, &(obj)); } while (0) -/* +/*% * Forward declarations of static functions. */ @@ -107,7 +109,7 @@ static cfg_type_t cfg_type_viewopts; static cfg_type_t cfg_type_zone; static cfg_type_t cfg_type_zoneopts; -/* tkey-dhkey */ +/*% tkey-dhkey */ static cfg_tuplefielddef_t tkey_dhkey_fields[] = { { "name", &cfg_type_qstring, 0 }, @@ -120,7 +122,7 @@ static cfg_type_t cfg_type_tkey_dhkey = { tkey_dhkey_fields }; -/* listen-on */ +/*% listen-on */ static cfg_tuplefielddef_t listenon_fields[] = { { "port", &cfg_type_optional_port, 0 }, @@ -130,7 +132,7 @@ static cfg_tuplefielddef_t listenon_fields[] = { static cfg_type_t cfg_type_listenon = { "listenon", cfg_parse_tuple, cfg_print_tuple, cfg_doc_tuple, &cfg_rep_tuple, listenon_fields }; -/* acl */ +/*% acl */ static cfg_tuplefielddef_t acl_fields[] = { { "name", &cfg_type_astring, 0 }, @@ -141,7 +143,7 @@ static cfg_tuplefielddef_t acl_fields[] = { static cfg_type_t cfg_type_acl = { "acl", cfg_parse_tuple, cfg_print_tuple, cfg_doc_tuple, &cfg_rep_tuple, acl_fields }; -/* masters */ +/*% masters */ static cfg_tuplefielddef_t masters_fields[] = { { "name", &cfg_type_astring, 0 }, { "port", &cfg_type_optional_port, 0 }, @@ -152,7 +154,7 @@ static cfg_tuplefielddef_t masters_fields[] = { static cfg_type_t cfg_type_masters = { "masters", cfg_parse_tuple, cfg_print_tuple, cfg_doc_tuple, &cfg_rep_tuple, masters_fields }; -/* +/*% * "sockaddrkeylist", a list of socket addresses with optional keys * and an optional default port, as used in the masters option. * E.g., @@ -185,7 +187,7 @@ static cfg_type_t cfg_type_namesockaddrkeylist = { namesockaddrkeylist_fields }; -/* +/*% * A list of socket addresses with an optional default port, * as used in the also-notify option. E.g., * "port 1234 { 10.0.0.1; 1::2 port 69; }" @@ -200,7 +202,7 @@ static cfg_type_t cfg_type_portiplist = { portiplist_fields }; -/* +/*% * A public key, as in the "pubkey" statement. */ static cfg_tuplefielddef_t pubkey_fields[] = { @@ -213,7 +215,7 @@ static cfg_tuplefielddef_t pubkey_fields[] = { static cfg_type_t cfg_type_pubkey = { "pubkey", cfg_parse_tuple, cfg_print_tuple, cfg_doc_tuple, &cfg_rep_tuple, pubkey_fields }; -/* +/*% * A list of RR types, used in grant statements. * Note that the old parser allows quotes around the RR type names. */ @@ -235,7 +237,7 @@ static cfg_type_t cfg_type_matchtype = { &matchtype_enums }; -/* +/*% * A grant statement, used in the update policy. */ static cfg_tuplefielddef_t grant_fields[] = { @@ -254,7 +256,7 @@ static cfg_type_t cfg_type_updatepolicy = { &cfg_rep_list, &cfg_type_grant }; -/* +/*% * A view statement. */ static cfg_tuplefielddef_t view_fields[] = { @@ -266,7 +268,7 @@ static cfg_tuplefielddef_t view_fields[] = { static cfg_type_t cfg_type_view = { "view", cfg_parse_tuple, cfg_print_tuple, cfg_doc_tuple, &cfg_rep_tuple, view_fields }; -/* +/*% * A zone statement. */ static cfg_tuplefielddef_t zone_fields[] = { @@ -278,7 +280,7 @@ static cfg_tuplefielddef_t zone_fields[] = { static cfg_type_t cfg_type_zone = { "zone", cfg_parse_tuple, cfg_print_tuple, cfg_doc_tuple, &cfg_rep_tuple, zone_fields }; -/* +/*% * A "category" clause in the "logging" statement. */ static cfg_tuplefielddef_t category_fields[] = { @@ -290,7 +292,7 @@ static cfg_type_t cfg_type_category = { "category", cfg_parse_tuple, cfg_print_tuple, cfg_doc_tuple, &cfg_rep_tuple, category_fields }; -/* +/*% * A trusted key, as used in the "trusted-keys" statement. */ static cfg_tuplefielddef_t trustedkey_fields[] = { @@ -327,7 +329,7 @@ static cfg_type_t cfg_type_optional_wild_name = { print_keyvalue, doc_optional_keyvalue, &cfg_rep_string, &wild_name_kw }; -/* +/*% * An rrset ordering element. */ static cfg_tuplefielddef_t rrsetorderingelement_fields[] = { @@ -343,7 +345,7 @@ static cfg_type_t cfg_type_rrsetorderingelement = { rrsetorderingelement_fields }; -/* +/*% * A global or view "check-names" option. Note that the zone * "check-names" option has a different syntax. */ @@ -387,7 +389,7 @@ static cfg_type_t cfg_type_optional_port = { doc_optional_keyvalue, &cfg_rep_uint32, &port_kw }; -/* A list of keys, as in the "key" clause of the controls statement. */ +/*% A list of keys, as in the "key" clause of the controls statement. */ static cfg_type_t cfg_type_keylist = { "keylist", cfg_parse_bracketed_list, cfg_print_bracketed_list, cfg_doc_bracketed_list, &cfg_rep_list, &cfg_type_astring @@ -425,7 +427,7 @@ static cfg_type_t cfg_type_transferformat = { &transferformat_enums }; -/* +/*% * The special keyword "none", as used in the pid-file option. */ @@ -439,7 +441,7 @@ static cfg_type_t cfg_type_none = { "none", NULL, print_none, NULL, &cfg_rep_void, NULL }; -/* +/*% * A quoted string or the special keyword "none". Used in the pid-file option. */ static isc_result_t @@ -466,7 +468,7 @@ doc_qstringornone(cfg_printer_t *pctx, const cfg_type_t *type) { static cfg_type_t cfg_type_qstringornone = { "qstringornone", parse_qstringornone, NULL, doc_qstringornone, NULL, NULL }; -/* +/*% * keyword hostname */ @@ -480,7 +482,7 @@ static cfg_type_t cfg_type_hostname = { "hostname", NULL, print_hostname, NULL, &cfg_rep_boolean, NULL }; -/* +/*% * "server-id" arguement. */ @@ -512,7 +514,7 @@ doc_serverid(cfg_printer_t *pctx, const cfg_type_t *type) { static cfg_type_t cfg_type_serverid = { "serverid", parse_serverid, NULL, doc_serverid, NULL, NULL }; -/* +/*% * Port list. */ static isc_result_t @@ -541,7 +543,7 @@ static cfg_type_t cfg_type_bracketed_portlist = { &cfg_rep_list, &cfg_type_port }; -/* +/*% * Clauses that can be found within the top level of the named.conf * file only. */ @@ -557,7 +559,7 @@ namedconf_clauses[] = { { NULL, NULL, 0 } }; -/* +/*% * Clauses that can occur at the top level or in the view * statement, but not in the options block. */ @@ -570,7 +572,7 @@ namedconf_or_view_clauses[] = { { NULL, NULL, 0 } }; -/* +/*% * Clauses that can be found within the 'options' statement. */ static cfg_clausedef_t @@ -683,7 +685,7 @@ static cfg_type_t cfg_type_lookaside = { &cfg_rep_tuple, lookaside_fields }; -/* +/*% * Clauses that can be found within the 'view' statement, * with defaults in the 'options' statement. */ @@ -739,7 +741,7 @@ view_clauses[] = { { NULL, NULL, 0 } }; -/* +/*% * Clauses that can be found within the 'view' statement only. */ static cfg_clausedef_t @@ -750,7 +752,7 @@ view_only_clauses[] = { { NULL, NULL, 0 } }; -/* +/*% * Clauses that can be found in a 'zone' statement, * with defaults in the 'view' or 'options' statement. */ @@ -793,7 +795,7 @@ zone_clauses[] = { { NULL, NULL, 0 } }; -/* +/*% * Clauses that can be found in a 'zone' statement * only. */ @@ -820,7 +822,7 @@ zone_only_clauses[] = { }; -/* The top-level named.conf syntax. */ +/*% The top-level named.conf syntax. */ static cfg_clausedef_t * namedconf_clausesets[] = { @@ -834,7 +836,7 @@ LIBISCCFG_EXTERNAL_DATA cfg_type_t cfg_type_namedconf = { &cfg_rep_map, namedconf_clausesets }; -/* The "options" statement syntax. */ +/*% The "options" statement syntax. */ static cfg_clausedef_t * options_clausesets[] = { @@ -846,7 +848,7 @@ options_clausesets[] = { static cfg_type_t cfg_type_options = { "options", cfg_parse_map, cfg_print_map, cfg_doc_map, &cfg_rep_map, options_clausesets }; -/* The "view" statement syntax. */ +/*% The "view" statement syntax. */ static cfg_clausedef_t * view_clausesets[] = { @@ -859,7 +861,7 @@ view_clausesets[] = { static cfg_type_t cfg_type_viewopts = { "view", cfg_parse_map, cfg_print_map, cfg_doc_map, &cfg_rep_map, view_clausesets }; -/* The "zone" statement syntax. */ +/*% The "zone" statement syntax. */ static cfg_clausedef_t * zone_clausesets[] = { @@ -870,7 +872,7 @@ zone_clausesets[] = { static cfg_type_t cfg_type_zoneopts = { "zoneopts", cfg_parse_map, cfg_print_map, cfg_doc_map, &cfg_rep_map, zone_clausesets }; -/* +/*% * Clauses that can be found within the 'key' statement. */ static cfg_clausedef_t @@ -889,7 +891,7 @@ static cfg_type_t cfg_type_key = { "key", cfg_parse_named_map, cfg_print_map, cfg_doc_map, &cfg_rep_map, key_clausesets }; -/* +/*% * Clauses that can be found in a 'server' statement. */ static cfg_clausedef_t @@ -917,7 +919,7 @@ static cfg_type_t cfg_type_server = { }; -/* +/*% * Clauses that can be found in a 'channel' clause in the * 'logging' statement. * @@ -950,12 +952,12 @@ static cfg_type_t cfg_type_channel = { &cfg_rep_map, channel_clausesets }; -/* A list of log destination, used in the "category" clause. */ +/*% A list of log destination, used in the "category" clause. */ static cfg_type_t cfg_type_destinationlist = { "destinationlist", cfg_parse_bracketed_list, cfg_print_bracketed_list, cfg_doc_bracketed_list, &cfg_rep_list, &cfg_type_astring }; -/* +/*% * Clauses that can be found in a 'logging' statement. */ static cfg_clausedef_t @@ -1037,14 +1039,14 @@ parse_sizeval(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) { return (result); } -/* +/*% * A size value (number + optional unit). */ static cfg_type_t cfg_type_sizeval = { "sizeval", parse_sizeval, cfg_print_uint64, cfg_doc_terminal, &cfg_rep_uint64, NULL }; -/* +/*% * A size, "unlimited", or "default". */ @@ -1059,7 +1061,7 @@ static cfg_type_t cfg_type_size = { &cfg_rep_string, size_enums }; -/* +/*% * A size or "unlimited", but not "default". */ static const char *sizenodefault_enums[] = { "unlimited", NULL }; @@ -1068,7 +1070,7 @@ static cfg_type_t cfg_type_sizenodefault = { &cfg_rep_string, sizenodefault_enums }; -/* +/*% * optional_keyvalue */ static isc_result_t @@ -1204,7 +1206,7 @@ static cfg_type_t cfg_type_optional_keyref = { doc_optional_keyvalue, &cfg_rep_string, &key_kw }; -/* +/*% * A "controls" statement is represented as a map with the multivalued * "inet" and "unix" clauses. */ @@ -1296,7 +1298,7 @@ static cfg_type_t cfg_type_controls = { "controls", cfg_parse_map, cfg_print_map, cfg_doc_map, &cfg_rep_map, &controls_clausesets }; -/* +/*% * An optional class, as used in view and zone statements. */ static isc_result_t @@ -1408,7 +1410,7 @@ static cfg_type_t cfg_type_querysource = { "querysource", NULL, print_querysource, NULL, &cfg_rep_sockaddr, NULL }; -/* addrmatchelt */ +/*% addrmatchelt */ static isc_result_t parse_addrmatchelt(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) { @@ -1452,7 +1454,7 @@ parse_addrmatchelt(cfg_parser_t *pctx, const cfg_type_t *type, cfg_obj_t **ret) return (result); } -/* +/*% * A negated address match list element (like "! 10.0.0.1"). * Somewhat sneakily, the caller is expected to parse the * "!", but not to print it. @@ -1474,21 +1476,21 @@ static cfg_type_t cfg_type_negated = { &negated_fields }; -/* An address match list element */ +/*% An address match list element */ static cfg_type_t cfg_type_addrmatchelt = { "address_match_element", parse_addrmatchelt, NULL, cfg_doc_terminal, NULL, NULL }; -/* A bracketed address match list */ +/*% A bracketed address match list */ static cfg_type_t cfg_type_bracketed_aml = { "bracketed_aml", cfg_parse_bracketed_list, cfg_print_bracketed_list, cfg_doc_bracketed_list, &cfg_rep_list, &cfg_type_addrmatchelt }; -/* +/*% * The socket address syntax in the "controls" statement is silly. * It allows both socket address families, but also allows "*", * whis is gratuitously interpreted as the IPv4 wildcard address. @@ -1500,7 +1502,7 @@ static cfg_type_t cfg_type_controls_sockaddr = { cfg_doc_sockaddr, &cfg_rep_sockaddr, &controls_sockaddr_flags }; -/* +/*% * Handle the special kludge syntax of the "keys" clause in the "server" * statement, which takes a single key with or without braces and semicolon. */ @@ -1539,7 +1541,7 @@ static cfg_type_t cfg_type_server_key_kludge = { }; -/* +/*% * An optional logging facility. */ @@ -1565,7 +1567,7 @@ static cfg_type_t cfg_type_optional_facility = { NULL, NULL }; -/* +/*% * A log severity. Return as a string, except "debug N", * which is returned as a keyword object. */ @@ -1610,7 +1612,7 @@ static cfg_type_t cfg_type_logseverity = { "log_severity", parse_logseverity, NULL, cfg_doc_terminal, NULL, NULL }; -/* +/*% * The "file" clause of the "channel" statement. * This is yet another special case. */ @@ -1698,7 +1700,7 @@ static cfg_type_t cfg_type_logfile = { &cfg_rep_tuple, logfile_fields }; -/* An IPv4/IPv6 address with optional port, "*" accepted as wildcard. */ +/*% An IPv4/IPv6 address with optional port, "*" accepted as wildcard. */ static cfg_type_t cfg_type_sockaddr4wild = { "sockaddr4wild", cfg_parse_sockaddr, cfg_print_sockaddr, cfg_doc_sockaddr, &cfg_rep_sockaddr, &sockaddr4wild_flags @@ -1709,7 +1711,7 @@ static cfg_type_t cfg_type_sockaddr6wild = { cfg_doc_sockaddr, &cfg_rep_sockaddr, &sockaddr6wild_flags }; -/* +/*% * lwres */ @@ -1746,7 +1748,7 @@ static cfg_type_t cfg_type_lwres = { lwres_clausesets }; -/* +/*% * rndc */ @@ -1902,7 +1904,7 @@ static cfg_type_t cfg_type_bracketed_sockaddrnameportlist = { &cfg_rep_list, &cfg_type_sockaddrnameport }; -/* +/*% * A list of socket addresses or name with an optional default port, * as used in the dual-stack-servers option. E.g., * "port 1234 { dual-stack-servers.net; 10.0.0.1; 1::2 port 69; }" @@ -1918,7 +1920,7 @@ static cfg_type_t cfg_type_nameportiplist = { &cfg_rep_tuple, nameportiplist_fields }; -/* +/*% * masters element. */ diff --git a/lib/isccfg/parser.c b/lib/isccfg/parser.c index 51a275a3af..33c6840a15 100644 --- a/lib/isccfg/parser.c +++ b/lib/isccfg/parser.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: parser.c,v 1.116 2005/01/17 23:58:33 marka Exp $ */ +/* $Id: parser.c,v 1.117 2005/04/27 04:57:28 sra Exp $ */ + +/*! \file */ #include @@ -125,7 +127,7 @@ cfg_rep_t cfg_rep_void = { "void", free_noop }; * Configuration type definitions. */ -/* +/*% * An implicit list. These are formed by clauses that occur multiple times. */ static cfg_type_t cfg_type_implicitlist = { diff --git a/lib/isccfg/version.c b/lib/isccfg/version.c index 1e220b5463..57679e0329 100644 --- a/lib/isccfg/version.c +++ b/lib/isccfg/version.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.c,v 1.3 2004/03/05 05:12:22 marka Exp $ */ +/* $Id: version.c,v 1.4 2005/04/27 04:57:28 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/lwres/assert_p.h b/lib/lwres/assert_p.h index b93b1636fc..0c500340e5 100644 --- a/lib/lwres/assert_p.h +++ b/lib/lwres/assert_p.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: assert_p.h,v 1.10 2004/03/05 05:12:45 marka Exp $ */ +/* $Id: assert_p.h,v 1.11 2005/04/27 04:57:29 sra Exp $ */ #ifndef LWRES_ASSERT_P_H #define LWRES_ASSERT_P_H 1 +/*! \file */ + #include /* Required for assert() prototype. */ #define REQUIRE(x) assert(x) diff --git a/lib/lwres/context.c b/lib/lwres/context.c index 0db414c3f6..6e0541f73e 100644 --- a/lib/lwres/context.c +++ b/lib/lwres/context.c @@ -15,8 +15,76 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: context.c,v 1.46 2004/09/17 05:59:28 marka Exp $ */ +/* $Id: context.c,v 1.47 2005/04/27 04:57:29 sra Exp $ */ +/*! \file context.c + lwres_context_create() creates a #lwres_context_t structure for use in + lightweight resolver operations. It holds a socket and other data + needed for communicating with a resolver daemon. The new + lwres_context_t is returned through contextp, a pointer to a + lwres_context_t pointer. This lwres_context_t pointer must initially + be NULL, and is modified to point to the newly created + lwres_context_t. + + When the lightweight resolver needs to perform dynamic memory + allocation, it will call malloc_function to allocate memory and + free_function to free it. If malloc_function and free_function are + NULL, memory is allocated using malloc and free. It is not + permitted to have a NULL malloc_function and a non-NULL free_function + or vice versa. arg is passed as the first parameter to the memory + allocation functions. If malloc_function and free_function are NULL, + arg is unused and should be passed as NULL. + + Once memory for the structure has been allocated, it is initialized + using lwres_conf_init() and returned via *contextp. + + lwres_context_destroy() destroys a #lwres_context_t, closing its + socket. contextp is a pointer to a pointer to the context that is to + be destroyed. The pointer will be set to NULL when the context has + been destroyed. + + The context holds a serial number that is used to identify resolver + request packets and associate responses with the corresponding + requests. This serial number is controlled using + lwres_context_initserial() and lwres_context_nextserial(). + lwres_context_initserial() sets the serial number for context *ctx to + serial. lwres_context_nextserial() increments the serial number and + returns the previous value. + + Memory for a lightweight resolver context is allocated and freed using + lwres_context_allocmem() and lwres_context_freemem(). These use + whatever allocations were defined when the context was created with + lwres_context_create(). lwres_context_allocmem() allocates len bytes + of memory and if successful returns a pointer to the allocated + storage. lwres_context_freemem() frees len bytes of space starting at + location mem. + + lwres_context_sendrecv() performs I/O for the context ctx. Data are + read and written from the context's socket. It writes data from + sendbase -- typically a lightweight resolver query packet -- and waits + for a reply which is copied to the receive buffer at recvbase. The + number of bytes that were written to this receive buffer is returned + in *recvd_len. + +\section context_return Return Values + + lwres_context_create() returns #LWRES_R_NOMEMORY if memory for the + struct lwres_context could not be allocated, #LWRES_R_SUCCESS + otherwise. + + Successful calls to the memory allocator lwres_context_allocmem() + return a pointer to the start of the allocated space. It returns NULL + if memory could not be allocated. + + #LWRES_R_SUCCESS is returned when lwres_context_sendrecv() completes + successfully. #LWRES_R_IOERROR is returned if an I/O error occurs and + #LWRES_R_TIMEOUT is returned if lwres_context_sendrecv() times out + waiting for a response. + +\section context_see See Also + + lwres_conf_init(), malloc, free. + */ #include #include @@ -37,7 +105,7 @@ #include "context_p.h" #include "assert_p.h" -/* +/*! * Some systems define the socket length argument as an int, some as size_t, * some as socklen_t. The last is what the current POSIX standard mandates. * This definition is here so it can be portable but easily changed if needed. @@ -46,7 +114,7 @@ #define LWRES_SOCKADDR_LEN_T unsigned int #endif -/* +/*! * Make a socket nonblocking. */ #ifndef MAKE_NONBLOCKING @@ -69,9 +137,16 @@ lwres_malloc(void *, size_t); static void lwres_free(void *, void *, size_t); +/*! + * lwres_result_t + */ static lwres_result_t context_connect(lwres_context_t *); +/*% + * Creates a #lwres_context_t structure for use in + * lightweight resolver operations. + */ lwres_result_t lwres_context_create(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, @@ -118,6 +193,12 @@ lwres_context_create(lwres_context_t **contextp, void *arg, return (LWRES_R_SUCCESS); } +/*% +Destroys a #lwres_context_t, closing its socket. +contextp is a pointer to a pointer to the context that is +to be destroyed. The pointer will be set to NULL +when the context has been destroyed. + */ void lwres_context_destroy(lwres_context_t **contextp) { lwres_context_t *ctx; @@ -134,7 +215,7 @@ lwres_context_destroy(lwres_context_t **contextp) { CTXFREE(ctx, sizeof(lwres_context_t)); } - +/*% Increments the serial number and returns the previous value. */ lwres_uint32_t lwres_context_nextserial(lwres_context_t *ctx) { REQUIRE(ctx != NULL); @@ -142,6 +223,7 @@ lwres_context_nextserial(lwres_context_t *ctx) { return (ctx->serial++); } +/*% Sets the serial number for context *ctx to serial. */ void lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t serial) { REQUIRE(ctx != NULL); @@ -149,6 +231,7 @@ lwres_context_initserial(lwres_context_t *ctx, lwres_uint32_t serial) { ctx->serial = serial; } +/*% Frees len bytes of space starting at location mem. */ void lwres_context_freemem(lwres_context_t *ctx, void *mem, size_t len) { REQUIRE(mem != NULL); @@ -157,6 +240,7 @@ lwres_context_freemem(lwres_context_t *ctx, void *mem, size_t len) { CTXFREE(mem, len); } +/*% Allocates len bytes of memory and if successful returns a pointer to the allocated storage. */ void * lwres_context_allocmem(lwres_context_t *ctx, size_t len) { REQUIRE(len != 0U); @@ -334,6 +418,7 @@ lwres_context_recv(lwres_context_t *ctx, return (LWRES_R_SUCCESS); } +/*% performs I/O for the context ctx. */ lwres_result_t lwres_context_sendrecv(lwres_context_t *ctx, void *sendbase, int sendlen, diff --git a/lib/lwres/context_p.h b/lib/lwres/context_p.h index 0600ad5f11..5e61bd31d7 100644 --- a/lib/lwres/context_p.h +++ b/lib/lwres/context_p.h @@ -15,42 +15,48 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: context_p.h,v 1.13 2004/03/05 05:12:45 marka Exp $ */ +/* $Id: context_p.h,v 1.14 2005/04/27 04:57:29 sra Exp $ */ #ifndef LWRES_CONTEXT_P_H #define LWRES_CONTEXT_P_H 1 -/* +/*! \file */ + +/*@{*/ +/** * Helper functions, assuming the context is always called "ctx" in * the scope these functions are called from. */ #define CTXMALLOC(len) ctx->malloc(ctx->arg, (len)) #define CTXFREE(addr, len) ctx->free(ctx->arg, (addr), (len)) +/*@}*/ #define LWRES_DEFAULT_TIMEOUT 120 /* 120 seconds for a reply */ -/* +/** * Not all the attributes here are actually settable by the application at * this time. */ struct lwres_context { - unsigned int timeout; /* time to wait for reply */ - lwres_uint32_t serial; /* serial number state */ + unsigned int timeout; /*%< time to wait for reply */ + lwres_uint32_t serial; /*%< serial number state */ /* * For network I/O. */ - int sock; /* socket to send on */ - lwres_addr_t address; /* address to send to */ + int sock; /*%< socket to send on */ + lwres_addr_t address; /*%< address to send to */ + /*@{*/ /* * Function pointers for allocating memory. */ lwres_malloc_t malloc; lwres_free_t free; void *arg; + /*@}*/ - /* + /*% * resolv.conf-like data */ lwres_conf_t confdata; diff --git a/lib/lwres/gai_strerror.c b/lib/lwres/gai_strerror.c index fd24bd8556..a02d0e554a 100644 --- a/lib/lwres/gai_strerror.c +++ b/lib/lwres/gai_strerror.c @@ -15,10 +15,37 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gai_strerror.c,v 1.16 2004/03/05 05:12:45 marka Exp $ */ +/* $Id: gai_strerror.c,v 1.17 2005/04/27 04:57:29 sra Exp $ */ +/*! \file gai_strerror.c + * lwres_gai_strerror() returns an error message corresponding to an + * error code returned by getaddrinfo(). The following error codes and + * their meaning are defined in \link netdb.h include/lwres/netdb.h.\endlink + * + * \li #EAI_ADDRFAMILY address family for hostname not supported + * \li #EAI_AGAIN temporary failure in name resolution + * \li #EAI_BADFLAGS invalid value for #ai_flags + * \li #EAI_FAIL non-recoverable failure in name resolution + * \li #EAI_FAMILY ai_family not supported + * \li #EAI_MEMORY memory allocation failure + * \li #EAI_NODATA no address associated with hostname + * \li #EAI_NONAME hostname or servname not provided, or not known + * \li #EAI_SERVICE servname not supported for ai_socktype + * \li #EAI_SOCKTYPE ai_socktype not supported + * \li #EAI_SYSTEM system error returned in errno + * + * The message invalid error code is returned if ecode is out of range. + * + * ai_flags, ai_family and ai_socktype are elements of the struct + * addrinfo used by lwres_getaddrinfo(). + * + * \section gai_strerror_see See Also + * + * strerror, lwres_getaddrinfo(), getaddrinfo(), RFC2133. + */ #include +/*% Text of error messages. */ static const char *gai_messages[] = { "no error", "address family for hostname not supported", @@ -36,6 +63,7 @@ static const char *gai_messages[] = { "bad protocol" }; +/*% Returns an error message corresponding to an error code returned by getaddrinfo() */ char * lwres_gai_strerror(int ecode) { union { diff --git a/lib/lwres/getaddrinfo.c b/lib/lwres/getaddrinfo.c index 733b5494f0..649c696145 100644 --- a/lib/lwres/getaddrinfo.c +++ b/lib/lwres/getaddrinfo.c @@ -18,7 +18,118 @@ * IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getaddrinfo.c,v 1.43 2004/03/05 05:48:26 marka Exp $ */ +/* $Id: getaddrinfo.c,v 1.44 2005/04/27 04:57:29 sra Exp $ */ + +/*! \file */ + +/** + * lwres_getaddrinfo() is used to get a list of IP addresses and port + * numbers for host hostname and service servname. The function is the + * lightweight resolver's implementation of getaddrinfo() as defined in + * RFC2133. hostname and servname are pointers to null-terminated strings + * or NULL. hostname is either a host name or a numeric host address + * string: a dotted decimal IPv4 address or an IPv6 address. servname is + * either a decimal port number or a service name as listed in + * /etc/services. + * + * If the operating system does not provide a struct addrinfo, the + * following structure is used: + * + * \code + * struct addrinfo { + * int ai_flags; // AI_PASSIVE, AI_CANONNAME + * int ai_family; // PF_xxx + * int ai_socktype; // SOCK_xxx + * int ai_protocol; // 0 or IPPROTO_xxx for IPv4 and IPv6 + * size_t ai_addrlen; // length of ai_addr + * char *ai_canonname; // canonical name for hostname + * struct sockaddr *ai_addr; // binary address + * struct addrinfo *ai_next; // next structure in linked list + * }; + * \endcode + * + * + * hints is an optional pointer to a struct addrinfo. This structure can + * be used to provide hints concerning the type of socket that the caller + * supports or wishes to use. The caller can supply the following + * structure elements in *hints: + * + *
    + *
  • ai_family: + * The protocol family that should be used. When ai_family is set + * to PF_UNSPEC, it means the caller will accept any protocol + * family supported by the operating system.
    • + * + *
  • ai_socktype: + * denotes the type of socket -- SOCK_STREAM, SOCK_DGRAM or + * SOCK_RAW -- that is wanted. When ai_socktype is zero the caller + * will accept any socket type.
    • + * + *
  • ai_protocol: + * indicates which transport protocol is wanted: IPPROTO_UDP or + * IPPROTO_TCP. If ai_protocol is zero the caller will accept any + * protocol.
    • + * + *
  • ai_flags: + * Flag bits. If the AI_CANONNAME bit is set, a successful call to + * lwres_getaddrinfo() will return a null-terminated string + * containing the canonical name of the specified hostname in + * ai_canonname of the first addrinfo structure returned. Setting + * the AI_PASSIVE bit indicates that the returned socket address + * structure is intended for used in a call to bind(2). In this + * case, if the hostname argument is a NULL pointer, then the IP + * address portion of the socket address structure will be set to + * INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 + * address.

    + * + * When ai_flags does not set the AI_PASSIVE bit, the returned + * socket address structure will be ready for use in a call to + * connect(2) for a connection-oriented protocol or connect(2), + * sendto(2), or sendmsg(2) if a connectionless protocol was + * chosen. The IP address portion of the socket address structure + * will be set to the loopback address if hostname is a NULL + * pointer and AI_PASSIVE is not set in ai_flags.

    + * + * If ai_flags is set to AI_NUMERICHOST it indicates that hostname + * should be treated as a numeric string defining an IPv4 or IPv6 + * address and no name resolution should be attempted. + *
+ * + * All other elements of the struct addrinfo passed via hints must be + * zero. + * + * A hints of NULL is treated as if the caller provided a struct addrinfo + * initialized to zero with ai_familyset to PF_UNSPEC. + * + * After a successful call to lwres_getaddrinfo(), *res is a pointer to a + * linked list of one or more addrinfo structures. Each struct addrinfo + * in this list cn be processed by following the ai_next pointer, until a + * NULL pointer is encountered. The three members ai_family, ai_socktype, + * and ai_protocol in each returned addrinfo structure contain the + * corresponding arguments for a call to socket(2). For each addrinfo + * structure in the list, the ai_addr member points to a filled-in socket + * address structure of length ai_addrlen. + * + * All of the information returned by lwres_getaddrinfo() is dynamically + * allocated: the addrinfo structures, and the socket address structures + * and canonical host name strings pointed to by the addrinfostructures. + * Memory allocated for the dynamically allocated structures created by a + * successful call to lwres_getaddrinfo() is released by + * lwres_freeaddrinfo(). ai is a pointer to a struct addrinfo created by + * a call to lwres_getaddrinfo(). + * + * \section lwresreturn RETURN VALUES + * + * lwres_getaddrinfo() returns zero on success or one of the error codes + * listed in gai_strerror() if an error occurs. If both hostname and + * servname are NULL lwres_getaddrinfo() returns #EAI_NONAME. + * + * \section lwressee SEE ALSO + * + * lwres(3), lwres_getaddrinfo(), lwres_freeaddrinfo(), + * lwres_gai_strerror(), RFC2133, getservbyname(3), connect(2), + * sendto(2), sendmsg(2), socket(2). + */ #include @@ -35,6 +146,8 @@ #define SIN6(addr) ((struct sockaddr_in6 *)(addr)) #define SUN(addr) ((struct sockaddr_un *)(addr)) +/*! \struct addrinfo + */ static struct addrinfo *ai_reverse(struct addrinfo *oai), *ai_clone(struct addrinfo *oai, int family), @@ -55,7 +168,7 @@ static void set_order(int, int (**)(const char *, int, struct addrinfo **, #define FOUND_MAX 2 #define ISC_AI_MASK (AI_PASSIVE|AI_CANONNAME|AI_NUMERICHOST) - +/*% Get a list of IP addresses and port numbers for host hostname and service servname. */ int lwres_getaddrinfo(const char *hostname, const char *servname, const struct addrinfo *hints, struct addrinfo **res) @@ -137,7 +250,7 @@ lwres_getaddrinfo(const char *hostname, const char *servname, } #ifdef AF_LOCAL - /* + /*! * First, deal with AF_LOCAL. If the family was not set, * then assume AF_LOCAL if the first character of the * hostname/servname is '/'. @@ -573,6 +686,7 @@ add_ipv6(const char *hostname, int flags, struct addrinfo **aip, return (result); } +/*% Free address info. */ void lwres_freeaddrinfo(struct addrinfo *ai) { struct addrinfo *ai_next; @@ -615,7 +729,7 @@ get_local(const char *name, int socktype, struct addrinfo **res) { } #endif -/* +/*! * Allocate an addrinfo structure, and a sockaddr structure * of the specificed length. We initialize: * ai_addrlen diff --git a/lib/lwres/gethost.c b/lib/lwres/gethost.c index b75c9e2e91..9507c30ad5 100644 --- a/lib/lwres/gethost.c +++ b/lib/lwres/gethost.c @@ -15,7 +15,139 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: gethost.c,v 1.30 2004/03/05 05:12:45 marka Exp $ */ +/* $Id: gethost.c,v 1.31 2005/04/27 04:57:29 sra Exp $ */ + +/*! \file */ + +/** + * These functions provide hostname-to-address and address-to-hostname + * lookups by means of the lightweight resolver. They are similar to the + * standard gethostent(3) functions provided by most operating systems. + * They use a struct hostent which is usually defined in . + * + * \code + * struct hostent { + * char *h_name; // official name of host + * char **h_aliases; // alias list + * int h_addrtype; // host address type + * int h_length; // length of address + * char **h_addr_list; // list of addresses from name server + * }; + * #define h_addr h_addr_list[0] // address, for backward compatibility + * \endcode + * + * The members of this structure are: + * + * \li h_name: + * The official (canonical) name of the host. + * + * \li h_aliases: + * A NULL-terminated array of alternate names (nicknames) for the + * host. + * + * \li h_addrtype: + * The type of address being returned -- PF_INET or PF_INET6. + * + * \li h_length: + * The length of the address in bytes. + * + * \li h_addr_list: + * A NULL terminated array of network addresses for the host. Host + * addresses are returned in network byte order. + * + * For backward compatibility with very old software, h_addr is the first + * address in h_addr_list. + * + * lwres_gethostent(), lwres_sethostent(), lwres_endhostent(), + * lwres_gethostent_r(), lwres_sethostent_r() and lwres_endhostent_r() + * provide iteration over the known host entries on systems that provide + * such functionality through facilities like /etc/hosts or NIS. The + * lightweight resolver does not currently implement these functions; it + * only provides them as stub functions that always return failure. + * + * lwres_gethostbyname() and lwres_gethostbyname2() look up the hostname + * name. lwres_gethostbyname() always looks for an IPv4 address while + * lwres_gethostbyname2() looks for an address of protocol family af: + * either PF_INET or PF_INET6 -- IPv4 or IPV6 addresses respectively. + * Successful calls of the functions return a struct hostent for the name + * that was looked up. NULL is returned if the lookups by + * lwres_gethostbyname() or lwres_gethostbyname2() fail. + * + * Reverse lookups of addresses are performed by lwres_gethostbyaddr(). + * addr is an address of length len bytes and protocol family type -- + * PF_INET or PF_INET6. lwres_gethostbyname_r() is a thread-safe function + * for forward lookups. If an error occurs, an error code is returned in + * *error. resbuf is a pointer to a struct hostent which is initialised + * by a successful call to lwres_gethostbyname_r() . buf is a buffer of + * length len bytes which is used to store the h_name, h_aliases, and + * h_addr_list elements of the struct hostent returned in resbuf. + * Successful calls to lwres_gethostbyname_r() return resbuf, which is a + * pointer to the struct hostent it created. + * + * lwres_gethostbyaddr_r() is a thread-safe function that performs a + * reverse lookup of address addr which is len bytes long and is of + * protocol family type -- PF_INET or PF_INET6. If an error occurs, the + * error code is returned in *error. The other function parameters are + * identical to those in lwres_gethostbyname_r(). resbuf is a pointer to + * a struct hostent which is initialised by a successful call to + * lwres_gethostbyaddr_r(). buf is a buffer of length len bytes which is + * used to store the h_name, h_aliases, and h_addr_list elements of the + * struct hostent returned in resbuf. Successful calls to + * lwres_gethostbyaddr_r() return resbuf, which is a pointer to the + * struct hostent it created. + * + * \section gethost_return Return Values + * + * The functions lwres_gethostbyname(), lwres_gethostbyname2(), + * lwres_gethostbyaddr(), and lwres_gethostent() return NULL to indicate + * an error. In this case the global variable lwres_h_errno will contain + * one of the following error codes defined in \link netdb.h :\endlink + * + * \li #HOST_NOT_FOUND: + * The host or address was not found. + * + * \li #TRY_AGAIN: + * A recoverable error occurred, e.g., a timeout. Retrying the + * lookup may succeed. + * + * \li #NO_RECOVERY: + * A non-recoverable error occurred. + * + * \li #NO_DATA: + * The name exists, but has no address information associated with + * it (or vice versa in the case of a reverse lookup). The code + * NO_ADDRESS is accepted as a synonym for NO_DATA for backwards + * compatibility. + * + * lwres_hstrerror() translates these error codes to suitable error + * messages. + * + * lwres_gethostent() and lwres_gethostent_r() always return NULL. + * + * Successful calls to lwres_gethostbyname_r() and + * lwres_gethostbyaddr_r() return resbuf, a pointer to the struct hostent + * that was initialised by these functions. They return NULL if the + * lookups fail or if buf was too small to hold the list of addresses and + * names referenced by the h_name, h_aliases, and h_addr_list elements of + * the struct hostent. If buf was too small, both lwres_gethostbyname_r() + * and lwres_gethostbyaddr_r() set the global variable errno to ERANGE. + * + * \section gethost_see See Also + * + * gethostent(), \link getipnode.c getipnode\endlink, lwres_hstrerror() + * + * \section gethost_bugs Bugs + * + * lwres_gethostbyname(), lwres_gethostbyname2(), lwres_gethostbyaddr() + * and lwres_endhostent() are not thread safe; they return pointers to + * static data and provide error codes through a global variable. + * Thread-safe versions for name and address lookup are provided by + * lwres_gethostbyname_r(), and lwres_gethostbyaddr_r() respectively. + * + * The resolver daemon does not currently support any non-DNS name + * services such as /etc/hosts or NIS, consequently the above functions + * don't, either. + */ #include @@ -34,6 +166,7 @@ static struct hostent *he = NULL; static int copytobuf(struct hostent *, struct hostent *, char *, int); +/*% Always looks for an IPv4 address. */ struct hostent * lwres_gethostbyname(const char *name) { @@ -44,6 +177,7 @@ lwres_gethostbyname(const char *name) { return (he); } +/*% Looks for either an IPv4 or IPv6 address. */ struct hostent * lwres_gethostbyname2(const char *name, int af) { if (he != NULL) @@ -53,6 +187,7 @@ lwres_gethostbyname2(const char *name, int af) { return (he); } +/*% Reverse lookup of addresses. */ struct hostent * lwres_gethostbyaddr(const char *addr, int len, int type) { @@ -63,6 +198,7 @@ lwres_gethostbyaddr(const char *addr, int len, int type) { return (he); } +/*% Stub function. Always returns failure. */ struct hostent * lwres_gethostent(void) { if (he != NULL) @@ -71,6 +207,7 @@ lwres_gethostent(void) { return (NULL); } +/*% Stub function. Always returns failure. */ void lwres_sethostent(int stayopen) { /* @@ -79,6 +216,7 @@ lwres_sethostent(int stayopen) { UNUSED(stayopen); } +/*% Stub function. Always returns failure. */ void lwres_endhostent(void) { /* @@ -86,6 +224,7 @@ lwres_endhostent(void) { */ } +/*% Thread-safe function for forward lookups. */ struct hostent * lwres_gethostbyname_r(const char *name, struct hostent *resbuf, char *buf, int buflen, int *error) @@ -105,6 +244,7 @@ lwres_gethostbyname_r(const char *name, struct hostent *resbuf, return (resbuf); } +/*% Thread-safe reverse lookup. */ struct hostent * lwres_gethostbyaddr_r(const char *addr, int len, int type, struct hostent *resbuf, char *buf, int buflen, @@ -125,6 +265,7 @@ lwres_gethostbyaddr_r(const char *addr, int len, int type, return (resbuf); } +/*% Stub function. Always returns failure. */ struct hostent * lwres_gethostent_r(struct hostent *resbuf, char *buf, int buflen, int *error) { UNUSED(resbuf); @@ -134,6 +275,7 @@ lwres_gethostent_r(struct hostent *resbuf, char *buf, int buflen, int *error) { return (NULL); } +/*% Stub function. Always returns failure. */ void lwres_sethostent_r(int stayopen) { /* @@ -142,6 +284,7 @@ lwres_sethostent_r(int stayopen) { UNUSED(stayopen); } +/*% Stub function. Always returns failure. */ void lwres_endhostent_r(void) { /* diff --git a/lib/lwres/getipnode.c b/lib/lwres/getipnode.c index 333e255e1a..31ac799190 100644 --- a/lib/lwres/getipnode.c +++ b/lib/lwres/getipnode.c @@ -15,7 +15,110 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getipnode.c,v 1.38 2005/04/27 00:24:02 marka Exp $ */ +/* $Id: getipnode.c,v 1.39 2005/04/27 04:57:29 sra Exp $ */ + +/*! \file */ + +/** + * These functions perform thread safe, protocol independent + * nodename-to-address and address-to-nodename translation as defined in + * RFC2553. This use a struct hostent which is defined in namedb.h: + * + * \code + * struct hostent { + * char *h_name; // official name of host + * char **h_aliases; // alias list + * int h_addrtype; // host address type + * int h_length; // length of address + * char **h_addr_list; // list of addresses from name server + * }; + * #define h_addr h_addr_list[0] // address, for backward compatibility + * \endcode + * + * The members of this structure are: + * + * \li h_name: + * The official (canonical) name of the host. + * + * \li h_aliases: + * A NULL-terminated array of alternate names (nicknames) for the + * host. + * + * \li h_addrtype: + * The type of address being returned - usually PF_INET or + * PF_INET6. + * + * \li h_length: + * The length of the address in bytes. + * + * \li h_addr_list: + * A NULL terminated array of network addresses for the host. Host + * addresses are returned in network byte order. + * + * lwres_getipnodebyname() looks up addresses of protocol family af for + * the hostname name. The flags parameter contains ORed flag bits to + * specify the types of addresses that are searched for, and the types of + * addresses that are returned. The flag bits are: + * + * \li #AI_V4MAPPED: + * This is used with an af of #AF_INET6, and causes IPv4 addresses + * to be returned as IPv4-mapped IPv6 addresses. + * + * \li #AI_ALL: + * This is used with an af of #AF_INET6, and causes all known + * addresses (IPv6 and IPv4) to be returned. If #AI_V4MAPPED is + * also set, the IPv4 addresses are return as mapped IPv6 + * addresses. + * + * \li #AI_ADDRCONFIG: + * Only return an IPv6 or IPv4 address if here is an active + * network interface of that type. This is not currently + * implemented in the BIND 9 lightweight resolver, and the flag is + * ignored. + * + * \li #AI_DEFAULT: + * This default sets the #AI_V4MAPPED and #AI_ADDRCONFIG flag bits. + * + * lwres_getipnodebyaddr() performs a reverse lookup of address src which + * is len bytes long. af denotes the protocol family, typically PF_INET + * or PF_INET6. + * + * lwres_freehostent() releases all the memory associated with the struct + * hostent pointer. Any memory allocated for the h_name, h_addr_list + * and h_aliases is freed, as is the memory for the hostent structure + * itself. + * + * \section getipnode_return Return Values + * + * If an error occurs, lwres_getipnodebyname() and + * lwres_getipnodebyaddr() set *error_num to an appropriate error code + * and the function returns a NULL pointer. The error codes and their + * meanings are defined in \link netdb.h \endlink: + * + * \li #HOST_NOT_FOUND: + * No such host is known. + * + * \li #NO_ADDRESS: + * The server recognised the request and the name but no address + * is available. Another type of request to the name server for + * the domain might return an answer. + * + * \li #TRY_AGAIN: + * A temporary and possibly transient error occurred, such as a + * failure of a server to respond. The request may succeed if + * retried. + * + * \li #NO_RECOVERY: + * An unexpected failure occurred, and retrying the request is + * pointless. + * + * lwres_hstrerror() translates these error codes to suitable error + * messages. + * + * \section getipnode_see See Also + * + * getaddrinfo.c, gethost.c, getnameinfo.c, herror.c, RFC2553 + */ #include @@ -80,7 +183,7 @@ hostfromname(lwres_gabnresponse_t *name, int af); *** Public functions. ***/ -/* +/*! * AI_V4MAPPED + AF_INET6 * If no IPv6 address then a query for IPv4 and map returned values. * @@ -222,6 +325,7 @@ lwres_getipnodebyname(const char *name, int af, int flags, int *error_num) { return (he3); } +/*% performs a reverse lookup of address src which is len bytes long. af denotes the protocol family, typically #PF_INET or PF_INET6. */ struct hostent * lwres_getipnodebyaddr(const void *src, size_t len, int af, int *error_num) { struct hostent *he1, *he2; @@ -345,6 +449,7 @@ lwres_getipnodebyaddr(const void *src, size_t len, int af, int *error_num) { return (he1); } +/*% releases all the memory associated with the struct hostent pointer */ void lwres_freehostent(struct hostent *he) { char **cpp; diff --git a/lib/lwres/getnameinfo.c b/lib/lwres/getnameinfo.c index 627a81c804..fa40758933 100644 --- a/lib/lwres/getnameinfo.c +++ b/lib/lwres/getnameinfo.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getnameinfo.c,v 1.35 2004/08/28 06:16:59 marka Exp $ */ +/* $Id: getnameinfo.c,v 1.36 2005/04/27 04:57:29 sra Exp $ */ + +/*! \file */ /* * Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. @@ -53,6 +55,62 @@ * but INRIA implementation returns EAI_xxx defined for getaddrinfo(). */ + +/** + * This function is equivalent to the getnameinfo(3) function defined in + * RFC2133. lwres_getnameinfo() returns the hostname for the struct + * sockaddr sa which is salen bytes long. The hostname is of length + * hostlen and is returned via *host. The maximum length of the hostname + * is 1025 bytes: #NI_MAXHOST. + * + * The name of the service associated with the port number in sa is + * returned in *serv. It is servlen bytes long. The maximum length of the + * service name is #NI_MAXSERV - 32 bytes. + * + * The flags argument sets the following bits: + * + * \li #NI_NOFQDN: + * A fully qualified domain name is not required for local hosts. + * The local part of the fully qualified domain name is returned + * instead. + * + * \li #NI_NUMERICHOST + * Return the address in numeric form, as if calling inet_ntop(), + * instead of a host name. + * + * \li #NI_NAMEREQD + * A name is required. If the hostname cannot be found in the DNS + * and this flag is set, a non-zero error code is returned. If the + * hostname is not found and the flag is not set, the address is + * returned in numeric form. + * + * \li #NI_NUMERICSERV + * The service name is returned as a digit string representing the + * port number. + * + * \li #NI_DGRAM + * Specifies that the service being looked up is a datagram + * service, and causes getservbyport() to be called with a second + * argument of "udp" instead of its default of "tcp". This is + * required for the few ports (512-514) that have different + * services for UDP and TCP. + * + * \section getnameinfo_return Return Values + * + * lwres_getnameinfo() returns 0 on success or a non-zero error code if + * an error occurs. + * + * \section getname_see See Also + * + * RFC2133, getservbyport(), + * lwres_getnamebyaddr(). lwres_net_ntop(). + * + * \section getnameinfo_bugs Bugs + * + * RFC2133 fails to define what the nonzero return values of + * getnameinfo() are. + */ + #include #include @@ -67,12 +125,13 @@ #define SUCCESS 0 +/*% afd structure definition */ static struct afd { int a_af; size_t a_addrlen; size_t a_socklen; } afdl [] = { - /* + /*! * First entry is linked last... */ { AF_INET, sizeof(struct in_addr), sizeof(struct sockaddr_in) }, @@ -88,7 +147,7 @@ static struct afd { #define ENI_SALEN 6 #define ENI_NOSOCKET 7 -/* +/*! * The test against 0 is there to keep the Solaris compiler * from complaining about "end-of-loop code not reached". */ @@ -97,6 +156,7 @@ static struct afd { if (result != 0) goto cleanup; \ } while (0) +/*% lightweight resolver socket address structure to hostname and service name */ int lwres_getnameinfo(const struct sockaddr *sa, size_t salen, char *host, size_t hostlen, char *serv, size_t servlen, int flags) diff --git a/lib/lwres/getrrset.c b/lib/lwres/getrrset.c index 515f6b20f2..34575d057d 100644 --- a/lib/lwres/getrrset.c +++ b/lib/lwres/getrrset.c @@ -15,7 +15,77 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: getrrset.c,v 1.14 2004/03/05 05:12:46 marka Exp $ */ +/* $Id: getrrset.c,v 1.15 2005/04/27 04:57:29 sra Exp $ */ + +/*! \file */ + +/** + * DESCRIPTION + * + * lwres_getrrsetbyname() gets a set of resource records associated with + * a hostname, class, and type. hostname is a pointer a to + * null-terminated string. The flags field is currently unused and must + * be zero. + * + * After a successful call to lwres_getrrsetbyname(), *res is a pointer + * to an #rrsetinfo structure, containing a list of one or more #rdatainfo + * structures containing resource records and potentially another list of + * rdatainfo structures containing SIG resource records associated with + * those records. The members #rri_rdclass and #rri_rdtype are copied from + * the parameters. #rri_ttl and #rri_name are properties of the obtained + * rrset. The resource records contained in #rri_rdatas and #rri_sigs are + * in uncompressed DNS wire format. Properties of the rdataset are + * represented in the #rri_flags bitfield. If the #RRSET_VALIDATED bit is + * set, the data has been DNSSEC validated and the signatures verified. + * + * All of the information returned by lwres_getrrsetbyname() is + * dynamically allocated: the rrsetinfo and rdatainfo structures, and the + * canonical host name strings pointed to by the rrsetinfostructure. + * Memory allocated for the dynamically allocated structures created by a + * successful call to lwres_getrrsetbyname() is released by + * lwres_freerrset(). rrset is a pointer to a struct rrset created by a + * call to lwres_getrrsetbyname(). + * + * The following structures are used: + * + * \code + * struct rdatainfo { + * unsigned int rdi_length; // length of data + * unsigned char *rdi_data; // record data + * }; + * + * struct rrsetinfo { + * unsigned int rri_flags; // RRSET_VALIDATED... + * unsigned int rri_rdclass; // class number + * unsigned int rri_rdtype; // RR type number + * unsigned int rri_ttl; // time to live + * unsigned int rri_nrdatas; // size of rdatas array + * unsigned int rri_nsigs; // size of sigs array + * char *rri_name; // canonical name + * struct rdatainfo *rri_rdatas; // individual records + * struct rdatainfo *rri_sigs; // individual signatures + * }; + * \endcode + * + * \section getrrset_return Return Values + * + * lwres_getrrsetbyname() returns zero on success, and one of the + * following error codes if an error occurred: + * + * \li #ERRSET_NONAME: the name does not exist + * + * \li #ERRSET_NODATA: + * the name exists, but does not have data of the desired type + * + * \li #ERRSET_NOMEMORY: + * memory could not be allocated + * + * \li #ERRSET_INVAL: + * a parameter is invalid + * + * \li #ERRSET_FAIL: + * other failure + */ #include @@ -29,6 +99,9 @@ #include "assert_p.h" +/*! + * Structure to map results + */ static unsigned int lwresult_to_result(lwres_result_t lwresult) { switch (lwresult) { @@ -40,7 +113,8 @@ lwresult_to_result(lwres_result_t lwresult) { } } -/* +/*@{*/ +/*! * malloc / calloc functions that guarantee to only * return NULL if there is an error, like they used * to before the ANSI C committee broke them. @@ -61,7 +135,9 @@ sane_calloc(size_t number, size_t size) { memset(mem, 0, len); return (mem); } +/*@}*/ +/*% Returns a set of resource records associated with a hostname, class, and type. hostname is a pointer a to null-terminated string. */ int lwres_getrrsetbyname(const char *hostname, unsigned int rdclass, unsigned int rdtype, unsigned int flags, @@ -191,6 +267,7 @@ lwres_getrrsetbyname(const char *hostname, unsigned int rdclass, return (result); } +/*% Releases memory allocated for the dynamically allocated structures created by a successful call to lwres_getrrsetbyname(). */ void lwres_freerrset(struct rrsetinfo *rrset) { unsigned int i; diff --git a/lib/lwres/herror.c b/lib/lwres/herror.c index 7012025ef8..fe75244966 100644 --- a/lib/lwres/herror.c +++ b/lib/lwres/herror.c @@ -48,10 +48,31 @@ * SUCH DAMAGE. */ +/*! \file herror.c + lwres_herror() prints the string s on stderr followed by the string + generated by lwres_hstrerror() for the error code stored in the global + variable lwres_h_errno. + + lwres_hstrerror() returns an appropriate string for the error code + gievn by err. The values of the error codes and messages are as + follows: + +\li #NETDB_SUCCESS: Resolver Error 0 (no error) + +\li #HOST_NOT_FOUND: Unknown host + +\li #TRY_AGAIN: Host name lookup failure + +\li #NO_RECOVERY: Unknown server error + +\li #NO_DATA: No address associated with name + + */ + #if defined(LIBC_SCCS) && !defined(lint) static const char sccsid[] = "@(#)herror.c 8.1 (Berkeley) 6/4/93"; static const char rcsid[] = - "$Id: herror.c,v 1.13 2004/03/05 05:12:46 marka Exp $"; + "$Id: herror.c,v 1.14 2005/04/27 04:57:29 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -63,22 +84,22 @@ static const char rcsid[] = LIBLWRES_EXTERNAL_DATA int lwres_h_errno; -/* +/*! * these have never been declared in any header file so make them static */ static const char *h_errlist[] = { - "Resolver Error 0 (no error)", - "Unknown host", /* 1 HOST_NOT_FOUND */ - "Host name lookup failure", /* 2 TRY_AGAIN */ - "Unknown server error", /* 3 NO_RECOVERY */ - "No address associated with name", /* 4 NO_ADDRESS */ + "Resolver Error 0 (no error)", /*%< 0 no error */ + "Unknown host", /*%< 1 HOST_NOT_FOUND */ + "Host name lookup failure", /*%< 2 TRY_AGAIN */ + "Unknown server error", /*%< 3 NO_RECOVERY */ + "No address associated with name", /*%< 4 NO_ADDRESS */ }; static int h_nerr = { sizeof(h_errlist) / sizeof(h_errlist[0]) }; -/* +/*! * herror -- * print the error indicated by the h_errno value. */ @@ -87,7 +108,7 @@ lwres_herror(const char *s) { fprintf(stderr, "%s: %s\n", s, lwres_hstrerror(lwres_h_errno)); } -/* +/*! * hstrerror -- * return the string associated with a given "host" errno value. */ diff --git a/lib/lwres/include/lwres/context.h b/lib/lwres/include/lwres/context.h index 10b6b4e751..ade283e52b 100644 --- a/lib/lwres/include/lwres/context.h +++ b/lib/lwres/include/lwres/context.h @@ -15,18 +15,20 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: context.h,v 1.15 2004/03/05 05:12:52 marka Exp $ */ +/* $Id: context.h,v 1.16 2005/04/27 04:57:30 sra Exp $ */ #ifndef LWRES_CONTEXT_H #define LWRES_CONTEXT_H 1 +/*! \file */ + #include #include #include #include -/* +/*! * Used to set various options such as timeout, authentication, etc */ typedef struct lwres_context lwres_context_t; @@ -51,7 +53,7 @@ typedef void (*lwres_free_t)(void *arg, void *mem, size_t length); * Share /etc/resolv.conf data between contexts. */ -/* +/*! * _SERVERMODE * Don't allocate and connect a socket to the server, since the * caller _is_ a server. @@ -63,7 +65,7 @@ lwres_context_create(lwres_context_t **contextp, void *arg, lwres_malloc_t malloc_function, lwres_free_t free_function, unsigned int flags); -/* +/**< * Allocate a lwres context. This is used in all lwres calls. * * Memory management can be replaced here by passing in two functions. @@ -75,28 +77,22 @@ lwres_context_create(lwres_context_t **contextp, void *arg, * * If they are NULL, the standard malloc() and free() will be used. * - * Requires: + *\pre contextp != NULL && contextp == NULL. * - * contextp != NULL && contextp == NULL. - * - * Returns: - * - * Returns 0 on success, non-zero on failure. + *\return Returns 0 on success, non-zero on failure. */ void lwres_context_destroy(lwres_context_t **contextp); -/* +/**< * Frees all memory associated with a lwres context. * - * Requires: - * - * contextp != NULL && contextp == NULL. + *\pre contextp != NULL && contextp == NULL. */ lwres_uint32_t lwres_context_nextserial(lwres_context_t *ctx); -/* +/**< * XXXMLG Document */ diff --git a/lib/lwres/include/lwres/int.h b/lib/lwres/include/lwres/int.h index 966f5805ef..5bae2d5ae4 100644 --- a/lib/lwres/include/lwres/int.h +++ b/lib/lwres/include/lwres/int.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: int.h,v 1.8 2004/03/05 05:12:52 marka Exp $ */ +/* $Id: int.h,v 1.9 2005/04/27 04:57:31 sra Exp $ */ #ifndef LWRES_INT_H #define LWRES_INT_H 1 +/*! \file */ + typedef char lwres_int8_t; typedef unsigned char lwres_uint8_t; typedef short lwres_int16_t; diff --git a/lib/lwres/include/lwres/ipv6.h b/lib/lwres/include/lwres/ipv6.h index d0fef61299..00dd568c2c 100644 --- a/lib/lwres/include/lwres/ipv6.h +++ b/lib/lwres/include/lwres/ipv6.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: ipv6.h,v 1.10 2004/03/05 05:12:52 marka Exp $ */ +/* $Id: ipv6.h,v 1.11 2005/04/27 04:57:31 sra Exp $ */ #ifndef LWRES_IPV6_H #define LWRES_IPV6_H 1 @@ -24,7 +24,7 @@ ***** Module Info *****/ -/* +/*! \file ipv6.h * IPv6 definitions for systems which do not support IPv6. */ @@ -39,6 +39,7 @@ *** Types. ***/ +/*% in6_addr structure */ struct in6_addr { union { lwres_uint8_t _S6_u8[16]; @@ -46,10 +47,13 @@ struct in6_addr { lwres_uint32_t _S6_u32[4]; } _S6_un; }; +/*@{*/ +/*% IP v6 types */ #define s6_addr _S6_un._S6_u8 #define s6_addr8 _S6_un._S6_u8 #define s6_addr16 _S6_un._S6_u16 #define s6_addr32 _S6_un._S6_u32 +/*@}*/ #define IN6ADDR_ANY_INIT {{{ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 }}} #define IN6ADDR_LOOPBACK_INIT {{{ 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 }}} @@ -57,6 +61,7 @@ struct in6_addr { LIBLWRES_EXTERNAL_DATA extern const struct in6_addr in6addr_any; LIBLWRES_EXTERNAL_DATA extern const struct in6_addr in6addr_loopback; +/*% used in getaddrinfo.c and getnameinfo.c */ struct sockaddr_in6 { #ifdef LWRES_PLATFORM_HAVESALEN lwres_uint8_t sin6_len; @@ -74,13 +79,14 @@ struct sockaddr_in6 { #define SIN6_LEN 1 #endif +/*% in6_pktinfo structure */ struct in6_pktinfo { - struct in6_addr ipi6_addr; /* src/dst IPv6 address */ - unsigned int ipi6_ifindex; /* send/recv interface index */ + struct in6_addr ipi6_addr; /*%< src/dst IPv6 address */ + unsigned int ipi6_ifindex; /*%< send/recv interface index */ }; -/* - * Unspecified +/*! + * Unspecified IPv6 address */ #define IN6_IS_ADDR_UNSPECIFIED(a) \ (((a)->s6_addr32[0] == 0) && \ diff --git a/lib/lwres/include/lwres/lang.h b/lib/lwres/include/lwres/lang.h index 183390aa1a..a948838859 100644 --- a/lib/lwres/include/lwres/lang.h +++ b/lib/lwres/include/lwres/lang.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lang.h,v 1.7 2004/03/05 05:12:52 marka Exp $ */ +/* $Id: lang.h,v 1.8 2005/04/27 04:57:31 sra Exp $ */ #ifndef LWRES_LANG_H #define LWRES_LANG_H 1 +/*! \file */ + #ifdef __cplusplus #define LWRES_LANG_BEGINDECLS extern "C" { #define LWRES_LANG_ENDDECLS } diff --git a/lib/lwres/include/lwres/list.h b/lib/lwres/include/lwres/list.h index ba5b0cbe89..75caf804f6 100644 --- a/lib/lwres/include/lwres/list.h +++ b/lib/lwres/include/lwres/list.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: list.h,v 1.8 2004/03/05 05:12:52 marka Exp $ */ +/* $Id: list.h,v 1.9 2005/04/27 04:57:31 sra Exp $ */ #ifndef LWRES_LIST_H #define LWRES_LIST_H 1 +/*! \file */ + #define LWRES_LIST(type) struct { type *head, *tail; } #define LWRES_LIST_INIT(list) \ do { (list).head = NULL; (list).tail = NULL; } while (0) diff --git a/lib/lwres/include/lwres/lwbuffer.h b/lib/lwres/include/lwres/lwbuffer.h index 6a53f2a473..479586c3ad 100644 --- a/lib/lwres/include/lwres/lwbuffer.h +++ b/lib/lwres/include/lwres/lwbuffer.h @@ -1,4 +1,4 @@ -/* +/*! * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") * Copyright (C) 2000, 2001 Internet Software Consortium. * @@ -15,17 +15,10 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwbuffer.h,v 1.16 2004/03/05 05:12:52 marka Exp $ */ +/* $Id: lwbuffer.h,v 1.17 2005/04/27 04:57:31 sra Exp $ */ -#ifndef LWRES_LWBUFFER_H -#define LWRES_LWBUFFER_H 1 -/***** - ***** Module Info - *****/ - -/* - * Buffers +/*! \file lwbuffer.h * * A buffer is a region of memory, together with a set of related subregions. * Buffers are used for parsing and I/O operations. @@ -51,6 +44,7 @@ * region is empty. If the current offset advances beyond the chosen offset, * the active region will also be empty. * + * \verbatim * /----- used region -----\/-- available --\ * +----------------------------------------+ * | consumed | remaining | | @@ -68,9 +62,11 @@ * a-b == consumed region. * b-d == remaining region. * b-c == optional active region. + * \endverbatim * * The following invariants are maintained by all routines: * + *\verbatim * length > 0 * * base is a valid pointer to length bytes of memory @@ -81,24 +77,28 @@ * * 0 <= active <= used * (although active < current implies empty active region) + *\endverbatim * - * MP: + * \li MP: * Buffers have no synchronization. Clients must ensure exclusive * access. * - * Reliability: + * \li Reliability: * No anticipated impact. * - * Resources: + * \li Resources: * Memory: 1 pointer + 6 unsigned integers per buffer. * - * Security: + * \li Security: * No anticipated impact. * - * Standards: + * \li Standards: * None. */ +#ifndef LWRES_LWBUFFER_H +#define LWRES_LWBUFFER_H 1 + /*** *** Imports ***/ @@ -116,32 +116,35 @@ LWRES_LANG_BEGINDECLS #define LWRES_BUFFER_VALID(b) ((b) != NULL && \ (b)->magic == LWRES_BUFFER_MAGIC) -/* +/*! * The following macros MUST be used only on valid buffers. It is the * caller's responsibility to ensure this by using the LWRES_BUFFER_VALID * check above, or by calling another lwres_buffer_*() function (rather than * another macro.) */ -/* +/*! * Get the length of the used region of buffer "b" */ #define LWRES_BUFFER_USEDCOUNT(b) ((b)->used) -/* +/*! * Get the length of the available region of buffer "b" */ #define LWRES_BUFFER_AVAILABLECOUNT(b) ((b)->length - (b)->used) #define LWRES_BUFFER_REMAINING(b) ((b)->used - (b)->current) -/* +/*! * Note that the buffer structure is public. This is principally so buffer * operations can be implemented using macros. Applications are strongly * discouraged from directly manipulating the structure. */ typedef struct lwres_buffer lwres_buffer_t; +/*! + * Buffer data structure + */ struct lwres_buffer { unsigned int magic; unsigned char *base; @@ -158,7 +161,7 @@ struct lwres_buffer { void lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length); -/* +/**< * Make 'b' refer to the 'length'-byte region starting at base. * * Requires: @@ -171,7 +174,7 @@ lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length); void lwres_buffer_invalidate(lwres_buffer_t *b); -/* +/**< * Make 'b' an invalid buffer. * * Requires: @@ -184,7 +187,7 @@ lwres_buffer_invalidate(lwres_buffer_t *b); void lwres_buffer_add(lwres_buffer_t *b, unsigned int n); -/* +/**< * Increase the 'used' region of 'b' by 'n' bytes. * * Requires: @@ -197,7 +200,7 @@ lwres_buffer_add(lwres_buffer_t *b, unsigned int n); void lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n); -/* +/**< * Decrease the 'used' region of 'b' by 'n' bytes. * * Requires: @@ -210,7 +213,7 @@ lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n); void lwres_buffer_clear(lwres_buffer_t *b); -/* +/**< * Make the used region empty. * * Requires: @@ -223,9 +226,10 @@ lwres_buffer_clear(lwres_buffer_t *b); * */ + void lwres_buffer_first(lwres_buffer_t *b); -/* +/**< * Make the consumed region empty. * * Requires: @@ -240,7 +244,7 @@ lwres_buffer_first(lwres_buffer_t *b); void lwres_buffer_forward(lwres_buffer_t *b, unsigned int n); -/* +/**< * Increase the 'consumed' region of 'b' by 'n' bytes. * * Requires: @@ -253,7 +257,7 @@ lwres_buffer_forward(lwres_buffer_t *b, unsigned int n); void lwres_buffer_back(lwres_buffer_t *b, unsigned int n); -/* +/**< * Decrease the 'consumed' region of 'b' by 'n' bytes. * * Requires: @@ -266,7 +270,7 @@ lwres_buffer_back(lwres_buffer_t *b, unsigned int n); lwres_uint8_t lwres_buffer_getuint8(lwres_buffer_t *b); -/* +/**< * Read an unsigned 8-bit integer from 'b' and return it. * * Requires: @@ -286,7 +290,7 @@ lwres_buffer_getuint8(lwres_buffer_t *b); void lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val); -/* +/**< * Store an unsigned 8-bit integer from 'val' into 'b'. * * Requires: @@ -300,7 +304,7 @@ lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val); lwres_uint16_t lwres_buffer_getuint16(lwres_buffer_t *b); -/* +/**< * Read an unsigned 16-bit integer in network byte order from 'b', convert * it to host byte order, and return it. * @@ -321,7 +325,7 @@ lwres_buffer_getuint16(lwres_buffer_t *b); void lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val); -/* +/**< * Store an unsigned 16-bit integer in host byte order from 'val' * into 'b' in network byte order. * @@ -336,7 +340,7 @@ lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val); lwres_uint32_t lwres_buffer_getuint32(lwres_buffer_t *b); -/* +/**< * Read an unsigned 32-bit integer in network byte order from 'b', convert * it to host byte order, and return it. * @@ -357,7 +361,7 @@ lwres_buffer_getuint32(lwres_buffer_t *b); void lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val); -/* +/**< * Store an unsigned 32-bit integer in host byte order from 'val' * into 'b' in network byte order. * @@ -373,7 +377,7 @@ lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val); void lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, unsigned int length); -/* +/**< * Copy 'length' bytes of memory at 'base' into 'b'. * * Requires: @@ -386,7 +390,7 @@ lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, void lwres_buffer_getmem(lwres_buffer_t *b, unsigned char *base, unsigned int length); -/* +/**< * Copy 'length' bytes of memory from 'b' into 'base'. * * Requires: diff --git a/lib/lwres/include/lwres/lwpacket.h b/lib/lwres/include/lwres/lwpacket.h index e326826ebb..bf3a54a151 100644 --- a/lib/lwres/include/lwres/lwpacket.h +++ b/lib/lwres/include/lwres/lwpacket.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwpacket.h,v 1.18 2004/03/05 05:12:52 marka Exp $ */ +/* $Id: lwpacket.h,v 1.19 2005/04/27 04:57:31 sra Exp $ */ #ifndef LWRES_LWPACKET_H #define LWRES_LWPACKET_H 1 @@ -24,89 +24,124 @@ #include #include +/*% lwres_lwpacket_t */ typedef struct lwres_lwpacket lwres_lwpacket_t; +/*% lwres_lwpacket structure */ struct lwres_lwpacket { + /*! The overall packet length, including the + * entire packet header. + * This field is filled in by the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint32_t length; + /*! Specifies the header format. Currently, + * there is only one format, #LWRES_LWPACKETVERSION_0. + * This field is filled in by the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint16_t version; + /*! Specifies library-defined flags for this packet, such as + * whether the packet is a request or a reply. None of + * these are definable by the caller, but library-defined values + * can be set by the caller. For example, one bit in this field + * indicates if the packet is a request or a response. + * This field is filled in by + * the application wits the exception of the + * #LWRES_LWPACKETFLAG_RESPONSE bit, which is set by the library + * in the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint16_t pktflags; + /*! Set by the requestor and is returned in all replies. + * If two packets from the same source have the same serial + * number and are from the same source, they are assumed to + * be duplicates and the latter ones may be dropped. + * (The library does not do this by default on replies, but + * does so on requests.) + */ lwres_uint32_t serial; + /*! Opcodes between 0x04000000 and 0xffffffff + * are application defined. Opcodes between + * 0x00000000 and 0x03ffffff are + * reserved for library use. + * This field is filled in by the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint32_t opcode; + /*! Only valid for results. + * Results between 0x04000000 and 0xffffffff are application + * defined. + * Results between 0x00000000 and 0x03ffffff are reserved for + * library use. + * (This is the same reserved range defined in , + * so it + * would be trivial to map ISC_R_* result codes into packet result + * codes when appropriate.) + * This field is filled in by the + * \link lwres_gabn.c lwres_gabn_*()\endlink + * and \link lwres_gnba.c lwres_gnba_*()\endlink calls. + */ lwres_uint32_t result; + /*! Set to the maximum buffer size that the receiver can + * handle on requests, and the size of the buffer needed to + * satisfy a request + * when the buffer is too large for replies. + * This field is supplied by the application. + */ lwres_uint32_t recvlength; + /*! The packet level auth type used. + * Authtypes between 0x1000 and 0xffff are application defined. + * Authtypes + * between 0x0000 and 0x0fff are reserved for library use. + * This is currently + * unused and MUST be set to zero. + */ lwres_uint16_t authtype; + /*! The length of the authentication data. + * See the specific + * authtypes for more information on what is contained + * in this field. This is currently unused, and + * MUST be set to zero. + */ lwres_uint16_t authlength; }; -#define LWRES_LWPACKET_LENGTH (4 * 5 + 2 * 4) +#define LWRES_LWPACKET_LENGTH (4 * 5 + 2 * 4) /*%< Overall length. */ -#define LWRES_LWPACKETFLAG_RESPONSE 0x0001U /* if set, pkt is a response */ +#define LWRES_LWPACKETFLAG_RESPONSE 0x0001U /*%< If set, pkt is a response. */ -#define LWRES_LWPACKETVERSION_0 0 +#define LWRES_LWPACKETVERSION_0 0 /*%< Header format. */ -/* - * "length" is the overall packet length, including the entire packet header. +/*! \file lwpacket.h * - * "version" specifies the header format. Currently, there is only one - * format, LWRES_LWPACKETVERSION_0. - * - * "flags" specifies library-defined flags for this packet. None of these - * are definable by the caller, but library-defined values can be set by - * the caller. For example, one bit in this field indicates if the packet - * is a request or a response. - * - * "serial" is set by the requestor and is returned in all replies. If two - * packets from the same source have the same serial number and are from - * the same source, they are assumed to be duplicates and the latter ones - * may be dropped. (The library does not do this by default on replies, but - * does so on requests.) - * - * "opcode" is application defined. Opcodes between 0x04000000 and 0xffffffff - * are application defined. Opcodes between 0x00000000 and 0x03ffffff are - * reserved for library use. - * - * "result" is application defined, and valid only on replies. - * Results between 0x04000000 and 0xffffffff are application defined. - * Results between 0x00000000 and 0x03ffffff are reserved for library use. - * (This is the same reserved range defined in , so it - * would be trivial to map ISC_R_* result codes into packet result codes - * when appropriate.) - * - * "recvlength" is set to the maximum buffer size that the receiver can - * handle on requests, and the size of the buffer needed to satisfy a request - * when the buffer is too large for replies. - * - * "authtype" is the packet level auth type used. - * Authtypes between 0x1000 and 0xffff are application defined. Authtypes - * between 0x0000 and 0x0fff are reserved for library use. This is currently - * unused and MUST be set to zero. - * - * "authlen" is the length of the authentication data. See the specific - * authtypes for more information on what is contained in this field. This - * is currently unused, and MUST be set to zero. * * The remainder of the packet consists of two regions, one described by * "authlen" and one of "length - authlen - sizeof(lwres_lwpacket_t)". * * That is: * + * \code * pkt header * authlen bytes of auth information * data bytes - */ - -/* + * \endcode + * * Currently defined opcodes: * - * NOOP. Success is always returned, with the packet contents echoed. + *\li #LWRES_OPCODE_NOOP. Success is always returned, with the packet contents echoed. * - * GETADDRSBYNAME. Return all known addresses for a given name. + *\li #LWRES_OPCODE_GETADDRSBYNAME. Return all known addresses for a given name. * This may return NIS or /etc/hosts info as well as DNS * information. Flags will be provided to indicate ip4/ip6 * addresses are desired. * - * GETNAMEBYADDR. Return the hostname for the given address. Once + *\li #LWRES_OPCODE_GETNAMEBYADDR. Return the hostname for the given address. Once * again, it will return data from multiple sources. */ diff --git a/lib/lwres/include/lwres/lwres.h b/lib/lwres/include/lwres/lwres.h index 47b439caa1..be7b209fd7 100644 --- a/lib/lwres/include/lwres/lwres.h +++ b/lib/lwres/include/lwres/lwres.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres.h,v 1.51 2004/03/05 05:12:52 marka Exp $ */ +/* $Id: lwres.h,v 1.52 2005/04/27 04:57:31 sra Exp $ */ #ifndef LWRES_LWRES_H #define LWRES_LWRES_H 1 @@ -28,14 +28,16 @@ #include #include -/* +/*! \file */ + +/*! * Design notes: * * Each opcode has two structures and three functions which operate on each * structure. For example, using the "no operation/ping" opcode as an * example: * - * lwres_nooprequest_t: + *
  • lwres_nooprequest_t: * * lwres_nooprequest_render() takes a lwres_nooprequest_t and * and renders it into wire format, storing the allocated @@ -43,20 +45,20 @@ * is no longer needed, it must be freed by * lwres_context_freemem(). All other memory used by the * caller must be freed manually, including the - * lwres_nooprequest_t passed in. + * lwres_nooprequest_t passed in.

    * * lwres_nooprequest_parse() takes a wire format message and * breaks it out into a lwres_nooprequest_t. The structure * must be freed via lwres_nooprequest_free() when it is no longer - * needed. + * needed.

    * * lwres_nooprequest_free() releases into the lwres_context_t - * any space allocated during parsing. + * any space allocated during parsing.
    • * - * lwres_noopresponse_t: + *
  • lwres_noopresponse_t: * * The functions used are similar to the three used for - * requests, just with different names. + * requests, just with different names.
* * Typically, the client will use request_render, response_parse, and * response_free, while the daemon will use request_parse, response_render, @@ -64,62 +66,57 @@ * * The basic flow of a typical client is: * - * fill in a request_t, and call the render function. + * \li fill in a request_t, and call the render function. * - * Transmit the buffer returned to the daemon. + * \li Transmit the buffer returned to the daemon. * - * Wait for a response. + * \li Wait for a response. * - * When a response is received, parse it into a response_t. + * \li When a response is received, parse it into a response_t. * - * free the request buffer using lwres_context_freemem(). + * \li free the request buffer using lwres_context_freemem(). * - * free the response structure and its associated buffer using + * \li free the response structure and its associated buffer using * response_free(). */ -#define LWRES_UDP_PORT 921 -#define LWRES_RECVLENGTH 16384 -#define LWRES_ADDR_MAXLEN 16 /* changing this breaks ABI */ -#define LWRES_RESOLV_CONF "/etc/resolv.conf" +#define LWRES_UDP_PORT 921 /*%< UDP Port Number */ +#define LWRES_RECVLENGTH 16384 /*%< Maximum Packet Length */ +#define LWRES_ADDR_MAXLEN 16 /*%< changing this breaks ABI */ +#define LWRES_RESOLV_CONF "/etc/resolv.conf" /*%< Location of resolv.conf */ -/* - * Flags. - * - * These flags are only relevant to rrset queries. - * - * TRUSTNOTREQUIRED: DNSSEC is not required (input) - * SECUREDATA: The data was crypto-verified with DNSSEC (output) - * - */ +/*% DNSSEC is not required (input). Only relevant to rrset queries. */ #define LWRES_FLAG_TRUSTNOTREQUIRED 0x00000001U +/*% The data was crypto-verified with DNSSEC (output). */ #define LWRES_FLAG_SECUREDATA 0x00000002U -/* - * no-op - */ +/*% no-op */ #define LWRES_OPCODE_NOOP 0x00000000U +/*% lwres_nooprequest_t */ typedef struct { /* public */ lwres_uint16_t datalength; unsigned char *data; } lwres_nooprequest_t; +/*% lwres_noopresponse_t */ typedef struct { /* public */ lwres_uint16_t datalength; unsigned char *data; } lwres_noopresponse_t; -/* - * get addresses by name - */ +/*% get addresses by name */ #define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U +/*% lwres_addr_t */ typedef struct lwres_addr lwres_addr_t; + +/*% LWRES_LIST */ typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; +/*% lwres_addr */ struct lwres_addr { lwres_uint32_t family; lwres_uint16_t length; @@ -127,6 +124,7 @@ struct lwres_addr { LWRES_LINK(lwres_addr_t) link; }; +/*% lwres_gabnrequest_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -135,6 +133,7 @@ typedef struct { char *name; } lwres_gabnrequest_t; +/*% lwres_gabnresponse_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -145,21 +144,22 @@ typedef struct { lwres_uint16_t realnamelen; lwres_uint16_t *aliaslen; lwres_addrlist_t addrs; - /* if base != NULL, it will be freed when this structure is freed. */ + /*! if base != NULL, it will be freed when this structure is freed. */ void *base; size_t baselen; } lwres_gabnresponse_t; -/* - * get name by address - */ +/*% get name by address */ #define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U + +/*% lwres_gnbarequest_t */ typedef struct { /* public */ lwres_uint32_t flags; lwres_addr_t addr; } lwres_gnbarequest_t; +/*% lwres_gnbaresponse_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -168,16 +168,15 @@ typedef struct { char **aliases; lwres_uint16_t realnamelen; lwres_uint16_t *aliaslen; - /* if base != NULL, it will be freed when this structure is freed. */ + /*! if base != NULL, it will be freed when this structure is freed. */ void *base; size_t baselen; } lwres_gnbaresponse_t; -/* - * get rdata by name - */ +/*% get rdata by name */ #define LWRES_OPCODE_GETRDATABYNAME 0x00010003U +/*% lwres_grbnrequest_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -187,6 +186,7 @@ typedef struct { char *name; } lwres_grbnrequest_t; +/*% lwres_grbnresponse_t */ typedef struct { /* public */ lwres_uint32_t flags; @@ -201,58 +201,59 @@ typedef struct { lwres_uint16_t *rdatalen; unsigned char **sigs; lwres_uint16_t *siglen; - /* if base != NULL, it will be freed when this structure is freed. */ + /*% if base != NULL, it will be freed when this structure is freed. */ void *base; size_t baselen; } lwres_grbnresponse_t; +/*% Used by lwres_getrrsetbyname() */ #define LWRDATA_VALIDATED 0x00000001 -/* +/*! * resolv.conf data */ -#define LWRES_CONFMAXNAMESERVERS 3 /* max 3 "nameserver" entries */ -#define LWRES_CONFMAXLWSERVERS 1 /* max 1 "lwserver" entry */ -#define LWRES_CONFMAXSEARCH 8 /* max 8 domains in "search" entry */ -#define LWRES_CONFMAXLINELEN 256 /* max size of a line */ -#define LWRES_CONFMAXSORTLIST 10 +#define LWRES_CONFMAXNAMESERVERS 3 /*%< max 3 "nameserver" entries */ +#define LWRES_CONFMAXLWSERVERS 1 /*%< max 1 "lwserver" entry */ +#define LWRES_CONFMAXSEARCH 8 /*%< max 8 domains in "search" entry */ +#define LWRES_CONFMAXLINELEN 256 /*%< max size of a line */ +#define LWRES_CONFMAXSORTLIST 10 /*%< max 10 */ + +/*% lwres_conf_t */ typedef struct { lwres_context_t *lwctx; lwres_addr_t nameservers[LWRES_CONFMAXNAMESERVERS]; - lwres_uint8_t nsnext; /* index for next free slot */ + lwres_uint8_t nsnext; /*%< index for next free slot */ lwres_addr_t lwservers[LWRES_CONFMAXLWSERVERS]; - lwres_uint8_t lwnext; /* index for next free slot */ + lwres_uint8_t lwnext; /*%< index for next free slot */ char *domainname; char *search[LWRES_CONFMAXSEARCH]; - lwres_uint8_t searchnxt; /* index for next free slot */ + lwres_uint8_t searchnxt; /*%< index for next free slot */ struct { lwres_addr_t addr; - /* mask has a non-zero 'family' and 'length' if set */ + /*% mask has a non-zero 'family' and 'length' if set */ lwres_addr_t mask; } sortlist[LWRES_CONFMAXSORTLIST]; lwres_uint8_t sortlistnxt; - lwres_uint8_t resdebug; /* non-zero if 'options debug' set */ - lwres_uint8_t ndots; /* set to n in 'options ndots:n' */ - lwres_uint8_t no_tld_query; /* non-zero if 'options no_tld_query' */ + lwres_uint8_t resdebug; /*%< non-zero if 'options debug' set */ + lwres_uint8_t ndots; /*%< set to n in 'options ndots:n' */ + lwres_uint8_t no_tld_query; /*%< non-zero if 'options no_tld_query' */ } lwres_conf_t; -#define LWRES_ADDRTYPE_V4 0x00000001U /* ipv4 */ -#define LWRES_ADDRTYPE_V6 0x00000002U /* ipv6 */ +#define LWRES_ADDRTYPE_V4 0x00000001U /*%< ipv4 */ +#define LWRES_ADDRTYPE_V6 0x00000002U /*%< ipv6 */ -#define LWRES_MAX_ALIASES 16 /* max # of aliases */ -#define LWRES_MAX_ADDRS 64 /* max # of addrs */ +#define LWRES_MAX_ALIASES 16 /*%< max # of aliases */ +#define LWRES_MAX_ADDRS 64 /*%< max # of addrs */ LWRES_LANG_BEGINDECLS -/* - * This is in host byte order. - */ +/*% This is in host byte order. */ LIBLWRES_EXTERNAL_DATA extern lwres_uint16_t lwres_udp_port; LIBLWRES_EXTERNAL_DATA extern const char *lwres_resolv_conf; @@ -276,12 +277,12 @@ lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, void lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -295,12 +296,12 @@ lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp); void lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -332,12 +333,12 @@ lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, void lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -351,12 +352,12 @@ lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp); void lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -387,12 +388,12 @@ lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, void lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -406,12 +407,12 @@ lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp); void lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -426,12 +427,12 @@ lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp); lwres_result_t lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b); -/* +/**< * Allocate space and render into wire format a noop request packet. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * b != NULL, and points to a lwres_buffer_t. The contents of the * buffer structure will be initialized to contain the wire-format @@ -455,7 +456,7 @@ lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, lwres_result_t lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp); -/* +/**< * Parse a noop request. Note that to get here, the lwpacket must have * already been parsed and removed by the caller, otherwise it would be * pretty hard for it to know this is the right function to call. @@ -474,12 +475,12 @@ lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp); void lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp); -/* +/**< * Frees any dynamically allocated memory for this structure. * * Requires: * - * ctx != NULL, and be a context returned via lwres_contextcreate(). + * ctx != NULL, and be a context returned via lwres_context_create(). * * structp != NULL && *structp != NULL. * @@ -493,7 +494,7 @@ lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp); lwres_result_t lwres_conf_parse(lwres_context_t *ctx, const char *filename); -/* +/**< * parses a resolv.conf-format file and stores the results in the structure * pointed to by *ctx. * @@ -509,7 +510,7 @@ lwres_conf_parse(lwres_context_t *ctx, const char *filename); lwres_result_t lwres_conf_print(lwres_context_t *ctx, FILE *fp); -/* +/**< * Prints a resolv.conf-format of confdata output to fp. * * Requires: @@ -518,7 +519,7 @@ lwres_conf_print(lwres_context_t *ctx, FILE *fp); void lwres_conf_init(lwres_context_t *ctx); -/* +/**< * sets all internal fields to a default state. Used to initialize a new * lwres_conf_t structure (not reset a used on). * @@ -528,7 +529,7 @@ lwres_conf_init(lwres_context_t *ctx); void lwres_conf_clear(lwres_context_t *ctx); -/* +/**< * frees all internally allocated memory in confdata. Uses the memory * routines supplied by ctx. * @@ -538,8 +539,7 @@ lwres_conf_clear(lwres_context_t *ctx); lwres_conf_t * lwres_conf_get(lwres_context_t *ctx); -/* - * returns a pointer to the current config structure. +/**< * Be extremely cautions in modifying the contents of this structure; it * needs an API to return the various bits of data, walk lists, etc. * diff --git a/lib/lwres/include/lwres/netdb.h.in b/lib/lwres/include/lwres/netdb.h.in index 42eae93bc7..30f37db7db 100644 --- a/lib/lwres/include/lwres/netdb.h.in +++ b/lib/lwres/include/lwres/netdb.h.in @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: netdb.h.in,v 1.35 2004/03/05 05:12:53 marka Exp $ */ +/* $Id: netdb.h.in,v 1.36 2005/04/27 04:57:31 sra Exp $ */ + +/*! \file */ #ifndef LWRES_NETDB_H #define LWRES_NETDB_H 1 diff --git a/lib/lwres/include/lwres/platform.h.in b/lib/lwres/include/lwres/platform.h.in index c28a596b67..176cad9ab8 100644 --- a/lib/lwres/include/lwres/platform.h.in +++ b/lib/lwres/include/lwres/platform.h.in @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: platform.h.in,v 1.15 2004/08/28 06:17:00 marka Exp $ */ +/* $Id: platform.h.in,v 1.16 2005/04/27 04:57:31 sra Exp $ */ + +/*! \file */ #ifndef LWRES_PLATFORM_H #define LWRES_PLATFORM_H 1 @@ -98,4 +100,11 @@ #endif #endif +/* + * Tell Emacs to use C mode on this file. + * Local Variables: + * mode: c + * End: + */ + #endif /* LWRES_PLATFORM_H */ diff --git a/lib/lwres/include/lwres/result.h b/lib/lwres/include/lwres/result.h index c908008af4..8e04aec202 100644 --- a/lib/lwres/include/lwres/result.h +++ b/lib/lwres/include/lwres/result.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: result.h,v 1.15 2004/03/05 05:12:53 marka Exp $ */ +/* $Id: result.h,v 1.16 2005/04/27 04:57:31 sra Exp $ */ #ifndef LWRES_RESULT_H #define LWRES_RESULT_H 1 +/*! \file */ + typedef unsigned int lwres_result_t; #define LWRES_R_SUCCESS 0 diff --git a/lib/lwres/include/lwres/version.h b/lib/lwres/include/lwres/version.h index 2bb32f0e17..0613523467 100644 --- a/lib/lwres/include/lwres/version.h +++ b/lib/lwres/include/lwres/version.h @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.h,v 1.3 2004/03/05 05:12:53 marka Exp $ */ +/* $Id: version.h,v 1.4 2005/04/27 04:57:32 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/lwres/lwbuffer.c b/lib/lwres/lwbuffer.c index 6de95579f9..c8c20e4e66 100644 --- a/lib/lwres/lwbuffer.c +++ b/lib/lwres/lwbuffer.c @@ -15,7 +15,99 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwbuffer.c,v 1.11 2004/03/05 05:12:46 marka Exp $ */ +/* $Id: lwbuffer.c,v 1.12 2005/04/27 04:57:29 sra Exp $ */ + +/*! \file */ + +/** + * These functions provide bounds checked access to a region of memory + * where data is being read or written. They are based on, and similar + * to, the isc_buffer_ functions in the ISC library. + * + * A buffer is a region of memory, together with a set of related + * subregions. The used region and the available region are disjoint, and + * their union is the buffer's region. The used region extends from the + * beginning of the buffer region to the last used byte. The available + * region extends from one byte greater than the last used byte to the + * end of the buffer's region. The size of the used region can be changed + * using various buffer commands. Initially, the used region is empty. + * + * The used region is further subdivided into two disjoint regions: the + * consumed region and the remaining region. The union of these two + * regions is the used region. The consumed region extends from the + * beginning of the used region to the byte before the current offset (if + * any). The remaining region the current pointer to the end of the used + * region. The size of the consumed region can be changed using various + * buffer commands. Initially, the consumed region is empty. + * + * The active region is an (optional) subregion of the remaining region. + * It extends from the current offset to an offset in the remaining + * region. Initially, the active region is empty. If the current offset + * advances beyond the chosen offset, the active region will also be + * empty. + * + * + * \verbatim + * /------------entire length---------------\\ + * /----- used region -----\\/-- available --\\ + * +----------------------------------------+ + * | consumed | remaining | | + * +----------------------------------------+ + * a b c d e + * + * a == base of buffer. + * b == current pointer. Can be anywhere between a and d. + * c == active pointer. Meaningful between b and d. + * d == used pointer. + * e == length of buffer. + * + * a-e == entire length of buffer. + * a-d == used region. + * a-b == consumed region. + * b-d == remaining region. + * b-c == optional active region. + * \endverbatim + * + * lwres_buffer_init() initializes the lwres_buffer_t *b and assocates it + * with the memory region of size length bytes starting at location base. + * + * lwres_buffer_invalidate() marks the buffer *b as invalid. Invalidating + * a buffer after use is not required, but makes it possible to catch its + * possible accidental use. + * + * The functions lwres_buffer_add() and lwres_buffer_subtract() + * respectively increase and decrease the used space in buffer *b by n + * bytes. lwres_buffer_add() checks for buffer overflow and + * lwres_buffer_subtract() checks for underflow. These functions do not + * allocate or deallocate memory. They just change the value of used. + * + * A buffer is re-initialised by lwres_buffer_clear(). The function sets + * used , current and active to zero. + * + * lwres_buffer_first() makes the consumed region of buffer *p empty by + * setting current to zero (the start of the buffer). + * + * lwres_buffer_forward() increases the consumed region of buffer *b by n + * bytes, checking for overflow. Similarly, lwres_buffer_back() decreases + * buffer b's consumed region by n bytes and checks for underflow. + * + * lwres_buffer_getuint8() reads an unsigned 8-bit integer from *b and + * returns it. lwres_buffer_putuint8() writes the unsigned 8-bit integer + * val to buffer *b. + * + * lwres_buffer_getuint16() and lwres_buffer_getuint32() are identical to + * lwres_buffer_putuint8() except that they respectively read an unsigned + * 16-bit or 32-bit integer in network byte order from b. Similarly, + * lwres_buffer_putuint16() and lwres_buffer_putuint32() writes the + * unsigned 16-bit or 32-bit integer val to buffer b, in network byte + * order. + * + * Arbitrary amounts of data are read or written from a lightweight + * resolver buffer with lwres_buffer_getmem() and lwres_buffer_putmem() + * respectively. lwres_buffer_putmem() copies length bytes of memory at + * base to b. Conversely, lwres_buffer_getmem() copies length bytes of + * memory from b to base. + */ #include @@ -42,12 +134,10 @@ lwres_buffer_init(lwres_buffer_t *b, void *base, unsigned int length) b->active = 0; } +/* Make 'b' an invalid buffer. */ void lwres_buffer_invalidate(lwres_buffer_t *b) { - /* - * Make 'b' an invalid buffer. - */ REQUIRE(LWRES_BUFFER_VALID(b)); @@ -59,12 +149,10 @@ lwres_buffer_invalidate(lwres_buffer_t *b) b->active = 0; } +/* Increase the 'used' region of 'b' by 'n' bytes. */ void lwres_buffer_add(lwres_buffer_t *b, unsigned int n) { - /* - * Increase the 'used' region of 'b' by 'n' bytes. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used + n <= b->length); @@ -72,12 +160,10 @@ lwres_buffer_add(lwres_buffer_t *b, unsigned int n) b->used += n; } +/* Decrease the 'used' region of 'b' by 'n' bytes. */ void lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n) { - /* - * Decrease the 'used' region of 'b' by 'n' bytes. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used >= n); @@ -89,12 +175,10 @@ lwres_buffer_subtract(lwres_buffer_t *b, unsigned int n) b->active = b->used; } +/* Make the used region empty. */ void lwres_buffer_clear(lwres_buffer_t *b) { - /* - * Make the used region empty. - */ REQUIRE(LWRES_BUFFER_VALID(b)); @@ -103,24 +187,20 @@ lwres_buffer_clear(lwres_buffer_t *b) b->active = 0; } +/* Make the consumed region empty. */ void lwres_buffer_first(lwres_buffer_t *b) { - /* - * Make the consumed region empty. - */ REQUIRE(LWRES_BUFFER_VALID(b)); b->current = 0; } +/* Increase the 'consumed' region of 'b' by 'n' bytes. */ void lwres_buffer_forward(lwres_buffer_t *b, unsigned int n) { - /* - * Increase the 'consumed' region of 'b' by 'n' bytes. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->current + n <= b->used); @@ -128,12 +208,10 @@ lwres_buffer_forward(lwres_buffer_t *b, unsigned int n) b->current += n; } +/* Decrease the 'consumed' region of 'b' by 'n' bytes. */ void lwres_buffer_back(lwres_buffer_t *b, unsigned int n) { - /* - * Decrease the 'consumed' region of 'b' by 'n' bytes. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(n <= b->current); @@ -141,15 +219,13 @@ lwres_buffer_back(lwres_buffer_t *b, unsigned int n) b->current -= n; } +/* Read an unsigned 8-bit integer from 'b' and return it. */ lwres_uint8_t lwres_buffer_getuint8(lwres_buffer_t *b) { unsigned char *cp; lwres_uint8_t result; - /* - * Read an unsigned 8-bit integer from 'b' and return it. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used - b->current >= 1); @@ -162,6 +238,7 @@ lwres_buffer_getuint8(lwres_buffer_t *b) return (result); } +/* Put an unsigned 8-bit integer */ void lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val) { @@ -176,16 +253,13 @@ lwres_buffer_putuint8(lwres_buffer_t *b, lwres_uint8_t val) cp[0] = (val & 0x00ff); } +/* Read an unsigned 16-bit integer in network byte order from 'b', convert it to host byte order, and return it. */ lwres_uint16_t lwres_buffer_getuint16(lwres_buffer_t *b) { unsigned char *cp; lwres_uint16_t result; - /* - * Read an unsigned 16-bit integer in network byte order from 'b', - * convert it to host byte order, and return it. - */ REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used - b->current >= 2); @@ -199,6 +273,7 @@ lwres_buffer_getuint16(lwres_buffer_t *b) return (result); } +/* Put an unsigned 16-bit integer. */ void lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val) { @@ -214,17 +289,13 @@ lwres_buffer_putuint16(lwres_buffer_t *b, lwres_uint16_t val) cp[1] = (val & 0x00ff); } +/* Read an unsigned 32-bit integer in network byte order from 'b', convert it to host byte order, and return it. */ lwres_uint32_t lwres_buffer_getuint32(lwres_buffer_t *b) { unsigned char *cp; lwres_uint32_t result; - /* - * Read an unsigned 32-bit integer in network byte order from 'b', - * convert it to host byte order, and return it. - */ - REQUIRE(LWRES_BUFFER_VALID(b)); REQUIRE(b->used - b->current >= 4); @@ -239,6 +310,7 @@ lwres_buffer_getuint32(lwres_buffer_t *b) return (result); } +/* Put an unsigned 32-bit integer. */ void lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val) { @@ -256,6 +328,7 @@ lwres_buffer_putuint32(lwres_buffer_t *b, lwres_uint32_t val) cp[3] = (unsigned char)(val & 0x000000ff); } +/* copies length bytes of memory at base to b */ void lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, unsigned int length) @@ -270,6 +343,7 @@ lwres_buffer_putmem(lwres_buffer_t *b, const unsigned char *base, b->used += length; } +/* copies length bytes of memory at b to base */ void lwres_buffer_getmem(lwres_buffer_t *b, unsigned char *base, unsigned int length) diff --git a/lib/lwres/lwconfig.c b/lib/lwres/lwconfig.c index f2fa2e5e12..3f760779fc 100644 --- a/lib/lwres/lwconfig.c +++ b/lib/lwres/lwconfig.c @@ -15,26 +15,43 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwconfig.c,v 1.39 2004/06/28 06:23:05 jakob Exp $ */ +/* $Id: lwconfig.c,v 1.40 2005/04/27 04:57:29 sra Exp $ */ -/*** - *** Module for parsing resolv.conf files. - *** - *** entry points are: - *** lwres_conf_init(lwres_context_t *ctx) - *** initializes data structure for subsequent config parsing. - *** - *** lwres_conf_parse(lwres_context_t *ctx, const char *filename) - *** parses a file and fills in the data structure. - *** - *** lwres_conf_print(lwres_context_t *ctx, FILE *fp) - *** prints the config data structure to the FILE. - *** - *** lwres_conf_clear(lwres_context_t *ctx) - *** frees up all the internal memory used by the config data - *** structure, returning it to the lwres_context_t. - *** - ***/ +/*! \file */ + +/** + * Module for parsing resolv.conf files. + * + * lwres_conf_init() creates an empty lwres_conf_t structure for + * lightweight resolver context ctx. + * + * lwres_conf_clear() frees up all the internal memory used by that + * lwres_conf_t structure in resolver context ctx. + * + * lwres_conf_parse() opens the file filename and parses it to initialise + * the resolver context ctx's lwres_conf_t structure. + * + * lwres_conf_print() prints the lwres_conf_t structure for resolver + * context ctx to the FILE fp. + * + * \section lwconfig_return Return Values + * + * lwres_conf_parse() returns #LWRES_R_SUCCESS if it successfully read and + * parsed filename. It returns #LWRES_R_FAILURE if filename could not be + * opened or contained incorrect resolver statements. + * + * lwres_conf_print() returns #LWRES_R_SUCCESS unless an error occurred + * when converting the network addresses to a numeric host address + * string. If this happens, the function returns #LWRES_R_FAILURE. + * + * \section lwconfig_see See Also + * + * stdio(3), \link resolver resolver \endlink + * + * \section files Files + * + * /etc/resolv.conf + */ #include @@ -109,7 +126,7 @@ lwresaddr2af(int lwresaddrtype) } -/* +/*! * Eat characters from FP until EOL or EOF. Returns EOF or '\n' */ static int @@ -124,7 +141,7 @@ eatline(FILE *fp) { } -/* +/*! * Eats white space up to next newline or non-whitespace character (of * EOF). Returns the last character read. Comments are considered white * space. @@ -144,7 +161,7 @@ eatwhite(FILE *fp) { } -/* +/*! * Skip over any leading whitespace and then read in the next sequence of * non-whitespace characters. In this context newline is not considered * whitespace. Returns EOF on end-of-file, or the character @@ -203,6 +220,7 @@ lwres_strdup(lwres_context_t *ctx, const char *str) { return (p); } +/*% intializes data structure for subsequent config parsing. */ void lwres_conf_init(lwres_context_t *ctx) { int i; @@ -232,6 +250,7 @@ lwres_conf_init(lwres_context_t *ctx) { } } +/*% Frees up all the internal memory used by the config data structure, returning it to the lwres_context_t. */ void lwres_conf_clear(lwres_context_t *ctx) { int i; @@ -542,6 +561,7 @@ lwres_conf_parseoption(lwres_context_t *ctx, FILE *fp) { return (LWRES_R_SUCCESS); } +/*% parses a file and fills in the data structure. */ lwres_result_t lwres_conf_parse(lwres_context_t *ctx, const char *filename) { FILE *fp = NULL; @@ -600,6 +620,7 @@ lwres_conf_parse(lwres_context_t *ctx, const char *filename) { return (ret); } +/*% Prints the config data structure to the FILE. */ lwres_result_t lwres_conf_print(lwres_context_t *ctx, FILE *fp) { int i; @@ -695,6 +716,7 @@ lwres_conf_print(lwres_context_t *ctx, FILE *fp) { return (LWRES_R_SUCCESS); } +/*% Returns a pointer to the current config structure. */ lwres_conf_t * lwres_conf_get(lwres_context_t *ctx) { REQUIRE(ctx != NULL); diff --git a/lib/lwres/lwinetaton.c b/lib/lwres/lwinetaton.c index 6346d313ac..0ec84843b4 100644 --- a/lib/lwres/lwinetaton.c +++ b/lib/lwres/lwinetaton.c @@ -68,9 +68,11 @@ * SOFTWARE. */ +/*! \file lwinetaton.c + */ #if defined(LIBC_SCCS) && !defined(lint) static char sccsid[] = "@(#)inet_addr.c 8.1 (Berkeley) 6/17/93"; -static char rcsid[] = "$Id: lwinetaton.c,v 1.12 2004/03/05 05:12:46 marka Exp $"; +static char rcsid[] = "$Id: lwinetaton.c,v 1.13 2005/04/27 04:57:30 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -84,7 +86,7 @@ static char rcsid[] = "$Id: lwinetaton.c,v 1.12 2004/03/05 05:12:46 marka Exp $" #include "assert_p.h" -/* +/*! * Check whether "cp" is a valid ascii representation * of an Internet address and convert to a binary address. * Returns 1 if the address is valid, 0 if not. diff --git a/lib/lwres/lwinetntop.c b/lib/lwres/lwinetntop.c index d95c98e80d..bd3fd7f2d8 100644 --- a/lib/lwres/lwinetntop.c +++ b/lib/lwres/lwinetntop.c @@ -15,9 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/*! \file lwinetntop.c + */ #if defined(LIBC_SCCS) && !defined(lint) static char rcsid[] = - "$Id: lwinetntop.c,v 1.13 2004/08/28 06:16:59 marka Exp $"; + "$Id: lwinetntop.c,v 1.14 2005/04/27 04:57:30 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -45,7 +47,7 @@ static const char *inet_ntop6(const unsigned char *src, char *dst, size_t size); #endif -/* char * +/*! char * * lwres_net_ntop(af, src, dst, size) * convert a network format address to presentation format. * return: @@ -69,7 +71,7 @@ lwres_net_ntop(int af, const void *src, char *dst, size_t size) { /* NOTREACHED */ } -/* const char * +/*! const char * * inet_ntop4(src, dst, size) * format an IPv4 address * return: @@ -96,7 +98,7 @@ inet_ntop4(const unsigned char *src, char *dst, size_t size) { return (dst); } -/* const char * +/*! const char * * inet_ntop6(src, dst, size) * convert IPv6 binary address into presentation (printable) format * author: @@ -105,7 +107,7 @@ inet_ntop4(const unsigned char *src, char *dst, size_t size) { #ifdef AF_INET6 static const char * inet_ntop6(const unsigned char *src, char *dst, size_t size) { - /* + /*! * Note that int32_t and int16_t need only be "at least" large enough * to contain a value of the specified size. On some systems, like * Crays, there is no such thing as an integer variable with 16 bits. diff --git a/lib/lwres/lwinetpton.c b/lib/lwres/lwinetpton.c index 479a90f5a5..2693e71fcc 100644 --- a/lib/lwres/lwinetpton.c +++ b/lib/lwres/lwinetpton.c @@ -15,8 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/*! \file lwinetpton.c + */ + #if defined(LIBC_SCCS) && !defined(lint) -static char rcsid[] = "$Id: lwinetpton.c,v 1.9 2005/03/31 23:54:46 marka Exp $"; +static char rcsid[] = "$Id: lwinetpton.c,v 1.10 2005/04/27 04:57:30 sra Exp $"; #endif /* LIBC_SCCS and not lint */ #include @@ -38,7 +41,8 @@ static char rcsid[] = "$Id: lwinetpton.c,v 1.9 2005/03/31 23:54:46 marka Exp $"; static int inet_pton4(const char *src, unsigned char *dst); static int inet_pton6(const char *src, unsigned char *dst); -/* int +/*! + * int * lwres_net_pton(af, src, dst) * convert from presentation format (which usually means ASCII printable) * to network format (which is usually some kind of binary format). @@ -63,7 +67,7 @@ lwres_net_pton(int af, const char *src, void *dst) { /* NOTREACHED */ } -/* int +/*! int * inet_pton4(src, dst) * like inet_aton() but without all the hexadecimal and shorthand. * return: @@ -110,7 +114,7 @@ inet_pton4(const char *src, unsigned char *dst) { return (1); } -/* int +/*! int * inet_pton6(src, dst) * convert presentation level address to network order binary form. * return: diff --git a/lib/lwres/lwpacket.c b/lib/lwres/lwpacket.c index 9623509382..18eba8206a 100644 --- a/lib/lwres/lwpacket.c +++ b/lib/lwres/lwpacket.c @@ -15,7 +15,46 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwpacket.c,v 1.14 2004/03/05 05:12:46 marka Exp $ */ +/* $Id: lwpacket.c,v 1.15 2005/04/27 04:57:30 sra Exp $ */ + +/*! \file */ + +/** + * These functions rely on a struct lwres_lwpacket which is defined in + * \link lwpacket.h lwres/lwpacket.h.\endlink + * + * The following opcodes are currently defined: + * + * \li #LWRES_OPCODE_NOOP + * Success is always returned and the packet contents are + * echoed. The \link lwres_noop.c lwres_noop_*()\endlink functions should be used for this + * type. + * + * \li #LWRES_OPCODE_GETADDRSBYNAME + * returns all known addresses for a given name. The + * \link lwres_gabn.c lwres_gabn_*()\endlink functions should be used for this type. + * + * \li #LWRES_OPCODE_GETNAMEBYADDR + * return the hostname for the given address. The + * \link lwres_gnba.c lwres_gnba_*() \endlink functions should be used for this type. + * + * lwres_lwpacket_renderheader() transfers the contents of lightweight + * resolver packet structure #lwres_lwpacket_t *pkt in network byte + * order to the lightweight resolver buffer, *b. + * + * lwres_lwpacket_parseheader() performs the converse operation. It + * transfers data in network byte order from buffer *b to resolver + * packet *pkt. The contents of the buffer b should correspond to a + * #lwres_lwpacket_t. + * + * \section lwpacket_return Return Values + * + * Successful calls to lwres_lwpacket_renderheader() and + * lwres_lwpacket_parseheader() return #LWRES_R_SUCCESS. If there is + * insufficient space to copy data between the buffer *b and + * lightweight resolver packet *pkt both functions return + * #LWRES_R_UNEXPECTEDEND. + */ #include @@ -29,9 +68,12 @@ #include "assert_p.h" +/*% Length of Packet */ #define LWPACKET_LENGTH \ (sizeof(lwres_uint16_t) * 4 + sizeof(lwres_uint32_t) * 5) +/*% transfers the contents of lightweight resolver packet structure lwres_lwpacket_t *pkt in network byte order to the lightweight resolver buffer, *b. */ + lwres_result_t lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt) { REQUIRE(b != NULL); @@ -53,6 +95,8 @@ lwres_lwpacket_renderheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt) { return (LWRES_R_SUCCESS); } +/*% transfers data in network byte order from buffer *b to resolver packet *pkt. The contents of the buffer b should correspond to a lwres_lwpacket_t. */ + lwres_result_t lwres_lwpacket_parseheader(lwres_buffer_t *b, lwres_lwpacket_t *pkt) { lwres_uint32_t space; diff --git a/lib/lwres/lwres_gabn.c b/lib/lwres/lwres_gabn.c index 144e94f43f..c280d68912 100644 --- a/lib/lwres/lwres_gabn.c +++ b/lib/lwres/lwres_gabn.c @@ -15,7 +15,92 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres_gabn.c,v 1.29 2004/03/05 05:12:46 marka Exp $ */ +/* $Id: lwres_gabn.c,v 1.30 2005/04/27 04:57:30 sra Exp $ */ + +/*! \file lwres_gabn.c + These are low-level routines for creating and parsing lightweight + resolver name-to-address lookup request and response messages. + + There are four main functions for the getaddrbyname opcode. One render + function converts a getaddrbyname request structure -- + lwres_gabnrequest_t -- to the lighweight resolver's canonical format. + It is complemented by a parse function that converts a packet in this + canonical format to a getaddrbyname request structure. Another render + function converts the getaddrbyname response structure -- + lwres_gabnresponse_t -- to the canonical format. This is complemented + by a parse function which converts a packet in canonical format to a + getaddrbyname response structure. + + These structures are defined in \link lwres.h .\endlink They are shown below. + +\code +#define LWRES_OPCODE_GETADDRSBYNAME 0x00010001U + +typedef struct lwres_addr lwres_addr_t; +typedef LWRES_LIST(lwres_addr_t) lwres_addrlist_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint32_t addrtypes; + lwres_uint16_t namelen; + char *name; +} lwres_gabnrequest_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + lwres_uint16_t naddrs; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + lwres_addrlist_t addrs; + void *base; + size_t baselen; +} lwres_gabnresponse_t; +\endcode + + lwres_gabnrequest_render() uses resolver context ctx to convert + getaddrbyname request structure req to canonical format. The packet + header structure pkt is initialised and transferred to buffer b. The + contents of *req are then appended to the buffer in canonical format. + lwres_gabnresponse_render() performs the same task, except it converts + a getaddrbyname response structure lwres_gabnresponse_t to the + lightweight resolver's canonical format. + + lwres_gabnrequest_parse() uses context ctx to convert the contents of + packet pkt to a lwres_gabnrequest_t structure. Buffer b provides space + to be used for storing this structure. When the function succeeds, the + resulting lwres_gabnrequest_t is made available through *structp. + lwres_gabnresponse_parse() offers the same semantics as + lwres_gabnrequest_parse() except it yields a lwres_gabnresponse_t + structure. + + lwres_gabnresponse_free() and lwres_gabnrequest_free() release the + memory in resolver context ctx that was allocated to the + lwres_gabnresponse_t or lwres_gabnrequest_t structures referenced via + structp. Any memory associated with ancillary buffers and strings for + those structures is also discarded. + +\section lwres_gabn_return Return Values + + The getaddrbyname opcode functions lwres_gabnrequest_render(), + lwres_gabnresponse_render() lwres_gabnrequest_parse() and + lwres_gabnresponse_parse() all return #LWRES_R_SUCCESS on success. They + return #LWRES_R_NOMEMORY if memory allocation fails. + #LWRES_R_UNEXPECTEDEND is returned if the available space in the buffer + b is too small to accommodate the packet header or the + lwres_gabnrequest_t and lwres_gabnresponse_t structures. + lwres_gabnrequest_parse() and lwres_gabnresponse_parse() will return + #LWRES_R_UNEXPECTEDEND if the buffer is not empty after decoding the + received packet. These functions will return #LWRES_R_FAILURE if + pktflags in the packet header structure #lwres_lwpacket_t indicate that + the packet is not a response to an earlier query. + +\section lwres_gabn_see See Also + + \link lwpacket.c lwres_lwpacket \endlink + */ #include @@ -31,6 +116,7 @@ #include "context_p.h" #include "assert_p.h" +/*% uses resolver context ctx to convert getaddrbyname request structure req to canonical format. */ lwres_result_t lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -97,7 +183,7 @@ lwres_gabnrequest_render(lwres_context_t *ctx, lwres_gabnrequest_t *req, return (LWRES_R_SUCCESS); } - +/*% converts a getaddrbyname response structure lwres_gabnresponse_t to the lightweight resolver's canonical format. */ lwres_result_t lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -194,7 +280,7 @@ lwres_gabnresponse_render(lwres_context_t *ctx, lwres_gabnresponse_t *req, return (LWRES_R_SUCCESS); } - +/*% Uses context ctx to convert the contents of packet pkt to a lwres_gabnrequest_t structure. */ lwres_result_t lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnrequest_t **structp) @@ -243,6 +329,8 @@ lwres_gabnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (LWRES_R_SUCCESS); } +/*% Offers the same semantics as lwres_gabnrequest_parse() except it yields a lwres_gabnresponse_t structure. */ + lwres_result_t lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gabnresponse_t **structp) @@ -372,6 +460,7 @@ lwres_gabnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Release the memory in resolver context ctx that was allocated to the lwres_gabnrequest_t. */ void lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp) { @@ -386,6 +475,7 @@ lwres_gabnrequest_free(lwres_context_t *ctx, lwres_gabnrequest_t **structp) CTXFREE(gabn, sizeof(lwres_gabnrequest_t)); } +/*% Release the memory in resolver context ctx that was allocated to the lwres_gabnresponse_t. */ void lwres_gabnresponse_free(lwres_context_t *ctx, lwres_gabnresponse_t **structp) { diff --git a/lib/lwres/lwres_gnba.c b/lib/lwres/lwres_gnba.c index bbdc855a1d..eeae545154 100644 --- a/lib/lwres/lwres_gnba.c +++ b/lib/lwres/lwres_gnba.c @@ -15,7 +15,88 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres_gnba.c,v 1.23 2004/03/05 05:12:46 marka Exp $ */ +/* $Id: lwres_gnba.c,v 1.24 2005/04/27 04:57:30 sra Exp $ */ + +/*! \file lwres_gnba.c + These are low-level routines for creating and parsing lightweight + resolver address-to-name lookup request and response messages. + + There are four main functions for the getnamebyaddr opcode. One + render function converts a getnamebyaddr request structure -- + lwres_gnbarequest_t -- to the lightweight resolver's canonical + format. It is complemented by a parse function that converts a + packet in this canonical format to a getnamebyaddr request + structure. Another render function converts the getnamebyaddr + response structure -- lwres_gnbaresponse_t to the canonical format. + This is complemented by a parse function which converts a packet in + canonical format to a getnamebyaddr response structure. + + These structures are defined in \link lwres.h \endlink They are shown + below. + +\code +#define LWRES_OPCODE_GETNAMEBYADDR 0x00010002U + +typedef struct { + lwres_uint32_t flags; + lwres_addr_t addr; +} lwres_gnbarequest_t; + +typedef struct { + lwres_uint32_t flags; + lwres_uint16_t naliases; + char *realname; + char **aliases; + lwres_uint16_t realnamelen; + lwres_uint16_t *aliaslen; + void *base; + size_t baselen; +} lwres_gnbaresponse_t; +\endcode + + lwres_gnbarequest_render() uses resolver context ctx to convert + getnamebyaddr request structure req to canonical format. The packet + header structure pkt is initialised and transferred to buffer b. + The contents of *req are then appended to the buffer in canonical + format. lwres_gnbaresponse_render() performs the same task, except + it converts a getnamebyaddr response structure lwres_gnbaresponse_t + to the lightweight resolver's canonical format. + + lwres_gnbarequest_parse() uses context ctx to convert the contents + of packet pkt to a lwres_gnbarequest_t structure. Buffer b provides + space to be used for storing this structure. When the function + succeeds, the resulting lwres_gnbarequest_t is made available + through *structp. lwres_gnbaresponse_parse() offers the same +semantics as lwres_gnbarequest_parse() except it yields a + lwres_gnbaresponse_t structure. + + lwres_gnbaresponse_free() and lwres_gnbarequest_free() release the + memory in resolver context ctx that was allocated to the + lwres_gnbaresponse_t or lwres_gnbarequest_t structures referenced + via structp. Any memory associated with ancillary buffers and + strings for those structures is also discarded. + +\section lwres_gbna_return Return Values + + The getnamebyaddr opcode functions lwres_gnbarequest_render(), + lwres_gnbaresponse_render() lwres_gnbarequest_parse() and + lwres_gnbaresponse_parse() all return #LWRES_R_SUCCESS on success. + They return #LWRES_R_NOMEMORY if memory allocation fails. + #LWRES_R_UNEXPECTEDEND is returned if the available space in the + buffer b is too small to accommodate the packet header or the + lwres_gnbarequest_t and lwres_gnbaresponse_t structures. + lwres_gnbarequest_parse() and lwres_gnbaresponse_parse() will + return #LWRES_R_UNEXPECTEDEND if the buffer is not empty after + decoding the received packet. These functions will return + #LWRES_R_FAILURE if pktflags in the packet header structure + #lwres_lwpacket_t indicate that the packet is not a response to an + earlier query. + +\section lwres_gbna_see See Also + + \link lwpacket.c lwres_packet\endlink + + */ #include @@ -31,6 +112,7 @@ #include "context_p.h" #include "assert_p.h" +/*% Uses resolver context ctx to convert getnamebyaddr request structure req to canonical format. */ lwres_result_t lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -88,6 +170,7 @@ lwres_gnbarequest_render(lwres_context_t *ctx, lwres_gnbarequest_t *req, return (LWRES_R_SUCCESS); } +/*% Converts a getnamebyaddr response structure lwres_gnbaresponse_t to the lightweight resolver's canonical format. */ lwres_result_t lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -159,6 +242,7 @@ lwres_gnbaresponse_render(lwres_context_t *ctx, lwres_gnbaresponse_t *req, return (LWRES_R_SUCCESS); } +/*% Uses context ctx to convert the contents of packet pkt to a lwres_gnbarequest_t structure. */ lwres_result_t lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbarequest_t **structp) @@ -202,6 +286,8 @@ lwres_gnbarequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Offers the same semantics as lwres_gnbarequest_parse() except it yields a lwres_gnbaresponse_t structure. */ + lwres_result_t lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_gnbaresponse_t **structp) @@ -292,6 +378,7 @@ lwres_gnbaresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Release the memory in resolver context ctx that was allocated to the lwres_gnbarequest_t. */ void lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp) { @@ -306,6 +393,7 @@ lwres_gnbarequest_free(lwres_context_t *ctx, lwres_gnbarequest_t **structp) CTXFREE(gnba, sizeof(lwres_gnbarequest_t)); } +/*% Release the memory in resolver context ctx that was allocated to the lwres_gnbaresponse_t. */ void lwres_gnbaresponse_free(lwres_context_t *ctx, lwres_gnbaresponse_t **structp) { diff --git a/lib/lwres/lwres_grbn.c b/lib/lwres/lwres_grbn.c index 32061c0b23..413c68d4a5 100644 --- a/lib/lwres/lwres_grbn.c +++ b/lib/lwres/lwres_grbn.c @@ -15,7 +15,11 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres_grbn.c,v 1.6 2004/03/05 05:12:46 marka Exp $ */ +/* $Id: lwres_grbn.c,v 1.7 2005/04/27 04:57:30 sra Exp $ */ + +/*! \file lwres_grbn.c + + */ #include @@ -31,6 +35,7 @@ #include "context_p.h" #include "assert_p.h" +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ lwres_result_t lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -103,6 +108,7 @@ lwres_grbnrequest_render(lwres_context_t *ctx, lwres_grbnrequest_t *req, return (LWRES_R_SUCCESS); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ lwres_result_t lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -190,6 +196,7 @@ lwres_grbnresponse_render(lwres_context_t *ctx, lwres_grbnresponse_t *req, return (LWRES_R_SUCCESS); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ lwres_result_t lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_grbnrequest_t **structp) @@ -243,6 +250,7 @@ lwres_grbnrequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (LWRES_R_SUCCESS); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ lwres_result_t lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_grbnresponse_t **structp) @@ -376,6 +384,7 @@ lwres_grbnresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ void lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp) { @@ -390,6 +399,7 @@ lwres_grbnrequest_free(lwres_context_t *ctx, lwres_grbnrequest_t **structp) CTXFREE(grbn, sizeof(lwres_grbnrequest_t)); } +/*% Thread-save equivalent to \link lwres_gabn.c lwres_gabn* \endlink routines. */ void lwres_grbnresponse_free(lwres_context_t *ctx, lwres_grbnresponse_t **structp) { diff --git a/lib/lwres/lwres_noop.c b/lib/lwres/lwres_noop.c index 30e530a243..7e0442af93 100644 --- a/lib/lwres/lwres_noop.c +++ b/lib/lwres/lwres_noop.c @@ -15,7 +15,87 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwres_noop.c,v 1.15 2004/03/05 05:12:47 marka Exp $ */ +/* $Id: lwres_noop.c,v 1.16 2005/04/27 04:57:30 sra Exp $ */ + +/*! \file */ + +/** + * These are low-level routines for creating and parsing lightweight + * resolver no-op request and response messages. + * + * The no-op message is analogous to a ping packet: a packet is sent to + * the resolver daemon and is simply echoed back. The opcode is intended + * to allow a client to determine if the server is operational or not. + * + * There are four main functions for the no-op opcode. One render + * function converts a no-op request structure -- lwres_nooprequest_t -- + * to the lighweight resolver's canonical format. It is complemented by a + * parse function that converts a packet in this canonical format to a + * no-op request structure. Another render function converts the no-op + * response structure -- lwres_noopresponse_t to the canonical format. + * This is complemented by a parse function which converts a packet in + * canonical format to a no-op response structure. + * + * These structures are defined in \link lwres.h \endlink They are shown below. + * + * \code + * #define LWRES_OPCODE_NOOP 0x00000000U + * + * typedef struct { + * lwres_uint16_t datalength; + * unsigned char *data; + * } lwres_nooprequest_t; + * + * typedef struct { + * lwres_uint16_t datalength; + * unsigned char *data; + * } lwres_noopresponse_t; + * \endcode + * + * Although the structures have different types, they are identical. This + * is because the no-op opcode simply echos whatever data was sent: the + * response is therefore identical to the request. + * + * lwres_nooprequest_render() uses resolver context ctx to convert no-op + * request structure req to canonical format. The packet header structure + * pkt is initialised and transferred to buffer b. The contents of *req + * are then appended to the buffer in canonical format. + * lwres_noopresponse_render() performs the same task, except it converts + * a no-op response structure lwres_noopresponse_t to the lightweight + * resolver's canonical format. + * + * lwres_nooprequest_parse() uses context ctx to convert the contents of + * packet pkt to a lwres_nooprequest_t structure. Buffer b provides space + * to be used for storing this structure. When the function succeeds, the + * resulting lwres_nooprequest_t is made available through *structp. + * lwres_noopresponse_parse() offers the same semantics as + * lwres_nooprequest_parse() except it yields a lwres_noopresponse_t + * structure. + * + * lwres_noopresponse_free() and lwres_nooprequest_free() release the + * memory in resolver context ctx that was allocated to the + * lwres_noopresponse_t or lwres_nooprequest_t structures referenced via + * structp. + * + * \section lwres_noop_return Return Values + * + * The no-op opcode functions lwres_nooprequest_render(), + * lwres_noopresponse_render() lwres_nooprequest_parse() and + * lwres_noopresponse_parse() all return #LWRES_R_SUCCESS on success. They + * return #LWRES_R_NOMEMORY if memory allocation fails. + * #LWRES_R_UNEXPECTEDEND is returned if the available space in the buffer + * b is too small to accommodate the packet header or the + * lwres_nooprequest_t and lwres_noopresponse_t structures. + * lwres_nooprequest_parse() and lwres_noopresponse_parse() will return + * #LWRES_R_UNEXPECTEDEND if the buffer is not empty after decoding the + * received packet. These functions will return #LWRES_R_FAILURE if + * pktflags in the packet header structure #lwres_lwpacket_t indicate that + * the packet is not a response to an earlier query. + * + * \section lwres_noop_see See Also + * + * lwpacket.c + */ #include @@ -31,6 +111,7 @@ #include "context_p.h" #include "assert_p.h" +/*% Uses resolver context ctx to convert no-op request structure req to canonical format. */ lwres_result_t lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -82,6 +163,8 @@ lwres_nooprequest_render(lwres_context_t *ctx, lwres_nooprequest_t *req, return (LWRES_R_SUCCESS); } +/*% Converts a no-op response structure lwres_noopresponse_t to the lightweight resolver's canonical format. */ + lwres_result_t lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, lwres_lwpacket_t *pkt, lwres_buffer_t *b) @@ -132,6 +215,7 @@ lwres_noopresponse_render(lwres_context_t *ctx, lwres_noopresponse_t *req, return (LWRES_R_SUCCESS); } +/*% Uses context ctx to convert the contents of packet pkt to a lwres_nooprequest_t structure. */ lwres_result_t lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_nooprequest_t **structp) @@ -179,6 +263,7 @@ lwres_nooprequest_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Offers the same semantics as lwres_nooprequest_parse() except it yields a lwres_noopresponse_t structure. */ lwres_result_t lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, lwres_lwpacket_t *pkt, lwres_noopresponse_t **structp) @@ -226,6 +311,7 @@ lwres_noopresponse_parse(lwres_context_t *ctx, lwres_buffer_t *b, return (ret); } +/*% Release the memory in resolver context ctx. */ void lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp) { @@ -240,6 +326,7 @@ lwres_noopresponse_free(lwres_context_t *ctx, lwres_noopresponse_t **structp) CTXFREE(noop, sizeof(lwres_noopresponse_t)); } +/*% Release the memory in resolver context ctx. */ void lwres_nooprequest_free(lwres_context_t *ctx, lwres_nooprequest_t **structp) { diff --git a/lib/lwres/lwresutil.c b/lib/lwres/lwresutil.c index ce26818287..205fbabde1 100644 --- a/lib/lwres/lwresutil.c +++ b/lib/lwres/lwresutil.c @@ -15,7 +15,86 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: lwresutil.c,v 1.30 2004/03/05 05:12:47 marka Exp $ */ +/* $Id: lwresutil.c,v 1.31 2005/04/27 04:57:30 sra Exp $ */ + +/*! \file */ + +/** + * lwres_string_parse() retrieves a DNS-encoded string starting the + * current pointer of lightweight resolver buffer b: i.e. b->current. + * When the function returns, the address of the first byte of the + * encoded string is returned via *c and the length of that string is + * given by *len. The buffer's current pointer is advanced to point at + * the character following the string length, the encoded string, and + * the trailing NULL character. + * + * lwres_addr_parse() extracts an address from the buffer b. The + * buffer's current pointer b->current is presumed to point at an + * encoded address: the address preceded by a 32-bit protocol family + * identifier and a 16-bit length field. The encoded address is copied + * to addr->address and addr->length indicates the size in bytes of + * the address that was copied. b->current is advanced to point at the + * next byte of available data in the buffer following the encoded + * address. + * + * lwres_getaddrsbyname() and lwres_getnamebyaddr() use the + * lwres_gnbaresponse_t structure defined below: + * + * \code + * typedef struct { + * lwres_uint32_t flags; + * lwres_uint16_t naliases; + * lwres_uint16_t naddrs; + * char *realname; + * char **aliases; + * lwres_uint16_t realnamelen; + * lwres_uint16_t *aliaslen; + * lwres_addrlist_t addrs; + * void *base; + * size_t baselen; + * } lwres_gabnresponse_t; + * \endcode + * + * The contents of this structure are not manipulated directly but + * they are controlled through the \link lwres_gabn.c lwres_gabn*\endlink functions. + * + * The lightweight resolver uses lwres_getaddrsbyname() to perform + * foward lookups. Hostname name is looked up using the resolver + * context ctx for memory allocation. addrtypes is a bitmask + * indicating which type of addresses are to be looked up. Current + * values for this bitmask are #LWRES_ADDRTYPE_V4 for IPv4 addresses + * and #LWRES_ADDRTYPE_V6 for IPv6 addresses. Results of the lookup are + * returned in *structp. + * + * lwres_getnamebyaddr() performs reverse lookups. Resolver context + * ctx is used for memory allocation. The address type is indicated by + * addrtype: #LWRES_ADDRTYPE_V4 or #LWRES_ADDRTYPE_V6. The address to be + * looked up is given by addr and its length is addrlen bytes. The + * result of the function call is made available through *structp. + * + * \section lwresutil_return Return Values + * + * Successful calls to lwres_string_parse() and lwres_addr_parse() + * return #LWRES_R_SUCCESS. Both functions return #LWRES_R_FAILURE if + * the buffer is corrupt or #LWRES_R_UNEXPECTEDEND if the buffer has + * less space than expected for the components of the encoded string + * or address. + * + * lwres_getaddrsbyname() returns #LWRES_R_SUCCESS on success and it + * returns #LWRES_R_NOTFOUND if the hostname name could not be found. + * + * #LWRES_R_SUCCESS is returned by a successful call to + * lwres_getnamebyaddr(). + * + * Both lwres_getaddrsbyname() and lwres_getnamebyaddr() return + * #LWRES_R_NOMEMORY when memory allocation requests fail and + * #LWRES_R_UNEXPECTEDEND if the buffers used for sending queries and + * receiving replies are too small. + * + * \section lwresutil_see See Also + * + * lwbuffer.c, lwres_gabn.c + */ #include @@ -31,7 +110,8 @@ #include "assert_p.h" #include "context_p.h" -/* +/*% Parse data. */ +/*! * Requires: * * The "current" pointer in "b" points to encoded raw data. @@ -78,7 +158,8 @@ lwres_data_parse(lwres_buffer_t *b, unsigned char **p, lwres_uint16_t *len) return (LWRES_R_SUCCESS); } -/* +/*% Retrieves a DNS-encoded string. */ +/*! * Requires: * * The "current" pointer in "b" point to an encoded string. @@ -133,6 +214,7 @@ lwres_string_parse(lwres_buffer_t *b, char **c, lwres_uint16_t *len) return (LWRES_R_SUCCESS); } +/*% Extracts an address from the buffer b. */ lwres_result_t lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr) { @@ -154,6 +236,7 @@ lwres_addr_parse(lwres_buffer_t *b, lwres_addr_t *addr) return (LWRES_R_SUCCESS); } +/*% Used to perform forward lookups. */ lwres_result_t lwres_getaddrsbyname(lwres_context_t *ctx, const char *name, lwres_uint32_t addrtypes, lwres_gabnresponse_t **structp) @@ -268,6 +351,7 @@ lwres_getaddrsbyname(lwres_context_t *ctx, const char *name, } +/*% Used to perform reverse lookups. */ lwres_result_t lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype, lwres_uint16_t addrlen, const unsigned char *addr, @@ -376,6 +460,7 @@ lwres_getnamebyaddr(lwres_context_t *ctx, lwres_uint32_t addrtype, return (ret); } +/*% Get rdata by name. */ lwres_result_t lwres_getrdatabyname(lwres_context_t *ctx, const char *name, lwres_uint16_t rdclass, lwres_uint16_t rdtype, diff --git a/lib/lwres/unix/include/lwres/net.h b/lib/lwres/unix/include/lwres/net.h index 65dbbb3728..cec45edeb3 100644 --- a/lib/lwres/unix/include/lwres/net.h +++ b/lib/lwres/unix/include/lwres/net.h @@ -15,7 +15,7 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: net.h,v 1.5 2004/03/05 05:13:06 marka Exp $ */ +/* $Id: net.h,v 1.6 2005/04/27 04:57:32 sra Exp $ */ #ifndef LWRES_NET_H #define LWRES_NET_H 1 @@ -24,17 +24,15 @@ ***** Module Info *****/ -/* - * Basic Networking Types - * +/*! \file net.h * This module is responsible for defining the following basic networking * types: * - * struct in_addr - * struct in6_addr - * struct sockaddr - * struct sockaddr_in - * struct sockaddr_in6 + *\li struct in_addr + *\li struct in6_addr + *\li struct sockaddr + *\li struct sockaddr_in + *\li struct sockaddr_in6 * * It ensures that the AF_ and PF_ macros are defined. * @@ -42,7 +40,7 @@ * * It declares lwres_net_aton(), lwres_net_ntop(), and lwres_net_pton(). * - * It ensures that INADDR_LOOPBACK, INADDR_ANY and IN6ADDR_ANY_INIT + * It ensures that #INADDR_LOOPBACK, #INADDR_ANY and #IN6ADDR_ANY_INIT * are defined. */ @@ -79,7 +77,7 @@ #define in6_addr in_addr6 /* Required for pre RFC2133 implementations. */ #endif -/* +/*! * Required for some pre RFC2133 implementations. * IN6ADDR_ANY_INIT and IN6ADDR_LOOPBACK_INIT were added in * draft-ietf-ipngwg-bsd-api-04.txt or draft-ietf-ipngwg-bsd-api-05.txt. @@ -94,6 +92,9 @@ #endif #endif +/*! + * Initialize address loopback. See IN6ADDR_ANY_INIT + */ #ifndef IN6ADDR_LOOPBACK_INIT #ifdef s6_addr #define IN6ADDR_LOOPBACK_INIT { { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 } } } @@ -102,14 +103,18 @@ #endif #endif +/*% Used by AI_ALL */ #ifndef AF_INET6 #define AF_INET6 99 #endif + +/*% Used to return IPV6 address types. */ #ifndef PF_INET6 #define PF_INET6 AF_INET6 #endif +/*% inaddr Loopback */ #ifndef INADDR_LOOPBACK #define INADDR_LOOPBACK 0x7f000001UL #endif diff --git a/lib/lwres/version.c b/lib/lwres/version.c index 43cfa91f17..46b71ac10e 100644 --- a/lib/lwres/version.c +++ b/lib/lwres/version.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: version.c,v 1.8 2004/03/05 05:12:47 marka Exp $ */ +/* $Id: version.c,v 1.9 2005/04/27 04:57:30 sra Exp $ */ + +/*! \file */ #include diff --git a/lib/tests/include/tests/t_api.h b/lib/tests/include/tests/t_api.h index 288bf1c020..d0d1a2d482 100644 --- a/lib/tests/include/tests/t_api.h +++ b/lib/tests/include/tests/t_api.h @@ -15,11 +15,13 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: t_api.h,v 1.16 2004/06/21 05:36:40 marka Exp $ */ +/* $Id: t_api.h,v 1.17 2005/04/27 04:57:32 sra Exp $ */ #ifndef TESTS_T_API_H #define TESTS_T_API_H 1 +/*! \file */ + #include #include diff --git a/lib/tests/t_api.c b/lib/tests/t_api.c index 5c04aa8d49..faf9a3e28b 100644 --- a/lib/tests/t_api.c +++ b/lib/tests/t_api.c @@ -15,7 +15,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -/* $Id: t_api.c,v 1.54 2004/08/28 06:17:00 marka Exp $ */ +/* $Id: t_api.c,v 1.55 2005/04/27 04:57:32 sra Exp $ */ + +/*! \file */ #include @@ -52,7 +54,7 @@ static const char *Usage = "\t-t : run specified test number\n" "\t-x : don't execute tests in a subproc\n" "\t-q : use 'timeout' as the timeout value\n"; -/* +/*!< * -a --> run all tests * -b dir --> chdir to dir before running tests * -c config --> use config file 'config' @@ -65,7 +67,7 @@ static const char *Usage = * -q timeout --> use 'timeout' as the timeout value */ -#define T_MAXTESTS 256 /* must be 0 mod 8 */ +#define T_MAXTESTS 256 /*% must be 0 mod 8 */ #define T_MAXENV 256 #define T_DEFAULT_CONFIG "t_config" #define T_BUFSIZ 256