runlisp-base.conf (cmucl/run-script): Use `muffle-warning' function.

[runlisp] / lib.h

/* -*-c-*-
 *
 * Common definitions for `runlisp'
 *
 * (c) 2020 Mark Wooding
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of Runlisp, a tool for invoking Common Lisp scripts.
 *
 * Runlisp 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 3 of the License, or (at your
 * option) any later version.
 *
 * Runlisp 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 Runlisp.  If not, see <https://www.gnu.org/licenses/>.
 */

#ifndef LIB_H
#define LIB_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#include <limits.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdio.h>

/*----- Handy macros ------------------------------------------------------*/

#define N(v) (sizeof(v)/sizeof((v)[0]))
        /* The number of elements in the array V. */

/* Figure out the compiler version to see whether fancy tricks will work. */
#if defined(__GNUC__)
#  define GCC_VERSION_P(maj, min)                                       \
        (__GNUC__ > (maj) || (__GNUC__ == (maj) && __GNUC_MINOR__ >= (min)))
#else
#  define GCC_VERSION_P(maj, min) 0
#endif

#ifdef __clang__
#  define CLANG_VERSION_P(maj, min)                                     \
        (__clang_major__ > (maj) || (__clang_major__ == (maj) &&        \
                                     __clang_minor__ >= (min)))
#else
#  define CLANG_VERSION_P(maj, min) 0
#endif

#if GCC_VERSION_P(2, 5) || CLANG_VERSION_P(3, 3)

#  define NORETURN __attribute__((__noreturn__))
        /* Mark a function as not returning. */

#  define PRINTF_LIKE(fix, aix) __attribute__((__format__(printf, fix, aix)))
        /* Mark a function as accepting a printf(3)-like format string as
         * argument FIX, with arguments to be substituted starting at AIX.
         */
#endif

#if GCC_VERSION_P(4, 0) || CLANG_VERSION_P(3, 3)

#  define EXECL_LIKE(ntrail) __attribute__((__sentinel__(ntrail)))
        /* Mark a function as expecting a variable number of arguments
         * terminated by a null pointer, followed by NTRAIL further
         * arguments.
         */

#endif

/* Couldn't detect fancy compiler features.  We'll have to make do
 * without.
 */
#ifndef NORETURN
#  define NORETURN
#endif
#ifndef PRINTF_LIKE
#  define PRINTF_LIKE(fix, aix)
#endif
#ifndef EXECL_LIKE
#  define EXECL_LIKE(ntrail)
#endif

#define DISCARD(x) do if (x); while (0)
        /* Discard the result of evaluating expression X, without upsetting
         * the compiler.
         */

#define END ((const char *)0)
        /* A null pointer to terminate the argument tail to an `EXECL_LIKE'
         * function.  (Note that `NULL' is /not/ adequate for this purpose,
         * since it might expand simply to `0', which is an integer, not a
         * pointer, and might well be the wrong size and/or value.)
         */

/* Wrap up <ctype.h> macros with explicit conversions to `unsigned char'. */
#define CTYPE_HACK(func, ch) (func((unsigned char)(ch)))
#define ISSPACE(ch) CTYPE_HACK(isspace, ch)
#define ISALNUM(ch) CTYPE_HACK(isalnum, ch)
#define ISXDIGIT(ch) CTYPE_HACK(isxdigit, ch)
#define TOLOWER(ch) CTYPE_HACK(tolower, ch)
#define TOUPPER(ch) CTYPE_HACK(toupper, ch)

/* Wrap up comparison functions to take an ordering relation as part of their
 * syntax.  This makes it much harder to screw up.
 */
#define MEMCMP(x, op, y, n) (memcmp((x), (y), (n)) op 0)
#define STRCMP(x, op, y) (strcmp((x), (y)) op 0)
#define STRNCMP(x, op, y, n) (strncmp((x), (y), (n)) op 0)

#ifndef SIZE_MAX
#  define SIZE_MAX (-(size_t)1)
#endif
        /* The largest value that can be stored in an object of type
         * `size_t'.  A proper <limits.h> setting would be a preprocessor-
         * time constant, but we don't actually need that.
         */

/*----- Diagnostic utilities ----------------------------------------------*/

extern const char *progname;
        /* Our program name, for use in error messages. */

