cf_util.h

Go to the documentation of this file.

#pragma once
/*
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
 */
 
/**
 * $Id: f8a95ce4a0a6a22a3420bcb23b535081ec7928f8 $
 *
 * @file lib/server/cf_util.h
 * @brief API to create and manipulate internal format configurations.
 *
 * @copyright 2017 The FreeRADIUS server project
 */
RCSIDH(conf_file_h, "$Id: f8a95ce4a0a6a22a3420bcb23b535081ec7928f8 $")
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
 * Export the minimum amount of information about these structs
 */
typedef struct cf_item CONF_ITEM;       //!< Generic configuration element, extended to become
                                        ///< a #CONF_PAIR, a #CONF_SECTION or #CONF_DATA.
typedef struct cf_section CONF_SECTION; //!< #CONF_ITEM used to group multiple #CONF_PAIR and #CONF_SECTION, together.
typedef struct cf_pair CONF_PAIR;       //!< #CONF_ITEM with an attribute, an operator and a value.
typedef struct cf_data CONF_DATA;       //!< #CONF_ITEM used to associate arbitrary data
                                        ///< with a #CONF_PAIR or #CONF_SECTION.
typedef struct cf_comment CONF_COMMENT; //!< #CONF_ITEM holding a literal `# ...` comment line.
                                        ///< Only created when the parser is asked to preserve
                                        ///< comments (utilities opt in; the runtime parser does not).
 
#include <unistd.h>
#include <sys/time.h>
 
#include <freeradius-devel/util/rb.h>
#include <freeradius-devel/util/table.h>
#include <freeradius-devel/util/token.h>
#include <freeradius-devel/util/log.h>
 
#define FR_TIMEVAL_TO_MS(_x) (((_x)->tv_usec / 1000) + ((_x)->tv_sec * (uint64_t)1000))
#define FR_TIMESPEC_TO_MS(_x) (((_x)->tv_usec / 1000000) + ((_x)->tv_sec * (uint64_t)1000))
 
/** Auto cast from the input type to CONF_ITEM (which is the base type)
 *
 * Automatically casts:
 * - #CONF_SECTION
 * - #CONF_PAIR
 * - #CONF_DATA
 *
 * To a #CONF_ITEM, whilst performing talloc type checks.
 */
#define CF_TO_ITEM(_cf) \
_Generic((_cf), \
        CONF_SECTION *                  : cf_section_to_item((CONF_SECTION const *)_cf), \
        CONF_SECTION const *            : cf_section_to_item((CONF_SECTION const *)_cf), \
        CONF_PAIR *                     : cf_pair_to_item((CONF_PAIR const *)_cf), \
        CONF_PAIR const *               : cf_pair_to_item((CONF_PAIR const *)_cf), \
        CONF_DATA *                     : cf_data_to_item((CONF_DATA const *)_cf), \
        CONF_DATA const *               : cf_data_to_item((CONF_DATA const *)_cf), \
        CONF_COMMENT *                  : cf_comment_to_item((CONF_COMMENT const *)_cf), \
        CONF_COMMENT const *            : cf_comment_to_item((CONF_COMMENT const *)_cf), \
        default: _cf \
)
 
typedef int (*cf_walker_t)(void *data, void *ctx);
 
#define CF_IDENT_ANY ((void *) (-1))
 
/*
 *      Generic functions that apply to all types of #CONF_ITEM
 */
#define         cf_item_add(_parent, _child) _cf_item_add(CF_TO_ITEM(_parent), CF_TO_ITEM(_child))
void            _cf_item_add(CONF_ITEM *parent, CONF_ITEM *child);
 
#define         cf_item_insert_after(_parent, _prev, _child) _cf_item_insert_after(CF_TO_ITEM(_parent), CF_TO_ITEM(_prev), CF_TO_ITEM(_child))
void            _cf_item_insert_after(CONF_ITEM *parent, CONF_ITEM *prev, CONF_ITEM *child);
 
