diff options
| author | Soccera1 <[email protected]> | 2026-07-13 18:22:23 +1000 |
|---|---|---|
| committer | Soccera1 <[email protected]> | 2026-07-13 18:22:23 +1000 |
| commit | 6e2513d28da68283e795e2a04a7d68cb3af1cb7a (patch) | |
| tree | 0b84446aeaee691b2ea939873701dc9082374538 | |
| parent | 7ea75fb4424af8df393dd75dfb9b14a08aa46959 (diff) | |
| download | bnu-6e2513d28da68283e795e2a04a7d68cb3af1cb7a.tar.gz bnu-6e2513d28da68283e795e2a04a7d68cb3af1cb7a.zip | |
Make README better
| -rw-r--r-- | README.md | 274 |
1 files changed, 23 insertions, 251 deletions
@@ -193,254 +193,26 @@ GNU's native C code. ## Compatibility Notes -The test suite now covers recursive `cp`, copying into directory targets, -metadata preservation hooks, symbolic `chmod` mode clauses, signed and legacy -shorthand `head` and `tail` counts, zero-terminated `head` and `tail` records, -real FIFO creation through libc for -`mkfifo`/`mknod p` including octal and symbolic modes, and multi-call wrapper generation. On SELinux systems, -`mkdir`, `mkfifo`, and `mknod` apply validated explicit creation contexts with -`--context=CTX` and restore pathname defaults with `-Z`, including directories -created by `mkdir -p`. `cat` supports -numbering, blank squeezing, line end markers, tab markers, and common -nonprinting character display modes. Hash utilities support standard -checksum-file verification with `-c`/`--check`, `--status`, `--quiet`, -`--warn`, `--strict`, and `--ignore-missing`. `echo` -supports common GNU `-n`/`-e`/`-E`, long-option, POSIXLY_CORRECT, simple, octal, hex, escape, and `\c` forms. `basename` -supports suffix stripping, multiple-name mode, NUL-delimited output, and GNU -root and suffix edge cases; -`dirname` supports multiple names and NUL-delimited output, and both preserve -non-UTF-8 pathname bytes. `pwd` supports -physical output by default, logical `PWD` validation with `-L`, and operand -validation. Common option-parsed commands reject undeclared short and long options with GNU-style usage failures. `sort` covers -common GNU comparison modes including version, month, human numeric, -dictionary order, check variants, NUL-terminated records, and `-o` output. `ls` -covers hidden-file modes, -classification, recursive listing, size/time/extension/reverse sorting, -unsorted mode, basic color output, and POSIX ACL `+` mode indicators when -`getfacl` is available. Text ordering for both `sort` and `ls` follows the -active libc locale's collation rules, including non-UTF-8 command-line names; -C and POSIX locales retain bytewise ordering. `base32` and `base64` support -standalone RFC 4648 encoding/decoding, wrapping, and decode garbage handling. -`cat` streams ordinary file and special-device operands with bounded memory. -`cut` likewise streams bounded byte, character, and field selections from -special files, preserves invalid UTF-8 bytes, honors multibyte character -boundaries for `-b -n`, and follows libc-style multibyte blank classification. -`basenc` supports base16, base32, base32hex, base64, base64url, base2 MSB/LSB, -base58, z85, wrapping, strict decode garbage handling, and bounded-memory -streaming for the group-based encoders. -`cut` supports byte, character, delimiter, complement, output-delimiter, -NUL-terminated, and whitespace-delimited field modes, with interval-based -huge ranges and bounded-memory streaming for byte positions and safe field -selections. -`expand` and `unexpand` support explicit and repeating tab-stop forms and -bounded-memory conversion of stdin, files, and special devices while preserving -multibyte display-width and blank-run state across input chunks. -`fold` streams ordinary stdin, file, and special-device folding, distinguishes byte, character, and -display-column widths, and preserves zero-width characters without forcing -spurious line breaks. -Single-input `paste` preserves records through a bounded-memory stream, and -`od -v` incrementally formats ordinary and special files without accumulating -the complete input. -`comm` incrementally merges sorted non-regular inputs, `uniq` streams its -default and unseparated all-repeated modes, and negative-count `head` keeps -only the bounded byte or record tail needed for special devices. -From-start `tail` streams non-regular byte-record inputs directly, including -NUL-delimited device streams. -`factor` consumes non-regular standard input as a bounded token stream while -retaining batch optimization for regular-file input. -Checksum verification consumes non-regular checklist input line-by-line and -reports each verification result without waiting for end of input. -`join` streams selected unmatched records when the opposite input is known -empty, including NUL-delimited device input against `/dev/null`. -`wc` and `du` consume non-regular `--files0-from` sources one name at a time, -so FIFO and standard-input filename lists remain bounded even when unending. -`dircolors` supports shell output modes, database printing, and simple color -database files. -`cksum` supports the classic CRC form plus common digest algorithms through -`--algorithm`, including tagged, untagged, base64, and NUL-terminated output. -`sum` supports GNU's BSD and System V algorithms. `touch` supports explicit, -reference, access/modify-only, GNU `--time` aliases, and no-dereference -symlink timestamps. `factor` supports stdin and -argument factoring plus GNU exponent output. `expr` supports arithmetic, -comparisons, and common GNU string operations including length, substr, index, -and anchored regex matching. `id` supports current and named-user numeric and named user/group output -for primary and supplementary groups, NUL-delimited selected fields, and GNU-style choice validation; `groups` prints resolved primary and supplementary group names -when available and accepts username operands, and `logname` and `whoami` validate that no operands -are supplied. `users` accepts GNU's optional file operand. `who` supports simple heading, count, boot-time, `am i`, message-status, -short, users, and all-mode option forms. -Recursive `chmod -R` uses the same -numeric and symbolic mode parser as single-path `chmod`, including GNU -long-option abbreviation forms, and reports failed permission-changing syscalls -separately from pathname-access failures. `chown` and `chgrp` -cover common ownership/group changes, reference/from filters, recursive safety, -GNU `-H`/`-L`/`-P` symlink traversal semantics, inaccessible-directory -diagnostics, verbose failure records, and -GNU long-option abbreviation forms. `readlink` and `realpath` cover -common canonicalization, NUL delimiter, no-symlink, and relative-output modes. -`truncate` supports reference sizes, reference-relative size operators, -no-create mode, GNU byte suffixes, and common relative size operators. `tee` supports append, ignore-interrupts, and -output-error mode options. `cp`, `mv`, and `ln` -support GNU target-directory forms with `-t` and `-T`; all three accept GNU -long-option abbreviation forms, and `cp --parents` also -accepts the GNU-style `--parent` abbreviation; `mkdir` supports octal -and symbolic modes, `install` supports octal and symbolic `-m` modes for files -and directories; on SELinux systems it also preserves contexts with -`--preserve-context`, includes contexts in `-C` comparisons, restores default -labels with `-Z` (including `-D`/`-d` parents), and validates explicit -`--context=CTX` creation labels. `install -C` also compares the requested or -effective owner and group before deciding that an existing target can be left -unchanged. `rmdir` and `rm` cover common verbose, parent, -non-empty, interactive-mode, empty-directory removal, and GNU long-option -abbreviation modes. `cp --copy-contents` -copies FIFO contents when a writer supplies data during recursive copies, and -`cp -p` preserves POSIX ACLs when `getfacl` and `setfacl` are available. `cp` -and cross-filesystem `mv` preserve supported extended-attribute namespaces, -including attributes on symlinks; explicit `--preserve=xattr` reports restore -failures while archive and `--preserve=all` use GNU's best-effort behavior; -on an active SELinux system, `cp -a`, `--preserve=context`, `--context=CTX`, -and `-Z` respectively preserve, explicitly set, or restore destination security -contexts, with interposable libselinux `getfilecon` access and validation of -explicit labels. Missing optional source labels are ignored for archives while -an explicitly required context fails before copying. Context-preserving -`--parents` copies update both new and existing parent-directory labels; -explicitly required preservation fails before file data is written on a -fixed-context filesystem; and `-Z` creates with the source label before -restoring a pathname default, retaining that label when no default exists. -Directory creation uses a same-thread syscall while `setfscreatecon(3)` is -active, so Bun worker scheduling cannot silently lose explicit creation labels; -`cp --reflink=always|auto|never` attempts Linux native file cloning when the -filesystem supports it, and `cp --sparse=always|auto|never` controls sparse regular-file copying with -`SEEK_DATA`/`SEEK_HOLE` extent traversal and allocated-zero detection. -Cross-filesystem `mv` preserves sparse extents and recreates FIFO, device, and -socket nodes; failed source removal from sticky directories uses GNU's -operation-level diagnostic. With terminal input, `mv` also protects an -unwritable destination with GNU's default mode-aware prompt unless an effective -`-f` suppresses it. `cp` also retries destination creation when an interposed -`fstatat` reports a stale NFS entry that has disappeared before open. `link` and -`unlink` enforce fixed operand counts and support `--` for dash-prefixed names. -Capability xattrs are applied after final ownership changes, so -`cp --preserve=xattr` and `--preserve=all` retain Linux file capabilities. -Recursive `rm` traverses Linux directory streams incrementally, preserves raw -filename bytes, and distinguishes immediate read failures from partial traversal -failures. Noninteractive flat entries use a one-syscall unlink fast path with -metadata-aware fallback, keeping a 400,000-entry ext4 removal below GNU's -60-second performance gate. -`mktemp` supports files, directories, optional tmpdir/default temp placement, -explicit and implicit suffixes, suffix validation, and dry-run name generation. `dd` supports input/output block sizes, skip, count, seek, -byte-oriented flags, status modes, range-aware `nocache` input/output advice -that evicts through EOF only when EOF was reached, pre-copy seek -truncation with failure diagnostics, real seek-based stdin skipping and stdout -positioning (including block-device boundary validation), notrunc output writes, -and sparse output conversion. `split` -supports line, byte, line-byte, chunk-count, round-robin, -numeric, hex, configurable suffix starts, additional-suffix, and separator -modes, plus GNU-style operand validation. Fixed-number splitting of non-regular -input is disk-spooled through `$TMPDIR`, avoiding unbounded heap growth and -reporting storage exhaustion normally. `env` and `printenv` -support NUL-delimited output, and `env` handles empty environments, directory -changes, variable unsets, custom command argv0, and simple `-S` split strings. `sync` supports file -operands plus data and file-system mode flags. `df --sync` issues `sync(2)` -before its native filesystem query. `tail -f`/`-F` uses native inotify watches -for regular files and FIFOs, watches parent directories for name following, -removes stale watches across rotation, and falls back to blocking device reads -or polling when notification is unavailable or disabled; `--debug` reports the -selected strategy. Byte-count mode seeks relative to the true end of block -devices, including `-c +OFFSET`, without buffering the device. `stat` supports a -broader set of GNU file format escapes, `--printf`, and terse output. `du` -supports byte, block-size, human-readable, SI, apparent-size, total, and -NUL-terminated output modes, including GNU long-option abbreviations. During -concurrent directory moves it collapses stale descendants into one GNU-style -`fts_read failed` diagnostic and continues later operands. `df` -supports GNU block-size suffixes, human-readable/SI output, inode reporting, -local and file-system-type filtering, total row modes, over-mounted block-device -diagnostics, and byte-preserving non-UTF-8 mount names. `od` supports common -address, skip, limit, width, character, unsigned, and hex dump modes. `numfmt` -supports common scaling, table-field, header, delimiter, -padding, suffix, and invalid-value modes. `stdbuf` accepts input, output, and -error buffering mode options, including GNU long-option abbreviations, before running a command. `shuf` supports NUL records, repeat -mode, output files, deterministic random sources, and GNU operand/count validation. `shred` supports force, -verbose, exact, zero, remove, pass-count, and GNU long-option abbreviation modes. `uniq` supports common -counting, repeated, unique, field/character skipping, NUL-delimited, -all-repeated, group-delimiter, output-file, and operand-validation modes. `seq` handles fixed-point decimal -steps, negative operands with options, and common printf-style formatting. `printf` supports common numeric, -string, `%b`, `%q`, `\c` stop, Unicode escapes, and bounded streaming for very -large simple field widths. `sleep` and `timeout` support GNU -duration suffixes and fractional intervals; `timeout` also supports custom signals, preserve-status, -kill-after, disabled zero-duration timeouts, verbose signal diagnostics, default process-group -termination of descendants, `--foreground` PID-only behavior, and Linux parent-death signaling. -`nice` parses common -GNU adjustment forms before running a command. `nohup` preserves piped input, -makes commands immune to SIGHUP, implements terminal-only input/output/error -redirection and 0600 `nohup.out` creation, preserves command exit status, and -returns 127 for missing commands. `kill` supports signal -listing, signal table output, name/number conversion, and signal-zero checks. `date` supports more GNU format -escapes, padding/case flags, reference files, date files, debug diagnostics, -and real `--set` clock changes through `clock_settime(2)` when permitted. -`fmt` supports width shorthand, goal parsing, prefix-filtered formatting, -split-only mode, uniform spacing, and bounded paragraph formatting for -non-regular default input. `fold` supports byte, character, width, -and blank-aware wrapping modes. `tr` covers common POSIX character -classes, escaped characters, complement mode, deletion, translation, and repeat -squeezing. `tac` supports literal custom separators and before-separator mode; -non-seekable input is disk-spooled so an input failure does not prevent later -file operands from being processed. -`arch` and `hostid` expose platform identifiers with GNU-style operand -validation. `hostname` prints or attempts to set the system host name. `stty` supports -all-settings and saved-settings output modes, speed/size queries, real termios -setting forms, GNU fractional baud rounding and legacy speed aliases, C-style -numeric control values, and invalid-setting diagnostics. `tty` supports -silent/quiet status-only mode and GNU-style operand validation. `uname` supports common GNU -selectors including `-a`, `-s`, `-n`, `-r`, `-v`, `-m`, `-p`, `-i`, and `-o`. -`uptime` follows GNU coreutils' current-time, uptime, user-count, and load-average -format, with the standard optional utmp/wtmp file operand. -`nproc` supports `--all`, `--ignore`, OpenMP thread-limit environment -variables, cgroup v2 CPU quotas (including inherited quotas and scheduler -exceptions), and GNU-style operand and option diagnostics. -`nl` supports common body-selection, number-format, width, -separator, increment, starting-number, regex, and blank-grouping modes. `paste` -supports serial and parallel operation with custom escaped, column-cycled delimiters and -NUL-terminated records, including repeated stdin operands. `comm` supports custom output delimiters, totals, -NUL-terminated records, and sorted-order checking modes. `pinky` supports -simple short and long user records, including project/plan files and -left-to-right `-l`/`-s` mode selection. -`csplit` supports prefixes, digit widths, suffix formats, quiet mode, -empty-file elision, suppressed matched separators, regex offsets, and skip -patterns. `pr` supports omitted and custom page headers, line numbering, -custom first line numbers, margin indentation, and bounded-memory streaming -for default single-column pagination from stdin and special-file operands. `ptx` supports GNU-style -ignore-case option parsing, ignore/only word files, custom word and sentence -regexes, break-character files, automatic/manual references, and configurable -truncation markers. -`expr` preserves raw command-line bytes, applying character-aware length, -index, substring, and basic-regex behavior only in multibyte locales. -`ls -Z` and `stat %C` read SELinux contexts where the `security.selinux` -xattr is available, and long `ls` listings use GNU's `.` mode suffix for a -security context when no extended ACL takes precedence. Classification queries -regular-file mode bits without dereferencing symlink targets unnecessarily. -If a directory entry's metadata becomes inaccessible after `readdir`, `ls` -retains its kernel `d_type`, emits GNU's unknown-metadata row, and continues -with minor-error status (including accurate `--dired` offsets). -When `LS_COLORS` enables `ca=`, `ls` colors files carrying a -`security.capability` xattr using their full path; an empty `ca=` disables the -capability probe. -`chcon` supports explicit, reference, component, recursive, -and no-dereference context changes on SELinux-capable filesystems, and reports -failed full-context or partial-context operations on unlabeled files. -`cp`, `install`, and the file-creation commands support GNU context preservation, -explicit contexts, and default-policy restoration; `mv -Z`/`--context` restores -destination-policy labels after both renames and cross-filesystem moves. -`id -Z`/`--context` reports the current SELinux process label, and default `id` -output includes `context=...` outside POSIX mode. On newer stacked-LSM kernels, -the implementation uses `lsm_get_self_attr(2)` before legacy libselinux access. -`chroot` performs the real root switch, GNU `/` versus `--skip-chdir` handling, -command-status propagation, and user, primary-group, and supplementary-group -changes from named or forced-numeric specifications. -`runcon` prints the active process context, accepts complete contexts or GNU -compute/user/role/type/range forms, validates and computes transitions through -libselinux, and applies the requested exec label through legacy or modern LSM -interfaces before dispatching the command. -`yes` repeats the default `y` line or joined operand strings. -`test` and `[` support common file predicates, -read/write/execute checks, string and numeric comparisons, and file identity -and timestamp comparisons. `pathchk` supports GNU portability checks with -`-p`/`--portability` and leading-hyphen/empty-component checks with `-P`. +BNU targets command-line compatibility with GNU coreutils 9.11 for the +commands listed above. It is an independent JavaScript implementation, so +compatibility applies to observable command behavior rather than GNU internals +or binary interfaces. Passing the upstream command-test inventory does not +guarantee that every option combination, platform, locale, or filesystem +behaves identically. + +Some behavior depends on the host: + +- ACLs, extended attributes, security contexts, reflinks, sparse files, inotify, + device nodes, and similar features require corresponding operating-system and + filesystem support. +- Ownership changes, `chroot`, clock changes, device creation, and security-label + operations may require elevated privileges. +- Sorting, character handling, user and group lookup, terminal behavior, and + diagnostics can vary with the active locale and system configuration. +- Six upstream tests cannot start BNU because of Bun runtime or target-ABI + constraints. They are documented in + [`docs/gnu-test-boundaries.md`](docs/gnu-test-boundaries.md). + +Use `bnu COMMAND --help` for the options exposed by a command. The local and +upstream test suites provide the most precise record of currently verified +behavior. |