extern void set_progname(const char */*prog*/);
        /* Set `progname' from the pathname in PROG (typically from
         * `argv[0]').
         */

extern void vmoan(const char */*msg*/, va_list /*ap*/);
        /* Report an error or warning in Unix style, given a captured
         * argument cursor.
         */

extern PRINTF_LIKE(1, 2) void moan(const char */*msg*/, ...);
        /* Issue a warning message. */

extern NORETURN PRINTF_LIKE(1, 2) void lose(const char */*msg*/, ...);
        /* Issue a fatal error message and exit unsuccessfully. */

/*----- Memory allocation -------------------------------------------------*/

extern void *xmalloc(size_t /*n*/);
        /* Allocate and return a pointer to N bytes, or report a fatal error.
         *
         * Release the pointer using `free' as usual.  If N is zero, returns
         * null (but you are not expected to check for this).
         */

extern void *xrealloc(void */*p*/, size_t /*n*/);
        /* Resize the block at P (from `malloc' or `xmalloc') to be N bytes
         * long.
         *
         * The block might (and probably will) move, so it returns the new
         * address.  If N is zero, then the block is freed (if necessary) and
         * a null pointer returned; otherwise, if P is null then a fresh
         * block is allocated.  If allocation fails, then a fatal error is
         * reported.
         */

extern char *xstrndup(const char */*p*/, size_t /*n*/);
        /* Allocate and return a copy of the N-byte string starting at P.
         *
         * The new string is null-terminated, though P need not be.  If
         * allocation fails, then a fatal error is reported.
         */

extern char *xstrdup(const char */*p*/);
        /* Allocate and return a copy of the null-terminated string starting
         * at P.
         *
         * If allocation fails, then a fatal error is reported.
         */

/*----- Dynamic strings ---------------------------------------------------*/

/* A dynamic string.
 *
 * Note that the string might not be null-terminated.
 */
struct dstr {
  char *p;                              /* string base address */
  size_t len;                           /* current string length */
  size_t sz;                            /* allocated size of buffer */
};
#define DSTR_INIT { 0, 0, 0 }

extern void dstr_init(struct dstr */*d*/);
        /* Initialize the string D.
         *
         * Usually you'd use the static initializer `DSTR_INIT'.
         */

extern void dstr_reset(struct dstr */*d*/);
        /* Reset string D so it's empty again. */

extern void dstr_ensure(struct dstr */*d*/, size_t /*n*/);
        /* Ensure that D has at least N unused bytes available. */

extern void dstr_release(struct dstr */*d*/);
        /* Release the memory held by D.
         *
         * It must be reinitialized (e.g., by `dstr_init') before it can be
         * used again.
         */

extern void dstr_putm(struct dstr */*d*/, const void */*p*/, size_t /*n*/);
        /* Append the N-byte string at P to D.
         *
         * P need not be null-terminated.  D will not be null-terminated
         * afterwards.
         */

extern void dstr_puts(struct dstr */*d*/, const char */*p*/);
        /* Append the null-terminated string P to D.
         *
         * D /is/ guaranteed to be null-terminated after this.
         */

extern void dstr_putc(struct dstr */*d*/, int /*ch*/);
        /* Append the single character CH to D.
         *
         * D will not be null-terminated afterwards.
         */

extern void dstr_putcn(struct dstr */*d*/, int /*ch*/, size_t /*n*/);
        /* Append N copies of the character CH to D.
         *
         * D will not be null-terminated afterwards.
         */

extern void dstr_putz(struct dstr */*d*/);
        /* Null-terminate the string D.
         *
         * This doesn't change the length of D.  If further stuff is appended
         * then the null terminator will be overwritten.
         */

extern void dstr_vputf(struct dstr */*d*/,
                       const char */*p*/, va_list /*ap*/);
        /* Append stuff to D, determined by printf(3) format string P and
         * argument tail AP.
         *
         * D will not be null-terminated afterwards.
         */

extern PRINTF_LIKE(2, 3)
  void dstr_putf(struct dstr */*d*/, const char */*p*/, ...);
        /* Append stuff to D, determined by printf(3) format string P and
         * arguments.
         *
         * D will not be null-terminated afterwards.
         */