#define         cf_item_remove(_parent, _child) _cf_item_remove(CF_TO_ITEM(_parent), CF_TO_ITEM(_child))
CONF_ITEM       *_cf_item_remove(CONF_ITEM *parent, CONF_ITEM *child);
 
#define         cf_item_next(_parent, _curr) _cf_item_next(CF_TO_ITEM(_parent), _curr)
CONF_ITEM       *_cf_item_next(CONF_ITEM const *parent, CONF_ITEM const *curr);
 
/** Iterate over every child item of a CONF_SECTION (or any CONF_ITEM that has
 *  children).
 *
 * @param[in] _parent   to iterate over.  Any type CF_TO_ITEM() accepts.
 * @param[in] _iter     Name of the iteration variable.  Declared in the
 *                      scope of the loop with type `CONF_ITEM *`.
 *
 * Example:
 *  cf_item_foreach(my_section, ci) {
 *      if (cf_item_is_pair(ci)) { ... }
 *  }
 */
#define cf_item_foreach(_parent, _iter) \
        for (CONF_ITEM *_iter = cf_item_next(_parent, NULL); _iter != NULL; _iter = cf_item_next(_parent, _iter))
 
#define         cf_item_prev(_parent, _curr) _cf_item_prev(CF_TO_ITEM(_parent), _curr)
CONF_ITEM       *_cf_item_prev(CONF_ITEM const *parent, CONF_ITEM const *prev);
 
#define         cf_root(_cf) _cf_root(CF_TO_ITEM(_cf))
CONF_SECTION    *_cf_root(CONF_ITEM const *ci);
 
#define         cf_parent(_cf) _cf_parent(CF_TO_ITEM(_cf))
CONF_ITEM       *_cf_parent(CONF_ITEM const *ci);
 
#define         cf_lineno(_cf) _cf_lineno(CF_TO_ITEM(_cf))
int             _cf_lineno(CONF_ITEM const *ci);
 
#define         cf_filename(_cf) _cf_filename(CF_TO_ITEM(_cf))
char const      *_cf_filename(CONF_ITEM const *ci);
 
bool            cf_item_is_section(CONF_ITEM const *ci);
bool            cf_item_is_pair(CONF_ITEM const *ci);
bool            cf_item_is_data(CONF_ITEM const *ci);
bool            cf_item_is_comment(CONF_ITEM const *ci);
 
/** @hidecallergraph */
CONF_PAIR       *cf_item_to_pair(CONF_ITEM const *ci);
/** @hidecallergraph */
CONF_SECTION    *cf_item_to_section(CONF_ITEM const *ci);
/** @hidecallergraph */
CONF_DATA       *cf_item_to_data(CONF_ITEM const *ci);
/** @hidecallergraph */
CONF_COMMENT    *cf_item_to_comment(CONF_ITEM const *ci);
 
/** @hidecallergraph */
CONF_ITEM       *cf_pair_to_item(CONF_PAIR const *cp);
/** @hidecallergraph */
CONF_ITEM       *cf_section_to_item(CONF_SECTION const *cs);
/** @hidecallergraph */
CONF_ITEM       *cf_data_to_item(CONF_DATA const *cs);
/** @hidecallergraph */
CONF_ITEM       *cf_comment_to_item(CONF_COMMENT const *c);
 
/** Allocate a new comment item attached to `parent`.
 *
 * Inserted into the parent's ordered children list so it appears between
 * the surrounding pairs/sections at output time.  Not indexed by name -
 * comment lookup isn't meaningful.
 *
 * `text` is `talloc_strdup`ed onto the new node so the caller can free their
 * copy.  Returns NULL if allocation fails.
 */
CONF_COMMENT    *cf_comment_alloc(CONF_SECTION *parent, char const *text);
 
/** @hidecallergraph */
char const      *cf_comment_text(CONF_COMMENT const *c);
 
