From d64db6bad79e10f92c56e5572d6ae9072d62b3a3 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Fri, 1 Feb 2019 00:04:33 -0500 Subject: Add some documentation comments --- bfs.h | 4 ++++ bftw.h | 4 ++++ cmdline.h | 4 ++++ color.c | 20 ++++++++++++++++++++ color.h | 4 ++++ diag.h | 4 ++++ dstring.c | 3 +++ dstring.h | 4 ++++ eval.c | 4 ++++ eval.h | 5 +++++ exec.h | 4 ++++ expr.h | 4 ++++ main.c | 31 +++++++++++++++++++++++++++++++ mtab.h | 4 ++++ opt.c | 25 +++++++++++++++++++++++++ parse.c | 7 +++++++ posix1e.h | 7 +++++++ printf.h | 4 ++++ spawn.h | 4 ++++ stat.h | 10 +++++++++- util.h | 4 ++++ 21 files changed, 159 insertions(+), 1 deletion(-) diff --git a/bfs.h b/bfs.h index 34fdc3c..d5d3f93 100644 --- a/bfs.h +++ b/bfs.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * Constants about the bfs program itself. + */ + #ifndef BFS_H #define BFS_H diff --git a/bftw.h b/bftw.h index eff24bc..bed5800 100644 --- a/bftw.h +++ b/bftw.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * A file-walking API based on nftw(). + */ + #ifndef BFS_BFTW_H #define BFS_BFTW_H diff --git a/cmdline.h b/cmdline.h index 78e1f9a..4a1ef3b 100644 --- a/cmdline.h +++ b/cmdline.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * Representation of the parsed command line. + */ + #ifndef BFS_CMDLINE_H #define BFS_CMDLINE_H diff --git a/color.c b/color.c index 333b547..27df6a0 100644 --- a/color.c +++ b/color.c @@ -29,6 +29,9 @@ #include #include +/** + * A color for a file extension. + */ struct ext_color { const char *ext; size_t len; @@ -38,6 +41,9 @@ struct ext_color { struct ext_color *next; }; +/** + * The parsed form of LS_COLORS. + */ struct colors { const char *reset; const char *bold; @@ -77,6 +83,9 @@ struct colors { char *data; }; +/** + * A named color for parsing and lookup. + */ struct color_name { const char *name; size_t offset; @@ -84,6 +93,9 @@ struct color_name { #define COLOR_NAME(name, field) {name, offsetof(struct colors, field)} +/** + * All the known color names that can be referenced in LS_COLORS. + */ static const struct color_name color_names[] = { COLOR_NAME("bd", block), COLOR_NAME("bld", bold), @@ -118,6 +130,7 @@ static const struct color_name color_names[] = { {0}, }; +/** Get a color from the table. */ static const char **get_color(const struct colors *colors, const char *name) { for (const struct color_name *entry = color_names; entry->name; ++entry) { if (strcmp(name, entry->name) == 0) { @@ -128,6 +141,7 @@ static const char **get_color(const struct colors *colors, const char *name) { return NULL; } +/** Set the value of a color. */ static void set_color(struct colors *colors, const char *name, const char *value) { const char **color = get_color(colors, name); if (color) { @@ -288,6 +302,7 @@ int cfclose(CFILE *cfile) { return ret; } +/** Get the color for a file by its extension. */ static const char *ext_color(const struct colors *colors, const char *filename) { size_t namelen = strlen(filename); @@ -305,6 +320,7 @@ static const char *ext_color(const struct colors *colors, const char *filename) return NULL; } +/** Get the color for a file. */ static const char *file_color(const struct colors *colors, const char *filename, const struct BFTW *ftwbuf) { const struct bfs_stat *sb = ftwbuf->statbuf; if (!sb) { @@ -394,6 +410,7 @@ static const char *file_color(const struct colors *colors, const char *filename, return color; } +/** Print an ANSI escape sequence. */ static int print_esc(const char *esc, FILE *file) { if (fputs("\033[", file) == EOF) { return -1; @@ -408,6 +425,7 @@ static int print_esc(const char *esc, FILE *file) { return 0; } +/** Print a string with an optional color. */ static int print_colored(const struct colors *colors, const char *esc, const char *str, size_t len, FILE *file) { if (esc) { if (print_esc(esc, file) != 0) { @@ -426,6 +444,7 @@ static int print_colored(const struct colors *colors, const char *esc, const cha return 0; } +/** Print the path to a file with the appropriate colors. */ static int print_path(CFILE *cfile, const struct BFTW *ftwbuf) { const struct colors *colors = cfile->colors; FILE *file = cfile->file; @@ -450,6 +469,7 @@ static int print_path(CFILE *cfile, const struct BFTW *ftwbuf) { return 0; } +/** Print a link target with the appropriate colors. */ static int print_link(CFILE *cfile, const struct BFTW *ftwbuf) { int ret = -1; diff --git a/color.h b/color.h index 78db64a..7df3785 100644 --- a/color.h +++ b/color.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * Utilities for colored output on ANSI terminals. + */ + #ifndef BFS_COLOR_H #define BFS_COLOR_H diff --git a/diag.h b/diag.h index e84bbc1..54f2366 100644 --- a/diag.h +++ b/diag.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * Formatters for diagnostic messages. + */ + #ifndef BFS_DIAG_H #define BFS_DIAG_H diff --git a/dstring.c b/dstring.c index f4a865a..10e1557 100644 --- a/dstring.c +++ b/dstring.c @@ -27,10 +27,12 @@ struct dstring { char data[]; }; +/** Get the string header from the string data pointer. */ static struct dstring *dstrheader(const char *dstr) { return (struct dstring *)(dstr - offsetof(struct dstring, data)); } +/** Get the correct size for a dstring with the given capacity. */ static size_t dstrsize(size_t capacity) { return sizeof(struct dstring) + capacity + 1; } @@ -81,6 +83,7 @@ int dstresize(char **dstr, size_t length) { return 0; } +/** Common implementation of dstr{cat,ncat,app}. */ static int dstrcat_impl(char **dest, const char *src, size_t srclen) { size_t oldlen = dstrlen(*dest); size_t newlen = oldlen + srclen; diff --git a/dstring.h b/dstring.h index 1beccb5..d43a1f0 100644 --- a/dstring.h +++ b/dstring.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * A dynamic string library. + */ + #ifndef BFS_DSTRING_H #define BFS_DSTRING_H diff --git a/eval.c b/eval.c index e05aff1..b41ebf6 100644 --- a/eval.c +++ b/eval.c @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * Implementation of all the literal expressions. + */ + #include "eval.h" #include "bftw.h" #include "cmdline.h" diff --git a/eval.h b/eval.h index 89bf421..91cc944 100644 --- a/eval.h +++ b/eval.h @@ -14,6 +14,11 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * The evaluation functions that implement literal expressions like -name, + * -print, etc. + */ + #ifndef BFS_EVAL_H #define BFS_EVAL_H diff --git a/exec.h b/exec.h index 1a75064..78cdbd2 100644 --- a/exec.h +++ b/exec.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * Implementation of -exec/-execdir/-ok/-okdir. + */ + #ifndef BFS_EXEC_H #define BFS_EXEC_H diff --git a/expr.h b/expr.h index b7c5c15..0251d6b 100644 --- a/expr.h +++ b/expr.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * The expression tree representation. + */ + #ifndef BFS_EXPR_H #define BFS_EXPR_H diff --git a/main.c b/main.c index 066061d..261711b 100644 --- a/main.c +++ b/main.c @@ -14,6 +14,37 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * - main(): the entry point for bfs(1), a breadth-first version of find(1) + * - main.c (this file) + * + * - parse_cmdline(): parses the command line into an expression tree + * - cmdline.h (declares the parsed command line structure) + * - expr.h (declares the expression tree nodes) + * - parse.c (the parser itself) + * - opt.c (the expression optimizer) + * + * - eval_cmdline(): runs the expression on every file it sees + * - eval.[ch] (the main evaluation functions) + * - exec.[ch] (implements -exec[dir]/-ok[dir]) + * - printf.[ch] (implements -[f]printf) + * + * - bftw(): used by eval_cmdline() to walk the directory tree(s) + * - bftw.[ch] (an extended version of nftw(3)) + * + * - Utilities: + * - bfs.h (constants about bfs itself) + * - color.[ch] (for pretty terminal colors) + * - diag.[ch] (formats diagnostic messages) + * - dstring.[ch] (a dynamic string library) + * - mtab.[ch] (parses the system's mount table) + * - posix1e.[ch] (wraps POSIX.1e functionality, if present) + * - spawn.[ch] (spawns processes) + * - stat.[ch] (wraps stat(), or statx() on Linux) + * - typo.[ch] (fuzzy matching for typos) + * - util.[ch] (everything else) + */ + #include "cmdline.h" #include "util.h" #include diff --git a/mtab.h b/mtab.h index e8a021c..ef22716 100644 --- a/mtab.h +++ b/mtab.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * A facade over platform-specific APIs for enumerating mounted filesystems. + */ + #ifndef BFS_MTAB_H #define BFS_MTAB_H diff --git a/opt.c b/opt.c index 1157754..dd98ca0 100644 --- a/opt.c +++ b/opt.c @@ -14,6 +14,31 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * The expression optimizer. Different optimization levels are supported: + * + * -O1: basic logical simplifications, like folding (-true -and -foo) to -foo. + * + * -O2: dead code elimination and data flow analysis. struct opt_facts is used + * to record data flow facts that are true at various points of evaluation. + * Specifically, struct opt_facts records the facts that must be true before an + * expression is evaluated (state->facts), and those that must be true after the + * expression is evaluated, given that it returns true (state->facts_when_true) + * or false (state->facts_when_true). Additionally, state->facts_when_impure + * records the possible data flow facts before any expressions with side effects + * are evaluated. + * + * -O3: expression re-ordering to reduce expected cost. In an expression like + * (-foo -and -bar), if both -foo and -bar are pure (no side effects), they can + * be re-ordered to (-bar -and -foo). This is profitable if the expected cost + * is lower for the re-ordered expression, for example if -foo is very slow or + * -bar is likely to return false. + * + * -O4/-Ofast: aggressive optimizations that may affect correctness in corner + * cases. The main effect is to use facts_when_impure to determine if any side- + * effects are reachable at all, and skipping the traversal if not. + */ + #include "cmdline.h" #include "color.h" #include "eval.h" diff --git a/parse.c b/parse.c index 42a5a8f..80aeb88 100644 --- a/parse.c +++ b/parse.c @@ -14,6 +14,13 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * The command line parser. Expressions are parsed by recursive descent, with a + * grammar described in the comments of the parse_*() functions. The parser + * also accepts flags and paths at any point in the expression, by treating + * flags like always-true options, and skipping over paths wherever they appear. + */ + #include "bfs.h" #include "cmdline.h" #include "diag.h" diff --git a/posix1e.h b/posix1e.h index 8950498..d3d74ff 100644 --- a/posix1e.h +++ b/posix1e.h @@ -14,6 +14,13 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * The withdrawn POSIX.1e standard specified a security API for POSIX systems. + * Although it was never ratified, many of its interfaces are widely deployed + * in Unix-like systems. These functions wrap the POSIX.1e APIs if present, + * to support things like Access Control Lists and Capabilities. + */ + #ifndef BFS_POSIX1E_H #define BFS_POSIX1E_H diff --git a/printf.h b/printf.h index 27336eb..1c3957e 100644 --- a/printf.h +++ b/printf.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * Implementation of -printf/-fprintf. + */ + #ifndef BFS_PRINTF_H #define BFS_PRINTF_H diff --git a/spawn.h b/spawn.h index ef510e1..a634d6e 100644 --- a/spawn.h +++ b/spawn.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * A process-spawning library inspired by posix_spawn(). + */ + #ifndef BFS_SPAWN_H #define BFS_SPAWN_H diff --git a/stat.h b/stat.h index d9c9588..3887db4 100644 --- a/stat.h +++ b/stat.h @@ -1,6 +1,6 @@ /**************************************************************************** * bfs * - * Copyright (C) 2018 Tavian Barnes * + * Copyright (C) 2018-2019 Tavian Barnes * * * * Permission to use, copy, modify, and/or distribute this software for any * * purpose with or without fee is hereby granted. * @@ -14,6 +14,14 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * A facade over the stat() API that unifies some details that diverge between + * implementations, like the names of the timespec fields and the presence of + * file "birth" times. On new enough Linux kernels, the facade is backed by + * statx() instead, and so it exposes a similar interface with a mask for which + * fields were successfully returned. + */ + #ifndef BFS_STAT_H #define BFS_STAT_H diff --git a/util.h b/util.h index 4f70c1b..0a4779f 100644 --- a/util.h +++ b/util.h @@ -14,6 +14,10 @@ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * ****************************************************************************/ +/** + * Assorted utilities that don't belong anywhere else. + */ + #ifndef BFS_UTIL_H #define BFS_UTIL_H -- cgit v1.2.3