ff plan

ff: functional find. A short-switch find with NetBSD find(1) semantics where they matter, one interface on Linux, Darwin and NetBSD, delivered as C99 source (ff.c) and a bash function (ff.fn.bash).

This plan drives the package revisions. It took this shape at r0.7, when the package took the shape of cksh's and srt's: before that the plan was PLAN.md, a design record by revision (r1 to r10 there), kept whole as section 14. Items marked V (section 2) began as ambiguities with a proposed default; nothing downstream of an unconfirmed V item was built until it was ruled on. Decisions are recorded in section 12, the affected sections state the decision in place, and section 13 holds the status of each revision as built. Where a decision reverses an earlier one, both are stated.

revision 6af927be 20261114 193214 PST Sat --- r0.7: plan-ff.md opened from PLAN.md; V01-V09 ruled and built, V10 built as proposed and open; key grammar shared with srt and cksh; cksh package model
original 6ab7fec8 20260926 102008 PDT Sat --- PLAN.md, the design record of r0.1 to r0.6 (section 14)

(c) 2026 George Georgalis george@iuxta.com Unlimited use with attribution.

Contents


1 Purpose and scope

ff walks file trees and evaluates an expression for every node, as find does, with one letter per switch. It prints the names for which the expression holds, or with -v one cksh line per node, and with -k sorts what it prints by the columns of that line.

In scope: the walk, with an owned walker that never re-resolves a path it has checked; the primaries and actions of section 14; -v, the cksh line without a hash; sorting by column with the key grammar of srt and cksh; NUL-terminated records; a bash function that translates the same grammar to the native find and writes the same bytes.

Out of scope, by requirement: hashing (that is cksh, which reads the names ff prints); duplicate detection (that is srt -D); a global reverse option (V01); locale collation; -ok, -fprint, -printf, -flags, -fstype.

ff is one of three tools that share a record and a key grammar: ff finds files, cksh lists them, srt sorts listings. Section 4 holds the grammar the three agreed.

2 Intent verification

Each item states the ambiguity, the readings, and the ruling. V01 to V09 were ruled on 20261114, before r0.7 was built. V10 was not ruled on; it is built as proposed and stays open.

