Skip to content

GitLab

Commit ab023a65 authored by Rob Austein's avatar Rob Austein
Browse files

1851. [doc] Doxygen comment markup. [RT #11398]

parent b37b169d
Hide whitespace changes
Inline Side-by-side
Showing with 270 additions and 154 deletions
CHANGES
View file @ ab023a65
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
......
acconfig.h
View file @ ab023a65
......@@ -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 <sys/types.h> doesn't define. */
/** define to `int' if <sys/types.h> 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 <stdarg.h> /* Grr. Must be included *every time*. */
/*
#include <stdarg.h> /** 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 */
......
bin/check/check-tool.c
View file @ ab023a65
......@@ -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 <config.h>
......@@ -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)
{
......
bin/check/check-tool.h
View file @ ab023a65
......@@ -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 <isc/lang.h>
#include <isc/types.h>
......
bin/check/named-checkconf.c
View file @ ab023a65
......@@ -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 <config.h>
......@@ -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;
......
bin/check/named-checkzone.c
View file @ ab023a65
......@@ -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 <config.h>
......@@ -77,6 +79,7 @@ destroy(void) {
dns_zone_detach(&zone);
}
/*% main processing routine */
int
main(int argc, char **argv) {
int c;
......
bin/dig/dig.c
View file @ ab023a65
......@@ -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 <config.h>
#include <stdlib.h>
......@@ -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;
......
bin/dig/dighost.c
View file @ ab023a65
......@@ -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.