/** Control whether the CF parser preserves `# ...` comments.
 *
 * Defaults to off (historical behaviour: comments are dropped at parse
 * time).  Utilities that want comments to round-trip through the CF tree
 * should call the setter before `cf_file_read()`.  The runtime server
 * parser never opts in.
 */
void            cf_preserve_comments_set(bool preserve);
 
/** Opt out of `${var}` expansion when reading config (default: enabled).
 *
 * Utilities that round-trip the source - e.g. radjson2conf rebuilding
 * a fragment from JSON - call this with `false` so values containing
 * `${...}` survive verbatim instead of being resolved against an
 * incomplete tree.  $INCLUDE handling is a separate parser path and
 * is unaffected.
 */
void            cf_expand_variables_set(bool expand);
 
#define         cf_filename_set(_ci, _filename) _cf_filename_set(CF_TO_ITEM(_ci), _filename)
void            _cf_filename_set(CONF_ITEM *cs, char const *filename);
 
#define         cf_lineno_set(_ci, _lineno) _cf_lineno_set(CF_TO_ITEM(_ci), _lineno)
void            _cf_lineno_set(CONF_ITEM *cs, int lineno);
 
void            cf_item_free_children(CONF_ITEM *ci);
 
#define         cf_item_mark_parsed(_cf) _cf_item_mark_parsed(CF_TO_ITEM(_cf))
void            _cf_item_mark_parsed(CONF_ITEM *ci);
 
#define         cf_item_is_parsed(_cf) _cf_item_is_parsed(CF_TO_ITEM(_cf))
bool            _cf_item_is_parsed(CONF_ITEM *ci);
 
/*
 *      Section manipulation and searching
 */
#ifndef NDEBUG
#  define       cf_section_alloc(_ctx, _parent, _name1, _name2) \
                        _cf_section_alloc(_ctx, _parent, _name1, _name2, __FILE__, __LINE__)
#else
#  define       cf_section_alloc(_ctx, _parent, _name1, _name2) \
                        _cf_section_alloc(_ctx, _parent, _name1, _name2, NULL, 0)
#endif
CONF_SECTION    *_cf_section_alloc(TALLOC_CTX *ctx, CONF_SECTION *parent,
                                   char const *name1, char const *name2,
                                   char const *filename, int lineno);
CONF_SECTION    *cf_section_dup(TALLOC_CTX *ctx, CONF_SECTION *parent, CONF_SECTION const *cs,
                                char const *name1, char const *name2, bool copy_meta);
 
#define cf_section_foreach(_parent, _iter) \
                for (CONF_SECTION *_iter = cf_section_first(_parent); _iter; _iter = cf_section_next(_parent, _iter))
 
/** @hidecallergraph */
CONF_SECTION    *cf_section_first(CONF_SECTION const *cs);
 
/** @hidecallergraph */
CONF_SECTION    *cf_section_next(CONF_SECTION const *cs, CONF_SECTION const *curr);
 
/** @hidecallergraph */
CONF_SECTION    *cf_section_prev(CONF_SECTION const *cs, CONF_SECTION const *curr);
 
/** @hidecallergraph */
CONF_SECTION    *cf_section_find(CONF_SECTION const *cs, char const *name1, char const *name2);
/** @hidecallergraph */
CONF_SECTION    *cf_section_find_next(CONF_SECTION const *cs, CONF_SECTION const *subcs,
                                      char const *name1, char const *name2);
 
#define         cf_section_find_in_parent(_cf, _name1, _name2) \
                _cf_section_find_in_parent(CF_TO_ITEM(_cf), _name1, _name2)
CONF_SECTION    *_cf_section_find_in_parent(CONF_ITEM const *ci,
                                            char const *name1, char const *name2);
 
#define         cf_section_find_parent(_cf, _name1, _name2) \
                _cf_section_find_parent(CF_TO_ITEM(_cf), _name1, _name2)
CONF_SECTION    *_cf_section_find_parent(CONF_ITEM const *ci,
                                         char const *name1, char const *name2);
 
