/*----- Functions provided ------------------------------------------------*/
extern const char *my_getenv(const char */*name*/, const char */*dflt*/);
+ /* Look up the environment variable NAME.
+ *
+ * If it's found, return the value; otherwise return DFLT. This
+ * function looks up the environment variable in the `@ENV'
+ * configuration section, so (a) it's likely more efficient than
+ * getenv(3), and (b) the `init_config' function must have been
+ * called earlier.
+ */
+
extern long parse_int(const char */*what*/, const char */*p*/,
long /*min*/, long /*max*/);
+ /* Parse and return an integer from the string P.
+ *
+ * Report an error if the string doesn't look like an integer, or if
+ * it's not between MIN and MAX (inclusive). Qualify error messages
+ * using the adjective WHAT.
+ */
+
extern void argv_string(struct dstr */*d*/, const struct argv */*av*/);
+ /* Format string-vector AV as a sequence of possibly-quoted words.
+ *
+ * Append the resulting list to D.
+ */
+extern int file_exists_p(const char */*path*/, unsigned /*f*/);
#define FEF_EXEC 1u
#define FEF_VERBOSE 2u
-extern int file_exists_p(const char */*path*/, unsigned /*f*/);
+ /* Return whether PATH names an existing file.
+ *
+ * This will return zero if PATH names something which isn't a
+ * regular file. If `FEF_EXEC' is set in F, then additionally ensure
+ * that it's executable by the (real) calling uid. If `FEF_VERBOSE'
+ * is set in F, then report on the outcome of the check to standard
+ * error.
+ */
+
extern int found_in_path_p(const char */*prog*/, unsigned /*f*/);
+ /* Return whether PROG can be found in the `PATH'.
+ *
+ * If PROG is a pathname (absolute or relative -- i.e., if it
+ * contains a `/'), then just check that it names an executable
+ * program. Otherwise check to see whether `DIR/PROG' exists and is
+ * executable for any DIR in the `PATH'. The flags F are as for
+ * `file_exists_p'.
+ */
+extern int try_exec(struct argv */*av*/, unsigned /*f*/);
#define TEF_DRYRUN 1u
#define TEF_VERBOSE 2u
-extern int try_exec(struct argv */*av*/, unsigned /*f*/);
+ /* Try to run a program as indicated by the argument list AV.
+ *
+ * This is essentially execvp(3). If `TEF_VERBOSE' is set in F then
+ * trace what's going on to standard error. If `TEF_DRYRUN' is set
+ * in F then don't actually try to run the program: just check
+ * whether it exists and is vaguely plausible. Return -1 if there
+ * was a problem, or 0 if it was successful but didn't actually run
+ * the program because of the flags settings.
+ */
+
+extern void init_config(void);
+ /* Initialize the configuration machinery.
+ *
+ * This establishes the standard configuration sections `@CONFIG',
+ * `@BUILTIN', `@COMMON', and `@ENV', setting the corresponding
+ * global variables, and populates `@BUILTIN' (from compile-time
+ * configuration) and `@ENV' (from the environment variables).
+ */
extern void read_config_file(const char */*what*/,
const char */*file*/, unsigned /*f*/);
+ /* Read a named configuration FILE.
+ *
+ * WHAT is an adjective describing the configuration file, to be used
+ * in diagnostics; FILE is the actual filename to read; and F holds
+ * `CF_...' flags for `config_read_file', which actually does most
+ * of the work.
+ */
+
extern void read_config_dir(const char */*what*/,
const char */*path*/, unsigned /*f*/);
+ /* Read all of the configuration files in directory PATH.
+ *
+ * WHAT is an adjective describing the configuration directory, to be
+ * used in diagnostics; FILE is the actual filename to read; and F
+ * holds `CF_...' flags for `config_read_file', which actually reads
+ * the files.
+ *
+ * All of the files named `*.conf' in the directory are read, in
+ * ascending lexicographical order by name. If `CF_NOENTOK' is set
+ * in F, then ignore an error explaining that the directory doesn't
+ * exist. (This only ignores `ENOENT': any other problem is still a
+ * fatal error.)
+ */
+
extern void read_config_path(const char */*path*/, unsigned /*f*/);
+ /* Read configuration from a file or directory PATH.
+ *
+ * If PATH exists and names a directory then process all of the files
+ * within, as for `read_config_dir'; otherwise try to read it as a
+ * file, as for `read_config_file'. The flags F are passed to the
+ * respective function.
+ */
+
extern int set_config_var(const char */*assign*/);
-extern void init_config(void);
+ /* Apply a configuration variable setting in command-line syntax.
+ *
+ * ASSIGN should be a string in the form `[SECT:]VAR=VALUE'. Set VAR
+ * to VALUE in section SECT (defaults to `@CONFIG'). The variable is
+ * set with `CF_OVERRIDE' set to prevent the setting from being
+ * overwritten by a configuration file.
+ */
+
extern void load_default_config(void);
+ /* Load the default configuration files.
+ *
+ * This will read `ETCDIR/runlisp.d/*.conf', `ETCDIR/runlisp.conf',
+ * `~/.runlisp.conf', and `~/.config/runlisp.conf'.
+ */
+
extern void dump_config(void);
+ /* Dump the configuration to standard error. */
/*----- That's all, folks -------------------------------------------------*/