extern int dstr_readline(struct dstr */*d*/, FILE */*fp*/);
        /* Append the next input line from FP to D.
         *
         * Return 0 on success, or -1 if reading immediately fails or
         * encounters end-of-file (call ferror(3) to distinguish).  Any
         * trailing newline is discarded: it is not possible to determine
         * whether the last line was ended with a newline.  D is guaranteed
         * to be null-terminated afterwards.
         */

/*----- Dynamic vectors of strings ----------------------------------------*/

/* A dynamic vector of strings.
 *
 * This machinery only actually tracks character pointers.  It assumes that
 * the caller will manage the underlying storage for the strings.
 *
 * Note that `v' always points to the first element in the vector.  The
 * underlying storage starts `o' slots before this.
*/
struct argv {
  char **v;                             /* pointer the first element */
  size_t n;                             /* length of the vector */
  size_t o;                             /* number of spare slots at start */
  size_t sz;                            /* allocated size (in slots) */
};
#define ARGV_INIT { 0, 0, 0, 0 }

extern void argv_init(struct argv */*a*/v);
        /* Initialize the vector AV.
         *
         * Usually you'd use the static initializer `ARGV_INIT'.
         */

extern void argv_reset(struct argv */*av*/);
        /* Reset the vector AV so that it's empty again. */

extern void argv_ensure(struct argv */*av*/, size_t /*n*/);
        /* Ensure that AV has at least N unused slots at the end. */

extern void argv_ensure_offset(struct argv */*av*/, size_t /*n*/);
        /* Ensure that AV has at least N unused slots at the /start/. */

extern void argv_release(struct argv */*av*/);
        /* Release the memory held by AV.
         *
         * It must be reinitialized (e.g., by `argv_init') before it can be
         * used again.
         */

extern void argv_append(struct argv */*av*/, char */*p*/);
        /* Append the pointer P to AV. */

extern void argv_appendz(struct argv */*av*/);
        /* Append a null pointer to AV, without extending the vactor length.
         *
         * The null pointer will be overwritten when the next string is
         * appended.
         */

extern void argv_appendn(struct argv */*av*/,
                         char *const */*v*/, size_t /*n*/);
        /* Append a N-element vector V of pointers to AV. */

extern void argv_appendav(struct argv */*av*/, const struct argv */*bv*/);
        /* Append the variable-length vector BV to AV. */

extern void argv_appendv(struct argv */*av*/, va_list /*ap*/);
        /* Append the pointers from a variable-length argument list AP to AV.
         *
         * The list is terminated by a null pointer.
         */

extern EXECL_LIKE(0) void argv_appendl(struct argv */*av*/, ...);
        /* Append the argument pointers, terminated by a null pointer, to
         * AV.
         */

extern void argv_prepend(struct argv */*av*/, char */*p*/);
        /* Prepend the pointer P to AV. */

extern void argv_prependn(struct argv */*av*/,
                          char *const */*v*/, size_t /*n*/);
        /* Prepend a N-element vector V of pointers to AV. */

extern void argv_prependav(struct argv */*av*/, const struct argv */*bv*/);
        /* Prepend the variable-length vector BV to AV. */

extern void argv_prependv(struct argv */*av*/, va_list /*ap*/);
        /* Prepend the pointers from a variable-length argument list AP to
         * AV.
         *
         * The list is terminated by a null pointer.
         */

extern EXECL_LIKE(0) void argv_prependl(struct argv */*av*/, ...);
        /* Prepend the argument pointers, terminated by a null pointer, to
         * AV.
         */

/*----- Treaps ------------------------------------------------------------*/

/* A `treap' is a data structure for associating values with keys.  This
 * implementation assumes that keys are simply text strings.
 */
struct treap {
  struct treap_node *root;
};
#define TREAP_INIT { 0 }

/* A treap is a combination of a binary search tree and a binary heap.  The
 * nodes are ordered according to the search keys, in the usual way, so that
 * all the keys in a node's left subtree precede that node's key, and all of
 * the keys in its right subtree follow the node's key.  The trick is that
 * the tree must /also/ satisfy the heap condition regarding randomly
 * assigned `weights' attached to each node: so a node's weight must not be
 * less than their weight of either of its children.
 *
 * This combination uniquely determines the structure of the tree, except for
 * nodes whose weights exactly match one (or both) of their children.  (The
 * root must be the heaviest node in the tree.  The root's key splits the
 * remaining nodes into left and right subtrees, whose structure is then
 * uniquely determined by induction.)
 *
 * This is an /intrusive/ data structure.  A caller is expected to include a
 * `struct treap_node' as (probably) the initial part of a larger structure.
 */