char const      *cf_section_value_find(CONF_SECTION const *, char const *attr);
 
int8_t          cf_section_name_cmp(CONF_SECTION const *cs, char const *name1, char const *name2);
/** @hidecallergraph */
char const      *cf_section_name1(CONF_SECTION const *cs);
/** @hidecallergraph */
char const      *cf_section_name2(CONF_SECTION const *cs);
/** @hidecallergraph */
char const      *cf_section_name(CONF_SECTION const *cs);
char const      *cf_section_argv(CONF_SECTION const *cs, int argc);
fr_token_t      cf_section_name2_quote(CONF_SECTION const *cs);
fr_token_t      cf_section_argv_quote(CONF_SECTION const *cs, int argc);
 
#define cf_section_free_children(_x) cf_item_free_children(cf_section_to_item(_x))
 
 
/*
 *      Pair manipulation and searching
 */
CONF_PAIR       *cf_pair_alloc(CONF_SECTION *parent, char const *attr, char const *value,
                               fr_token_t op, fr_token_t lhs_type, fr_token_t rhs_type);
 
CONF_PAIR       *cf_pair_dup(CONF_SECTION *parent, CONF_PAIR *cp, bool copy_meta);
 
int             cf_pair_replace(CONF_SECTION *cs, CONF_PAIR *cp, char const *value);
 
CONF_PAIR       *cf_pair_first(CONF_SECTION const *cs);
 
CONF_PAIR       *cf_pair_next(CONF_SECTION const *cs, CONF_PAIR const *curr);
 
CONF_PAIR       *cf_pair_prev(CONF_SECTION const *cs, CONF_PAIR const *curr);
 
CONF_PAIR       *cf_pair_find(CONF_SECTION const *cs, char const *name);
 
CONF_PAIR       *cf_pair_find_next(CONF_SECTION const *cs, CONF_PAIR const *prev, char const *name);
 
CONF_PAIR       *cf_pair_find_in_parent(CONF_SECTION const *cs, char const *attr);
 
int             cf_pair_replace_or_add(CONF_SECTION *cs, char *ref, char const *value) CC_HINT(nonnull);
 
unsigned int    cf_pair_count_descendents(CONF_SECTION const *cs);
 
unsigned int    cf_pair_count(CONF_SECTION const *cs, char const *attr);
 
fr_slen_t       cf_pair_values_concat(fr_sbuff_t *sbuff, CONF_SECTION const *cs, char const *attr, char const *sep);
 
/** @hidecallergraph */
char const      *cf_pair_attr(CONF_PAIR const *pair);
/** @hidecallergraph */
char const      *cf_pair_value(CONF_PAIR const *pair);
/** @hidecallergraph */
fr_token_t      cf_pair_operator(CONF_PAIR const *pair);
 
fr_token_t      cf_pair_attr_quote(CONF_PAIR const *pair);
fr_token_t      cf_pair_value_quote(CONF_PAIR const *pair);
 
/*
 *      Data manipulation and searching
 */
#define         cf_data_find(_cf, _type, _name) _cf_data_find(CF_TO_ITEM(_cf), #_type, _name)
CONF_DATA const *_cf_data_find(CONF_ITEM const *ci, char const *type, char const *name);
 
#define         cf_data_find_next(_cf, _prev, _type, _name) _cf_data_find_next(CF_TO_ITEM(_cf), CF_TO_ITEM(_prev), #_type, _name)
CONF_DATA const *_cf_data_find_next(CONF_ITEM const *ci, CONF_ITEM const *prev, char const *type, char const *name);
 
#define         cf_data_find_in_parent(_cf, _type, _name) _cf_data_find_in_parent(CF_TO_ITEM(_cf), #_type, _name)
CONF_DATA       *_cf_data_find_in_parent(CONF_ITEM const *ci, char const *type, char const *name);
 
void            *cf_data_value(CONF_DATA const *cd);
 
