X-Git-Url: https://git.distorted.org.uk/~mdw/runlisp/blobdiff_plain/7b8ff279e7304e41b243459d78c3b6703bb8c3f5..8996f767e047eefa8af4d01b1434b54f4c169b79:/common.h

diff --git a/common.h b/common.h
index 6ec38c5..b761052 100644
--- a/common.h
+++ b/common.h
@@ -44,28 +44,127 @@ extern unsigned verbose;
 /*----- 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 -------------------------------------------------*/