struct treap_node {
  unsigned wt;                          /* weight (randomly assigned) */
  struct treap_node *left, *right;      /* left and right subtrees */
  char *k; size_t kn;                   /* key pointer and length */
};
#define TREAP_NODE_KEY(n) (((const struct treap_node *)(n))->k + 0)
#define TREAP_NODE_KEYLEN(n) (((const struct treap_node *)(n))->kn + 0)

/* We can't allocate nodes ourselves, because only the caller knows how.
 * Instead, insertion is split into two operations: `treap_probe' looks to
 * see whether a matching node is already in the treap, and returns it if so;
 * otherwise, it fills in this `treap_path' structure, which is passed back
 * to `treap_insert' to help it add the fresh node into the treap.  (See the
 * commentary in `treap_probe' and `treap_insert' for the details.)
 */
#define TREAP_PATHMAX 64
struct treap_path {
  struct treap_node **path[TREAP_PATHMAX];
  unsigned nsteps;
};

/* An external iterator for a treap.  (See the commentary for
 * `treap_start_iter' and `treap_next' for the details.)
 */
struct treap_iter {
  struct treap_node *stack[TREAP_PATHMAX];
  unsigned sp;
};

extern void treap_init(struct treap */*t*/);
        /* Initialize the treap T.
         *
         * Usually you'd use the static initializer `TREAP_INIT'.
         */

extern void *treap_lookup(const struct treap */*t*/,
                          const char */*k*/, size_t /*kn*/);
        /* Look up the KN-byte key K in the treap T.
         *
         * Return a pointer to the matching node if one was found, or null
         * otherwise.
         */

extern void *treap_probe(struct treap */*t*/,
                         const char */*k*/, size_t /*kn*/,
                         struct treap_path */*p*/);
        /* Look up the KN-byte K in the treap T, recording a path in P.
         *
         * This is similar to `treap_lookup', in that it returns the
         * requested node if it already exists, or null otherwise, but it
         * also records in P information to be used by `treap_insert' to
         * insert a new node with the given key if it's not there already.
         */

extern void treap_insert(struct treap */*t*/, const struct treap_path */*p*/,
                         struct treap_node */*n*/,
                         const char */*k*/, size_t /*kn*/);
        /* Insert a new node N into T, associating it with the KN-byte key K.
         *
         * Use the path data P, from `treap_probe', to help with insertion.
         */

extern void *treap_remove(struct treap */*t*/,
                          const char */*k*/, size_t /*kn*/);
        /* Remove the node with the KN-byte K from T.
         *
         * Return the address of the node we removed, or null if it couldn't
         * be found.
         */

extern void treap_start_iter(struct treap */*t*/, struct treap_iter */*i*/);
        /* Initialize an iterator I over T's nodes. */

extern void *treap_next(struct treap_iter */*i*/);
        /* Return the next node from I, in ascending order by key.
         *
         * If there are no more nodes, then return null.
         */

extern void treap_check(struct treap */*t*/);
        /* Check the treap structure rules for T. */

extern void treap_dump(struct treap */*t*/);
        /* Dump the treap T to standard output, for debugging purposes. */

/*----- Configuration file parsing ----------------------------------------*/

/* A configuration file. */
struct config {
  struct treap sections;                /* treap of sections */
  struct config_section *head, **tail;  /* section list, in creation order */
  struct config_section *fallback;      /* default parent section */
};
#define CONFIG_INIT { TREAP_INIT, 0, 0 }

/* A configuration section. */
struct config_section {
  struct treap_node _node;              /* treap intrustion */
  struct config_section *next;          /* next section in creation order */
  struct config_section **parents; size_t nparents; /* vector of parents */
  struct treap vars;                    /* treap of variables */
  struct treap cache;                   /* inheritance cache */
};
#define CONFIG_SECTION_NAME(sect) TREAP_NODE_KEY(sect)
#define CONFIG_SECTION_NAMELEN(sect) TREAP_NODE_KEYLEN(sect)