#define         cf_data_add(_cf, _data, _name, _free) _cf_data_add(CF_TO_ITEM(_cf), (void const *) _data, _name, _free, __FILE__, __LINE__)
CONF_DATA const *_cf_data_add(CONF_ITEM *ci, void const *data, char const *name, bool free, char const *filename, int lineno);
 
#define         cf_data_add_static(_cf, _data, _type, _name) _cf_data_add_static(CF_TO_ITEM(_cf), _data, #_type, _name, __FILE__, __LINE__)
CONF_DATA const *_cf_data_add_static(CONF_ITEM *ci, void const *data, char const *type, char const *name, char const *filename, int lineno);
 
/** Remove an item from a parent by type and name
 *
 * @param[in] _cf conf section or pair to remove data from.
 * @param[in] _type of data to remove.
 * @param[in] _name of data to remove.
 */
#define         cf_data_remove(_cf, _type, _name) _cf_data_remove(CF_TO_ITEM(_cf), cf_data_find(_cf, _type, _name))
 
/** Remove an item from a parent
 *
 * @param[in] _cf conf section or pair to remove data from.
 * @param[in] _cd conf data to remove.
 */
#define         cf_data_remove_by_data(_cf, _cd) _cf_data_remove(CF_TO_ITEM(_cf), _cd)
void            *_cf_data_remove(CONF_ITEM *ci, CONF_DATA const *_cd);
 
#define         cf_data_walk(_cf, _type, _cb, _ctx) _cf_data_walk(CF_TO_ITEM(_cf), #_type, _cb, _ctx)
int             _cf_data_walk(CONF_ITEM *ci, char const *type, cf_walker_t cb, void *ctx);
 
/*
 *      Validation
 */
int             cf_pair_in_table(int32_t *out, fr_table_num_sorted_t const *table, size_t table_len, CONF_PAIR *cp);
 
/*
 *      Error logging
 */
 
#define         cf_log_err(_cf, _fmt, ...)      _cf_log(L_ERR, CF_TO_ITEM(_cf), __FILE__, __LINE__, _fmt, ## __VA_ARGS__)
#define         cf_log_warn(_cf, _fmt, ...)     _cf_log(L_WARN, CF_TO_ITEM(_cf),  __FILE__, __LINE__, _fmt, ## __VA_ARGS__)
#define         cf_log_info(_cf, _fmt, ...)     _cf_log(L_INFO, CF_TO_ITEM(_cf),  __FILE__, __LINE__, _fmt, ## __VA_ARGS__)
#define         cf_log_debug(_cf, _fmt, ...)    _cf_log(L_DBG, CF_TO_ITEM(_cf),  __FILE__, __LINE__, _fmt, ## __VA_ARGS__)
void            _cf_vlog(fr_log_type_t type, CONF_ITEM const *ci, char const *file, int line, char const *fmt, va_list ap) CC_HINT(format (printf, 5, 0));
void            _cf_log(fr_log_type_t type, CONF_ITEM const *ci, char const *file, int line, char const *fmt, ...) CC_HINT(format (printf, 5, 6));
 
#define         cf_log_perr(_cf, _fmt, ...) _cf_log_perr(L_ERR, CF_TO_ITEM(_cf),  __FILE__, __LINE__, NULL, _fmt, ## __VA_ARGS__)
#define         cf_log_pwarn(_cf, _fmt, ...) _cf_log_perr(L_WARN, CF_TO_ITEM(_cf),  __FILE__, __LINE__, NULL, _fmt, ## __VA_ARGS__)
 
void            _cf_vlog_perr(fr_log_type_t type, CONF_ITEM const *ci, char const *file, int line,
                              fr_log_perror_format_t const *f_rules, char const *fmt, va_list ap)
                CC_HINT(format (printf, 6, 0));
void            _cf_log_perr(fr_log_type_t type, CONF_ITEM const *ci, char const *file, int line,
                              fr_log_perror_format_t const *f_rules, char const *fmt, ...)
                CC_HINT(format (printf, 6, 7));
 