V01 Global reverse. The grammar model gives -r for all columns. In ff -r is the ERE primary and takes an argument. Readings: (a) no reverse-all in ff, only -kNr; (b) an uppercase option -R (srt's -R randomizes); (c) move the regex primary to another letter. DECIDED: (a). Full descent is written out, -k5r,4r,6r,1r,2r.

V02 -k list as the next word. r0.6 read only a joined value, so in ff -k 5 the 5 was a path. DECIDED: the cksh rule. The next word is the list when it reads as one (a column number first, in the widest sense srt gives a list, so a list ff refuses is reported as a list and not walked as a path). ff -k 5 sorts . by mdate; a directory named 5 is written ./5; -k 7 is a usage error. -k may also end a group of options, -Sk5. As built, one departure from cksh: a word that begins with - is never the list, since -0 and -1 are primaries in ff, so in -k -1 the -1 is false; joined, -k-1 is refused with the cksh wording.

V03 Repeated -k. r0.6: the last one wins. DECIDED: the cksh rule. -k5 -k4 is -k5,4; naming a column twice is an error.

V04 Column 3 and letters. r0.6: -k3 kept walk order and held nothing. DECIDED: the null column is a no-op sort, so -k3 orders by 1,2,4,5,6. Letters, as ruled: on columns 1, 2, 4 and 5 x is valid and means what the column already is, a number; columns 3 and 6 are text; r reverses a column of either type; -k-1 is refused. As built, following cksh on the two cases the ruling leaves unstated: x on column 3 or 6 is refused (tag 6ab7ff51), since x asks for a number where the column is text, and any letter other than r and x is refused (6ab7ff52), since the types are fixed. Letters combine in either order, -k5xr and -k5rx.

V05 Columns without -v. A default print writes the name alone. DECIDED: -kN sorts by columns that are not shown, as ls -t sorts without -l. Column numbers always name the -v layout and every record is keyed by its node's stat. The srt equivalence of section 4 item 5 holds for -v output.

V06 -Z with -v. r0.6: -Z ended only -f and default-print names; -v lines kept the newline. DECIDED: -Z, --zero-terminated, ends every record with NUL, with -f or not; srt's -Z is NUL-terminated records in and out. As built, names are written raw under -Z, to a terminal too, on -v lines as on names.

V07 Hash notation. ff computes no hash; column 3 is always a dot. DECIDED: documentation only. Column 3 is described as the place of cksh's shake256-N, shake256-6 by default, with no slash notation anywhere. No hashing is added to ff.

V08 -V. In cksh and srt -V is the version; in ff it shows the native find command. DECIDED: ff keeps -V and gains --version only. --man and the formatter-driven --help follow cksh.

V09 Function hand-over. DECIDED: the function runs a binary named ff on PATH, with --fn and --bin to allow only one form; -V implies --fn, since only the function has a native command to show. As built: an explicit --bin with -V reaches the binary, which notes -V and runs; --fn with --bin is a usage error (6ab7ff55); --bin with no binary is status 2 (6ab7ff56); the binary refuses --fn (6ab7ff54) and accepts --bin. The words that choose the form are options, so they are not seen where an option is not: as the argument of a primary, among the words of an -x or -j command, or after --.

V10 Revision naming. OPEN, built as proposed. The six dated revisions are named r0.1 to r0.6 and this one r0.7; the r1 to r10 labels of PLAN.md stay in section 14 as that record's own numbering. The alternative, r0.6 to match the cksh and srt archives, is a change of label in the headers, FF_REV, the manual REVISION and the test of --version.

3 Interface

ff [-IHLDSXZV] [-k [col[r][,col[r]]...]] [--] [path ...] [expression], ff -h | --help | --man | --version, ff --fn ... | ff --bin ....

Options are uppercase letters, and -k, global, accepted anywhere except as the argument of a primary. Primaries are lowercase letters, the digits 0 and 1, or -mode and -delete. The option and primary tables, with their rationale, are in section 14 (Grammar); --help is the statement of the current implementation.

New or changed at r0.7:

wordmeaning
-k [list]sort; list joined, the next word, or after a group (-Sk5); section 4
-Z, --zero-terminatedevery record ends in NUL; names raw
--helpon a terminal, a man page through mandoc, else nroff and a pager, else the pager, else plain
--manthe manual as man page source; ff.1
--versionff r0.7 6af927be; the function adds (bash function)
--fn, --binallow only the function, only the binary
-Vunchanged; given to the function it keeps the function

Retired at r0.7: -krN (write -kNr); the --help pager warning, tag 6ab7ff4e.

4 Key grammar shared with srt and cksh

Settled first in srt (plan-srt.md, section 2), built in cksh (plan-cksh.md, section 4), and stated for ff as the model of this revision:

  1. Columns are words in the awk sense, counted from 1; widths and padding are not significant, and blanks may be squeezed.
  2. Sorting is asked for with -k list, col[opts][,col[opts]]...: the named columns in the order given, then the remaining columns left to right. Ties follow srt's order.
  3. A bare -k names no column. That means sort by file name; in srt, by whole record.
  4. Reverse is -kNr for one column or -r for all. -krN is not accepted.
  5. ff knows column types, so -k5,4,6 is srt -k5x,4x,6,1x,2x,3 on their output: node, links, time, and size by hexadecimal value, the hash and name as text.
  6. The name begins in column 6 with -v and runs to the end of the record.

As built in ff:

The srt equivalent of any ff list: the list, then the remaining columns, x added to 1, 2, 4 and 5. The suite checks three such pairs when srt is present, and two against cksh -n0 -x0 when cksh is.

5 Output

The default print and -f write the path. -v writes the cksh line, inode links . size mdate name, numbers in lowercase hexadecimal at the least widths cksh uses (%8jx %2jx . %8jx %08jx), the name with an indicator in the manner of ls -F. It is byte for byte what cksh -n0 -x0 writes for the same name. A time before 1970 is written with a minus sign, -12cff780 for 1960-01-01 UTC, as cksh writes it and as srt -x reads it; r0.6 wrote the two's complement, ffffffffed300880, which sorted after every later time.

Every record ends in newline, or under -Z in NUL. To a terminal, and not under -Z, control bytes and invalid UTF-8 in a name are written as \ooo.

6 Hash

ff reads no file and computes no hash. Column 3 is kept, as a dot, so that the columns of ff and cksh agree: it is the column where cksh writes shake256-N of the content, N hexadecimal characters, shake256-6 by default. The name is written with a hyphen and never with a slash, which is read three ways (bits, bytes, hexadecimal characters); plan-cksh.md section 6 has the case. To add the hash to what ff finds, ff ... | cksh.

7 Exit status and diagnostics

A bitmask: 1 usage, 2 environment, 4 node, 8 exec, 16 loop, 32 node changed. 1 and 2 are fatal. Diagnostics are one line on standard error, >>> ff : what 'name'[: why] (tag) for errors and ^^^ for warnings; the tag names the message and is the same in the function.

Tags added at r0.7:

tagmessage
6ab7ff4c-k requires columns 1-6, got (the tag of r0.6's key error)
6ab7ff4f-krN is not accepted, write -kNr; got -k
6ab7ff50-k counts columns 1-6 from the left only, got
6ab7ff51-k letter x is for the numeric columns 1 2 4 5; columns 3 and 6 are text, got
6ab7ff52-k accepts the letters r and x only: column types are fixed, got
6ab7ff53-k names a column twice, got
6ab7ff54--fn allows only the bash function (ff.fn.bash); this is the binary
6ab7ff55--fn and --bin cannot be combined (function)
6ab7ff56--bin allows only the ff binary, and none is on PATH (function, status 2)
6ab7ff57the function needs process substitution, which this bash lacks in POSIX mode (sh); use bash or the ff binary (function, status 2)

Retired: 6ab7ff4e, the pager that cannot run. --help now passes over a formatter or pager that cannot run and tries the next.

8 Package files

The manual follows the cksh model: body indented four blanks, a blank line after each heading, example groups as sub-headings indented two blanks with a blank line before each; sections NAME to REVISION with KEYS, BASH FUNCTION, ENVIRONMENT and SEE ALSO cksh(1), srt(1), find(1); no HISTORY and no COPYRIGHT. The copyright stays in every other file.

9 Verification

make test runs test-ff.sh beside ./ff. Every behavior case runs through the binary and then through the function, which is always given --fn; a parity pass compares the two byte for byte.

Cases added at r0.7:

  1. Key lists: named columns then the rest; -k, -k6r, two and three column lists, r and x in either order.
  2. Remaining columns: -k5 equals -k5,1,2,4,6.
  3. Null column: -k3 equals -k1; -k3,5 equals -k5.
  4. Repeated -k accumulates; a bare -k beside a list adds nothing.
  5. The list as the next word, before paths and inside the expression; -k before a path, before a primary, before -1, and last; -k 5, -k ./5, -k -- 5.
  6. -k ending a group: -Sk, -Sk5,6, -Zk.
  7. Column 6 as printed: a directory and a longer name, bare and -v.
  8. Rejects, each with status 1, and the six tags.
  9. -v: six columns, the dot; -Z -v ends in NUL with no newline; --zero-terminated.
  10. Signed mdate, where touch and the file system take 1960.
  11. srt and cksh equivalence, where they are on PATH. Each is run as the file found there, never by name, so a function of that name exported into the shell is not what is tested.
  12. --help on a terminal through stand-in formatters, each in a PATH of its own: mandoc first, nroff and the pager, the pager alone, a pager quit early, no pager at all.
  13. Manual: the section list, SEE ALSO, no copyright in -h, --help or --man, shake256-6 named, no slash label, ASCII, 80 columns, a blank line before each example group; --man structure; ff.1 equal to --man.
  14. Form selection: hand-over, --fn first and last, --bin, -V alone and in a group, --bin -V, --fn as a primary's argument, as an -x word and after --, both together, --bin with no binary, the binary's --fn and --bin, --version, --man; the hand-over under bash in POSIX mode, and with and without a binary where process substitution is missing (FF_NO_PROCSUB stands in for a bash before 5.1).
  15. Symlink policy in the function's records: -H on a link operand with -v and with -k, -L and -H on a dangling link.

10 Dependency posture

The binary needs C99 and libc, and nothing else at run time; the directory walker is owned rather than fts(3); on Linux, user and group names resolve through getent(1) at a fixed path. No setlocale() call is made. Static on Linux and NetBSD; on Darwin the ceiling is dynamic linkage against libSystem alone.

The function needs bash 4, the native find, stat(1) in the GNU or BSD form, and for -k a sort with -z and -s. --help uses mandoc or nroff when the host has one and a pager otherwise; none is required.

11 Revision sequence

r0.1 6ab7fec8  r0.2 6ab89f43  r0.3 6abb42b9  r0.4 6abc5da8
r0.5 6adcb748  r0.6 6ae4ea00  r0.7 6af927be

Named at r0.7 from the dated revisions (V10, open). Corrections to a released revision fold into it without a new name, as in cksh and srt. Breaking grammar changes are accepted until a stable release is declared; from then backward compatibility is maintained.

12 Decision log

itemdecisiondate
V01no global reverse in ff; -kNr only20261114
V02-k list joined or the next word when it reads as a list; -k may end a group; a word beginning with - is never the list20261114
V03repeated -k accumulate; a column named twice is an error; reverses r0.6, last wins20261114
V04column 3 is a null column; x valid on 1 2 4 5; r on any column; -k-1 refused; as built x on 3 or 6 and other letters refused20261114
V05-kN sorts by columns not shown, as ls -t without -l20261114
V06-Z, --zero-terminated: NUL ends every record, -v included; reverses r0.620261114
V07hash notation in documentation only: shake256-N, shake256-6, no slash; ff does not hash20261114
V08ff keeps -V; --version, --man; --help through a formatter20261114
V09function hands over to a binary on PATH; --fn, --bin; -V implies --fn20261114
V10r0.1-r0.6 named, this revision r0.7: built as proposed, not ruledopen
--uniform key grammar across srt, cksh, ff (section 4); -krN retired; duplicate detection is srt only; ff keeps -0 and -120261114
--file names plan-ff.md, test-ff.sh, makefile, ff.fn.bash, ff.c, README.md; cksh and srt r0.6 as method reference and templates20261114
--SEE ALSO srt and cksh in --help and the man page; no copyright there, kept in every other file20261114

13 Revision status

r0.7 (6af927be, 20261114)

Built, against the rulings of section 2:

Defects corrected, found in the review of r0.6 and of this revision:

Verified here (Linux, glibc 2.39, GNU find 4.9, bash 5.2, GNU make): 922 passed, 0 failed, 9 skipped as root; 926 passed, 0 failed, 7 skipped as an unprivileged user; srt r0.6 and cksh r0.6 on PATH for the equivalence cases. gcc and clang compile without a warning under -std=c99 -Wall -Wextra -Wpedantic. A gcc build under ASan and UBSan ran the suite clean.

Darwin report (20261114, make clean man test install, first r0.7 build): 914 passed, 4 failed, 12 skipped. The binary pass, the bash pass and parity were otherwise whole, the terminal --help cases and the signed mdate included. The 4 failures were the two cksh equivalence cases in each pass, and were the suite's, not ff's:

The corrections were verified on Linux only: the suite under bash in POSIX mode with functions named cksh and srt exported, 922 passed. The Darwin rerun is pending.

Not verified here: NetBSD, bmake; mandoc and nroff themselves (the suite uses stand-ins, and this host has neither); a locale other than C, for the LC_ALL=C sort correction, which rests on the shell's export rule and not on an observed misorder.

Open:

r0.6 (6ae4ea00, 20261030) and before

The record of r0.1 to r0.6 is section 14. Verified state as it stood: r0.6 passed under GNU make on Linux, 742 cases as root and 746 non-root, with gcc and clang and under ASan, UBSan and LeakSanitizer. On Darwin (arm64, Apple clang): r0.3 failed 4 of 325, two from /tmp being a symlink to /private/tmp and two from BSD -execdir passing bare names to the function, both answered in r0.4; r0.4 passed the binary and parity passes, its bash pass failing 3 cases that are BSD find differences, since probed and skipped; r0.5 passed whole, 694 cases, 12 skipped; a first build of r0.6 passed make all test install, 735 cases, 12 skipped. Never run under bmake or on NetBSD.

14 History: PLAN.md, the design record of r0.1 to r0.6

Kept as written. Its revision labels r1 to r10 are its own; its rev stamps are the dated revisions of section 11. Where it says -k[r][N], "the last one wins", -k3 "passes walk order through", -Z for names only, --help through $PAGER, test.sh or PLAN.md, sections 2 to 13 above supersede it.

Context

ff is a short-switch find: NetBSD find(1) semantics where they matter, one letter per switch, predictable on Linux and Darwin. The cksh project sets the development model and solution profile, carried forward whole:

Finding that reshapes the shell companion: Lua

Stock Lua (5.1--5.4) has no readdir, no lstat, no fnmatch, and no POSIX regex; its patterns are not ERE, so -E cannot be honored in pure Lua. Every filesystem call would route through io.popen/os.execute, which invoke sh -c --- a quoting and injection surface, plus a fork per directory. With the "no lua modules" rule in force (shell skill), luaposix/lfs are excluded, and Lua is not installed on this host either. The intuition that Lua offers better filesystem access holds only with modules.

Recommended companion instead: ff.fn.bash as a translator. It parses the ff grammar, emits an argv array for the host's native find (never eval, never a string), and runs it with -print0 piped into a bash post-filter only where the native dialect lacks a primary. The walk, lstat and regex engine are then the kernel-adjacent native find, which is exactly what the Lua walker would have been emulating through popen. Dialect probe once per call: BSD (find -E accepted, NetBSD/Darwin) vs GNU (-regextype).

Decided r1: bash-translator. Lua dropped.

Walker: owned, not fts(3)

fts is the high-frequency choice (every BSD find uses it) --- visibility bias flagged. Against it here: musl ships no fts (static musl link fails), glibc fts lacked LFS safety before 2.34, and fts's FTS_NOCHDIR/chdir modes give no per-open race proof. nftw has no subtree prune in POSIX. Owned walker:

Grammar (draft letters --- expect revision)

Positional like find: ff [options] [path...] [expression]; default path ., default action print. Options are uppercase letters, primaries lowercase letters or the digits 0 and 1 (r8), so the two sets never collide. The tables below carry the current letters; the decisions log records each change.

Options (before paths)

ffNetBSD findnote
-E-Eretired r10: -r is always ERE; -E is an unknown option
-I(-iname/-iregex)case-insensitive for every -n -p -r
-H / -L-H / -Lsymlink policy; -P default
-D-ddepth-first (post-order)
-S-ssorted traversal
-X-x / -xdevstay on one filesystem
-Z-print0NUL-terminated output (r8; was -0)
-h / --helpusage / manual; --help through $PAGER on a tty (r10)

Primaries (after paths); ! not, -o or, juxtaposition and, ( ) group

fffindsemantics
-n glob-namefnmatch on basename, no FNM_PERIOD
-p glob-pathfnmatch on whole path
-r ere-E -regexregexec on whole path; unanchored (grep-like, add ^$); decided r1, documented deviation; always ERE (r10)
-t fdlpsbc-typemultiple letters = or: -t fl
-d [+-]N-depth n / min/maxdepthwalker bound: -d -3 prunes below depth 3
-s [+-]N[ckMG]-sizebytes default; decided r1
-m -a -c -b [+-]N[smhdw]-mtime/-atime/-ctime/-Btimeunits as Darwin/FreeBSD; days default
-w [+-] -newerwhen: after, before or at (r6); the sign may stand apart (r8)
-y file-samefilesame device and inode (r8; was -same, r6)
-0 / -1-true / -falsetrue, false (r8; were -true -false, r6)
-k mode-permoctal or symbolic, -/+ prefixes as find
-u -g name/id-user -group
-e-empty
-l [+-]N-links
-i N-inum
-z-prune
-x cmd {} ; / +-execdirargv exec in the entry's directory, never a shell
-j cmd {} ; / +-execplain exec from ff's cwd, full path in {}; race-exposed, documented as such (r2)
-delete-deletea long switch to confirm; see below
-q-exit/-quitstop walk
-v-lscksh-shape line: hex fields, awk-sortable

-delete (r2): spelled in full rather than a single letter so a one-keystroke typo cannot destroy data. Implies -D post-order, as find does. Removal is unlinkat(dirfd, name, 0 | AT_REMOVEDIR) against the already-verified parent dirfd --- the same race closure as -x: no path is re-resolved. An operand ending in .., or the root directory by device and inode, is refused whole, not walked, bit 4 (r8; before, only the node was refused and its contents were still deleted); . is walked and kept, as find does; non-empty dir failure = bit 4, walk continues. The bash translator maps it to native -delete (both dialects have it) after refusing the same operands itself.

Excluded phase 1: -ok, -fprint, -printf (GNU only anyway), -flags, -fstype.

Security posture

Exit status bitmask

bitmeaning
1invalid option or expression
2environment: memory, stdout failure, fd exhaustion
4cannot stat or open a node; subtree skipped
8exec child failed or returned nonzero
16symlink cycle under -L
32node changed during walk (dev/ino mismatch)

Darwin variations to weigh

Files

Phases

  1. --help manual text first --- the grammar's source of truth.
  2. Walker + -n -p -r -t -d -z, -E -I -H -L -D -S -X -Z, print.
  3. -s -m -a -c -b -w -k -u -g -e -l -i.
  4. -x and -j (; and +), -delete, -q, -v.
  5. bash translator + parity section.
  6. Darwin extras after first Darwin run.

Verification

make && make test under GNU make (gcc, clang, -fsanitize=address,undefined, root and non-root) on Linux here; bmake if installable; Darwin and NetBSD runs by you --- the README states which were actually exercised, as cksh does.

Implementation record (r3, first build)

Where the build departs from or fills a gap in the plan above:

Decisions log

Compatibility

Stated requirement (r10): the grammar is still settling toward a stable requirement set and build, and incompatible changes are accepted until then: -k to -mode (r9), -0 to -Z (r8), BRE to ERE and -E retired (r10). Once the stable release is declared, backward compatibility is maintained. The changes so far mostly fail loudly: -E and -0 before a path are usage errors (status 1), and an old -k mode argument is now read as a path that cannot be stat'ed (status 4). The BRE-to-ERE change is the one that can change meaning without any error, which is why the manual's REGULAR EXPRESSIONS section carries the BRE difference table.