/* An entry in a section's inheritance cache: see `search_recursive' for
 * details.
 */
struct config_cache_entry {
  struct treap_node _node;              /* treap intrusion */
  unsigned f;                           /* flags */
#define CF_OPEN 1u                      /*   traps inheritance cycles */
  struct config_var *var;               /* pointer to inherited variable */
};

/* A configuration variable. */
struct config_var {
  struct treap_node _node;              /* treap intrusion */
  char *file; unsigned line;            /* source location, or null/0 */
  char *val; size_t n;                  /* value pointer and length */
  unsigned f;                           /* flags */
#define CF_LITERAL 1u                   /*   value should not be expanded */
#define CF_EXPAND 2u                    /*   traps expansion cycles */
#define CF_OVERRIDE 4u                  /*   override settings from files */
};
#define CONFIG_VAR_NAME(var) TREAP_NODE_KEY(var)
#define CONFIG_VAR_NAMELEN(var) TREAP_NODE_KEYLEN(var)

/* A section iterator.
 *
 * (Sections are visited in the order in which they were created.)
 */
struct config_section_iter {
  struct config_section *sect;          /* next section to return */
};

/* A variable iterator.
 *
 * (Variables are visited in lexicographical order.)
 */
struct config_var_iter {
  struct treap_iter i;
};

/* Common flags. */
#define CF_CREAT 1u                     /* create section or variable */
#define CF_INHERIT 2u                   /* look up variable in parents */

extern void config_init(struct config */*conf*/);
        /* Initialize the configuration state CONF.
         *
         * Usually you'd use the static initializer `CONFIG_INIT'.
         */

extern struct config_section *config_find_section(struct config */*conf*/,
                                                  unsigned /*f*/,
                                                  const char */*name*/);
        /* Find and return the section with null-terminated NAME in CONF.
         *
         * If no section is found, the behaviour depends on whether
         * `CF_CREAT' is set in F: if so, an empty section is created and
         * returned; otherwise, a null pointer is returned.
         */

extern struct config_section *config_find_section_n(struct config */*conf*/,
                                                    unsigned /*f*/,
                                                    const char */*name*/,
                                                    size_t /*sz*/);
        /* Find and return the section with the given SZ-byte NAME in CONF.
         *
         * This works like `config_find_section', but with an explicit length
         * for the NAME rather than null-termination.
         */

extern void config_set_fallback(struct config */*conf*/,
                                struct config_section */*sect*/);
        /* Set the fallback section for CONF to be SECT.
         *
         * That is, if a section has no explicit parents, then by default it
         * will have a single parent which is SECT.  If SECT is null then
         * there is no fallback section, and sections which don't have
         * explicitly specified parents have no parents at all.  (This is the
         * default situation.)
         */

extern void config_set_parent(struct config_section */*sect*/,
                              struct config_section */*parent*/);
        /* Arrange that SECT has PARENT as its single parent section.
         *
         * If PARENT is null, then arrange that SECT has no parents at all.
         * In either case, any `@parents' setting will be ignored.
         */

extern void config_start_section_iter(struct config */*conf*/,
                                      struct config_section_iter */*i*/);
        /* Initialize I to iterate over the sections defined in CONF. */

extern struct config_section *config_next_section
  (struct config_section_iter */*i*/);
        /* Return the next section from I, in order of creation.
         *
         * If there are no more sections, then return null.
         */

extern struct config_var *config_find_var(struct config */*conf*/,
                                          struct config_section */*sect*/,
                                          unsigned /*f*/,
                                          const char */*name*/);
        /* Find and return the variable with null-terminated NAME in SECT.
         *
         * If `CF_INHERIT' is set in F, then the function searches the
         * section's parents recursively; otherwise, it only checks to see
         * whether the variable is set directly in SECT.
         *
         * If no variable is found, the behaviour depends on whether
         * `CF_CREAT' is set in F: if so, an empty variable is created and
         * returned; otherwise, a null pointer is returned.
         *
         * Setting both `CF_INHERIT' and `CF_CREAT' is not useful.
         */

extern struct config_var *config_find_var_n(struct config */*conf*/,
                                            struct config_section */*sect*/,
                                            unsigned /*f*/,
                                            const char */*name*/,
                                            size_t /*sz*/);
        /* Find and return the variable with the given SZ-byte NAME in SECT.
         *
         * This works like `config_find_var', but with an explicit length for
         * the NAME rather than null-termination.
         */