#define         cf_log_debug_prefix(_cf, _fmt, ...) _cf_log_with_filename(L_DBG, CF_TO_ITEM(_cf),  __FILE__, __LINE__, _fmt, ## __VA_ARGS__)
void            _cf_log_with_filename(fr_log_type_t type, CONF_ITEM const *ci, char const *file, int line, char const *fmt, ...) CC_HINT(format (printf, 5, 6));
 
/** Log an error message against a specified child
 *
 * @param[in] _parent   CONF_SECTION.
 * @param[in] _child    string identifier.
 * @param[in] _fmt      of message.
 * @param[in] ...       arguments.
 */
#define         cf_log_err_by_child(_parent, _child, _fmt, ...) _cf_log_by_child(L_ERR, _parent, _child, __FILE__, __LINE__, _fmt, ## __VA_ARGS__)
 
/** Log an error message against a specified child, draining the thread local error stack
 *
 * @param[in] _parent   CONF_SECTION.
 * @param[in] _child    string identifier.
 * @param[in] _f_rules  Line prefixes.
 * @param[in] _fmt      of message.
 * @param[in] ...       arguments.
 */
#define         cf_log_perr_by_child(_parent, _child, _f_rules, _fmt, ...) _cf_log_perr_by_child(L_ERR, _parent, _child, __FILE__, __LINE__, _f_rules, _fmt, ## __VA_ARGS__)
 
/** Log a warning message against a specified child
 *
 * @param[in] _parent   CONF_SECTION.
 * @param[in] _child    string identifier.
 * @param[in] _fmt      of message.
 * @param[in] ...       arguments.
 */
#define         cf_log_warn_by_child(_parent, _child, _fmt, ...) _cf_log_by_child(L_WARN, _parent, _child, __FILE__, __LINE__, _fmt, ## __VA_ARGS__)
 
/** Log an info message against a specified child
 *
 * @param[in] _parent   CONF_SECTION.
 * @param[in] _child    string identifier.
 * @param[in] _fmt      of message.
 * @param[in] ...       arguments.
 */
#define         cf_log_info_by_child(_parent, _child, _fmt, ...) _cf_log_by_child(L_INFO, _parent, _child, __FILE__, __LINE__, _fmt, ## __VA_ARGS__)
 
/** Log a debug message against a specified child
 *
 * @param[in] _parent   CONF_SECTION.
 * @param[in] _child    string identifier.
 * @param[in] _fmt      of message.
 * @param[in] ...       arguments.
 */
#define         cf_log_debug_by_child(_parent, _child, _fmt, ...) _cf_log_by_child(L_DBG, _parent, _child, __FILE__, __LINE__, _fmt, ## __VA_ARGS__)
void            _cf_log_by_child(fr_log_type_t type, CONF_SECTION const *parent, char const *child,
                                   char const *file, int line, char const *fmt, ...) CC_HINT(format (printf, 6, 7));
 
void            _cf_log_perr_by_child(fr_log_type_t type, CONF_SECTION const *parent, char const *child,
                                      char const *file, int line, fr_log_perror_format_t const *f_rules,
                                      char const *fmt, ...) CC_HINT(format (printf, 7, 8));
 
#define         cf_item_debug(_cf) _cf_item_debug(CF_TO_ITEM(_cf))
void            _cf_item_debug(CONF_ITEM const *ci);
 
void            cf_pair_debug(CONF_PAIR *cp);
void            cf_section_debug(CONF_SECTION *cs);
 
#define         cf_canonicalize_error(_ci, _slen, _msg, _str) _cf_canonicalize_error(CF_TO_ITEM(_ci), _slen, _msg, _str)
void            _cf_canonicalize_error(CONF_ITEM *ci, ssize_t slen, char const *msg, char const *str);
 
#ifdef __cplusplus
}
#endif