summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTavian Barnes <tavianator@tavianator.com>2019-02-01 00:04:33 -0500
committerTavian Barnes <tavianator@tavianator.com>2019-02-09 17:06:38 -0500
commitd64db6bad79e10f92c56e5572d6ae9072d62b3a3 (patch)
treef1f334c165afecd1907e9c4cf377878ba172c35a
parent563b5f9d48e54dc2f5d61a23ce2171e005da201a (diff)
downloadbfs-d64db6bad79e10f92c56e5572d6ae9072d62b3a3.tar.xz
Add some documentation comments
-rw-r--r--bfs.h4
-rw-r--r--bftw.h4
-rw-r--r--cmdline.h4
-rw-r--r--color.c20
-rw-r--r--color.h4
-rw-r--r--diag.h4
-rw-r--r--dstring.c3
-rw-r--r--dstring.h4
-rw-r--r--eval.c4
-rw-r--r--eval.h5
-rw-r--r--exec.h4
-rw-r--r--expr.h4
-rw-r--r--main.c31
-rw-r--r--mtab.h4
-rw-r--r--opt.c25
-rw-r--r--parse.c7
-rw-r--r--posix1e.h7
-rw-r--r--printf.h4
-rw-r--r--spawn.h4
-rw-r--r--stat.h10
-rw-r--r--util.h4
21 files changed, 159 insertions, 1 deletions
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 <sys/stat.h>
#include <unistd.h>
+/**
+ * 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 <errno.h>
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 <tavianator@tavianator.com> *
+ * Copyright (C) 2018-2019 Tavian Barnes <tavianator@tavianator.com> *
* *
* 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