extern struct config_var *config_set_var(struct config */*conf*/,
                                         struct config_section */*sect*/,
                                         unsigned /*f*/,
                                         const char */*name*/,
                                         const char */*value*/);
        /* Set variable NAME to VALUE in SECT, with associated flags F.
         *
         * The names are null-terminated.  The flags are variable flags: see
         * `struct config_var' for details.  Returns the variable.
         *
         * If the variable is already set and has the `CF_OVERRIDE' flag,
         * then this function does nothing unless `CF_OVERRIDE' is /also/ set
         * in F.
         */

extern struct config_var *config_set_var_n(struct config */*conf*/,
                                           struct config_section */*sect*/,
                                           unsigned /*f*/,
                                           const char */*name*/,
                                           size_t /*namelen*/,
                                           const char */*value*/,
                                           size_t /*valuelen*/);
        /* As `config_set_var', except that the variable NAME and VALUE have
         * explicit lengths (NAMELEN and VALUELEN, respectively) rather than
         * being null-terminated.
         */

extern void config_start_var_iter(struct config */*conf*/,
                                  struct config_section */*sect*/,
                                  struct config_var_iter */*i*/);
        /* Initialize I to iterate over the variables directly defined in
         * SECT.
         */

extern struct config_var *config_next_var(struct config_var_iter */*i*/);
        /* Return next variable from I, in ascending lexicographical order.
         *
         * If there are no more variables, then return null.
         */

extern int config_read_file(struct config */*conf*/, const char */*file*/,
                            unsigned /*f*/);
#define CF_NOENTOK 1u
        /* Read and parse configuration FILE, applying its settings to CONF.
         *
         * If all goes well, the function returns 0.  If the file is not
         * found, then the behaviour depends on whether `CF_NOENTOK' is set
         * in F: if so, then the function simply returns -1.  Otherwise, a
         * fatal error is reported.  Note that this /only/ applies if the
         * file does not exist (specifically, opening it fails with `ENOENT')
         * -- any other problems are reported as fatal errors regardless of
         * the flag setting.
         */

extern void config_read_env(struct config */*conf*/,
                            struct config_section */*sect*/);
        /* Populate SECT with environment variables.
         *
         * Environment variables are always set with `CF_LITERAL'.
         */

extern void config_subst_string(struct config */*config*/,
                                struct config_section */*home*/,
                                const char */*what*/,
                                const char */*p*/, struct dstr */*d*/);
        /* Expand substitutions in a string.
         *
         * Expand the null-terminated string P relative to the HOME section,
         * using configuration CONFIG, and appending the result to dynamic
         * string D.  Blame WHAT in any error messages.
         */

extern char *config_subst_string_alloc(struct config */*config*/,
                                       struct config_section */*home*/,
                                       const char */*what*/,
                                       const char */*p*/);
        /* Expand substitutions in a string.
         *
         * Expand the null-terminated string P relative to the HOME section,
         * using configuration CONFIG, returning the result as a freshly
         * malloc(3)ed string.  Blame WHAT in any error messages.
         */

extern void config_subst_var(struct config */*config*/,
                             struct config_section */*home*/,
                             struct config_var */*var*/,
                             struct dstr */*d*/);
        /* Expand substitutions in a variable.
         *
         * Expand the value of the variable VAR relative to the HOME section,
         * using configuration CONFIG, appending the result to dynamic string
         * D.
         */

extern char *config_subst_var_alloc(struct config */*config*/,
                                    struct config_section */*home*/,
                                    struct config_var */*var*/);
        /* Expand substitutions in a variable.
         *
         * Expand the value of the variable VAR relative to the HOME section,
         * using configuration CONFIG, returning the result as a freshly
         * malloc(3)ed string.
         */

extern void config_subst_split_var(struct config */*config*/,
                                   struct config_section */*home*/,
                                   struct config_var */*var*/,
                                   struct argv */*av*/);
        /* Expand substitutions in a variable and split into words.
         *
         * Expand and word-split the value of the variable VAR relative to
         * the HOME section, using configuration CONFIG, appending the
         * resulting words into the vector AV.
         */

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif