girineko/dhcpd-pools
1
0
Fork 0
mirror of git://git.code.sf.net/p/dhcpd-pools/code synced 2025-12-16 15:57:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: improve doxygen documentation

Browse source 
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
This commit is contained in:
Sami Kerola 2017-11-13 23:27:12 +00:00
parent 887845df2a
commit c687f38ed6
No known key found for this signature in database
GPG key ID: A9553245FDE9B739
7 changed files with 111 additions and 58 deletions
Download patch file Download diff file Expand all files Collapse all files

9
src/analyze.c
View file

@ -55,7 +55,8 @@ void prepare_data(struct conf_t *state)
qsort(state->ranges, state->num_ranges, sizeof(struct range_t), &rangecomp); qsort(state->ranges, state->num_ranges, sizeof(struct range_t), &rangecomp);
} }
/*! \brief Perform counting. Join leases with ranges, and update counters. */ /*!\brief Perform counting. Join leases with ranges, and update range and
* shared network counters. */
void do_counting(struct conf_t *state) void do_counting(struct conf_t *state)
{ {
struct range_t *restrict range_p = state->ranges; struct range_t *restrict range_p = state->ranges;
@ -64,13 +65,13 @@ void do_counting(struct conf_t *state)
double block_size; double block_size;
/* Walk through ranges */ /* Walk through ranges */
for (i = 0; i < state->num_ranges; i++) { for (i = 0; i < state->num_ranges; i++, range_p++) {
while (l != NULL && ipcomp(&range_p->first_ip, &l->ip) < 0) while (l != NULL && ipcomp(&range_p->first_ip, &l->ip) < 0)
l = l->hh.prev; /* rewind */ l = l->hh.prev; /* rewind */
if (l == NULL) if (l == NULL)
l = state->leases; l = state->leases;
for (; l != NULL && ipcomp(&l->ip, &range_p->last_ip) <= 0; l = l->hh.next) { for (; l != NULL && ipcomp(&l->ip, &range_p->last_ip) <= 0; l = l->hh.next) {
if (ipcomp(&l->ip, &range_p->first_ip) < 0) if (unlikely(ipcomp(&l->ip, &range_p->first_ip) < 0))
continue; /* cannot happen? */ continue; /* cannot happen? */
/* IP in range */ /* IP in range */
switch (l->type) { switch (l->type) {
@ -99,7 +100,5 @@ void do_counting(struct conf_t *state)
state->shared_net_root->touched += range_p->touched; state->shared_net_root->touched += range_p->touched;
state->shared_net_root->backups += range_p->backups; state->shared_net_root->backups += range_p->backups;
} }
/* Next range. */
range_p++;
} }
} }

5
src/dhcpd-pools.c
View file

@ -66,6 +66,9 @@ int (*leasecomp) (const struct leases_t *restrict a, const struct leases_t *rest
void (*add_lease) (struct conf_t *state, union ipaddr_t *ip, enum ltype type); void (*add_lease) (struct conf_t *state, union ipaddr_t *ip, enum ltype type);
struct leases_t *(*find_lease) (struct conf_t *state, union ipaddr_t *ip); struct leases_t *(*find_lease) (struct conf_t *state, union ipaddr_t *ip);
/*! \brief An option argument parser to populate state header_limit and
* number_limit values.
*/
static int return_limit(const char c) static int return_limit(const char c)
{ {
if ('0' <= c && c < '8') if ('0' <= c && c < '8')
@ -129,7 +132,7 @@ static void skip_arg_parse(struct conf_t *state, char *optarg)
} }
} }
/*! \brief Command options parser. */ /*! \brief Command line options parser. */
static char parse_command_line_opts(struct conf_t *state, int argc, char **argv) static char parse_command_line_opts(struct conf_t *state, int argc, char **argv)
{ {
enum { enum {

96
src/dhcpd-pools.h
View file

@ -61,7 +61,11 @@
# define unlikely(x) (x) # define unlikely(x) (x)
# endif # endif
/* The attribute __hot__ was added in gcc 4.3. */ /*! \def _DP_ATTRIBUTE_HOT
* \brief The function attribute __hot__ was added in gcc 4.3. See gnu
* documentation for further information.
* https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-hot-function-attribute
*/
# if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3) # if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)
# define _DP_ATTRIBUTE_HOT __attribute__ ((__hot__)) # define _DP_ATTRIBUTE_HOT __attribute__ ((__hot__))
# else # else
@ -85,8 +89,9 @@ enum dhcp_version {
}; };
/*! \enum prefix_t /*! \enum prefix_t
* \brief Enumeration of interesting data in dhcpd.leases file, that has * \brief Enumeration of interesting data in dhcpd.leases file, that has to
* to be further examined, and saved. * be further examined, and saved. Functions xstrstr_v4() and xstrstr_v6()
* return one of these values to parse_leases().
*/ */
enum prefix_t { enum prefix_t {
PREFIX_LEASE, PREFIX_LEASE,
@ -100,15 +105,19 @@ enum prefix_t {
NUM_OF_PREFIX NUM_OF_PREFIX
}; };
/*! \enum color_mode
* \brief Enumeration whether to use or not color output.
*/
enum color_mode { enum color_mode {
color_unknown, color_unknown,
color_off, color_off,
color_on, color_on,
color_auto /* default */ color_auto /*!< Default, use colors when output terminal is interactive. */
}; };
/*! \struct shared_network_t /*! \struct shared_network_t
* \brief Counters for an individual shared network. * \brief Counters for an individual shared network. This data entry is
* also used for 'all networks' counting.
*/ */
struct shared_network_t { struct shared_network_t {
char *name; char *name;
@ -145,7 +154,7 @@ struct output_helper_t {
}; };
/*! \enum ltype /*! \enum ltype
* \brief Lease state types. * \brief Lease state types. These are the possible values in struct leases_t.
*/ */
enum ltype { enum ltype {
ACTIVE, ACTIVE,
@ -154,7 +163,7 @@ enum ltype {
}; };
/*! \struct leases_t /*! \struct leases_t
* \brief An individual lease. The leaases are hashed. * \brief An individual lease. These leaases are hashed.
*/ */
struct leases_t { struct leases_t {
union ipaddr_t ip; /* ip as key */ union ipaddr_t ip; /* ip as key */
@ -164,16 +173,16 @@ struct leases_t {
}; };
/*! \enum limbits /*! \enum limbits
* \brief Output limit bits: R_BIT ranges, S_BIT shared networks, A_BIT all. * \brief Output limit bits.
*/ */
enum limbits { enum limbits {
R_BIT = (1 << 0), R_BIT = (1 << 0), /*!< Range limit. */
S_BIT = (1 << 1), S_BIT = (1 << 1), /*!< Shared networks limit. */
A_BIT = (1 << 2) A_BIT = (1 << 2) /*!< All networks summary limit. */
}; };
/*! \def STATE_OK /*! \def STATE_OK
* \brief Nagios alarm exit values. * \brief Nagios alarm exit value.
*/ */
# define STATE_OK 0 # define STATE_OK 0
# define STATE_WARNING 1 # define STATE_WARNING 1
@ -196,39 +205,38 @@ struct output_sort {
* \brief Runtime configuration state. * \brief Runtime configuration state.
*/ */
struct conf_t { struct conf_t {
struct shared_network_t *shared_net_root; struct shared_network_t *shared_net_root; /*!< First entry in shared network linked list, that is the 'all networks', */
struct shared_network_t *shared_net_head; struct shared_network_t *shared_net_head; /*!< Last entry in shared network linked list. */
struct range_t *ranges; struct range_t *ranges; /*!< Array of ranges. */
unsigned int num_ranges; unsigned int num_ranges; /*!< Number of ranges in the ranges array. */
size_t ranges_size; size_t ranges_size; /*!< Size of the ranges array. */
struct leases_t *leases; struct leases_t *leases; /*!< An array of individual leases from dhcpd.leases file. */
char dhcpv6; enum dhcp_version ip_version; /*!< Designator if the dhcpd is running in IPv4 or IPv6 mode. */
enum dhcp_version ip_version; const char *dhcpdconf_file; /*!< Path to dhcpd.conf file. */
const char *dhcpdconf_file; const char *dhcpdlease_file; /*!< Path to dhcpd.leases file. */
const char *dhcpdlease_file; int output_format; /*!< Column to use in color_tags array. */
int output_format; struct output_sort *sorts; /*!< Linked list how to sort ranges. */
struct output_sort *sorts; const char *output_file; /*!< Output file path. */
const char *output_file; const char *mustach_template; /*!< Mustach template file path. */
const char *mustach_template; double warning; /*!< Warning percent threshold. */
double warning; double critical; /*!< Critical percent threshold. */
double critical; double warn_count; /*!< Maximum number of free IP's before warning. */
double warn_count; double crit_count; /*!< Maximum number of free IP's before critical. */
double crit_count; double minsize; /*!< Minimum size of range or shared network to be considered exceeding threshold. */
double minsize;
unsigned int unsigned int
reverse_order:1, reverse_order:1, /*!< Reverse sort order. */
backups_found:1, backups_found:1, /*!< Indicator if dhcpd.leases file has leases in backup state. */
snet_alarms:1, snet_alarms:1, /*!< Suppress alarming thresholds for ranges that are part of a shared network. */
perfdata:1, perfdata:1, /*!< Include performance statistics when using Nagios alarm output format. */
all_as_shared:1, all_as_shared:1, /*!< Treat stand-alone subnets as a shared network. */
header_limit:4, header_limit:4, /*!< Bits to suppress header output. */
number_limit:3, number_limit:3, /*!< Bits to suppress value output. */
skip_ok:1, skip_ok:1, /*!< Skip none-alarming values from output. */
skip_warning:1, skip_warning:1, /*!< Skip warning values from output. */
skip_critical:1, skip_critical:1, /*!< Skip critical values from output. */
skip_minsize:1, skip_minsize:1, /*!< Skip alarming values that are below minsize from output. */
skip_suppressed:1, skip_suppressed:1, /*!< Skip alarming values that are suppressed with --snet-alarms option, or they are shared networks without IP availability. */
color_mode:2; color_mode:2; /*!< Indicator if colors should be used in output. */
}; };
/* Function prototypes */ /* Function prototypes */

7
src/getdata.c
View file

@ -64,7 +64,8 @@ enum dhcpd_magic_numbers {
}; };
/*! \enum isc_conf_parser /*! \enum isc_conf_parser
* \brief Configuration file parsing state flags. * \brief Configuration file parsing state flags. The
* is_interesting_config_clause() will return one of these to parse_config().
*/ */
enum isc_conf_parser { enum isc_conf_parser {
ITS_NOTHING_INTERESTING, ITS_NOTHING_INTERESTING,
@ -195,8 +196,8 @@ static void reorder_last_first(struct range_t *range_p)
} }
/*! \brief The dhcpd.conf file parser. /*! \brief The dhcpd.conf file parser.
* FIXME: This spaghetti monster function need to be rewrote at least * FIXME: This spaghetti monster function needs to be rewrote at least
* ones. * ones more.
*/ */
void parse_config(struct conf_t *state, const int is_include, const char *restrict config_file, void parse_config(struct conf_t *state, const int is_include, const char *restrict config_file,
struct shared_network_t *restrict shared_p) struct shared_network_t *restrict shared_p)

21
src/mustach-dhcpd-pools.c
View file

@ -53,6 +53,9 @@
#include "mustach.h" #include "mustach.h"
#include "xalloc.h" #include "xalloc.h"
/*! \struct expl
* \brief A structure that travels through mustach via closure void pointer.
*/
struct expl { struct expl {
struct conf_t *state; struct conf_t *state;
struct range_t *range_p; struct range_t *range_p;
@ -64,7 +67,9 @@ struct expl {
static int must_enter(void *closure, const char *name); static int must_enter(void *closure, const char *name);
static int must_leave(void *closure); static int must_leave(void *closure);
/* This can be called when template is invalid end put happens before enter. */ /*! \brief This function can be called when mustach template is invalid.
* In such case either must_put_range or must_put_shnet is tried to call before
* must_enter. */
static int must_put_err(void *closure __attribute__ ((unused)), static int must_put_err(void *closure __attribute__ ((unused)),
const char *name __attribute__ ((unused)), const char *name __attribute__ ((unused)),
int escape __attribute__ ((unused)), FILE *file __attribute__ ((unused))) int escape __attribute__ ((unused)), FILE *file __attribute__ ((unused)))
@ -72,7 +77,8 @@ static int must_put_err(void *closure __attribute__ ((unused)),
return MUSTACH_ERROR_SYSTEM; return MUSTACH_ERROR_SYSTEM;
} }
/* Set mustach function pointers. */ /*! \struct mustach_itf
* \brief Mustach function pointers. */
static struct mustach_itf itf = { static struct mustach_itf itf = {
.start = NULL, .start = NULL,
.enter = must_enter, .enter = must_enter,
@ -81,6 +87,7 @@ static struct mustach_itf itf = {
.leave = must_leave .leave = must_leave
}; };
/*! \brief Mustach range aka {{#subnets}} tag parser and printer. */
static int must_put_range(void *closure, const char *name, int escape static int must_put_range(void *closure, const char *name, int escape
__attribute__ ((unused)), FILE *file) __attribute__ ((unused)), FILE *file)
{ {
@ -162,6 +169,7 @@ static int must_put_range(void *closure, const char *name, int escape
return 0; return 0;
} }
/*! \brief Mustach shared networks aka {{#shared-networks}} tag parser and printer. */
static int must_put_shnet(void *closure, const char *name, int escape static int must_put_shnet(void *closure, const char *name, int escape
__attribute__ ((unused)), FILE *file) __attribute__ ((unused)), FILE *file)
{ {
@ -230,6 +238,7 @@ static int must_put_shnet(void *closure, const char *name, int escape
return 0; return 0;
} }
/*! \brief A function to move to next range when {{/subnets}} is encountered. */
static int must_next_range(void *closure) static int must_next_range(void *closure)
{ {
struct expl *e = closure; struct expl *e = closure;
@ -243,6 +252,8 @@ static int must_next_range(void *closure)
return 1; return 1;
} }
/*! \brief A function to move to next shared network when {{/shared-networks}}
* is encountered. */
static int must_next_shnet(void *closure) static int must_next_shnet(void *closure)
{ {
struct expl *e = closure; struct expl *e = closure;
@ -261,6 +272,8 @@ static int must_next_shnet(void *closure)
return 0; return 0;
} }
/*! \brief Function that is called when mustach is searching output loops from
* template file. */
static int must_enter(void *closure, const char *name) static int must_enter(void *closure, const char *name)
{ {
struct expl *e = closure; struct expl *e = closure;
@ -292,6 +305,7 @@ static int must_enter(void *closure, const char *name)
return 0; return 0;
} }
/*! \brief Function that is called when all elements within a print loop are outputed. */
static int must_leave(void *closure __attribute__ ((unused))) static int must_leave(void *closure __attribute__ ((unused)))
{ {
struct expl *e = closure; struct expl *e = closure;
@ -301,6 +315,7 @@ static int must_leave(void *closure __attribute__ ((unused)))
return 0; return 0;
} }
/*! \brief Read mustach template to memory. */
static char *must_read_template(const char *filename) static char *must_read_template(const char *filename)
{ {
int f; int f;
@ -322,7 +337,7 @@ static char *must_read_template(const char *filename)
return result; return result;
} }
/*! \brief Start mustach processing. */
int mustach_dhcpd_pools(struct conf_t *state) int mustach_dhcpd_pools(struct conf_t *state)
{ {
struct expl e = { .state = state }; struct expl e = { .state = state };

16
src/other.c
View file

@ -159,6 +159,10 @@ int parse_ipaddr_v6(struct conf_t *state
return rv == 1; return rv == 1;
} }
/*! \brief Convert string to a desimal format network marks.
* \param src Digit that should be a network mask.
* \return Network mask, or -1 when failing.
*/
static int strtol_mask(const char *str) static int strtol_mask(const char *str)
{ {
long num; long num;
@ -178,6 +182,10 @@ static int strtol_mask(const char *str)
return -1; return -1;
} }
/*! \brief Find last address in IPv4 range by using cidr format.
* \param addr Pointer to memory where address needs to be stored.
* \return Allocated string format of the address.
*/
static char *cidr_last_v4(union ipaddr_t *restrict addr, const int mask) static char *cidr_last_v4(union ipaddr_t *restrict addr, const int mask)
{ {
union ipaddr_t last_ip; union ipaddr_t last_ip;
@ -194,6 +202,10 @@ static char *cidr_last_v4(union ipaddr_t *restrict addr, const int mask)
return xstrdup(ip); return xstrdup(ip);
} }
/*! \brief Find last address in IPv6 range by using cidr format.
* \param addr Pointer to memory where address needs to be stored.
* \return Allocated string format of the address.
*/
static char *cidr_last_v6(union ipaddr_t *restrict addr, const int mask) static char *cidr_last_v6(union ipaddr_t *restrict addr, const int mask)
{ {
union ipaddr_t bitmask; union ipaddr_t bitmask;
@ -213,6 +225,10 @@ static char *cidr_last_v6(union ipaddr_t *restrict addr, const int mask)
return xstrdup(ip); return xstrdup(ip);
} }
/*! \brief Convert a cidr notated address to a range.
* \param range_p Pointer to memory where addresses need to be stored.
* \param word A range as a cidr string.
*/
void parse_cidr(struct conf_t *state, struct range_t *range_p, const char *word) void parse_cidr(struct conf_t *state, struct range_t *range_p, const char *word)
{ {
char *divider; char *divider;

15
src/output.c
View file

@ -81,6 +81,9 @@ enum count_status_t {
COLOR_RESET COLOR_RESET
}; };
/*! \var color_tags
* \brief Array of stings that make colors to start and end in different
* schemas per array column. */
static const char *color_tags[][NUM_OF_OUT_FORMS] = { static const char *color_tags[][NUM_OF_OUT_FORMS] = {
[STATUS_OK] = { "", "" }, [STATUS_OK] = { "", "" },
[STATUS_WARN] = { "\033[1;33m", " style=\"color:magenta;font-style:italic\"" }, [STATUS_WARN] = { "\033[1;33m", " style=\"color:magenta;font-style:italic\"" },
@ -90,7 +93,8 @@ static const char *color_tags[][NUM_OF_OUT_FORMS] = {
[COLOR_RESET] = { "\033[0m", "" } [COLOR_RESET] = { "\033[0m", "" }
}; };
/*! \brief Calculate range percentages and such. */ /*! \brief Calculate range percentages and such.
* \return Indicator if the entry should be skipped from output. */
int range_output_helper(struct conf_t *state, struct output_helper_t *oh, int range_output_helper(struct conf_t *state, struct output_helper_t *oh,
struct range_t *range_p) struct range_t *range_p)
{ {
@ -127,7 +131,8 @@ int range_output_helper(struct conf_t *state, struct output_helper_t *oh,
return 0; return 0;
} }
/*! \brief Calculate shared network percentages and such. */ /*! \brief Calculate shared network percentages and such.
* \return Indicator if the entry should be skipped from output. */
int shnet_output_helper(struct conf_t *state, struct output_helper_t *oh, int shnet_output_helper(struct conf_t *state, struct output_helper_t *oh,
struct shared_network_t *shared_p) struct shared_network_t *shared_p)
{ {
@ -170,6 +175,8 @@ int shnet_output_helper(struct conf_t *state, struct output_helper_t *oh,
} }
/*! \brief Output a color based on output_helper_t status.
* \return Indicator whether coloring was started or not. */
static int start_color(struct conf_t *state, struct output_helper_t *oh, FILE *outfile) static int start_color(struct conf_t *state, struct output_helper_t *oh, FILE *outfile)
{ {
if (oh->status == STATUS_OK) { if (oh->status == STATUS_OK) {
@ -179,6 +186,8 @@ static int start_color(struct conf_t *state, struct output_helper_t *oh, FILE *o
return 1; return 1;
} }
/*! \brief Helper function to open a output file.
* \return The outfile in all of the output functions. */
static FILE *open_outfile(struct conf_t *state) static FILE *open_outfile(struct conf_t *state)
{ {
FILE *outfile; FILE *outfile;
@ -194,6 +203,8 @@ static FILE *open_outfile(struct conf_t *state)
return outfile; return outfile;
} }
/*! \brief Helper function to close outfile. */
static void close_outfile(FILE *outfile) static void close_outfile(FILE *outfile)
{ {
if (outfile == stdout) { if (outfile == stdout) {