From 880be39a5842f9a4685f2f56982920ca00786681 Mon Sep 17 00:00:00 2001 From: Christopher Wellons Date: Tue, 20 Oct 2026 06:33:28 -0400 Subject: [PATCH] Add manual pages for the BusyBox applets A page for each applet in the kit, plus .so stubs for aliases such as egrep and unxz. Each was written from the pinned busybox-w32 source with the kit's patches and configuration, then checked against the source and by experiment. The NOTES sections cover Windows behavior. Co-Authored-By: Claude Opus 5.5 --- man/man1/[.1 | 1 + man/man1/[[.1 | 1 + man/man1/arch.1 | 88 ++ man/man1/ash.1 | 1 + man/man1/awk.1 | 1418 +++++++++++++++++++++++++++++++ man/man1/base32.1 | 186 +++++ man/man1/base64.1 | 203 +++++ man/man1/basename.1 | 299 +++++++ man/man1/bc.1 | 857 +++++++++++++++++++ man/man1/bunzip2.1 | 1 + man/man1/busybox.1 | 930 +++++++++++++++++++++ man/man1/bzcat.1 | 1 + man/man1/bzip2.1 | 377 +++++++++ man/man1/cal.1 | 205 +++++ man/man1/cat.1 | 299 +++++++ man/man1/chattr.1 | 251 ++++++ man/man1/chmod.1 | 367 ++++++++ man/man1/cksum.1 | 185 +++++ man/man1/clear.1 | 177 ++++ man/man1/cmp.1 | 284 +++++++ man/man1/comm.1 | 211 +++++ man/man1/cp.1 | 574 +++++++++++++ man/man1/cpio.1 | 671 +++++++++++++++ man/man1/crc32.1 | 171 ++++ man/man1/cut.1 | 571 +++++++++++++ man/man1/date.1 | 871 +++++++++++++++++++ man/man1/dc.1 | 945 +++++++++++++++++++++ man/man1/dd.1 | 580 +++++++++++++ man/man1/df.1 | 409 +++++++++ man/man1/diff.1 | 566 +++++++++++++ man/man1/dirname.1 | 253 ++++++ man/man1/dos2unix.1 | 208 +++++ man/man1/du.1 | 411 +++++++++ man/man1/echo.1 | 340 ++++++++ man/man1/ed.1 | 667 +++++++++++++++ man/man1/egrep.1 | 1 + man/man1/env.1 | 383 +++++++++ man/man1/expand.1 | 216 +++++ man/man1/expr.1 | 586 +++++++++++++ man/man1/factor.1 | 175 ++++ man/man1/false.1 | 97 +++ man/man1/fgrep.1 | 1 + man/man1/find.1 | 939 +++++++++++++++++++++ man/man1/fold.1 | 291 +++++++ man/man1/free.1 | 255 ++++++ man/man1/fsync.1 | 202 +++++ man/man1/getopt.1 | 457 ++++++++++ man/man1/grep.1 | 580 +++++++++++++ man/man1/groups.1 | 251 ++++++ man/man1/hd.1 | 1 + man/man1/head.1 | 365 ++++++++ man/man1/hexdump.1 | 479 +++++++++++ man/man1/httpd.1 | 966 ++++++++++++++++++++++ man/man1/iconv.1 | 503 +++++++++++ man/man1/id.1 | 259 ++++++ man/man1/inotifyd.1 | 389 +++++++++ man/man1/install.1 | 488 +++++++++++ man/man1/ipcalc.1 | 314 +++++++ man/man1/jn.1 | 275 ++++++ man/man1/join.1 | 422 ++++++++++ man/man1/kill.1 | 371 +++++++++ man/man1/killall.1 | 435 ++++++++++ man/man1/lash.1 | 1 + man/man1/less.1 | 680 +++++++++++++++ man/man1/ln.1 | 444 ++++++++++ man/man1/logname.1 | 170 ++++ man/man1/ls.1 | 805 ++++++++++++++++++ man/man1/lsattr.1 | 343 ++++++++ man/man1/lzcat.1 | 1 + man/man1/lzma.1 | 322 ++++++++ man/man1/lzop.1 | 305 +++++++ man/man1/lzopcat.1 | 1 + man/man1/man.1 | 520 ++++++++++++ man/man1/md5sum.1 | 419 ++++++++++ man/man1/mkdir.1 | 368 +++++++++ man/man1/mktemp.1 | 358 ++++++++ man/man1/mv.1 | 407 +++++++++ man/man1/nc.1 | 318 +++++++ man/man1/nl.1 | 328 ++++++++ man/man1/nproc.1 | 131 +++ man/man1/od.1 | 671 +++++++++++++++ man/man1/paste.1 | 335 ++++++++ man/man1/patch.1 | 513 ++++++++++++ man/man1/pgrep.1 | 376 +++++++++ man/man1/pidof.1 | 323 ++++++++ man/man1/pipe_progress.1 | 123 +++ man/man1/pkill.1 | 1 + man/man1/printenv.1 | 240 ++++++ man/man1/printf.1 | 690 ++++++++++++++++ man/man1/ps.1 | 419 ++++++++++ man/man1/pwd.1 | 257 ++++++ man/man1/readlink.1 | 344 ++++++++ man/man1/realpath.1 | 330 ++++++++ man/man1/reset.1 | 240 ++++++ man/man1/rev.1 | 208 +++++ man/man1/rm.1 | 394 +++++++++ man/man1/rmdir.1 | 326 ++++++++ man/man1/sed.1 | 1088 ++++++++++++++++++++++++ man/man1/seq.1 | 336 ++++++++ man/man1/sh.1 | 1698 ++++++++++++++++++++++++++++++++++++++ man/man1/sha1sum.1 | 1 + man/man1/sha256sum.1 | 1 + man/man1/sha3sum.1 | 1 + man/man1/sha512sum.1 | 1 + man/man1/shred.1 | 268 ++++++ man/man1/shuf.1 | 366 ++++++++ man/man1/sleep.1 | 245 ++++++ man/man1/sort.1 | 585 +++++++++++++ man/man1/split.1 | 386 +++++++++ man/man1/ssl_client.1 | 272 ++++++ man/man1/stat.1 | 796 ++++++++++++++++++ man/man1/su.1 | 406 +++++++++ man/man1/sum.1 | 224 +++++ man/man1/sync.1 | 108 +++ man/man1/tac.1 | 237 ++++++ man/man1/tail.1 | 568 +++++++++++++ man/man1/tar.1 | 972 ++++++++++++++++++++++ man/man1/tee.1 | 284 +++++++ man/man1/test.1 | 691 ++++++++++++++++ man/man1/time.1 | 470 +++++++++++ man/man1/timeout.1 | 507 ++++++++++++ man/man1/touch.1 | 509 ++++++++++++ man/man1/tr.1 | 422 ++++++++++ man/man1/true.1 | 122 +++ man/man1/truncate.1 | 357 ++++++++ man/man1/ts.1 | 517 ++++++++++++ man/man1/ttysize.1 | 154 ++++ man/man1/uname.1 | 225 +++++ man/man1/uncompress.1 | 273 ++++++ man/man1/unexpand.1 | 284 +++++++ man/man1/uniq.1 | 352 ++++++++ man/man1/unix2dos.1 | 1 + man/man1/unlzma.1 | 1 + man/man1/unlzop.1 | 1 + man/man1/unxz.1 | 1 + man/man1/uptime.1 | 210 +++++ man/man1/usleep.1 | 142 ++++ man/man1/uudecode.1 | 259 ++++++ man/man1/uuencode.1 | 253 ++++++ man/man1/watch.1 | 407 +++++++++ man/man1/wc.1 | 328 ++++++++ man/man1/wget.1 | 801 ++++++++++++++++++ man/man1/which.1 | 363 ++++++++ man/man1/whoami.1 | 212 +++++ man/man1/whois.1 | 347 ++++++++ man/man1/xargs.1 | 693 ++++++++++++++++ man/man1/xz.1 | 300 +++++++ man/man1/xzcat.1 | 1 + man/man1/yes.1 | 245 ++++++ 149 files changed, 53282 insertions(+) create mode 100644 man/man1/[.1 create mode 100644 man/man1/[[.1 create mode 100644 man/man1/arch.1 create mode 100644 man/man1/ash.1 create mode 100644 man/man1/awk.1 create mode 100644 man/man1/base32.1 create mode 100644 man/man1/base64.1 create mode 100644 man/man1/basename.1 create mode 100644 man/man1/bc.1 create mode 100644 man/man1/bunzip2.1 create mode 100644 man/man1/busybox.1 create mode 100644 man/man1/bzcat.1 create mode 100644 man/man1/bzip2.1 create mode 100644 man/man1/cal.1 create mode 100644 man/man1/cat.1 create mode 100644 man/man1/chattr.1 create mode 100644 man/man1/chmod.1 create mode 100644 man/man1/cksum.1 create mode 100644 man/man1/clear.1 create mode 100644 man/man1/cmp.1 create mode 100644 man/man1/comm.1 create mode 100644 man/man1/cp.1 create mode 100644 man/man1/cpio.1 create mode 100644 man/man1/crc32.1 create mode 100644 man/man1/cut.1 create mode 100644 man/man1/date.1 create mode 100644 man/man1/dc.1 create mode 100644 man/man1/dd.1 create mode 100644 man/man1/df.1 create mode 100644 man/man1/diff.1 create mode 100644 man/man1/dirname.1 create mode 100644 man/man1/dos2unix.1 create mode 100644 man/man1/du.1 create mode 100644 man/man1/echo.1 create mode 100644 man/man1/ed.1 create mode 100644 man/man1/egrep.1 create mode 100644 man/man1/env.1 create mode 100644 man/man1/expand.1 create mode 100644 man/man1/expr.1 create mode 100644 man/man1/factor.1 create mode 100644 man/man1/false.1 create mode 100644 man/man1/fgrep.1 create mode 100644 man/man1/find.1 create mode 100644 man/man1/fold.1 create mode 100644 man/man1/free.1 create mode 100644 man/man1/fsync.1 create mode 100644 man/man1/getopt.1 create mode 100644 man/man1/grep.1 create mode 100644 man/man1/groups.1 create mode 100644 man/man1/hd.1 create mode 100644 man/man1/head.1 create mode 100644 man/man1/hexdump.1 create mode 100644 man/man1/httpd.1 create mode 100644 man/man1/iconv.1 create mode 100644 man/man1/id.1 create mode 100644 man/man1/inotifyd.1 create mode 100644 man/man1/install.1 create mode 100644 man/man1/ipcalc.1 create mode 100644 man/man1/jn.1 create mode 100644 man/man1/join.1 create mode 100644 man/man1/kill.1 create mode 100644 man/man1/killall.1 create mode 100644 man/man1/lash.1 create mode 100644 man/man1/less.1 create mode 100644 man/man1/ln.1 create mode 100644 man/man1/logname.1 create mode 100644 man/man1/ls.1 create mode 100644 man/man1/lsattr.1 create mode 100644 man/man1/lzcat.1 create mode 100644 man/man1/lzma.1 create mode 100644 man/man1/lzop.1 create mode 100644 man/man1/lzopcat.1 create mode 100644 man/man1/man.1 create mode 100644 man/man1/md5sum.1 create mode 100644 man/man1/mkdir.1 create mode 100644 man/man1/mktemp.1 create mode 100644 man/man1/mv.1 create mode 100644 man/man1/nc.1 create mode 100644 man/man1/nl.1 create mode 100644 man/man1/nproc.1 create mode 100644 man/man1/od.1 create mode 100644 man/man1/paste.1 create mode 100644 man/man1/patch.1 create mode 100644 man/man1/pgrep.1 create mode 100644 man/man1/pidof.1 create mode 100644 man/man1/pipe_progress.1 create mode 100644 man/man1/pkill.1 create mode 100644 man/man1/printenv.1 create mode 100644 man/man1/printf.1 create mode 100644 man/man1/ps.1 create mode 100644 man/man1/pwd.1 create mode 100644 man/man1/readlink.1 create mode 100644 man/man1/realpath.1 create mode 100644 man/man1/reset.1 create mode 100644 man/man1/rev.1 create mode 100644 man/man1/rm.1 create mode 100644 man/man1/rmdir.1 create mode 100644 man/man1/sed.1 create mode 100644 man/man1/seq.1 create mode 100644 man/man1/sh.1 create mode 100644 man/man1/sha1sum.1 create mode 100644 man/man1/sha256sum.1 create mode 100644 man/man1/sha3sum.1 create mode 100644 man/man1/sha512sum.1 create mode 100644 man/man1/shred.1 create mode 100644 man/man1/shuf.1 create mode 100644 man/man1/sleep.1 create mode 100644 man/man1/sort.1 create mode 100644 man/man1/split.1 create mode 100644 man/man1/ssl_client.1 create mode 100644 man/man1/stat.1 create mode 100644 man/man1/su.1 create mode 100644 man/man1/sum.1 create mode 100644 man/man1/sync.1 create mode 100644 man/man1/tac.1 create mode 100644 man/man1/tail.1 create mode 100644 man/man1/tar.1 create mode 100644 man/man1/tee.1 create mode 100644 man/man1/test.1 create mode 100644 man/man1/time.1 create mode 100644 man/man1/timeout.1 create mode 100644 man/man1/touch.1 create mode 100644 man/man1/tr.1 create mode 100644 man/man1/true.1 create mode 100644 man/man1/truncate.1 create mode 100644 man/man1/ts.1 create mode 100644 man/man1/ttysize.1 create mode 100644 man/man1/uname.1 create mode 100644 man/man1/uncompress.1 create mode 100644 man/man1/unexpand.1 create mode 100644 man/man1/uniq.1 create mode 100644 man/man1/unix2dos.1 create mode 100644 man/man1/unlzma.1 create mode 100644 man/man1/unlzop.1 create mode 100644 man/man1/unxz.1 create mode 100644 man/man1/uptime.1 create mode 100644 man/man1/usleep.1 create mode 100644 man/man1/uudecode.1 create mode 100644 man/man1/uuencode.1 create mode 100644 man/man1/watch.1 create mode 100644 man/man1/wc.1 create mode 100644 man/man1/wget.1 create mode 100644 man/man1/which.1 create mode 100644 man/man1/whoami.1 create mode 100644 man/man1/whois.1 create mode 100644 man/man1/xargs.1 create mode 100644 man/man1/xz.1 create mode 100644 man/man1/xzcat.1 create mode 100644 man/man1/yes.1 diff --git a/man/man1/[.1 b/man/man1/[.1 new file mode 100644 index 0000000..84e0568 --- /dev/null +++ b/man/man1/[.1 @@ -0,0 +1 @@ +.so man1/test.1 diff --git a/man/man1/[[.1 b/man/man1/[[.1 new file mode 100644 index 0000000..84e0568 --- /dev/null +++ b/man/man1/[[.1 @@ -0,0 +1 @@ +.so man1/test.1 diff --git a/man/man1/arch.1 b/man/man1/arch.1 new file mode 100644 index 0000000..7bef9de --- /dev/null +++ b/man/man1/arch.1 @@ -0,0 +1,88 @@ +.TH ARCH 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +arch \- print the processor architecture +.SH SYNOPSIS +.B arch +.RB [ \-\-help ] +.SH DESCRIPTION +.B arch +prints the name of the processor architecture that busybox runs as, +followed by a newline, on standard output. +It is the same as +.BR "uname\ \-m" . +The 64-bit kit prints +.BR x86_64 , +and the 32-bit kit prints +.BR i686 . +.PP +The name comes from the Windows +.B GetSystemInfo +function, which reports the architecture of the calling process, not the +machine's native one. +So on 64-bit Windows the 32-bit kit, which runs under WOW64, prints +.BR i686 , +and on ARM64 Windows the 64-bit kit, which runs under x64 emulation, +prints +.BR x86_64 . +.SH OPTIONS +.B arch +has one option, and ignores its arguments, including unknown options and +operands, unless the first is +.BR \-\-help . +.TP +.B \-\-help +When it is the first argument, print a usage message on standard output +and exit with status 0, ignoring the other arguments. +In any other position it is ignored. +.SH ENVIRONMENT +.B arch +reads no environment variables of its own. +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Standard output could not be written, as when it is closed or is a pipe +whose reader has exited. +A message is printed on standard error. +.SH EXAMPLES +Print the architecture: +.PP +.RS 4 +.EX +$ arch +x86_64 +.EE +.RE +.PP +Create a build directory named after the architecture: +.PP +.RS 4 +.EX +$ mkdir \-p build/$(arch) +.EE +.RE +.SH NOTES +Unlike GNU +.BR arch , +it has no +.B \-\-version +option, and it ignores operands and unknown options instead of rejecting +them. +.PP +The output line ends with LF, not CRLF. +.PP +The kit's +.B sh +runs +.B arch +inside the shell process, without starting a new one, except where the +shell needs a separate process anyway, as for a command substitution or +a pipeline. +.SH SEE ALSO +.BR busybox (1), +.BR sh (1), +.BR uname (1) diff --git a/man/man1/ash.1 b/man/man1/ash.1 new file mode 100644 index 0000000..ddc511e --- /dev/null +++ b/man/man1/ash.1 @@ -0,0 +1 @@ +.so man1/sh.1 diff --git a/man/man1/awk.1 b/man/man1/awk.1 new file mode 100644 index 0000000..1c8be79 --- /dev/null +++ b/man/man1/awk.1 @@ -0,0 +1,1418 @@ +.TH AWK 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +awk \- pattern scanning and text processing language +.SH SYNOPSIS +.B awk +.RB [ \-F +.IR fs ] +.RB [ \-v +\fIvar\fB=\fIvalue\fR]...\& +.I program +.RI [ operand ...] +.br +.B awk +.RB [ \-F +.IR fs ] +.RB [ \-v +\fIvar\fB=\fIvalue\fR]...\& +.RB { \-f +.I progfile +.RB "| " \-e +.IR text }...\& +.RI [ operand ...] +.br +.B awk +.RB [ \-F +.IR fs ] +.RB [ \-v +\fIvar\fB=\fIvalue\fR]...\& +.B \-E +.I progfile +.RI [ file ...] +.SH DESCRIPTION +.B awk +reads text as a sequence of records, normally lines, splits each record +into fields, and runs a program of pattern-action rules on each record. +This is the busybox +.BR awk , +which implements the POSIX language with some gawk extensions. +.PP +The program is the first operand, unless it comes from +.BR \-f , +.BR \-e , +or +.BR \-E . +Each remaining operand of the form +\fIvar\fB=\fIvalue\fR, +where +.I var +is a variable name, assigns +.I value +to +.I var +when +.B awk +reaches it in the list of operands, after the +.B BEGIN +rules have run. +Any other operand names an input file, and the files are read in order. +An operand of +.BR \- , +or the absence of file operands, means standard input. +Output goes to standard output unless redirected. +.SS Program structure +A program is a sequence of rules and function definitions: +.PP +.RS 4 +.EX +\fIpattern\fR { \fIstatements\fR } +function \fIname\fR(\fIparameter\fR, ...) { \fIstatements\fR } +.EE +.RE +.PP +For each record, +.B awk +runs the statements of every rule whose pattern matches, in program +order. +A rule without a pattern matches every record, and a pattern without an +action prints the record. +The patterns are: +.TP +.B BEGIN +Matches once, before any input is read. +A program with only +.B BEGIN +rules exits after running them, without reading input. +.TP +.B END +Matches once, after the input is exhausted or an +.B exit +statement runs. +.BR $0 , +.BR NF , +and +.B NR +keep their values from the last record. +.TP +.I expression +Matches when the expression is true: a nonzero number, or a non-empty +string. +A regular expression constant alone, as in +.BR /x/ , +means +.BR "$0 ~ /x/" . +.TP +\fIpattern1\fB, \fIpattern2\fR +Matches every record from one that matches +.I pattern1 +through the next that matches +.IR pattern2 , +inclusive, and then starts looking for +.I pattern1 +again. +.PP +There may be several +.B BEGIN +and +.B END +rules, run in program order, and each needs its opening brace on the same +line. +.PP +Statements are separated by newlines or semicolons and grouped with +braces. +A newline may also follow a comma, a brace, a semicolon, or a binary +operator such as +.BR && . +A backslash at the end of a line joins it to the next, and +.B # +starts a comment that runs to the end of the line. +.PP +.B func +is a synonym for +.BR function . +Parameters are local to the function. +A caller may pass fewer arguments than there are parameters, and the +rest serve as local variables. +Scalars are passed by value and arrays by reference. +In a call, the +.B ( +must follow the name immediately. +Functions may be recursive and may be called before their definition. +.SS Values +Every value is a string or a double-precision number, and is converted +as needed. +An uninitialized variable is both 0 and the empty string. +.PP +Numeric constants are decimal, with an optional fraction and exponent, +hexadecimal with a +.B 0x +prefix, or octal with a leading 0. +Octal applies only to constants in the program. +.PP +String constants are enclosed in double quotes and recognize the escapes +.BR \e\(dq , +.BR \e\e , +.BR \e/ , +.BR \ea , +.BR \eb , +.BR \ee , +.BR \ef , +.BR \en , +.BR \er , +.BR \et , +.BR \ev , +.B \e +followed by 1 to 3 octal digits, and +.B \ex +followed by 1 or 2 hex digits. +A backslash before any other character is dropped. +The same escapes apply to the values of +.B \-v +and operand assignments, and to the argument of +.BR \-F . +.PP +Fields, the values read by +.BR getline , +the elements of +.B ARGV +and +.B ENVIRON +and of arrays made by +.BR split , +and values assigned on the command line are strings, and each one that +looks like a number, ignoring leading and trailing blanks, is also +numeric. +Two values compare as numbers when both are numeric, and otherwise as +strings, byte by byte. +A string used as a number takes the value of its longest numeric prefix, +so +.B \(dq12abc\(dq +is 12 and +.B \(dqabc\(dq +is 0. +.PP +A number with an integer value from \-2^63 up to, but not including, 2^63 +converts to a string as an integer. +Other numbers convert with the format in +.BR CONVFMT , +or in +.B OFMT +when written by +.BR print . +.PP +Arrays are associative and indexed by strings. +The subscript +.B a[i, j] +is +.I i +and +.I j +joined by +.BR SUBSEP . +.SS Expressions +The operators, from highest to lowest precedence: +.TP +.BI ( expr ) +Grouping. +.TP +.BI $ expr +Field reference. +.TP +.BR ++ " " \-\- +Increment and decrement, as a prefix or postfix. +.TP +.BR ^ " " ** +Exponentiation. +.TP +.BR ! " " + " " \- +Logical not, unary plus, and negation. +.TP +.BR * " " / " " % +Multiplication, division, and remainder. +The remainder has the sign of the dividend, and division or remainder by +zero is a fatal error. +.TP +.BR + " " \- +Addition and subtraction. +.TP +.I "expr expr" +String concatenation. +.TP +.BR < " " <= " " != " " == " " > " " >= +Comparison, giving 1 or 0. +.TP +.BR ~ " " !~ +Regular expression match and non-match. +The right operand is a regular expression. +.TP +.B in +.IB subscript " in " array +is 1 if +.I array +has an element with that subscript, without creating one. +A parenthesized list, as in +.BR "(i, j) in a" , +is a multiple subscript. +.TP +.B && +Logical and, evaluating its right operand only when needed. +.TP +.B || +Logical or, likewise. +.TP +.B ?: +Conditional. +.TP +.BR = " " += " " \-= " " *= " " /= " " %= " " ^= " " **= +Assignment, grouping right to left. +.PP +Binary operators other than assignment group left to right. +.SS Regular expressions +Regular expressions are POSIX extended regular expressions, with the GNU +operators +.B \e< +and +.B \e> +for the start and end of a word, +.B \eb +for a word boundary, +.B \eB +for a position that is not a word boundary, +.B \ew +and +.B \eW +for word and non-word characters, +.B \es +and +.B \eS +for space and non-space characters, and +.B \e\(ga +and +.B \e\(aq +for the start and end of the string. +.PP +A regular expression constant is written between slashes. +The escapes of string constants are processed in it, except that a +backslash before any other character is kept, so +.B \e.\& +matches a period and +.B \e/ +a slash. +In a constant, +.B \eb +is a backspace. +.PP +Where a regular expression is expected, any other expression is +converted to a string and compiled as a dynamic regular expression. +In a string constant, the backslashes must be doubled, as in +.BR \(dq\e\e.\(dq . +A string that is not a valid extended regular expression is compiled as +a basic regular expression. +.PP +While +.B IGNORECASE +is true, matching ignores the case of ASCII letters. +.SS Records and fields +Records are separated by +.BR RS : +.IP \(bu 2 +A single character, newline by default, separates records. +.IP \(bu 2 +An empty string separates records at one or more blank lines, and makes +newline a field separator in addition to a single-character or regular +expression +.BR FS . +With a regular expression, +.B NF +is then wrong; see +.BR NOTES . +Leading newlines in the input are skipped. +.IP \(bu 2 +A longer string is a regular expression. +.PP +Each record is +.BR $0 , +and is split into the fields +.BR $1 , +.BR $2 , +\&... through +.BI $ NF +by +.BR FS : +.IP \(bu 2 +A single space, the default, separates fields at runs of spaces, tabs, +and newlines, and ignores those at the start and end. +.IP \(bu 2 +Any other single character separates fields literally, even one special +in regular expressions, such as +.BR | . +While +.B IGNORECASE +is true, a letter matches either case. +.IP \(bu 2 +An empty string makes each byte a field. +.IP \(bu 2 +A longer string is a regular expression. +.PP +An assignment to +.B FS +applies from the next record. +A reference to a field beyond +.B NF +gives the empty string. +Assigning to a field, or to +.BR NF , +rebuilds +.B $0 +from the fields joined by +.BR OFS , +and assigning to a field beyond +.B NF +first adds empty fields. +Assigning to +.B $0 +splits it again. +A negative field number or +.B NF +is a fatal error. +.SS Statements +.TP +\fBif (\fIcondition\fB) \fIstatement\fR [\fBelse \fIstatement\fR] +Run the first +.I statement +if +.I condition +is true, and otherwise the second, if any. +.TP +\fBwhile (\fIcondition\fB) \fIstatement\fR +Run +.I statement +while +.I condition +is true. +.TP +\fBdo \fIstatement \fBwhile (\fIcondition\fB)\fR +Run +.IR statement , +then repeat while +.I condition +is true. +.TP +\fBfor (\fIinit\fB; \fIcondition\fB; \fIstep\fB) \fIstatement\fR +Evaluate +.IR init , +then run +.I statement +and evaluate +.I step +while +.I condition +is true. +Each of the three expressions may be empty, and an empty +.I condition +is true. +.TP +\fBfor (\fIvar \fBin \fIarray\fB) \fIstatement\fR +Run +.I statement +with +.I var +set to each subscript that +.I array +has when the loop starts, in no particular order. +.TP +.BR break ", " continue +Leave the innermost loop, or start its next iteration. +.TP +.B next +Stop processing the current record and read the next. +.TP +.B nextfile +Stop processing the current input file and go on to the next. +.TP +\fBexit\fR [\fIexpr\fR] +Run the +.B END +rules, then exit with status +.IR expr , +or with the status of an earlier +.BR exit , +or 0. +In an +.B END +rule, exit immediately. +.TP +\fBreturn\fR [\fIexpr\fR] +Return from a function with the value of +.IR expr , +or with the empty string, which does not compare equal to 0. +A function that ends without +.B return +also returns the empty string. +.TP +\fBdelete \fIarray\fB[\fIsubscript\fB]\fR +Remove an element. +Without a subscript, +.BI delete " array" +removes them all. +.TP +\fBprint\fR [\fIexpr\fR, ...] [\fIredirection\fR] +Write the values separated by +.B OFS +and followed by +.BR ORS , +or +.B $0 +when there are none. +Numbers are written as described under +.BR Values . +.TP +\fBprintf \fIformat\fR[, \fIexpr\fR, ...] [\fIredirection\fR] +Write the values formatted by +.I format +as described under +.BR Formats . +.PP +An expression may also be a statement, and braces group statements into +one. +The values of +.B print +and +.B printf +may be enclosed in parentheses, and outside parentheses a +.B > +is a redirection: +.TP +.BI > " file" +Write to +.IR file , +truncating it when it is first opened. +It stays open, so later output to it follows. +.TP +.BI >> " file" +Append to +.IR file . +.TP +.BI | " command" +Write to the standard input of +.IR command , +which runs in +.BR "sh\ \-c" . +.PP +Each distinct +.I file +or +.I command +is opened once and stays open until closed with +.BR close . +At exit, +.B awk +closes every pipe and waits for its command. +The names +.BR /dev/stdin , +.BR /dev/stdout , +and +.B /dev/stderr +refer to the standard streams. +.SS Input +.B getline +reads one record at a time, from the main input or from a file or +command named in the expression: +.TP +.B getline +Read the next record of the main input into +.BR $0 , +and set +.BR NF , +.BR NR , +.BR FNR , +and +.BR RT . +.TP +.BI "getline " var +Read the next record of the main input into +.IR var , +and set +.BR NR , +.BR FNR , +and +.BR RT . +.TP +.BI "getline < " file +Read the next record of +.I file +into +.BR $0 , +and set +.B NF +and +.BR RT . +.TP +.BI "getline " var " < " file +Read the next record of +.I file +into +.IR var , +and set +.BR RT . +.TP +.IB command " | getline" +Read the next record of the output of +.IR command , +which runs in +.BR "sh\ \-c" , +into +.BR $0 , +and set +.B NF +and +.BR RT . +.TP +.IB command " | getline " var +Read the next record of the output of +.I command +into +.IR var , +and set +.BR RT . +.PP +.B getline +returns 1 after reading a record, 0 at the end of the input, and \-1 if +.I file +cannot be opened or read, setting +.BR ERRNO . +A file or command stays open, and successive calls read successive +records, until it is closed with +.BR close . +.SS Formats +.B printf +and +.B sprintf +copy their format to the output, replacing each conversion specification +with the next value. +A specification is a +.BR % , +optional flags +.BR \- , +.BR + , +space, +.BR # , +and +.BR 0 , +an optional width, an optional precision after a period, and a +conversion character: +.TP +.B c +A number as the byte with that value, modulo 256, or the first byte of +a string. +.TP +.BR d ", " i ", " o ", " u ", " x ", " X +The value converted to a 32-bit +.BR int , +in decimal, octal, unsigned decimal, or hexadecimal. +.TP +.BR e ", " E ", " f ", " F ", " g ", " G ", " a ", " A +The value as a floating-point number, as in C, except that +.B F +prints nothing. +.TP +.B s +The value as a string. +.TP +.B % +A literal +.BR % , +consuming no value. +.PP +A missing value is the empty string or 0. +Any other letter ends the specification, which is written unchanged and +still consumes a value, so length modifiers such as +.B l +are not supported. +A width or precision of +.B * +is a fatal error. +.SS Functions +Arithmetic: +.TP +.BI atan2( y ", " x ) +The arctangent of +.IR y / x +in radians, from \-pi to pi. +.TP +\fBcos(\fIx\fB)\fR, \fBsin(\fIx\fB)\fR +The cosine and sine of +.I x +radians. +.TP +\fBexp(\fIx\fB)\fR, \fBlog(\fIx\fB)\fR +The exponential and natural logarithm. +.TP +.BI int( x ) +.I x +truncated toward zero. +.TP +.B rand() +A random number from 0 up to, but not including, 1. +The sequence is the same in every run until +.B srand +is called. +.TP +.BI sqrt( x ) +The square root. +.TP +\fBsrand(\fR[\fIx\fR]\fB)\fR +Seed +.B rand +with +.IR x , +or with the current time in seconds, and return the previous seed, +initially 1. +.PP +Strings: +.TP +\fBgensub(\fIr\fB, \fIs\fB, \fIh\fR [\fB, \fIt\fR]\fB)\fR +Return a copy of +.IR t , +or of +.BR $0 , +in which matches of the regular expression +.I r +are replaced by +.IR s ; +.I t +is not changed. +If +.I h +is a positive number, only match number +.I h +is replaced, and otherwise, as with +.BR \(dqg\(dq , +every match. +In +.IR s , +.B & +and +.B \e0 +stand for the matched text, +.B \e1 +through +.B \e9 +for the text matched by that parenthesized subexpression, and +.B \e& +for a literal +.BR & . +.TP +\fBgsub(\fIr\fB, \fIs\fR [\fB, \fIt\fR]\fB)\fR +Replace every match of +.I r +in the variable, field, or element +.IR t , +or in +.BR $0 , +by +.IR s , +and return the number of replacements. +In +.IR s , +.B & +stands for the matched text, +.B \e& +for a literal +.BR & , +and +.B \e\e +for a backslash. +.TP +.BI index( s ", " t ) +The position of the first occurrence of +.I t +in +.IR s , +counting from 1, or 0 if there is none or +.I t +is empty. +.TP +\fBlength\fR[\fB(\fIs\fB)\fR] +The length of +.IR s , +or of +.B $0 +without an argument. +For an array, the number of elements. +.TP +.BI match( s ", " r ) +The position of the leftmost longest match of +.I r +in +.IR s , +or 0. +Set +.B RSTART +to the position and +.B RLENGTH +to the length of the match, or \-1. +.TP +\fBsplit(\fIs\fB, \fIa\fR [\fB, \fIfs\fR]\fB)\fR +Delete the elements of array +.IR a , +split +.I s +into +\fIa\fB[1]\fR +through +\fIa\fB[\fIn\fB]\fR +by +.IR fs , +or by +.BR FS , +and return +.IR n . +.I fs +is interpreted as +.B FS +is, and may be a regular expression constant. +.TP +\fBsprintf(\fIformat\fR [\fB, \fIexpr\fR ...]\fB)\fR +The string that +.B printf +would write. +.TP +\fBsub(\fIr\fB, \fIs\fR [\fB, \fIt\fR]\fB)\fR +Like +.BR gsub , +for the first match only. +.TP +\fBsubstr(\fIs\fB, \fIm\fR [\fB, \fIn\fR]\fB)\fR +Up to +.I n +bytes of +.I s +starting at position +.IR m , +or the rest of +.IR s . +Fractions in +.I m +and +.I n +are truncated, and an +.I m +before the start counts as 1 without shortening the result. +.TP +\fBtolower(\fIs\fB)\fR, \fBtoupper(\fIs\fB)\fR +.I s +with ASCII letters converted to lowercase or uppercase. +.PP +Bit operations, on 32-bit unsigned integers: +.TP +.BI and( a ", " b ) +Bitwise and. +.TP +.BI compl( a ) +Bitwise complement. +.TP +\fBlshift(\fIa\fB, \fIn\fB)\fR, \fBrshift(\fIa\fB, \fIn\fB)\fR +.I a +shifted left or right by +.I n +bits. +.TP +.BI or( a ", " b ) +Bitwise or. +.TP +.BI xor( a ", " b ) +Bitwise exclusive or. +.PP +Time: +.TP +.BI mktime( spec ) +The time in seconds since 1970-01-01 00:00:00 UTC of the local time +given by the string +.IR spec , +\(dq\fIYYYY MM DD HH MM SS\fR\(dq. +An optional seventh number is positive for daylight saving time, 0 for +standard time, or negative to determine it. +Out-of-range values are normalized, so month 13 is January of the next +year. +The result is \-1 when +.I spec +has fewer than six numbers or a month of 0, or gives a time before the +epoch. +.TP +\fBstrftime(\fR[\fIformat\fR [\fB, \fIt\fR]]\fB)\fR +The time +.IR t , +in seconds since the epoch, or the current time, formatted in local time +by the C function +.BR strftime . +The default +.I format +is +.BR "\(dq%a %b %d %H:%M:%S %Z %Y\(dq" . +A result longer than 239 bytes is the empty string. +See +.B NOTES +for the conversions. +.TP +.B systime() +The current time in seconds since the epoch. +.PP +Input and output: +.TP +.BI close( name ) +Close the file or pipe that +.I name +opened, so that the next use of +.I name +opens it again. +Return 0 on success, or \-1 and set +.B ERRNO +if +.I name +is not open. +.TP +\fBfflush(\fR[\fIname\fR]\fB)\fR +Flush standard output, or the output file or pipe +.IR name , +or all output if +.I name +is the empty string. +.TP +.BI system( command ) +Flush all output, run +.I command +in +.BR "sh\ \-c" , +wait for it, and return its exit status, from 0 to 255. +An empty +.I command +returns 0 without running anything. +.SS Variables +.TP +.B ARGC +The number of elements in +.BR ARGV . +.TP +.B ARGIND +The index in +.B ARGV +of the current input file. +.TP +.B ARGV +.B ARGV[0] +is +.BR awk , +and +.B ARGV[1] +through +.B ARGV[ARGC\-1] +are the operands after the program. +Changes made before the input is read change the input files, and empty +elements are skipped. +.TP +.B CONVFMT +The format for converting non-integral numbers to strings, by default +.BR %.6g . +.TP +.B ENVIRON +The environment, indexed by variable name. +Unlike Windows environment variable names, the subscripts are +case-sensitive. +Changing it does not affect the commands that +.B awk +runs. +.TP +.B ERRNO +The C +.B errno +value from the last failed +.B getline +or +.BR close , +a number rather than a message. +.TP +.B FILENAME +The name of the current input file, +.B \- +for standard input, or empty in +.BR BEGIN . +.TP +.B FNR +The number of the current record within the current file. +.TP +.B FS +The field separator, by default a single space. +.TP +.B IGNORECASE +When true, regular expression matching, string comparison, +.BR index , +and single-character field separators ignore the case of ASCII letters. +.TP +.B NF +The number of fields in the current record. +.TP +.B NR +The number of records read so far. +.TP +.B OFMT +The format for numbers written by +.BR print , +by default +.BR %.6g . +.TP +.B OFS +The output field separator, by default a single space. +.TP +.B ORS +The output record separator, by default a newline. +.TP +.B RLENGTH +The length of the text matched by +.BR match , +or \-1. +.TP +.B RS +The record separator, by default a newline. +.TP +.B RSTART +The position of the text matched by +.BR match , +or 0. +.TP +.B RT +The text that ended the last record read, such as the newline or the +text that a regular expression +.B RS +matched. +.TP +.B SUBSEP +The separator of multiple subscripts, by default +.BR \(dq\e034\(dq . +.SH OPTIONS +Options must come before the program and the other operands, and option +parsing stops at the first operand or at +.BR \-\- . +An option's argument may be attached, as in +.BR \-F: , +or be the next argument. +When +.BR \-f , +.BR \-e , +or +.B \-E +gives the program, the first operand is an input file. +.TP +\fB\-v \fIvar\fB=\fIvalue\fR +Assign +.I value +to the variable +.I var +before the program runs. +.TP +.BI "\-F " fs +Set +.B FS +to +.IR fs , +after processing escapes, so +.B \-F \(aq\et\(aq +gives a tab. +.TP +.BI "\-f " progfile +Read the program from +.IR progfile , +where +.B \- +means standard input. +.TP +.BI "\-E " progfile +Read the program from +.I progfile +as +.B \-f +does, then stop option parsing. +Every remaining operand is an input file, even one of the form +\fIvar\fB=\fIvalue\fR. +.TP +.BI "\-e " text +Use +.I text +as program text. +.TP +.BI "\-W " option +Ignored, with a warning. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit with status 0. +.PP +.B \-f +and +.B \-e +may be given several times and mixed, and their programs are combined +in order. +Each must be complete on its own, but functions are shared, so one can +be a library of functions for the others. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the C runtime replaces each argument containing wildcards with the names +of the files it matches, if any, even when the argument is quoted. +From +.BR cmd.exe , +a program containing +.B * +or +.B ?\& +is replaced if it happens to match file names. +When it is unset, busybox sets it to +.B 0 +for its child processes, so commands run from the busybox shell, which +expands wildcards itself, receive their arguments as given. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.TP +.B TZ +The time zone of +.B mktime +and +.BR strftime , +in the format of the Microsoft C runtime, such as +.B UTC0 +or +.BR EST5EDT . +When it is unset, the Windows time zone setting applies. +.PP +.B awk +copies the whole environment into +.BR ENVIRON , +and the commands it runs inherit it. +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Invalid usage, a syntax error, or a fatal error, such as division by +zero or a file that cannot be opened. +.PP +An +.B exit +statement with an expression sets the status to its value converted to +an integer, modulo 256. +.PP +Errors in the program are reported on standard error as +.PP +.RS 4 +.EX +awk: \fIsource\fR:\fIline\fR: \fImessage\fR +.EE +.RE +.PP +where +.I source +is the +.B \-f +file name, or +.B cmd. line +for program text from the command line. +.SH EXAMPLES +Print the first field of the rows of a CSV file whose second field is at +least 100: +.PP +.RS 4 +.EX +$ cat stock.csv +name,qty +bolt,120 +nut,80 +washer,300 +$ awk \-F, \(aqNR > 1 && $2 >= 100 { print $1 }\(aq stock.csv +bolt +washer +.EE +.RE +.PP +Total the sizes in a long directory listing: +.PP +.RS 4 +.EX +$ ls \-l | awk \(aq{ s += $5 } END { print s }\(aq +.EE +.RE +.PP +List the symbols that an object file needs from elsewhere: +.PP +.RS 4 +.EX +$ nm \-u main.o | awk \(aq{ print $2 }\(aq +__main +puts +.EE +.RE +.PP +Show where lines are longer than 72 bytes: +.PP +.RS 4 +.EX +$ awk \(aqlength > 72 { print FILENAME ":" FNR }\(aq *.c +.EE +.RE +.PP +Count the words in a file, most frequent first: +.PP +.RS 4 +.EX +$ awk \(aq{ for (i = 1; i <= NF; i++) n[$i]++ } + END { for (w in n) print n[w], w }\(aq notes.txt | sort \-rn +.EE +.RE +.PP +Pass a value from the shell, compared as a number: +.PP +.RS 4 +.EX +$ awk \-v max="$LIMIT" \(aq$2 > max\(aq data.txt +.EE +.RE +.PP +Combine a library of functions with a program on the command line: +.PP +.RS 4 +.EX +$ awk \-f lib.awk \-e \(aq{ print trim($0) }\(aq input.txt +.EE +.RE +.PP +Print the date: +.PP +.RS 4 +.EX +$ awk \(aqBEGIN { print strftime("%Y\-%m\-%d") }\(aq +.EE +.RE +.SH NOTES +Input files, standard input, program files, and the output of commands +read by +.B getline +are read in text mode: CR LF becomes LF, and a Ctrl-Z byte ends the +input. +Program text on the command line is not, and a CR in it is a syntax +error. +Output has bare LF line endings, and is flushed after every +.B print +and +.B printf +statement. +.PP +Commands run by +.BR system , +.BR "print |" , +and +.B "| getline" +run in busybox +.BR "sh\ \-c" , +not +.BR cmd.exe . +.B close +of a pipe returns 0 once its command finishes, not the command's exit +status. +A command that cannot be found is reported by the shell, so +.B "| getline" +sees the end of input rather than returning \-1. +.PP +File names may use drive letters and either kind of slash. +Besides +.BR /dev/stdin , +.BR /dev/stdout , +and +.BR /dev/stderr , +the name +.B /dev/null +works, and +.B /dev/tty +is the console. +As an operand or as the argument of +.BR \-f , +.B \- +means standard input, but after +.B < +or +.B > +it names a file, so use +.B /dev/stdin +or +.B /dev/stdout +there. +.PP +Strings are byte strings. +.BR length , +.BR substr , +.BR index , +.BR match , +and +.B printf +widths count bytes, so a non-ASCII UTF-8 character counts as two to +four. +In a regular expression, +.B .\& +and bracket expressions match single bytes. +On Windows 10 version 1903 and later, busybox runs with UTF-8 as its code +page, so program text and file names from the command line are UTF-8. +On earlier versions they are in the ANSI code page. +When standard output is a console, output is converted from that code +page to the console's for display. +Strings cannot contain NUL bytes, and with a single-character +.BR RS , +a NUL byte in the input also ends a record. +.PP +Numbers are formatted by the Microsoft C runtime, so exponents have +three digits, as in +.BR 1e+020 ; +infinity and NaN print as +.BR 1.#INF , +.BR \-1.#INF , +.BR 1.#QNAN , +or +.BR \-1.#IND ; +and the +.B %F +conversion prints nothing. +Strings such as +.BR 0x1A , +.BR inf , +and +.B nan +are numeric, so input fields like them compare as numbers. +Integer +.B printf +conversions use a 32-bit +.BR int , +so print larger integers with +.BR %.0f . +.PP +.B mktime +returns a 32-bit value, so it wraps around for times after 03:14:07 UTC +on 19 January 2038. +.B strftime +supports the conversions of the Microsoft C runtime, plus +.BR %e , +.BR %s , +.BR %T , +.BR %z , +and a +.B \- +flag that removes the padding of +.BR d , +.BR H , +.BR I , +.BR j , +.BR m , +.BR M , +.BR S , +.BR U , +.BR w , +.BR W , +.BR y , +and +.BR Y , +as in +.BR %\-d . +A format with any other conversion, such as +.B %F +or +.BR %D , +gives the empty string. +When +.B TZ +is unset, +.B %Z +gives the Windows name of the time zone, such as +.BR "Eastern Standard Time" . +.B strftime +treats a time before the epoch or after the year 3000 as 0. +.PP +Differences from POSIX awk and gawk: +.IP \(bu 2 +.B ^ +and +.B ** +group left to right, so +.B 2^3^2 +is 64. +.IP \(bu 2 +An assignment in either branch of +.B ?: +is a syntax error unless it is in parentheses, as in +.BR "c ? (a = 1) : (b = 2)" . +.IP \(bu 2 +.IB command " | getline" +does not change +.B NR +or +.BR FNR . +.IP \(bu 2 +.B substr +truncates fractional positions and lengths instead of rounding them. +.IP \(bu 2 +An input file that cannot be opened is a fatal error, and the +.B END +rules do not run. +.IP \(bu 2 +With an empty +.BR RS , +a last record followed by a single newline keeps that newline, which +adds an empty field when +.B FS +is a single character other than space. +.IP \(bu 2 +With an empty +.B RS +and a regular expression +.BR FS , +newlines in a record separate fields but are not counted in +.BR NF , +so the fields at the end of the record are lost. +.IP \(bu 2 +.B ERRNO +is a number. +.IP \(bu 2 +There are no long options other than +.BR \-\-help , +and +.B \-W +is ignored. +.PP +Extensions to POSIX awk, all from gawk, include +.BR \-e , +.BR \-E , +.BR ARGIND , +.BR ERRNO , +.BR IGNORECASE , +.BR RT , +regular expression +.BR RS , +.BR func , +.BR ** , +.BR **= , +.B length +of an array, +.BR gensub , +the bit and time functions, and hexadecimal and octal constants. +.SH SEE ALSO +.BR busybox (1), +.BR cut (1), +.BR grep (1), +.BR sed (1), +.BR sh (1), +.BR sort (1) diff --git a/man/man1/base32.1 b/man/man1/base32.1 new file mode 100644 index 0000000..7a60af4 --- /dev/null +++ b/man/man1/base32.1 @@ -0,0 +1,186 @@ +.TH BASE32 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +base32 \- encode or decode data in base32 +.SH SYNOPSIS +.B base32 +.RB [ \-di ] +.RB [ \-w +.IR cols ] +.RI [ file ] +.SH DESCRIPTION +.B base32 +encodes +.I file +in base32, as defined by RFC 4648, or with +.B \-d +decodes it, and writes the result to standard output. +With no +.IR file , +or when it is +.BR \- , +it reads standard input. +.PP +Encoding turns each 5 octets into 8 characters from the alphabet +.B A +to +.B Z +and +.B 2 +to +.BR 7 , +and pads the last group to 8 characters with +.BR = . +The output is broken into lines of 76 characters, the last of which may +be shorter, and each line ends with a newline. +Empty input produces no output. +.PP +Decoding accepts letters in either case. +Whitespace, control characters, and other characters outside the +alphabet are ignored, so line breaks and spaces may appear anywhere. +Padding is required. +When the input ends inside a group of 8 characters, +.B base32 +writes the octets of the complete groups, reports +.BR "truncated input" , +and exits with status 1. +Decoding continues after padding, so encodings joined with line breaks +between them decode as one. +.SH OPTIONS +Options may be grouped and may follow +.IR file . +The argument of +.B \-w +may be attached, as in +.BR \-w0 , +or be the next argument. +.B \-\- +ends the options. +.TP +.B \-d +Decode instead of encode. +.TP +.B \-i +Accepted for compatibility and ignored. +Decoding always ignores characters outside the alphabet. +.TP +.BI "\-w " cols +Break encoded output into lines of +.I cols +characters instead of 76. +A +.I cols +of 0 writes no line breaks at all, not even a final newline. +.I cols +is a decimal number up to 2147483647. +Ignored when decoding. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +When set, options must come before +.IR file . +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Invalid option or +.IR cols , +more than one +.IR file , +.I file +could not be opened or read, truncated input when decoding, or a write +error. +.TP +.B 141 +Standard output is a pipe whose reader exited before +.B base32 +finished writing. +When this is first detected as the output is flushed at exit, the +status is 1 instead. +.SH EXAMPLES +Encode a string: +.PP +.RS 4 +.EX +$ printf hello | base32 +NBSWY3DP +.EE +.RE +.PP +Decode a key written in groups, and show it in hex: +.PP +.RS 4 +.EX +$ echo \(aqJBSW Y3DP EHPK 3PXP\(aq | base32 \-d | xxd \-p +48656c6c6f21deadbeef +.EE +.RE +.PP +Generate a random 160-bit secret: +.PP +.RS 4 +.EX +$ head \-c 20 /dev/urandom | base32 +.EE +.RE +.PP +Encode a file on a single line: +.PP +.RS 4 +.EX +$ base32 \-w0 key.bin >key.txt +.EE +.RE +.SH NOTES +Differences from GNU +.BR base32 : +.IP \(bu 2 +There are no long options, such as +.B \-\-decode +or +.BR \-\-wrap . +.IP \(bu 2 +Decoding accepts lowercase letters. +.IP \(bu 2 +Decoding ignores characters outside the alphabet even without +.BR \-i . +.PP +Decoding works through the input in pieces that end at a character with +code 32 (space) or less, or after 80 characters, which causes two bugs: +.IP \(bu 2 +A character outside the alphabet with a code above 32, inside a group of +8 that continues into the next piece, shifts the decoding, which +corrupts the output or ends in truncated input. +.IP \(bu 2 +Data after padding in the last piece is reported as truncated input, +as in +.B MZXW6===MZXW6=== +with no final newline. +.PP +Standard input and output are binary. +Encoded lines end with LF, and carriage returns in encoded input are +ignored, so CRLF line endings decode correctly. +Decoded octets reach a file or pipe unchanged, but when standard output +is a console they pass through the busybox-w32 console layer as text: +escape sequences take effect, non-ASCII bytes may be converted, and NUL +bytes cut the output short. +.PP +.I file +may be a Windows path, with a drive letter and either kind of slash, or +a device name such as +.IR /dev/null ; +see +.BR busybox (1). +.SH SEE ALSO +.BR base64 (1), +.BR busybox (1), +.BR uuencode (1), +.BR xxd (1) diff --git a/man/man1/base64.1 b/man/man1/base64.1 new file mode 100644 index 0000000..b0e8d36 --- /dev/null +++ b/man/man1/base64.1 @@ -0,0 +1,203 @@ +.TH BASE64 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +base64 \- encode or decode base64 +.SH SYNOPSIS +.B base64 +.RB [ \-w +.IR col ] +.RI [ file ] +.br +.B base64 \-d +.RI [ file ] +.SH DESCRIPTION +.B base64 +encodes +.I file +as base64 on standard output, or with +.B \-d +decodes it. +With no +.IR file , +or when it is +.BR \- , +it reads standard input. +.PP +Encoding uses the standard alphabet of RFC 4648: uppercase letters, +lowercase letters, digits, +.BR + , +and +.BR / . +Each 3 input bytes become 4 characters, and the output is padded with +.B = +to a multiple of 4 characters. +The output is broken into lines of +.I col +characters, set by +.BR \-w , +and each line, including a shorter last line, ends in LF. +Empty input produces no output. +.PP +Decoding writes the bytes that the input encodes. +Characters outside the alphabet are skipped, including spaces, line +breaks, NUL bytes, and the +.B \- +and +.B _ +of the URL-safe alphabet, so base64url input does not decode correctly. +An +.B = +is padding only where it completes a group of 4 characters, and is +otherwise skipped. +Decoding continues after padding, so encodings joined with line breaks +between them decode to the joined data. +If the input ends inside a group, as unpadded input may, +.B base64 +writes what it has decoded and fails with +.BR "truncated input" . +.SH OPTIONS +Options may be grouped and may follow +.IR file . +The argument of +.B \-w +may be attached, as in +.BR \-w0 , +or be the next argument. +.B \-\- +ends the options. +.TP +.B \-d +Decode instead of encode. +.TP +.B \-i +Accepted and ignored. +Decoding always skips characters outside the alphabet. +.TP +.BI "\-w " col +Wrap encoded lines at +.I col +characters. +The default is 76, and 0 disables wrapping, in which case no newline at +all is written. +.I col +is a decimal number from 0 to 2147483647. +Ignored with +.BR \-d . +.TP +.B \-\-help +When it is the first argument, print a usage message on standard output +and exit. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +If set, options must precede +.IR file . +.PP +Variables that busybox-w32 reads in every applet, such as those that +control console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Invalid command line, +.I file +could not be opened or read, truncated input, or an error writing +standard output. +.TP +.B 141 +Standard output is a pipe that was closed while +.B base64 +was writing to it. +A closed pipe found only when the output is flushed at exit gives status +1 instead. +.SH EXAMPLES +Encode a file: +.PP +.RS 4 +.EX +$ base64 hello.txt +SGVsbG8sIHdvcmxkIQo= +.EE +.RE +.PP +Decode a file: +.PP +.RS 4 +.EX +$ base64 \-d hello.b64 >hello.txt +.EE +.RE +.PP +Encode a file as a single line with no final newline: +.PP +.RS 4 +.EX +$ base64 \-w0 icon.png >icon.txt +.EE +.RE +.PP +Make a random 32-byte key: +.PP +.RS 4 +.EX +$ head \-c 32 /dev/urandom | base64 +.EE +.RE +.SH NOTES +Differences from GNU base64: +.IP \(bu 2 +There are no long options, such as +.B \-\-decode +or +.BR \-\-wrap , +and no +.BR \-\-version . +.IP \(bu 2 +.B \-d +skips characters outside the alphabet whether or not +.B \-i +is given, where GNU fails without +.BR \-i . +.PP +Encoded lines end with LF, not CRLF. +Input is read in binary mode, so files are encoded byte for byte. +.PP +When standard output is a console, decoded data passes through the +busybox-w32 console layer as text, so binary data does not display +faithfully. +Redirect it to a file or a pipe. +.PP +Decoding reads the input in pieces that end at a character with code 32 +(space) or less, or after 80 characters, and has two bugs: +.IP \(bu 2 +A group of 4 characters that continues into the next piece decodes +wrongly, or fails as truncated input, when a skipped character falls +inside the group before the break. +This includes an +.B = +that ends a line before the +.B = +that starts the next, which an encoder writes for some inputs when it +wraps at an odd width, such as +.BR "\-w 3" . +The last byte of such encoded data is lost without an error. +.IP \(bu 2 +Characters that follow +.B = +padding with no space or line break in between, as in +.BR YQ==YQ== , +can fail as truncated input. +.PP +.I file +may be a Windows path, with a drive letter and either kind of slash, or +a busybox-w32 device name such as +.I /dev/null +or +.IR /dev/urandom . +.SH SEE ALSO +.BR base32 (1), +.BR busybox (1), +.BR uudecode (1), +.BR uuencode (1) diff --git a/man/man1/basename.1 b/man/man1/basename.1 new file mode 100644 index 0000000..2c8b97d --- /dev/null +++ b/man/man1/basename.1 @@ -0,0 +1,299 @@ +.TH BASENAME 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +basename \- strip the directory and suffix from a path +.SH SYNOPSIS +.B basename +.I path +.RI [ suffix ] +.br +.B basename \-a +.RB [ \-s +.IR suffix ] +.IR path ... +.br +.B basename \-s +.I suffix +.IR path ... +.SH DESCRIPTION +.B basename +prints the last component of +.IR path , +followed by a newline, with an optional +.I suffix +removed. +It works on the string alone and does not access the file system. +.PP +Both slash and backslash separate components. +Trailing separators are removed, and the result is what follows the last +separator that is left, so +.B a/b// +and +.B a\eb +both give +.BR b . +An empty +.I path +gives an empty line. +A path of separators alone gives its first character, so +.B /// +gives +.BR / . +.PP +A drive, an ASCII letter and a colon at the start of +.IR path , +is not a component, so the drive-relative +.B C:foo +gives +.BR foo . +When only separators follow the drive, the result is the drive and the +first separator: +.B C:/ +gives +.BR C:/ , +.B C:\e\e +gives +.BR C:\e , +and a bare +.B C: +gives +.BR C: . +A colon anywhere else is an ordinary character. +.PP +A UNC path begins with two separators, a host name, a separator, and a +share name. +The host and the share together are a root, which is never split, so +.B //host/share +and +.B //host/share/ +both give +.BR //host/share , +and +.B //host/share/dir +gives +.BR dir . +Device paths are UNC paths too: +.B \e\e?\eC:\e +gives +.BR \e\e?\eC: . +The result for two separators and a host without a share, such as +.BR //usr , +is unspecified. +.PP +If +.I suffix +is given, and the result ends with it and is longer than it, the suffix +is removed from the end, even from a root, so +.B C:/ +with a +.I suffix +of +.B / +gives +.BR C: . +The comparison is exact, so it is case-sensitive. +A result equal to the suffix is left whole, and an empty suffix removes +nothing. +.PP +With neither +.B \-a +nor +.BR \-s , +there is one +.I path +and an optional second operand, the +.IR suffix . +Any further operand is an error. +With either option, every operand is a +.IR path , +and each result is written on its own line, in order. +.SH OPTIONS +Options may be grouped, as in +.BR "\-as .c" , +and the argument of +.B \-s +may be attached, as in +.BR \-s.c . +Option parsing stops at the first operand, so a later +.B \-a +or +.B \-s +is an operand. +.B \-\- +ends the options, for a +.I path +that begins with a dash. +.TP +.B \-a +Treat every operand as a +.IR path . +.TP +.BI "\-s " suffix +Remove +.I suffix +from each +.IR path . +Implies +.BR \-a . +If given more than once, the last +.I suffix +is used. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the C runtime expands the wildcards +.B * +and +.B ?\& +in the last component of each argument when +.B basename +starts, even in quoted arguments, as needed for commands typed in +.BR cmd.exe . +A pattern that matches nothing is left as it is. +When the variable is unset, busybox sets it to +.BR 0 , +so that busybox programs it starts, such as from the kit's shell, do +not expand their arguments again. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Invalid command line, with a usage message on standard error: no +.IR path , +more than two operands without +.B \-a +or +.BR \-s , +an unknown option, or +.B \-s +without an argument. +.IP +It is also the status when standard output cannot be written, as when +it is closed. +No message is printed, and any remaining operands are skipped. +.TP +.B 141 +Standard output is a pipe whose reader has exited. +No message is printed. +.SH EXAMPLES +Strip the directory and the suffix: +.PP +.RS 4 +.EX +$ basename C:/w64devkit/bin/gcc.exe .exe +gcc +.EE +.RE +.PP +Strip a Windows path, quoted to protect the backslashes: +.PP +.RS 4 +.EX +$ basename \(aqC:\eUsers\eme\eDocuments\e\(aq +Documents +.EE +.RE +.PP +List the C sources in a directory by name, without the suffix: +.PP +.RS 4 +.EX +$ basename \-s .c src/*.c +.EE +.RE +.PP +Compile each C source in a directory into an object file of the same +name in the current directory: +.PP +.RS 4 +.EX +$ for f in src/*.c; do +> cc \-c \-o "$(basename "$f" .c).o" "$f" +> done +.EE +.RE +.SH NOTES +Differences from GNU basename: +.IP \(bu 2 +Backslashes are separators, and drives and UNC shares are roots. +.IP \(bu 2 +A path that begins with two separators, a host, and a share is a UNC +path, so +.B basename //usr/lib +prints +.BR //usr/lib , +not +.BR lib . +.IP \(bu 2 +There is no +.BR \-z , +and no long option other than +.BR \-\-help , +so +.B \-\-version +is an error. +.IP \(bu 2 +Options are not recognized after the first operand. +.IP \(bu 2 +A write error gives no message. +.PP +.I suffix +is compared case-sensitively although Windows file names are not, so +.B basename \-s .c MAIN.C +prints +.BR MAIN.C . +.PP +The wildcard expansion described under +.B BB_GLOBBING +can turn one argument into several. +Started from +.BR cmd.exe , +.B basename *.c +takes the second match for a +.I suffix +when two files match, and fails with a usage message when more do. +.PP +On Windows 10 version 1903 and later, +.I path +may contain any Unicode characters. +On older versions it is limited to the ANSI code page, and in a +double-byte code page, such as Shift JIS, the second byte of a character +may be taken for a backslash. +.PP +Lines end with LF, not CRLF. +When standard output is a console, the result is converted for display +from the ANSI code page, which is UTF-8 on Windows 10 version 1903 and +later. +.PP +The kit's +.B sh +runs +.B basename +inside the shell process, without starting a new one, except where the +shell needs a separate process anyway, as for a command substitution or +a pipeline. +.SH SEE ALSO +.BR busybox (1), +.BR dirname (1), +.BR realpath (1), +.BR sh (1) diff --git a/man/man1/bc.1 b/man/man1/bc.1 new file mode 100644 index 0000000..0211578 --- /dev/null +++ b/man/man1/bc.1 @@ -0,0 +1,857 @@ +.TH BC 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +bc \- arbitrary-precision calculator language +.SH SYNOPSIS +.B bc +.RB [ \-ilqsvw ] +.RI [ file ...] +.SH DESCRIPTION +.B bc +runs programs in the bc language, which has arbitrary-precision decimal +arithmetic, variables, arrays, functions, and C-like control flow. +It reads each +.I file +in turn, then standard input, and runs each statement as soon as it has +been read. +Results go to standard output and are flushed as the statements run. +.PP +A +.B quit +or +.B halt +statement ends +.B bc +at once, so a script that should not go on to read standard input ends +with one of them. +A +.I file +named +.B \- +is a file of that name, not standard input. +With +.BR \-l , +.B bc +first loads the math library, described below. +.PP +This is the bc applet of +.BR busybox (1), +which shares its code with +.BR dc (1). +.SS Interactive use +When standard input is a console, +.B bc +prints a banner, unless +.B \-q +is given, and reads lines with the line editor of +.BR sh (1), +without a prompt, completion, or a saved history. +Files named on the command line run first. +An error is reported and +.B bc +goes on with the next line, instead of exiting. +After an error in a +.IR file , +the rest of that file is skipped, and +.B bc +goes on with the next file or with the console. +But a +.I file +that cannot be opened, or that holds a byte that is not allowed (see +.BR NOTES ), +still ends +.B bc +with status 1. +.PP +Ctrl-C stops a running calculation, prints +.BR "interrupted execution" , +and returns to the line editor. +While a +.I file +runs, Ctrl-C ends +.B bc +with status 1 instead. +At the line editor, Ctrl-C, or Ctrl-D on an empty line, ends the input. +.PP +When standard input is not a console, the first error ends +.B bc +with status 1. +.SS Messages +Errors and warnings go to standard error, as +.PP +.RS 4 +.EX +bc: \fIfile\fR:\fIline\fR: \fImessage\fR +.EE +.RE +.PP +for a +.IR file , +and as +.PP +.RS 4 +.EX +bc: \fImessage\fR +.EE +.RE +.PP +for standard input. +A message about syntax may end with +\fBat \(aq\fItext\fB\(aq\fR, +where +.I text +is the rest of the line, from the token at which the parser stopped. +.SS Input +Input is ASCII text; see +.BR NOTES . +Statements are separated by newlines or semicolons. +White space between tokens is ignored. +A comment is +.B /* +up to the next +.BR */ , +which may span lines and does not nest, or +.B # +up to the end of the line. +A backslash directly before a newline is skipped, so a line can continue, +even in the middle of a number. +A backslash anywhere else outside a string or comment is an error. +.PP +A name starts with a lowercase letter and continues with lowercase +letters, digits, and underscores. +Variables, arrays, and functions have separate name spaces, so +.BR f , +.BR f[] , +and +.B f() +are three different things. +A variable or array element that has not been set is 0. +These words are reserved: +.PP +.RS 4 +.B auto break continue define else for halt ibase if last +.B length limits obase print quit read return scale sqrt while +.RE +.PP +A number is a string of the digits +.B 0 +to +.B 9 +and uppercase letters +.B A +to +.BR Z , +with at most one period. +Lowercase letters are names. +A one-digit number, ignoring leading zeros, has the value of its digit, +whatever +.B ibase +is, so +.B A +is always ten. +In a longer number, a digit not less than +.B ibase +counts as +.B ibase +minus one, so +.B ZZ +is the largest two-digit number in the current base. +A number is converted when the statement containing it runs, using the +.B ibase +in effect then, so the body of a function uses the +.B ibase +at the time of the call. +.PP +A string is text in double quotes. +It may span lines, has no escape sequences, and so cannot contain a +double quote. +A string appears only as a statement or as an item of +.BR print . +.SS Expressions +The operators, from the highest precedence to the lowest: +.TP +.B "++ \-\-" +Add 1 to, or subtract 1 from, a variable, an array element, +.BR ibase , +.BR obase , +.BR scale , +or +.BR last . +The value of a prefix form is the new value, and that of a postfix form +is the old value. +.TP +.B "\- !" +Unary minus and logical not. +Not yields 1 for 0 and 0 for anything else. +They have equal precedence, and both bind tighter than +.BR ^ , +so +.B \-2^2 +is 4. +.TP +.B ^ +Power, right associative. +The exponent must be an integer, though a fraction of zeros as in +.B 2.0 +is accepted, and it may be negative. +.TP +.B "* / %" +Left associative. +The remainder has the sign of the dividend. +Dividing by zero is an error. +.TP +.B "+ \-" +Left associative. +.TP +.B "= ^= *= /= %= += \-=" +Assignment, right associative, yielding the assigned value. +The left side is a variable, an array element, +.BR ibase , +.BR obase , +.BR scale , +or +.BR last . +Assignment binds tighter than comparison, so +.B a = 1 < 2 +means +.BR "(a = 1) < 2" . +.TP +.B "== <= >= != < >" +Left associative, yielding 1 or 0. +.TP +.B "&& ||" +Equal precedence, left associative, yielding 1 or 0. +Both operands are always evaluated. +.PP +Parentheses group. +A name followed by +.BI ( arguments ) +calls a function, and a name followed by +.BI [ index ] +is an array element. +The index is truncated to an integer, and must be from 0 to 2147483647. +An array grows as needed. +.PP +The special variables are +.B ibase +(the input base, from 2 to 36, initially 10), +.B obase +(the output base, from 2 to 999, initially 10), +.B scale +(the number of digits kept after the point, from 0 to 4294967295, +initially 0), and +.B last +(the value last printed, initially 0). +A period alone, as in +.BR "x = ." , +means +.BR last . +.PP +The built-in functions are: +.TP +.BI length( x ) +The number of significant digits of +.IR x : +leading zeros are not counted, even after the point, but trailing zeros +are, so +.B length(0.050) +is 2. +.B length(0) +is 1. +With an array, +.BI length( a []) +is one more than the highest index used, read or written, and at least 1. +.TP +.BI scale( x ) +The number of digits after the point of +.IR x . +.TP +.BI sqrt( x ) +The square root of +.IR x , +with the larger of +.B scale +and +.BI scale( x ) +digits after the point. +It is an error when +.I x +is negative. +.TP +.B read() +Reads a line from standard input, evaluates it as an expression using the +current +.BR ibase , +and yields its value. +When the program itself comes from standard input, the line is the next +line of it. +An empty line, or one that is not an expression, is an error. +.PP +The scale of a result follows POSIX. +For +.B + +and +.BR \- , +it is the larger of the operand scales. +For +.BR * , +it is the smaller of the sum of the operand scales and the larger of +.B scale +and the operand scales. +For +.BR / , +it is +.BR scale . +For +.BR ^ , +it is +.B scale +when the exponent is negative, and otherwise the smaller of the base's +scale times the exponent and the larger of +.B scale +and the base's scale. +The remainder +.B a % b +is +.BR "a \- (a / b) * b" , +computed with the larger of +.B scale +plus the scale of +.I b +and the scale of +.IR a . +.SS Statements +.TP +.I expression +Evaluates the expression, and unless it is an assignment, writes its +value and a newline. +A parenthesized assignment, such as +.BR "(x = 5)" , +is written, and +.B x++ +writes the old value. +A call of a +.B void +function writes nothing, unless the function returns a value. +.TP +.BI \(dq string \(dq +Writes the string unchanged, with no newline. +.TP +.BI "print " list +Writes each item of the comma-separated +.IR list , +a string or an expression, with no newline between or after them. +In a string, these sequences are replaced: +.RS +.IP \(bu 2 +.BR \ea , +.BR \eb , +.BR \ef , +.BR \en , +.BR \er , +and +.B \et +by the control characters bell, backspace, form feed, line feed, carriage +return, and tab; +.IP \(bu 2 +.B \ee +and +.B \e\e +by one backslash. +.RE +.IP +Any other backslash is written as it is. +.TP +.BI { statements } +Groups statements, which are separated by newlines or semicolons. +.TP +.B if (\fIcondition\fB) \fIstatement\fR [\fBelse \fIstatement\fR] +Runs the first statement when the condition is not zero, and otherwise +the second. +A newline may follow the right parenthesis, and the +.B else +keyword, but not two newlines. +The +.B else +must follow the end of the first statement on the same line, with no +semicolon or newline between, as in +.BR "} else {" . +.TP +.BI "while (" condition ") " statement +Repeats the statement while the condition is not zero. +.TP +.BI "for (" init "; " condition "; " update ") " statement +As in C: runs the +.I init +expression once, then repeats the statement and the +.I update +expression while the +.I condition +is not zero. +Each of the three may be empty, and an empty condition is true. +.TP +.B break +Leaves the innermost +.B while +or +.B for +loop. +.TP +.B continue +Goes on to the next iteration of the innermost loop, running the +.I update +expression of a +.B for +loop. +Outside a loop, +.B continue +makes +.B bc +crash. +.TP +.BI "return (" expression ) +Ends a function, with the value of the expression. +.B return +alone gives 0, and the parentheses may be left out. +Allowed only in a function body. +.TP +.B halt +Ends +.B bc +when it runs. +.TP +.B quit +Ends +.B bc +when it is read, even in a branch that never runs. +.TP +.B limits +Writes the limits of this implementation when it is read: +.RS +.EX +BC_BASE_MAX = 999 +BC_DIM_MAX = 2147483647 +BC_SCALE_MAX = 4294967295 +BC_STRING_MAX = 4294967294 +MAX Exponent = 999999999 +Number of vars = 999999999 +.EE +.RE +.SS Functions +A top-level statement defines a function: +.PP +.RS 4 +.EX +define name(parameters) { + auto locals + statements +} +.EE +.RE +.PP +Each parameter is a name for a value, +.IB a [] +for an array that is copied when the function is called, or +.BI * a [] +for a reference to the caller's array. +An +.B auto +list, which must come first in the body, names local variables and +arrays, which start out as 0. +Variables are dynamically scoped: a function sees the locals and +parameters of its callers. +A function that ends without a +.B return +gives 0. +.PP +A function may be called before it is defined, but must exist when the +call runs, and the call must have as many arguments as the function has +parameters. +An array is passed as +.IB a []. +Defining a function again replaces it. +The body must be a braced block; the opening brace may be on the next +line. +.PP +.BI "define void " name () +defines a function that gives no value, so that a call used as a +statement writes nothing, unless a +.B return +in it gives a value. +Used in an expression, such a call counts as 0. +.B void +is otherwise not a keyword. +.SS Output +A number is written in base +.BR obase . +Zero is +.BR 0 , +a negative number starts with a minus sign, and a number below 1 starts +with the point, as in +.BR .5 . +With an +.B obase +of 16 or less, digits are +.B 0 +to +.BR 9 , +then +.B A +to +.BR F . +With a larger one, each digit is a decimal number padded with zeros to +the width of +.B obase +minus one and preceded by a space, or by the point for the first digit +after it, so 255.5 is +.B " 02 55.50" +with an +.B obase +of 100. +The digits after the point in another base are produced until they cover +the scale of the number, so in base 2, +.B .5 +prints as +.BR .1000 . +.PP +A number that does not fit on a line is broken with a backslash and a +newline. +Each line, backslash included, then has one character fewer than the +line length, 69 by default. +The count includes whatever +.B print +wrote earlier on the line, and a number that starts past the limit is +not broken at all. +See +.BR BC_LINE_LENGTH . +.SS Math library +.B \-l +sets +.B scale +to 20 and defines these functions, which compute to the current +.BR scale , +with angles in radians: +.TP +.BI s( x ) +Sine. +.TP +.BI c( x ) +Cosine. +.TP +.BI a( x ) +Arctangent. +.TP +.BI l( x ) +Natural logarithm. +A zero or negative argument gives 1 minus 10 raised to +.BR scale . +.TP +.BI e( x ) +The exponential function, e to the power +.IR x . +.TP +.BI j( n , x ) +The Bessel function of integer order +.IR n , +which is truncated to an integer. +.SH OPTIONS +Options may be grouped, as in +.BR \-lq , +and may follow the +.I file +operands. +Long options start with +.B \-\- +and take no argument; a unique prefix of one is enough. +.B \-\- +ends the options. +A first argument of +.B \-\-help +prints a usage message on standard output and exits with status 0. +There is no +.BR \-h . +.TP +.BR \-q ", " \-\-quiet +Do not print the banner of an interactive session. +.TP +.BR \-l ", " \-\-mathlib +Load the math library, which sets +.B scale +to 20. +.TP +.BR \-s ", " \-\-standard +Treat the following extensions to POSIX bc as errors: +.RS +.IP \(bu 2 +A name longer than one character. +.IP \(bu 2 +The keywords +.BR continue , +.BR else , +.BR halt , +.BR last , +.BR limits , +.BR print , +and +.BR read , +and a period for +.BR last . +.IP \(bu 2 +The +.B # +comment, and the operators +.BR ! , +.BR && , +and +.BR || . +.IP \(bu 2 +A comparison outside the condition of +.BR if , +.BR while , +or +.BR for , +or more than one comparison in a condition. +.IP \(bu 2 +An empty expression in +.BR for . +.IP \(bu 2 +A +.B return +expression without parentheses. +.IP \(bu 2 +A function's left brace on a line after the +.B define +line. +.IP \(bu 2 +A reference parameter. +.RE +.IP +Each message begins with +.BR POSIX , +as in +.BR "POSIX does not allow the \(aqprint\(aq keyword" . +.TP +.BR \-w ", " \-\-warn +Write the messages of +.B \-s +as warnings, and go on. +With both options, +.B \-s +wins. +.TP +.BR \-i ", " \-\-interactive +Accepted and ignored. +Interactive use depends only on standard input being a console. +.TP +.BR \-v ", " \-\-version +Print the version on standard output, and exit with status 0. +The output is three lines, the first of which is +.B bc +and the busybox version. +It is also the banner of an interactive session. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the +.I file +operands are expanded, as needed when run from +.BR cmd.exe . +.TP +.B BC_ENV_ARGS +Options and file operands, separated by white space with no quoting, +handled before the command line. +The files are read first. +Only the files and +.B \-v +have an effect; see +.BR NOTES . +.TP +.B BC_LINE_LENGTH +The line length for numbers, as a decimal number. +A line, including its trailing backslash, has at most one character less +than this. +The default is 70, and +.B 0 +never breaks lines. +A value that is not a number, is negative, or is 1 or 2 means the default. +.TP +.B POSIXLY_CORRECT +When set, has the effect of +.BR \-s , +and the first +.I file +operand ends the options, so that later arguments such as +.B \-q +are file names. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output and +.B COLUMNS +for the width of the line editor, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +End of input, or a +.B quit +or +.B halt +statement. +In an interactive session, errors in the input do not change this. +.TP +.B 1 +An invalid option, a +.I file +that cannot be opened or holds a byte that is not allowed, an error in +the input when standard input is not a console, Ctrl-C while a +.I file +runs, or an error reading or writing. +.SH EXAMPLES +Calculate with large numbers: +.PP +.RS 4 +.EX +$ echo \(aq2^100\(aq | bc +1267650600228229401496703205376 +.EE +.RE +.PP +Divide to 20 digits: +.PP +.RS 4 +.EX +$ echo \(aqscale=20; 1/3\(aq | bc +\&.33333333333333333333 +.EE +.RE +.PP +Compute pi with the math library: +.PP +.RS 4 +.EX +$ echo \(aq4*a(1)\(aq | bc \-l +3.14159265358979323844 +.EE +.RE +.PP +Convert between bases: +.PP +.RS 4 +.EX +$ echo \(aqobase=16; 255\(aq | bc +FF +$ echo \(aqibase=16; FF\(aq | bc +255 +.EE +.RE +.PP +Run a program with a function: +.PP +.RS 4 +.EX +$ bc <<\(aqEOF\(aq +define f(n) { + if (n < 2) return (1) + return (n * f(n \- 1)) +} +f(20) +EOF +2432902008176640000 +.EE +.RE +.PP +Write several items on one line: +.PP +.RS 4 +.EX +$ echo \(aqfor (i = 1; i <= 3; i++) print i, " ", i^2, "\en"\(aq | bc +1 1 +2 4 +3 9 +.EE +.RE +.PP +Keep a number from being broken across lines: +.PP +.RS 4 +.EX +$ echo \(aq2^300\(aq | BC_LINE_LENGTH=0 bc +.EE +.RE +.SH NOTES +Input must be ASCII text. +NUL bytes are ignored. +Any other control character except tab, carriage return, and newline, +including form feed and Ctrl-Z, and any byte from 0x7f up, such as UTF-8 +text or a byte order mark, is rejected as +.BI "illegal character 0x" NN +even in a comment or a string. +The whole line is rejected before any of its statements run. +.PP +Files and standard input are read in binary mode, so scripts with LF or +CRLF line ends both work, since a carriage return is white space. +But a backslash must be followed directly by the LF, so a continued line +in a CRLF script is an error. +A carriage return in a string stays in the output, and Ctrl-Z does not +end a file. +Output lines end with LF. +.PP +File names may use +.B / +or +.B \e +and drive letters. +Standard input is read after the last file and cannot be named. +.PP +The error for +.B ibase +says the range is 2 to 16, but values up to 36 are accepted. +.PP +Only the file operands and +.B \-v +of +.B BC_ENV_ARGS +take effect. +Parsing the command line replaces the options it set, so +.B \-l +and the others are lost. +An unrecognized option in it makes +.B bc +crash. +.PP +Ctrl-C is handled by +.B bc +only when standard input is a console. +Otherwise it ends +.B bc +as it does any program. +.PP +Numbers are stored one digit per byte, so large scales and exponents use +a lot of memory. +.PP +Differences from GNU bc: +.IP \(bu 2 +A period is a synonym of +.BR last , +as in BSD bc. +.IP \(bu 2 +.B length +accepts an array, as in +\fBlength(\fIa\fB[])\fR. +.IP \(bu 2 +.B !\& +has the precedence of unary minus. +.IP \(bu 2 +.B read() +accepts an expression, not only a number. +.IP \(bu 2 +.B && +and +.B || +have equal precedence. +.SH SEE ALSO +.BR busybox (1), +.BR dc (1), +.BR sh (1) diff --git a/man/man1/bunzip2.1 b/man/man1/bunzip2.1 new file mode 100644 index 0000000..a26cfa1 --- /dev/null +++ b/man/man1/bunzip2.1 @@ -0,0 +1 @@ +.so man1/bzip2.1 diff --git a/man/man1/busybox.1 b/man/man1/busybox.1 new file mode 100644 index 0000000..c3e62d8 --- /dev/null +++ b/man/man1/busybox.1 @@ -0,0 +1,930 @@ +.TH BUSYBOX 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +busybox \- one program providing the shell and many Unix commands +.SH SYNOPSIS +.I applet +.RI [ argument ...] +.br +.B busybox +.RI [ applet +.RI [ argument ...]] +.br +.B busybox +.BR \-\-list [ \-full ] +.br +.B busybox \-\-install +.RB [ \-s ] +.RB [ \-u +| +.IR dir ] +.br +.B busybox \-\-uninstall +.RB [ \-n ] +.I file +.br +.B busybox \-\-help +.RI [ applet ] +.br +.B busybox \-\-version +.br +.B busybox \-\-busybox +.I applet +.RI [ argument ...] +.SH DESCRIPTION +.B busybox +is a single program, +.IR busybox.exe , +that contains the kit's shell and most of its Unix commands, each called +an applet. +It is busybox-w32, the Windows port of BusyBox, with w64devkit's +patches; see +.BR NOTES . +An applet is a small implementation of the command of the same name, +usually with fewer options than its GNU or BSD namesake. +.PP +With no arguments, +.B busybox +prints its version, a usage summary, and the list of applets on +standard output, and exits. +.PP +Every applet except +.BR [ , +.BR echo , +.BR false , +.BR test , +and +.B true +prints its usage on standard output and exits with status 0 when its +first argument is +.BR \-\-help . +In the shell, a builtin of the same name, such as +.B printf +or +.BR kill , +runs instead and does not do this. +.SS Choosing the applet +.B busybox +runs the applet named by its first command-line word, the name it was +started under. +The word is converted to lowercase, a leading +.B \- +is dropped, and so is a +.BR .exe , +.BR .com , +.BR .bat , +.BR .cmd , +or +.B .sh +suffix or a final period. +The last component of what remains names the applet, so that +.B LS.EXE +and +.B C:\ew64devkit\ebin\els.exe +both run +.BR ls . +.PP +A name that begins with +.BR busybox , +such as +.B busybox.exe +or +.BR busybox64.exe , +runs +.B busybox +itself, which performs one of the +.B OPTIONS +or runs the applet named by its first argument. +A directory part in that argument is ignored, but the rest must match +exactly: +.B busybox ls +works, but +.B busybox LS +and +.B busybox ls.exe +do not. +.PP +An unknown applet prints +.IB name ": applet not found" +on standard error, and the exit status is 127. +.SS Launchers +The kit's +.I bin +directory holds +.I busybox.exe +and, for most applets, a launcher named after the applet, such as +.IR ls.exe . +A launcher is a small separate program, not a link. +It starts +.I busybox.exe +from its own directory with its own command line unchanged, waits for +it, and exits with its exit status. +The launcher itself ignores Ctrl+C, leaving it to +.BR busybox . +.PP +These applets have no launcher: +.BR [ , +.BR cdrop , +.BR drop , +.BR flock , +.BR pdrop , +.BR sha384sum , +and +.BR stty . +Run them as +.B busybox +.IR applet , +or by name in the kit's shell, which runs applets without searching +.BR PATH . +.SS Applets +This build has these applets. +.BR sh , +.BR ash , +and +.B lash +are names of the same shell. +.TP +Shell +.BR ash , +.BR lash , +.B sh +.TP +Files +.BR chattr , +.BR chmod , +.BR cp , +.BR dd , +.BR df , +.BR du , +.BR find , +.BR flock , +.BR fsync , +.BR install , +.BR jn , +.BR ln , +.BR ls , +.BR lsattr , +.BR mkdir , +.BR mktemp , +.BR mv , +.BR pwd , +.BR readlink , +.BR realpath , +.BR rm , +.BR rmdir , +.BR shred , +.BR stat , +.BR sync , +.BR touch , +.B truncate +.TP +Text +.BR awk , +.BR cat , +.BR cmp , +.BR comm , +.BR cut , +.BR diff , +.BR dos2unix , +.BR ed , +.BR egrep , +.BR expand , +.BR fgrep , +.BR fold , +.BR grep , +.BR head , +.BR iconv , +.BR join , +.BR less , +.BR nl , +.BR paste , +.BR patch , +.BR rev , +.BR sed , +.BR shuf , +.BR sort , +.BR split , +.BR tac , +.BR tail , +.BR tee , +.BR tr , +.BR unexpand , +.BR uniq , +.BR unix2dos , +.B wc +.TP +Binary data +.BR base32 , +.BR base64 , +.BR hd , +.BR hexdump , +.BR od , +.BR uudecode , +.B uuencode +.TP +Checksums +.BR cksum , +.BR crc32 , +.BR md5sum , +.BR sha1sum , +.BR sha256sum , +.BR sha384sum , +.BR sha3sum , +.BR sha512sum , +.B sum +.TP +Compression and archives +.BR bunzip2 , +.BR bzcat , +.BR bzip2 , +.BR cpio , +.BR lzcat , +.BR lzma , +.BR lzop , +.BR lzopcat , +.BR tar , +.BR uncompress , +.BR unlzma , +.BR unlzop , +.BR unxz , +.BR xz , +.B xzcat +.TP +Processes +.BR kill , +.BR killall , +.BR pgrep , +.BR pidof , +.BR pkill , +.BR ps , +.BR time , +.BR timeout , +.B watch +.TP +System and users +.BR arch , +.BR cdrop , +.BR drop , +.BR free , +.BR groups , +.BR id , +.BR logname , +.BR nproc , +.BR pdrop , +.BR su , +.BR uname , +.BR uptime , +.B whoami +.TP +Terminal +.BR clear , +.BR reset , +.BR stty , +.B ttysize +.TP +Network +.BR httpd , +.BR ipcalc , +.BR nc , +.BR ssl_client , +.BR wget , +.B whois +.TP +Scripting +.BR [ , +.BR basename , +.BR bc , +.BR cal , +.BR date , +.BR dc , +.BR dirname , +.BR echo , +.BR env , +.BR expr , +.BR factor , +.BR false , +.BR getopt , +.BR inotifyd , +.BR pipe_progress , +.BR printenv , +.BR printf , +.BR seq , +.BR sleep , +.BR test , +.BR true , +.BR ts , +.BR usleep , +.BR which , +.BR xargs , +.B yes +.TP +Other +.BR busybox , +.B man +.SS Applets left out +The kit builds +.B busybox +without these applets, and ships other programs under their names: +.TP +.BR gzip ", " gunzip ", " zcat ", " unzip +tugz, which also provides +.B zip +and +.BR zipinfo ; +see +.BR gzip (1) +and +.BR unzip (1). +.TP +.B vi +Vim; see +.BR vim (1). +.TP +.B xxd +rexxd; see +.BR xxd (1). +.TP +.B uuidgen +The kit's own; see +.BR uuidgen (1). +.TP +.B make +GNU make; see +.BR make (1). +.TP +.BR ar ", " strings +GNU binutils. +.PP +These are left out with no replacement: +.BR ascii , +.BR bash , +.BR crond , +.BR crontab , +.BR dpkg , +.BR dpkg\-deb , +.BR ftpget , +.BR ftpput , +.BR link , +.BR pdpmake , +.BR rpm , +.BR rpm2cpio , +.BR tsort , +.BR unlink , +and the +.B [[ +form of +.BR test . +.SS Running commands +When the shell, or an applet such as +.BR env , +.BR find , +.BR time , +.BR timeout , +or +.BR xargs , +runs a command, it finds the command as follows: +.IP \(bu 2 +A command named by an applet runs that applet, even when +.B PATH +has a program of the same name, unless +.B BB_OVERRIDE_APPLETS +says otherwise. +.IP \(bu 2 +A command given as +.IR /bin/name , +.IR /usr/bin/name , +.IR /sbin/name , +or +.IR /usr/sbin/name , +when no such file exists, runs the applet +.IR name . +.IP \(bu 2 +Other commands without a directory part are looked up in +.BR PATH . +Each candidate is tried as given and then with +.BR .com , +.BR .exe , +.BR .sh , +.BR .bat , +and +.B .cmd +appended, unless it already ends in one of these or in a period. +An empty element in +.B PATH +stands for the current directory. +When started from a Windows environment, as from +.BR cmd.exe , +busybox drops a single trailing semicolon from +.BR PATH . +.IP \(bu 2 +A file that begins with +.B #!\& +runs under the interpreter it names. +For an interpreter in +.IR /bin , +.IR /usr/bin , +.IR /sbin , +or +.IR /usr/sbin , +busybox runs the applet of that name if there is one, or else that file +if it exists, or else the program of that name in +.BR PATH , +so that +.B #!/bin/sh +and +.B #!/usr/bin/env +lines work. +When the shell runs the file, this search uses +.B PATH +as it was when the shell started, ignoring changes made in the shell. +A file whose name ends in +.B .sh +and that has no +.B #!\& +line runs under +.BR sh . +.SH OPTIONS +These options are recognized only as the first argument. +Except for +.BR \-\-busybox , +they work only when +.B busybox +is started under its own name, where any other first argument is an +applet name. +.TP +.B \-\-list +Print the name of each applet on its own line, in sorted order. +.TP +.B \-\-list\-full +Like +.BR \-\-list , +but precede each name with a field of 8 columns, holding +.BR NOFORK , +.BR noexec , +or nothing, and with the applet's conventional Unix directory, such as +.BR usr/bin/ . +The shell runs +.B NOFORK +applets within its own process. +Any longer argument that begins with +.B \-\-list +works the same. +.TP +\fB\-\-install\fR [\fB\-s\fR] [\fB\-u\fR | \fIdir\fR] +Create a hard link to +.I busybox.exe +for each applet, named after the applet with +.B .exe +appended, in +.IR dir , +which is created if needed, or else in the directory that contains +.IR busybox.exe . +Existing files are left alone. +Other failures are reported, but do not change the exit status. +.RS +.TP +.B \-s +Create symbolic links instead. +Windows allows this only with administrator rights or in developer +mode. +.TP +.B \-u +Install into the directories +.IR /bin , +.IR /sbin , +.IR /usr/bin , +and +.I /usr/sbin +of the system drive, creating them, putting each applet in the +directory that +.B \-\-list\-full +shows. +.RE +.IP +The kit's launchers make this unnecessary for most applets. +.TP +\fB\-\-uninstall\fR [\fB\-n\fR] \fIfile\fR +Delete every hard link to +.IR file , +including +.I file +itself. +Given +.IR busybox.exe , +or any link that +.B \-\-install +made, this deletes +.I busybox.exe +and all its links, except that Windows refuses to delete the last link +to a running program. +The kit's launchers are not links, so given a launcher, this deletes +only that launcher. +Failures are reported, but do not change the exit status. +On Windows XP, which lacks the API for finding links, it does nothing. +.RS +.TP +.B \-n +Print the full path of each link instead of deleting it. +.RE +.TP +\fB\-\-help\fR [\fIapplet\fR] +Print the usage of +.I applet +on standard output and exit with status 0. +An unknown +.I applet +fails as described above. +Without +.IR applet , +or when it is +.BR busybox , +print what +.B busybox +prints with no arguments. +.TP +.B \-\-version +Print the version on standard output and exit. +When further arguments follow, +.B \-\-version +is taken as an applet name, and fails. +.TP +\fB\-\-busybox\fR \fIapplet\fR [\fIargument\fR ...] +Run +.I applet +whatever name +.B busybox +was started under, even one that does not begin with +.BR busybox . +It treats +.I applet +as the name it was started under, so the rules of +.B Choosing the applet +apply: +.B "\-\-busybox LS.EXE" +runs +.BR ls . +.SH ENVIRONMENT +The +.B BB_ +variables are specific to busybox-w32. +In the shell, export them: busybox reads them from the environment. +.TP +.B BB_CRITICAL_ERROR_DIALOGS +When it is +.BR 1 , +Windows shows its critical-error dialogs, such as for a drive with no +disk in it. +Otherwise busybox suppresses them, and the operation fails with an +error instead. +.TP +.B BB_FIX_BACKSLASH +When it is +.BR 1 , +.B ls +converts backslashes in its operands to forward slashes, so that the +names it prints have forward slashes. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the C runtime expands wildcards in the arguments of +.B busybox +when it starts, which serves commands typed in +.BR cmd.exe . +It expands quoted arguments too, and leaves a pattern that matches +nothing as it is. +When the variable is unset, busybox then sets it to +.BR 0 , +so that busybox programs it starts, such as from the shell, do not +expand their arguments again. +.TP +.B BB_OVERRIDE_APPLETS +Applets that the shell and other applets should not run by name, so +that a program in +.B PATH +runs instead. +It does not affect starting an applet with its launcher or with +.BR busybox . +The value is one of: +.RS +.TP +.B \- +Use no applets. +.TP +.B + +Use a program of the same name in +.BR PATH , +when there is one, instead of any applet. +.TP +.I list +Applet names separated by spaces, commas, or semicolons. +The names before the first semicolon are not used at all, and those +after it are replaced only when a program of that name is in +.BR PATH . +.RE +.IP +In the kit, the program found is usually the applet's own launcher in +.IR bin , +which runs the applet anyway, unless a directory earlier in +.B PATH +has a program of that name. +.TP +.B BB_SKIP_ANSI_EMULATION +The older form of +.BR BB_TERMINAL_MODE , +used only when that is unset: +.B 1 +means mode 1, +.B 2 +means mode 5, and any other value means mode 0. +.TP +.B BB_SYSTEMROOT +A drive, such as +.BR D: , +to use instead of the system drive, the drive that holds the Windows +system directory. +A directory works too. +The system drive is where +.B "\-\-install \-u" +installs, where the login shell looks for +.IR /etc/profile , +and where +.B man +looks for its configuration files in +.IR /etc . +.TP +.B BB_TERMINAL_MODE +How busybox uses the console, from 0 to 5. +In virtual terminal (VT) output mode, the console interprets the escape +sequences that applets write, such as for color. +Otherwise busybox interprets the common ones itself, through the console +API. +VT input mode makes the console send escape sequences for keys. +.RS +.TP +.B 0 +No VT output or input. +.TP +.B 1 +Force VT output. +.TP +.B 2 +Force VT input. +.TP +.B 3 +Force VT output and input. +.TP +.B 4 +Use VT output and input only when the console already has them +enabled. +.TP +.B 5 +Like 4, but also enable VT output when the console supports it. +.RE +.IP +The default is 5, or 0 when +.B CONEMUPID +is set or under Wine. +A number outside this range means 5, and a value that is not a number +means 0. +Modes 0 to 3 are meant for testing. +.TP +.B BB_UMASK +The file mode creation mask, in octal, applied before each applet runs. +The default is +.BR 002 . +The owner write bit, +.BR 200 , +makes new files read-only. +The group and other write bits, +.BR 022 , +only remove those bits from the permissions that busybox reports. +The shell's +.B umask +command sets and exports this variable. +.TP +.BR COLUMNS ", " LINES +The terminal width and height for applets that fit their output to it, +such as +.B ls +and +.BR less , +and the width of the applet list that +.B busybox +prints with no arguments. +The defaults are the size of the console window, or 80 by 24 when +neither standard output nor standard error is a console. +When set, they override the console window, and a value of 1 or less, +or 30000 or more, means 80 or 24. +.TP +.B HOME +When it is unset, busybox uses the user's profile directory. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +The first of these that is set decides how text is handled. +When its value is +.BR C , +text is single bytes, and console output is written without code page +conversion. +Otherwise text is UTF-8 when the ANSI code page is UTF-8, and single +bytes when it is not. +.TP +.B PATH +Where external programs are found; see +.BR "Running commands" . +.TP +.B TMPDIR +When it is unset, busybox uses +.BR TMP , +then +.BR TEMP . +.SH EXIT STATUS +.TP +.B 0 +Success, for +.B busybox +with no arguments or with one of the +.BR OPTIONS . +.TP +.B 1 +Invalid arguments to +.B \-\-install +or +.BR \-\-uninstall . +.TP +.B 127 +The applet was not found. +.TP +.B 382 +A launcher could not start +.IR busybox.exe , +such as when it is missing from the launcher's directory. +The launcher prints a message beginning +.B w64devkit: +on standard error. +The kit's shell sees it as 126, its low byte. +.PP +Otherwise the exit status is that of the applet. +.SH EXAMPLES +List the applets: +.PP +.RS 4 +.EX +$ busybox \-\-list +.EE +.RE +.PP +Show the usage of an applet: +.PP +.RS 4 +.EX +$ busybox \-\-help sort +.EE +.RE +.PP +Run an applet that has no launcher: +.PP +.RS 4 +.EX +$ busybox sha384sum kit.zip +.EE +.RE +.PP +List the applets that the shell runs in its own process: +.PP +.RS 4 +.EX +$ busybox \-\-list\-full | grep NOFORK +.EE +.RE +.PP +In the shell, run +.I wget.exe +from +.I ~/bin +instead of the +.B wget +applet: +.PP +.RS 4 +.EX +$ export PATH="$HOME/bin;$PATH" +$ export BB_OVERRIDE_APPLETS=wget +.EE +.RE +.SH NOTES +Paths may use forward or back slashes. +Prefer forward slashes, since in the shell a backslash quotes the next +character. +An absolute path has a drive, as in +.IR c:/path , +or is a UNC path, as in +.IR //host/share/path . +A path such as +.I /path +is relative to the root of the current drive. +.PP +A path such as +.I c:name +is relative to the current directory of that drive, and a bare drive such +as +.I c: +is that directory, as in Windows. +Applets name the entries of +.I c: +as +.IR c:name , +and the root of the drive is +.IR c:/ . +.PP +Applets accept these Unix device names: +.I /dev/null +for +.BR NUL , +.I /dev/tty +for the console, +.IR /dev/zero , +.IR /dev/urandom , +.IR /dev/stdin , +.IR /dev/stdout , +.IR /dev/stderr , +and +.IR /dev/fd/N . +.PP +Files and standard streams are binary, with no CRLF translation: +applets write LF line endings. +.PP +Owners and permissions are synthesized. +A file shows as writable unless it is read-only, and as executable when +its name ends in +.BR .com , +.BR .exe , +.BR .sh , +.BR .bat , +or +.BR .cmd , +when it begins with +.BR #! , +or when it is a Windows program. +.PP +busybox has a manifest that makes its ANSI code page UTF-8 on Windows 10 +version 1903 or later, so that file names, arguments, and text may +contain any Unicode character. +On older systems they are limited to the system's ANSI code page. +Console output is converted to the console's code page, unless +.BR LC_ALL , +.BR LC_CTYPE , +or +.B LANG +is +.BR C . +If both of the console's code pages are 850 when busybox first uses the +console, it changes them to 858, which adds the euro sign. +.PP +w64devkit changes busybox-w32 as follows: +.IP \(bu 2 +The login shell also reads the kit's +.IR etc/profile , +line editing never beeps, Tab does nothing where a command name is +expected but none is typed, the history holds 1024 lines by default and +up to 16384, and the +.B noiconify +option is on by default, so that +.B noconsole +hides the console window instead of minimizing it; see +.BR sh (1). +.IP \(bu 2 +Automatic decompression, as in +.B tar +and +.BR man , +recognizes zstd data and decompresses it with the kit's +.BR unzstd , +and +.B tar +has a +.B \-\-zstd +option. +.IP \(bu 2 +gzip data is decompressed by running the kit's +.BR gunzip . +.IP \(bu 2 +.B man +finds the kit's pages and formats them with the kit's +.BR nroff , +and +.B less \-R +passes color and font escape sequences through. +.SH SEE ALSO +.BR gzip (1), +.BR less (1), +.BR ls (1), +.BR make (1), +.BR man (1), +.BR nroff (1), +.BR sh (1), +.BR unzip (1), +.BR uuidgen (1), +.BR vim (1), +.BR w64devkit (1), +.BR xxd (1), +.BR zstd (1) diff --git a/man/man1/bzcat.1 b/man/man1/bzcat.1 new file mode 100644 index 0000000..a26cfa1 --- /dev/null +++ b/man/man1/bzcat.1 @@ -0,0 +1 @@ +.so man1/bzip2.1 diff --git a/man/man1/bzip2.1 b/man/man1/bzip2.1 new file mode 100644 index 0000000..4744cc8 --- /dev/null +++ b/man/man1/bzip2.1 @@ -0,0 +1,377 @@ +.TH BZIP2 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +bzip2, bunzip2, bzcat \- compress or decompress files in the bzip2 format +.SH SYNOPSIS +.B bzip2 +.RB [ \-cfkqsvz ] +.RB [ \-1 " ... " \-9 ] +.RI [ file ...] +.br +.B bzip2 +.BR \-d | \-t +.RB [ \-cfkqv ] +.RI [ file ...] +.br +.B bunzip2 +.RB [ \-cdfkqtv ] +.RI [ file ...] +.br +.B bzcat +.RB [ \-cdfkqtv ] +.RI [ file ...] +.SH DESCRIPTION +.B bzip2 +compresses files in the bzip2 format, which sorts blocks of input with +the Burrows-Wheeler transform and then applies Huffman coding. +.B bunzip2 +decompresses them, and +.B bzcat +decompresses them to standard output. +.B bunzip2 +is the same as +.BR "bzip2 \-d" , +and +.B bzcat +is the same as +.BR "bunzip2 \-c" . +.PP +Each +.I file +is replaced: +.B bzip2 +appends +.B .bz2 +to its name, and +.B bunzip2 +removes that suffix. +The input file is deleted once its output is complete. +.B bunzip2 +skips a name that does not end in +.BR .bz2 , +reporting +.BR "unknown suffix \- ignored" . +An existing output file is an error unless +.B \-f +is given. +.PP +With no +.I file +operands, or for a +.I file +named +.BR \- , +the command reads standard input and writes standard output. +With +.BR \-c , +and always for +.BR bzcat , +all output goes to standard output, the input files are kept, and +compressed file names need not end in +.BR .bz2 . +.PP +When a file fails, the error is reported on standard error, the partial +output file is removed, the input file is kept, and the remaining files +are still processed. +Output already written to standard output remains. +Reading standard input from a console without +.BR \-f , +or failing to delete an input file, ends the command at once. +.PP +The options +.B \-1 +to +.B \-9 +set the block size to 100,000 to 900,000 bytes. +Larger blocks usually compress better and need more memory. +The block size is recorded in the compressed data, so decompression +needs no option. +.PP +Concatenated bzip2 streams, such as the output of several +.B bzip2 \-c +commands appended to one file, decompress as one. +Data after the last stream is ignored unless it begins with +.BR BZ , +which is then an error. +.SS Diagnostics +Damaged input is reported with one of these messages: +.TP +.B invalid magic +The input does not begin with +.BR BZ . +.TP +.B CRC error +The checksum of a block or of the whole stream does not match. +For a stream with no data, the file still counts as a success. +.TP +.BI "bunzip error " n +.I n +is +.B \-2 +for a damaged stream or block header, +.B \-3 +for a truncated or unreadable file, +.B \-5 +for corrupt data, or +.B \-7 +for a block in the obsolete randomized format. +.SH OPTIONS +Options may be grouped, as in +.BR \-kv , +and may follow file operands unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +There are no long options. +.B bunzip2 +and +.B bzcat +accept only +.BR \-c , +.BR \-d , +.BR \-f , +.BR \-k , +.BR \-q , +.BR \-t , +and +.BR \-v , +as does +.B bzip2 +when +.B \-d +or +.B \-t +is given. +.TP +.BR \-1 " ... " \-9 +Compress with a block size of the given multiple of 100,000 bytes. +The default is +.BR \-9 . +When several are given, the lowest wins. +.TP +.B \-d +Decompress. +.B bunzip2 +and +.B bzcat +ignore it. +.TP +.B \-c +Write to standard output and keep the input files. +Compressing several files produces a series of streams, which +decompress as one. +.TP +.B \-f +Remove an existing output file before writing it, and read standard +input even when it is a console. +Without +.BR \-f , +reading standard input from a console fails with +.BR "compressed data not read from terminal" . +.TP +.B \-k +Keep the input files. +.TP +.B \-t +Test: decompress each file and discard the output, keeping the input +files. +The +.B .bz2 +suffix is not required. +Overrides +.BR \-c . +.TP +.B \-q +Accepted and ignored. +.TP +.B \-s +The same as +.BR \-2 . +.TP +.B \-v +After converting each +.I file +to an output file, print its name, a percentage, and the output name +on standard error, even with +.BR \-k . +When decompressing, the percentage is the space saved by compression, +or a huge number if the compressed file is the larger. +When compressing, it is computed wrongly and is usually a huge number. +Nothing is printed for standard input, or with +.B \-c +or +.BR \-t . +.TP +.B \-z +Compress. +It has no effect, since +.B bzip2 +compresses unless given +.B \-d +or +.BR \-t . +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit. +The message omits some options. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the command line are expanded at startup, for callers such +as +.B cmd.exe +that do not expand them. +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell do not expand +their arguments again. +.TP +.B BB_UMASK +An octal file mode creation mask applied at startup. +If it includes the owner write bit, +.BR 0200 , +output files are created read-only. +.TP +.B POSIXLY_CORRECT +If set, options must precede the file operands. +.PP +Startup and messages written to a console also depend on +.BR BB_CRITICAL_ERROR_DIALOGS , +.BR BB_SKIP_ANSI_EMULATION , +.BR BB_TERMINAL_MODE , +.BR LANG , +.BR LC_ALL , +and +.BR LC_CTYPE , +as for every busybox applet; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Invalid option, or an error with any file. +.SH EXAMPLES +Compress a file, replacing it with +.IR notes.txt.bz2 : +.PP +.RS 4 +.EX +$ bzip2 notes.txt +.EE +.RE +.PP +Decompress a file and report the space saved: +.PP +.RS 4 +.EX +$ bunzip2 \-v numbers.txt.bz2 +numbers.txt.bz2: 77% \- replaced with numbers.txt +.EE +.RE +.PP +Check the integrity of all compressed files in a directory: +.PP +.RS 4 +.EX +$ bzip2 \-t *.bz2 +.EE +.RE +.PP +Compress with the smallest blocks, keeping the original: +.PP +.RS 4 +.EX +$ bzip2 \-c \-1 build.log >build.log.bz2 +.EE +.RE +.PP +Compress two files into one, then decompress the result: +.PP +.RS 4 +.EX +$ bzip2 \-c part1.txt part2.txt >whole.bz2 +$ bzcat whole.bz2 >whole.txt +.EE +.RE +.PP +List the contents of a compressed tar archive: +.PP +.RS 4 +.EX +$ bzcat src.tar.bz2 | tar \-tf \- +.EE +.RE +.SH NOTES +Differences from bzip2 1.0: +.IP \(bu 2 +There are no long options, such as +.BR \-\-stdout , +and no +.B \-L +or +.BR \-V . +.IP \(bu 2 +.B \-s +selects 200,000-byte blocks when compressing, and is rejected when +decompressing, rather than reducing the memory used to decompress. +.IP \(bu 2 +Of several level options, the lowest wins, not the last. +.IP \(bu 2 +.B \-q +has no effect, and +.B \-v +prints a different report, only for files converted to an output +file. +.IP \(bu 2 +.B bunzip2 +recognizes only the +.B .bz2 +suffix, compared case-sensitively, so +.I FILE.BZ2 +is skipped. +It does not handle the +.BR .bz , +.BR .tbz , +or +.B .tbz2 +suffixes, and does not decompress other names to +.IB name .out\fR. +.IP \(bu 2 +.B bzip2 +compresses a file even if its name already ends in +.BR .bz2 . +.IP \(bu 2 +The output file gets the current time, not the input's modification +time. +.IP \(bu 2 +Standard input is not read from a console without +.BR \-f , +when compressing as well as when decompressing, but compressed data is +written to a console without complaint. +.IP \(bu 2 +The +.B BZIP2 +and +.B BZIP +environment variables are ignored. +.IP \(bu 2 +Blocks in the obsolete randomized format are rejected. +.PP +Standard input and output are in binary mode. +Output names are formed from the input path as written, so drive +letters and backslashes work, and the suffix test looks only at the text +after the last period. +A read-only input file is still deleted, and its output is also +read-only. +Paths may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +.SH SEE ALSO +.BR busybox (1), +.BR gzip (1), +.BR tar (1), +.BR zstd (1) diff --git a/man/man1/cal.1 b/man/man1/cal.1 new file mode 100644 index 0000000..1e2d98b --- /dev/null +++ b/man/man1/cal.1 @@ -0,0 +1,205 @@ +.TH CAL 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +cal \- display a calendar +.SH SYNOPSIS +.B cal +.RB [ \-jmy ] +.RI [[ month ] +.IR year ] +.SH DESCRIPTION +.B cal +prints a calendar of one month, or of a whole year, on standard output. +With no operands, it prints the current month, or with +.B \-y +the current year. +With one operand, it prints the whole +.IR year . +With two, it prints +.I month +of +.IR year . +A single operand is always a year: +.B cal 9 +prints the year 9, not September, and +.B cal 26 +the year 26, not 2026. +.PP +.I month +is a number from 1 to 12, and +.I year +a number from 1 to 9999. +Both are decimal, and may have leading zeros but no sign, spaces, or +other characters. +Month names are not accepted. +.PP +Dates up to 2 September 1752 are in the Julian calendar, and later dates +in the Gregorian calendar, following the change in Great Britain and its +colonies, so September 1752 has no 3rd to 13th. +Through 1752 every fourth year is a leap year. +From 1753 on, a year divisible by 100 is a leap year only when it is also +divisible by 400. +The Julian calendar extends back to the year 1. +.SS Output format +A month is a heading with the month name and the year, centered, then a +line of two-letter weekday names, then six week rows. +Each day is a number right-aligned in a field 2 characters wide, or 3 +with +.BR \-j , +and one space separates the fields. +Weeks start on Sunday, or on Monday with +.BR \-m . +A week row with no days in it is printed as a line of spaces rather than +omitted, so a month is always 8 lines. +.PP +A year is the year number, centered, then an empty line, then the months +side by side, three to a row, or two with +.BR \-j . +Each row of months starts with a line of their names, each centered over +its month, and a line of weekday names, followed by six week rows. +Nothing separates one row of months from the next except a last week row +with no days in it. +A year is always 34 lines, or 50 with +.BR \-j . +.PP +Month and weekday names are always in English. +.SH OPTIONS +Options may be grouped, as in +.BR \-jy , +and may follow the operands unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +.TP +.B \-j +Number each day by its day of the year, from 1 to 366, instead of its day +of the month. +The usage message calls these Julian dates. +.TP +.B \-m +Start weeks on Monday instead of Sunday. +.TP +.B \-y +Print the whole year: the current year with no operands, or +.IR year . +A +.I month +operand is ignored, and is not checked. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B TZ +The time zone that determines the current month and year, used only when +no +.I year +is given. +The format is that of the Microsoft C runtime: a three-letter zone name, +the hours to add to local time to give UTC, optionally followed by +minutes and seconds after colons, and an optional three-letter daylight +saving zone name, as in +.BR EST5EDT . +When it is unset or empty, the Windows time zone setting applies. +.TP +.B POSIXLY_CORRECT +When set, options must come before the operands. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid option or more than two operands, with a usage message on +standard error; a +.I month +or +.I year +that is not a number or is out of range; or an error writing standard +output. +.SH EXAMPLES +Show August 2026 with weeks starting on Monday: +.PP +.RS 4 +.EX +$ cal \-m 8 2026 + August 2026 +Mo Tu We Th Fr Sa Su + 1 2 + 3 4 5 6 7 8 9 +10 11 12 13 14 15 16 +17 18 19 20 21 22 23 +24 25 26 27 28 29 30 +31 +.EE +.RE +.PP +Show the whole of the current year, then of 2027: +.PP +.RS 4 +.EX +$ cal \-y +$ cal 2027 +.EE +.RE +.PP +Show the day of the year of each day in March 2026: +.PP +.RS 4 +.EX +$ cal \-j 3 2026 +.EE +.RE +.PP +Show the change to the Gregorian calendar: +.PP +.RS 4 +.EX +$ cal 9 1752 + September 1752 +Su Mo Tu We Th Fr Sa + 1 2 14 15 16 +17 18 19 20 21 22 23 +24 25 26 27 28 29 30 +\& +\& +\& +.EE +.RE +.SH NOTES +Differences from the util-linux +.B cal +common on Linux: +.IP \(bu 2 +Only +.BR \-j , +.BR \-m , +and +.B \-y +are accepted, and +.B \-\-help +is the only long option. +.IP \(bu 2 +The current day is not highlighted. +.IP \(bu 2 +.I month +must be a number. +.PP +In BSD +.BR cal , +.B \-m +selects a month instead. +.PP +With +.BR \-j , +the days of 1752 after 2 September are numbered as if the 11 dropped +days existed, so 14 September is day 258 and 31 December is day 366. +.PP +Lines end with LF, not CRLF. +.SH SEE ALSO +.BR busybox (1), +.BR date (1) diff --git a/man/man1/cat.1 b/man/man1/cat.1 new file mode 100644 index 0000000..9b8b86a --- /dev/null +++ b/man/man1/cat.1 @@ -0,0 +1,299 @@ +.TH CAT 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +cat \- concatenate files to standard output +.SH SYNOPSIS +.B cat +.RB [ \-nbvteAu ] +.RI [ file ...] +.SH DESCRIPTION +.B cat +writes the contents of each +.I file +to standard output, in order. +With no +.I file +operands, or for a +.I file +named +.BR \- , +it reads standard input. +A +.I file +that cannot be opened is reported on standard error and skipped, and the +remaining files are still written. +A read error ends that file. +It is reported only without options, and with +.B \-n +or +.B \-b +alone it does not affect the exit status. +.PP +Without options, the bytes are copied unchanged. +The options number the lines, show nonprinting characters, or both. +.SS Line numbers +With +.B \-n +or +.BR \-b , +a numbered line starts with its number, right-aligned in 6 columns, +and a tab. +Numbering starts at 1 and continues across files. +.PP +Without +.BR \-v , +.BR \-t , +.BR \-e , +or +.BR \-A , +the input is read as lines of text, which changes it: a CR before an LF +is removed, a NUL byte ends a line and is removed, and every line is +written with a final LF, including the last line of a file that has +none. +.PP +With any of them, the number is followed by two spaces instead of a +tab, and lines end only at LF: a CR or NUL is shown like any other byte. +A file that does not end with an LF then runs into the first line of the +next file, which gets no number. +.SS Nonprinting characters +With +.BR \-v , +.BR \-t , +.BR \-e , +or +.BR \-A , +each byte is written as follows, so the output is plain ASCII: +.IP \(bu 2 +LF and the printable ASCII characters 0x20 to 0x7E are written as +themselves, and so is tab, unless +.B \-t +is given. +.IP \(bu 2 +Any other byte below 0x20 is +.B \(ha +followed by the character 0x40 above it, from +.B \(ha@ +to +.BR \(ha_ , +so CR is +.B \(haM +and ESC is +.BR \(ha[ . +DEL, 0x7F, is +.BR \(ha? . +.IP \(bu 2 +A byte from 0x80 to 0xFF is +.B M\- +followed by the byte 0x80 below it, written as itself if printable and +in +.B \(ha +form otherwise, so 0x8A is +.B M\-\(haJ +and 0xFF is +.BR M\-\(ha? . +Text in UTF-8 appears byte by byte: the encoding of +.B e +with an acute accent, 0xC3 0xA9, is +.BR M\-CM\-) . +.SH OPTIONS +Options may be grouped, as in +.BR \-vn , +and may follow +.I file +operands. +.B \-\- +ends the options. +.TP +.B \-n +Number every output line, as described under +.BR "Line numbers" . +.TP +.B \-b +Number only nonempty lines. +Empty lines are written without a number and are not counted. +Without +.BR \-v , +.BR \-t , +.BR \-e , +or +.BR \-A , +a line holding only a CR is empty. +Overrides +.BR \-n . +.TP +.B \-v +Show nonprinting characters, as described under +.BR "Nonprinting characters" . +.TP +.B \-t +Like +.BR \-v , +and also show each tab as +.BR \(haI . +.TP +.B \-e +Like +.BR \-v , +and also write +.B $ +before each LF. +A last line without an LF gets no +.BR $ . +.TP +.B \-A +Same as +.BR \-vte . +.TP +.B \-u +Accepted for compatibility and ignored. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options, so that later arguments such as +.B \-n +are file names. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid option, a +.I file +could not be opened or read, or standard output could not be written. +.TP +.B 141 +Standard output is a pipe that was closed before all output was written. +.SH EXAMPLES +Reassemble a file cut into pieces by +.BR split : +.PP +.RS 4 +.EX +$ cat backup.zip.?? >backup.zip +.EE +.RE +.PP +Number the lines of a source file: +.PP +.RS 4 +.EX +$ cat \-n main.c +.EE +.RE +.PP +Reveal CR line endings, tabs, and trailing spaces: +.PP +.RS 4 +.EX +$ printf \(aqone\er\entwo\etthree \en\(aq | cat \-A +one\(haM$ +two\(haIthree $ +.EE +.RE +.PP +Write a file from a here-document: +.PP +.RS 4 +.EX +$ cat >config.h < #define VERSION "1.0" +> EOF +.EE +.RE +.SH NOTES +Differences from GNU cat: +.IP \(bu 2 +There are no long options, and no +.BR \-E , +.BR \-T , +or +.BR \-s . +.IP \(bu 2 +With +.B \-n +or +.B \-b +alone, line endings change, as described under +.BR "Line numbers" . +.IP \(bu 2 +With +.BR \-v , +.BR \-t , +.BR \-e , +or +.BR \-A , +line numbers are followed by two spaces, not a tab. +.PP +Standard input and output are binary, so without options CR LF line +endings and Ctrl-Z characters are copied unchanged. +.PP +File names may use drive letters and backslashes. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +The device names +.IR /dev/null , +.IR /dev/zero , +.IR /dev/urandom , +.IR /dev/stdin , +.I /dev/tty +(the console), and +.I /dev/fd/N +work as on Unix. +A directory operand fails with +.BR "Permission denied" , +or with +.B \-n +or +.B \-b +alone, +.BR "Is a directory" . +.PP +Lines typed at a console arrive with CR LF line endings. +To end the input, type Ctrl-Z at the start of a line and press Enter. +Ctrl-D is an ordinary character. +.PP +When standard output is a console, text is converted for display from +the ANSI code page, which is UTF-8 on Windows 10 version 1903 and later. +Escape sequences, such as those for color, take effect, and busybox +emulates them on consoles without virtual terminal support. +Without options, output is written in blocks as it is read, and a block +that contains a NUL byte is written as is, with no conversion or +emulation. +.SH SEE ALSO +.BR busybox (1), +.BR dos2unix (1), +.BR head (1), +.BR less (1), +.BR nl (1), +.BR split (1), +.BR tac (1), +.BR tee (1), +.BR xxd (1) diff --git a/man/man1/chattr.1 b/man/man1/chattr.1 new file mode 100644 index 0000000..4f9c44d --- /dev/null +++ b/man/man1/chattr.1 @@ -0,0 +1,251 @@ +.TH CHATTR 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +chattr \- change Windows file attributes +.SH SYNOPSIS +.B chattr +.RB [ \-R ] +.IR mode ... +.IR file ... +.SH DESCRIPTION +.B chattr +changes the Windows file attributes of each +.IR file . +Each +.I mode +is a +.B + +to add attributes, or a +.B \- +to remove them, followed by attribute letters: +.TP +.B r +Read-only. +.TP +.B h +Hidden. +.TP +.B s +System. +.TP +.B a +Archive. +.TP +.B t +Temporary. +.TP +.B n +Not content indexed. +.PP +Letters are case-sensitive. +Several modes may be given, as in +.BR "+hs \-r" , +and together they make one change applied to every +.IR file . +Of these six attributes, those that no mode names are left unchanged. +For other attributes, see +.BR NOTES . +Adding and removing the same attribute is an error, reported as +.BR "can\(aqt set and unset a flag" , +and then no file is changed. +.BR lsattr (1) +lists the attributes. +.PP +Arguments are read as modes up to the first that begins with neither +.B + +nor +.BR \- . +That argument and every later one is a +.IR file , +even one that begins with +.B + +or +.BR \- . +.PP +Files are changed in order. +A +.I file +that cannot be found, or whose attributes cannot be set, is reported on +standard error as +.PP +.RS 4 +.EX +chattr: can\(aqt stat \(aq\fIfile\fR\(aq: \fIreason\fR +chattr: setting flags on \fIfile\fR: \fIreason\fR +.EE +.RE +.PP +and the remaining files are still processed. +.SH OPTIONS +.B R +is recognized in any +.I mode +that begins with +.BR \- , +so +.B \-Rh +recurses and removes the hidden attribute, and +.B \-R +may follow other modes, as in +.BR "+h \-R" . +.B +R +is an error. +Unless some mode begins with +.B + +or removes an attribute, +.B chattr +fails with +.BR "must use \- or +" , +so +.B \-R +alone is an error. +There is no +.BR \-\- ; +write a first +.I file +that begins with +.B \- +or +.B + +as, for example, +.IR ./\-name . +.TP +.B \-R +Recurse: after changing a directory, change every entry in it, including +hidden entries and names that begin with a dot, and the entries of its +subdirectories. +Symbolic links and junctions are changed but not descended into. +The entries of a directory that cannot be read are skipped without a +message. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.PP +Variables that busybox-w32 reads in every applet, such as those that +control console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +Files that could not be found or changed do not affect the status. +.TP +.B 1 +An invalid command line: no +.IR file , +no mode that begins with +.B + +or removes an attribute, an unknown attribute letter, or the same +attribute both added and removed. +A usage or error message is printed on standard error, and no file is +changed. +.SH EXAMPLES +Make a file read-only, and show the result: +.PP +.RS 4 +.EX +$ chattr +r config.h +$ lsattr config.h +\-\-\-\-\-r\-\-a\-\- config.h +.EE +.RE +.PP +Clear the hidden and system attributes throughout a directory tree: +.PP +.RS 4 +.EX +$ chattr \-R \-hs backup +.EE +.RE +.PP +Make a file hidden and system, and no longer read-only: +.PP +.RS 4 +.EX +$ chattr +hs \-r desktop.ini +.EE +.RE +.SH NOTES +Differences from the e2fsprogs +.B chattr +on Linux: +.IP \(bu 2 +The attributes are Windows file attributes, not ext2 inode flags, and +the letters mean different things: +.B a +is archive, not append-only, and +.B s +is system, not secure deletion. +.IP \(bu 2 +There is no +.B = +mode: an argument that begins with +.B = +is a +.IR file . +.IP \(bu 2 +There is no +.BR \-f , +.BR \-p , +.BR \-V , +or +.BR \-v ; +each is an unknown attribute letter. +.IP \(bu 2 +Errors on individual files do not change the exit status. +.PP +.B chattr +passes +.B SetFileAttributes +only the six attributes above, so any other attribute that call can +set, such as offline, pinned, or unpinned, is cleared from every file +.B chattr +changes, even when no mode names it. +A mode of +.B + +alone adds nothing, so +.BI "chattr + " file +only clears those attributes. +Pinned and unpinned record whether cloud storage such as OneDrive keeps +a file on the device. +Other attributes that +.BR lsattr (1) +shows, such as compressed, encrypted, and sparse, cannot be changed. +.PP +The temporary attribute cannot be set on a directory. +The attempt fails with +.BR "Invalid argument" , +and none of that directory's attributes change, though with +.B \-R +its entries still do. +.PP +A symbolic link or junction is changed itself, not its target. +Devices such as +.I /dev/null +are skipped without a message. +.PP +File names may use drive letters and backslashes. +A bare drive such as +.I C: +names the current directory of that drive. +On Windows 10 version 1903 or later, file names may contain any Unicode +characters, and on older systems only those of the system code page. +A path of 260 or more characters, counting the current directory when the +path is relative, cannot be changed and is reported as +.B can\(aqt stat +like a missing file. +.SH SEE ALSO +.BR busybox (1), +.BR chmod (1), +.BR lsattr (1) diff --git a/man/man1/chmod.1 b/man/man1/chmod.1 new file mode 100644 index 0000000..4811900 --- /dev/null +++ b/man/man1/chmod.1 @@ -0,0 +1,367 @@ +.TH CHMOD 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +chmod \- change file permissions +.SH SYNOPSIS +.B chmod +.RB [ \-Rcvf ] +.I mode +.IR file ... +.SH DESCRIPTION +.B chmod +changes the permissions of each +.I file +according to +.IR mode . +On Windows this sets or clears the read-only attribute; see +.BR Windows , +below. +.PP +Files are processed in order. +A file that cannot be found or changed is reported on standard error, +and the remaining files are still processed. +.SS Modes +A +.I mode +is octal or symbolic. +.PP +An octal +.I mode +is a number from 0 to 7777, written with octal digits only, that +replaces the whole mode. +It is the sum of 4000 for set-user-ID, 2000 for set-group-ID, 1000 for +sticky, and read 4, write 2, and execute 1, times 100 for the owner, 10 +for the group, and 1 for others. +An octal +.I mode +cannot be combined with symbolic clauses. +.PP +A symbolic +.I mode +is a list of clauses separated by commas, applied in turn to the file's +current mode. +A clause is zero or more class letters, +.B u +for the owner, +.B g +for the group, +.B o +for others, and +.B a +for all three, then one or more operations, as in +.BR u+r\-x . +An operation is an operator followed by zero or more permission letters, +or by a single class letter. +The operators are: +.TP +.B + +Add the permissions to the named classes. +.TP +.B \- +Remove the permissions from the named classes. +.TP +.B = +Clear all permissions of the named classes, then add the given ones. +.PP +The permission letters are: +.TP +.B r +Read. +.TP +.B w +Write. +.TP +.B x +Execute. +.TP +.B X +Execute, but only if the file is a directory or has some execute bit +set, counting changes made earlier in the +.IR mode . +.TP +.B s +Set-user-ID with +.BR u , +set-group-ID with +.BR g , +and both with +.B a +or no class letters. +.TP +.B t +Sticky, only with +.B a +or no class letters. +.PP +A class letter +.BR u , +.BR g , +or +.B o +after the operator stands for the read, write, and execute permissions +that class has at that point, as in +.BR g=u . +.PP +With no class letters, a clause acts as with +.BR a , +except that it neither adds nor removes the bits set in the umask, +though +.B = +still clears them. +See +.BR BB_UMASK . +An empty clause, or an empty +.IR mode , +changes nothing. +Any other text, such as a class letter at the end of the +.IR mode , +makes the +.I mode +invalid. +.SS Windows +Windows files have no Unix mode. +busybox-w32 derives one for each file from its attributes, name, and +contents, as shown by +.BR "ls \-l" , +and a symbolic +.I mode +is applied to that. +Of the resulting mode, +.B chmod +uses only the owner write bit, 200. +If it is clear, +.B chmod +sets the read-only attribute of +.IR file , +and if it is set, +.B chmod +clears it. +The other bits are discarded, and other attributes are unchanged. +So +.BR u\-w , +.BR a\-w , +and +.B 444 +make a file read-only, +.BR u+w , +.BR a+w , +and +.B 644 +make it writable, and +.B +x +and +.B go\-w +change nothing. +.PP +In the derived mode, a directory has every read, write, and execute bit +set. +Any other file has every read bit, every write bit unless it is +read-only, and every execute bit if it is named with a +.BR .com , +.BR .exe , +.BR .sh , +.BR .bat , +or +.B .cmd +suffix, in any case, or if its contents begin with +.B #!\& +or are a Windows program other than a DLL. +Group and other write bits that are set in the umask are clear. +.B chmod +cannot change the execute bits. +.PP +A directory never becomes read-only: whatever the +.IR mode , +.B chmod +clears the read-only attribute of every directory it processes. +.SH OPTIONS +Options may be grouped, as in +.BR \-Rv , +and may follow the operands unless +.B POSIXLY_CORRECT +is set. +A +.I mode +that begins with a dash, such as +.BR \-w , +is taken as the +.IR mode , +not as options. +.B \-\- +ends the options, for a +.I file +whose name begins with a dash. +.TP +.B \-R +Recurse: change each +.I file +that is a directory, then everything below it. +Symbolic links and junctions found inside are skipped, and one named as +a +.I file +is not descended into. +A directory whose mode cannot be changed is not descended into. +.TP +.B \-c +For each file whose mode changes, print a line on standard output: +.RS +.PP +.EX +mode of \(aq\fIfile\fR\(aq changed to \fIoctal\fR (\fIperms\fR) +.EE +.RE +.IP +where +.I octal +is the new mode as 4 octal digits and +.I perms +is its 9 permission characters, as in the +.B ls \-l +format. +.TP +.B \-v +Print that line for every file, whether or not its mode changes. +.TP +.B \-f +Do not report a file whose mode cannot be changed. +A file that does not exist, a directory that cannot be read, and, with +.BR \-R , +a directory whose mode cannot be changed are still reported. +The exit status is unaffected. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B BB_UMASK +The umask, in octal, for clauses with no class letters and for the +derived mode. +The kit's +.B sh +sets and exports it in its +.B umask +builtin. +When it is unset, the umask is 0002. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Variables that busybox-w32 reads in every applet, such as those that +control console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Invalid command line, with a usage message on standard error; an invalid +.IR mode ; +or a file could not be found or changed. +An invalid +.I mode +is reported at the first +.I file +that exists, and +.B chmod +stops there, before changing anything. +.SH EXAMPLES +Make a file read-only, reporting the change: +.PP +.RS 4 +.EX +$ chmod \-v a\-w config.h +mode of \(aqconfig.h\(aq changed to 0444 (r\-\-r\-\-r\-\-) +.EE +.RE +.PP +Make it writable again: +.PP +.RS 4 +.EX +$ chmod u+w config.h +.EE +.RE +.PP +Make every file in a tree writable, as after copying it from read-only +media: +.PP +.RS 4 +.EX +$ chmod \-R u+w project +.EE +.RE +.PP +Make the C sources in a tree read-only: +.PP +.RS 4 +.EX +$ find src \-name \(aq*.[ch]\(aq \-exec chmod 444 {} + +.EE +.RE +.SH NOTES +Differences from GNU chmod: +.IP \(bu 2 +There are no long options except +.BR \-\-help , +and so no +.B \-\-reference +or +.BR \-\-preserve\-root . +.IP \(bu 2 +.B \-v +reports every file as changed, even when its mode is unchanged. +.PP +.B chmod +does not change a file's owner or its access control list, which is what +usually controls access on Windows. +.PP +.B \-c +and +.B \-v +report the mode computed from the derived one, not what is stored, so +.B "chmod \-c u+x notes.txt" +reports a change that has no effect, and a directory is reported with +the mode given even though it stays writable. +.PP +Scripts that run +.B chmod +x +succeed and change nothing, and a file that begins with +.B #!\& +is already executable. +.PP +.BR lsattr (1) +shows the read-only attribute itself, including that of a directory. +To set the read-only attribute of a directory, or the hidden, system, +and other attributes, use +.BR chattr (1). +.PP +Output lines end with LF, not CRLF. +.I file +may use a drive letter and either kind of slash. +A bare drive such as +.I c: +names the current directory of that drive, and with +.B \-R +the files below it are reported as +.IR c:name . +On Windows 10 version 1903 or later, file names may contain any Unicode +characters, and on older systems only those of the system code page. +.SH SEE ALSO +.BR busybox (1), +.BR chattr (1), +.BR find (1), +.BR ls (1), +.BR lsattr (1), +.BR sh (1), +.BR stat (1) diff --git a/man/man1/cksum.1 b/man/man1/cksum.1 new file mode 100644 index 0000000..ba5cee0 --- /dev/null +++ b/man/man1/cksum.1 @@ -0,0 +1,185 @@ +.TH CKSUM 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +cksum \- print CRC checksums and sizes of files +.SH SYNOPSIS +.B cksum +.RI [ file ...] +.SH DESCRIPTION +.B cksum +prints a 32-bit CRC and the size in bytes of each +.IR file . +With no +.I file +operands, or for a +.I file +named +.BR \- , +it reads standard input. +.PP +The CRC is the one specified by POSIX for +.BR cksum : +polynomial 0x04C11DB7, most significant bit first, starting from zero. +It covers the contents followed by their length in bytes, least +significant byte first, in as few bytes as the length needs, so none for +an empty file. +The result is complemented. +It is not the CRC-32 of zip, gzip, and PNG, which +.BR crc32 (1) +prints. +.PP +Each output line is the CRC in decimal, a space, the size in bytes, a +space, and the file name as given on the command line. +When standard input is read because there are no operands, the name and +the space before it are left out. +For an operand of +.BR \- , +the name is +.BR \- . +.PP +A file that cannot be opened is reported on standard error and skipped, +and the remaining files are still read. +An error while reading a file ends the command at once. +.SH OPTIONS +.B cksum +takes no options other than +.BR \-\-help . +Any other argument that begins with a dash, except +.B \- +itself, is an invalid option, even after a +.IR file , +unless +.B POSIXLY_CORRECT +is set. +An invalid option prints a usage message on standard error. +.B \-\- +ends the options, for a +.I file +whose name begins with a dash. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when the program starts, even in +quoted operands, as needed when run from +.BR cmd.exe . +A pattern that matches nothing is left as it is. +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +names written to a console are not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every file was read, or +.B \-\-help +was given. +.TP +.B 1 +A file could not be opened or read, an option was invalid, or standard +output could not be written. +.TP +.B 141 +Standard output is a pipe whose reader exited before all output was +written. +If the pipe breaks only when the output still buffered at exit is +written, the status is 1 instead. +.SH EXAMPLES +Print the CRC and size of standard input: +.PP +.RS 4 +.EX +$ printf abc | cksum +1219131554 3 +.EE +.RE +.PP +Print the CRC and size of a file: +.PP +.RS 4 +.EX +$ cksum abc.txt +1219131554 3 abc.txt +.EE +.RE +.PP +List DLLs in two directories by checksum, so that copies with the same +contents are adjacent: +.PP +.RS 4 +.EX +$ cksum old/*.dll new/*.dll | sort +.EE +.RE +.SH NOTES +Differences from GNU coreutils: +.IP \(bu 2 +There are no options besides +.BR \-\-help . +GNU +.BR \-a , +.BR \-c , +.BR \-\-tag , +and the rest have no equivalent. +Use +.B md5sum +and the related commands for other algorithms and for checking lists. +.IP \(bu 2 +The output is the same as that of GNU +.B cksum +without options. +.PP +The usage message shows +.I file +as required, but it is optional. +.PP +Standard input is closed after it is read, so a second +.B \- +operand fails with +.BR "Bad file descriptor" , +and the command ends there. +.PP +Files and standard input are read as binary, so checksums match those +of the same bytes on other systems, and a text file with CR LF line +endings does not match a copy with LF line endings. +Output lines end with LF. +.PP +A +.I file +may be a Windows path, with a drive letter and either kind of slash, or +a busybox-w32 device name such as +.IR /dev/null . +It is printed exactly as given. +On Windows 10 version 1903 or later, file names may contain any Unicode +characters, and on older systems only those of the system code page. +A directory operand fails with +.BR "Permission denied" . +.PP +When standard output is a console, names are converted for display from +the ANSI code page to the console's output code page. +.PP +A 32-bit CRC detects accidental damage, not deliberate tampering. +.SH SEE ALSO +.BR busybox (1), +.BR crc32 (1), +.BR md5sum (1), +.BR sum (1) diff --git a/man/man1/clear.1 b/man/man1/clear.1 new file mode 100644 index 0000000..dad233f --- /dev/null +++ b/man/man1/clear.1 @@ -0,0 +1,177 @@ +.TH CLEAR 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +clear \- clear the terminal screen +.SH SYNOPSIS +.B clear +.RB [ \-\-help ] +.SH DESCRIPTION +.B clear +writes two escape sequences to standard output: +.RB ESC\ [H , +which moves the cursor to the top left corner of the screen, then +.RB ESC\ [J , +which erases from the cursor to the end of the screen. +It writes these 6 bytes even when standard output is not a terminal. +.PP +When standard output is a console with virtual terminal processing +enabled, the console interprets the sequences; see +.BR BB_TERMINAL_MODE . +Otherwise busybox emulates them through the console API: it moves the +cursor to the top left corner of the console window and fills the window +from there to the bottom with spaces. +Either way only the visible window is cleared, and text that has +scrolled above it stays in the scrollback. +.PP +When standard output is not a console, such as a file or a pipe, the +bytes are written unchanged, for whatever reads them to interpret. +.SH OPTIONS +.B clear +takes no options, and ignores its arguments unless the first is +.BR \-\-help . +.TP +.B \-\-help +Print a usage message on standard output and exit. +.SH ENVIRONMENT +These variables are read only when standard output is a console. +.TP +.B BB_TERMINAL_MODE +How busybox handles escape sequences written to a console. +With +.B 0 +or +.BR 2 , +it disables the console's virtual terminal processing and emulates the +sequences itself. +With +.B 1 +or +.BR 3 , +it enables virtual terminal processing and passes the sequences +through, even if the console cannot interpret them. +With +.BR 4 , +it passes them through if the console already has virtual terminal +processing enabled, and otherwise emulates them. +With +.BR 5 , +it enables virtual terminal processing if the console supports it, and +otherwise emulates the sequences. +A number outside 0 to 5 means +.BR 5 , +and text that is not a number means +.BR 0 . +.TP +.B BB_SKIP_ANSI_EMULATION +Used when +.B BB_TERMINAL_MODE +is unset: +.B 1 +means mode +.BR 1 , +.B 2 +means mode +.BR 5 , +and any other value means mode +.BR 0 . +.TP +.B CONEMUPID +When neither of the above is set, the mode is +.BR 5 , +or +.B 0 +if +.B CONEMUPID +is set, as under ConEmu, or when running under Wine. +.PP +The busybox startup code also reads +.BR BB_CRITICAL_ERROR_DIALOGS , +.BR BB_GLOBBING , +and +.BR BB_UMASK , +and console output reads +.BR LC_ALL , +.BR LC_CTYPE , +and +.BR LANG , +none of which changes what +.B clear +does; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Standard output could not be written, as when it is closed. +.TP +.B 141 +Standard output is a pipe whose reader has exited. +.SH EXAMPLES +Clear the screen: +.PP +.RS 4 +.EX +$ clear +.EE +.RE +.PP +Clear the screen before a build, so that only its messages show: +.PP +.RS 4 +.EX +$ clear && make +.EE +.RE +.PP +Save the sequence in a variable, and clear the screen with it later +without running +.BR clear : +.PP +.RS 4 +.EX +$ cls=$(clear) +$ printf %s "$cls" +.EE +.RE +.SH NOTES +Differences from the ncurses +.BR clear : +.IP \(bu 2 +It writes the same sequence regardless of +.BR TERM , +and does not use terminfo. +.IP \(bu 2 +Like ncurses +.BR "clear \-x" , +it never clears the scrollback. +.IP \(bu 2 +It has no +.BR \-T , +.BR \-V , +or +.B \-x +options, and ignores other arguments instead of rejecting them. +.PP +To also erase the scrollback of a classic console window, use +.BR reset , +which clears the console's whole screen buffer. +.PP +At an interactive +.B sh +prompt, Ctrl-L clears the screen the same way, keeping the command line +being edited. +.PP +The kit's +.B sh +runs +.B clear +inside the shell process, without starting a new one, except where the +shell needs a separate process anyway, as for a command substitution or +a pipeline. +When it runs inside the shell and standard output is a pipe whose +reader has exited, it ends the shell itself with status 141. +.SH SEE ALSO +.BR busybox (1), +.BR reset (1), +.BR sh (1) diff --git a/man/man1/cmp.1 b/man/man1/cmp.1 new file mode 100644 index 0000000..45f84cf --- /dev/null +++ b/man/man1/cmp.1 @@ -0,0 +1,284 @@ +.TH CMP 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +cmp \- compare two files byte by byte +.SH SYNOPSIS +.B cmp +.RB [ \-l | \-s ] +.RB [ \-n +.IR count ] +.I file1 +.RI [ file2 +.RI [ skip1 +.RI [ skip2 ]]] +.SH DESCRIPTION +.B cmp +compares +.I file1 +with +.I file2 +byte by byte and reports the first difference. +A file named +.B \- +is standard input, and +.I file2 +defaults to +.BR \- . +If both files are +.BR \- , +.B cmp +exits with status 0 without reading. +.PP +.I skip1 +and +.I skip2 +are numbers of bytes to skip at the start of +.I file1 +and +.IR file2 , +and +.I skip2 +defaults to 0. +Each is a decimal number, optionally followed by a suffix that +multiplies it: +.BR k , +.BR K , +.BR kiB , +or +.B KiB +for 1024; +.BR m , +.BR M , +.BR miB , +or +.B MiB +for 1048576; +.BR g , +.BR G , +.BR giB , +or +.B GiB +for 1073741824; and +.BR KB , +.BR MB , +or +.B GB +for powers of 1000. +Skipped bytes are read and discarded, so skipping works on pipes, and a +file shorter than its skip is compared as empty. +.PP +At the first differing byte, +.B cmp +writes a line to standard output and stops: +.PP +.RS 4 +.EX +\fIfile1\fR \fIfile2\fR differ: byte \fIn\fR, line \fIm\fR +.EE +.RE +.PP +.I n +is the position of the byte, counting from 1, and +.I m +is 1 plus the number of LF bytes before it. +Both count from the skip points. +If one file ends before a difference is found, +.B cmp +instead writes +.PP +.RS 4 +.EX +cmp: EOF on \fIfile\fR +.EE +.RE +.PP +to standard error, naming the shorter file. +Files are named in messages as given on the command line, and an absent +.I file2 +as +.BR \- . +.SH OPTIONS +Options may be grouped, as in +.BR "\-ln 100" , +and the argument of +.B \-n +may be attached, as in +.BR \-n100 . +Long options may be abbreviated to a unique prefix, and the argument of +.B \-\-bytes +may follow +.B = +or be the next argument. +Options may follow operands, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +.TP +.BR \-l ", " \-\-verbose +Report every differing byte, not only the first. +For each, write a line to standard output with its position in decimal +and its values in +.I file1 +and +.I file2 +in octal, separated by spaces, with each octal value padded on the left +with spaces to 3 characters. +If one file is shorter, the EOF message follows the lines for the bytes +the files have in common. +Incompatible with +.BR \-s . +.TP +.BR \-s ", " \-\-quiet ", " \-\-silent +Write no difference or EOF message, and no message when a file cannot +be opened, so only the exit status reports the result. +Read errors and command line errors are still reported. +Incompatible with +.BR \-l . +.TP +\fB\-n\fR \fIcount\fR, \fB\-\-bytes=\fIcount\fR +Compare at most +.I count +bytes after the skips. +.I count +is a decimal number from 0 to 2147483647, with no suffix. +If given more than once, the last is used. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit with status 0. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when +.B cmp +starts, as needed when it is run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +The files are identical, or identical in their first +.I count +bytes, or both are +.BR \- . +.TP +.B 1 +A difference was found, or one file ended before the other. +Also an invalid command line, including an invalid +.IR count , +.IR skip1 , +or +.IR skip2 , +with a message on standard error. +.TP +.B 2 +A file could not be opened or read, or standard output could not be +written, as when it is a pipe whose reader has exited. +.TP +.B 141 +With +.BR \-l , +standard output is a pipe whose reader exited before +.B cmp +finished writing a long listing. +.SH EXAMPLES +Compare two files: +.PP +.RS 4 +.EX +$ cmp old.txt new.txt +old.txt new.txt differ: byte 15, line 2 +.EE +.RE +.PP +List every differing byte: +.PP +.RS 4 +.EX +$ cmp \-l old.txt new.txt +15 107 147 +22 56 41 +.EE +.RE +.PP +Check in a script whether a rebuilt program is unchanged: +.PP +.RS 4 +.EX +$ if cmp \-s old/prog.exe prog.exe; then echo unchanged; fi +.EE +.RE +.PP +Compare the output of a program with the expected output: +.PP +.RS 4 +.EX +$ ./prog | cmp \- expected.txt +.EE +.RE +.PP +Compare a 4 KiB file with the data at offset 1 MiB of a disk image: +.PP +.RS 4 +.EX +$ cmp \-n 4096 part.bin disk.img 0 1M +.EE +.RE +.SH NOTES +Differences from GNU cmp: +.IP \(bu 2 +There is no +.BR \-b , +.BR \-i , +or +.BR \-v , +nor their long forms. +.IP \(bu 2 +.I count +takes no suffix and is at most 2147483647. +.IP \(bu 2 +The EOF message does not give the byte and line number where the shorter +file ends. +.IP \(bu 2 +.B \-l +does not pad positions to a common width. +.IP \(bu 2 +An invalid command line exits with status 1, the same as for differing +files, not 2. +.PP +Files and standard input are read in binary mode, so text with CRLF line +endings differs from the same text with LF line endings. +Output lines end with LF, not CRLF. +.PP +.I file1 +and +.I file2 +may be Windows paths, with a drive letter and either kind of slash, or +busybox-w32 device names such as +.I /dev/null +and +.IR /dev/zero . +Since +.I /dev/zero +never ends, +.BI "cmp " file " /dev/zero" +writes only the EOF message, and exits with status 1, when +.I file +contains nothing but zero bytes. +File names may contain any Unicode characters on Windows 10 version 1903 +and later, and are limited to the ANSI code page on earlier versions. +.SH SEE ALSO +.BR busybox (1), +.BR diff (1), +.BR xxd (1) diff --git a/man/man1/comm.1 b/man/man1/comm.1 new file mode 100644 index 0000000..e89315f --- /dev/null +++ b/man/man1/comm.1 @@ -0,0 +1,211 @@ +.TH COMM 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +comm \- compare two sorted files line by line +.SH SYNOPSIS +.B comm +.RB [ \-123 ] +.I file1 +.I file2 +.SH DESCRIPTION +.B comm +compares two files whose lines are sorted, and writes three columns: +lines only in +.IR file1 , +lines only in +.IR file2 , +and lines in both. +Either file may be +.BR \- , +for standard input. +.PP +.B comm +reads a line from each file and compares the two as bytes. +If they are equal, it writes the line in the third column and reads the +next line of both files. +Otherwise it writes the lesser line in the column of its file and reads +the next line of that file only. +When one file ends, the rest of the other is written in its column. +Repeated lines pair off one to one: a line that appears three times in +.I file1 +and once in +.I file2 +is written once in the third column and twice in the first. +.PP +The result is correct only when both files are sorted in byte order, as +.B sort +with no options sorts them. +Input out of order is not detected. +Lines in both files may then be reported as unique, with no message and +exit status 0. +.PP +Each output line is an input line preceded by one tab for each column to +its left that is not suppressed. +Without options, a line in the second column starts with one tab, and a +line in the third column with two. +Output follows the merged order of the input. +.PP +A line ends at a newline, and the last line of a file need not have one. +A carriage return directly before the newline is removed, so files with +CRLF and LF line endings compare equal. +A NUL byte also ends a line, and is not written. +Every output line ends with LF. +.SH OPTIONS +Options may be grouped, as in +.BR \-12 , +and may follow the operands, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +With all three options, +.B comm +writes nothing. +.TP +.B \-1 +Suppress the first column: lines only in +.IR file1 . +.TP +.B \-2 +Suppress the second column: lines only in +.IR file2 . +.TP +.B \-3 +Suppress the third column: lines in both files. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Variables that busybox-w32 reads in every applet, such as those that +control console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, whether or not the files have lines in common. +.TP +.B 1 +Invalid command line, such as an unknown option or other than two +operands, with a usage message on standard error; a file could not be +opened; or memory ran out. +.TP +.B 141 +A write to standard output failed because it is a pipe whose reader +has exited. +.SH EXAMPLES +Show the three columns: +.PP +.RS 4 +.EX +$ cat a.txt +apple +banana +cherry +$ cat b.txt +banana +cherry +fig +$ comm a.txt b.txt +apple + banana + cherry + fig +.EE +.RE +.PP +Print the lines in both files: +.PP +.RS 4 +.EX +$ comm \-12 a.txt b.txt +banana +cherry +.EE +.RE +.PP +Print the lines only in the first file: +.PP +.RS 4 +.EX +$ comm \-23 old.txt new.txt +.EE +.RE +.PP +Print the lines only in the second of two unsorted lists, sorting both +first and passing the second on standard input: +.PP +.RS 4 +.EX +$ sort old.txt >old.sorted +$ sort new.txt | comm \-13 old.sorted \- +.EE +.RE +.SH NOTES +Differences from GNU comm: +.IP \(bu 2 +Input order is never checked. +GNU comm reports unsorted input by default, and then exits with status 1. +.IP \(bu 2 +Lines are compared as bytes, not in the collation order of the locale. +.IP \(bu 2 +The only long option is +.BR \-\-help : +there is no +.BR \-\-check\-order , +.BR \-\-nocheck\-order , +.BR \-\-output\-delimiter , +or +.BR \-\-total , +and no +.BR \-z . +.IP \(bu 2 +A carriage return before a newline is removed, and a NUL byte ends a +line. +.PP +Because lines are compared as bytes, both files must use the same +encoding, and a byte order mark at the start of a file is part of its +first line. +Lines may be of any length. +A read error ends a file silently. +.PP +Errors writing standard output, other than a pipe whose reader has +exited, are ignored. +Output still buffered when +.B comm +finishes is written at exit without any check, so a failure there leaves +the exit status 0. +.PP +Both operands may be +.BR \- , +but the two files then read from the same standard input, and the +result is meaningless. +.PP +.I file1 +and +.I file2 +may be Windows paths, with a drive letter and either kind of slash, or a +busybox-w32 device name such as +.IR /dev/null . +On Windows 10 version 1903 or later, file names may contain any Unicode +characters, and on older systems only those of the system code page. +.SH SEE ALSO +.BR busybox (1), +.BR cmp (1), +.BR diff (1), +.BR join (1), +.BR sort (1), +.BR uniq (1) diff --git a/man/man1/cp.1 b/man/man1/cp.1 new file mode 100644 index 0000000..ef32613 --- /dev/null +++ b/man/man1/cp.1 @@ -0,0 +1,574 @@ +.TH CP 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +cp \- copy files and directories +.SH SYNOPSIS +.B cp +.RI [ options ] +.I source dest +.br +.B cp +.RI [ options ] +.IR source ...\& +.I directory +.br +.B cp +.RI [ options ] +.BI "\-t " directory +.IR source ...\& +.SH DESCRIPTION +.B cp +copies files, and with +.B \-R +directories, to another name or into a directory. +It is the +.BR busybox (1) +applet, which has fewer options than GNU +.BR cp ; +see +.BR NOTES . +.SS Operands +With +.BR \-t , +every operand is a +.I source +and is copied into +.IR directory . +Otherwise, with two operands, +.I source +is copied to +.I dest +itself, except that when +.I dest +is an existing directory, or a symbolic link or junction to one, +.I source +is copied into it. +.B \-T +always copies to +.IR dest . +With more than two operands, the last is +.IR directory . +.PP +A copy into +.I directory +is named after the last component of +.IR source , +with trailing slashes and backslashes removed, so +.B cp \-r src/ out +makes +.I out/src +when +.I out +exists. +.B cp +does not check beforehand that +.I directory +exists or is a directory: the copy of each +.I source +then fails on its own. +.PP +It is an error for a destination to be the same file as its source. +.B cp +compares the volume and file index, so names that differ only in case, +and hard links to one file, are detected. +.SS What is copied +A regular file is copied to a new file. +A directory is copied only with +.BR \-R : +it is created if it does not exist, or merged with the existing +directory if it does, and all its entries, hidden ones included, are +copied into it. +Without +.BR \-R , +a directory is reported as omitted, and the exit status is 1. +.PP +A symbolic link is followed, and the file it points to is copied, unless +.BR \-d , +.BR \-P , +.BR \-R , +or +.B \-a +is given and +.B \-L +is not. +Then the link itself is copied, as a new symbolic link with the same +target, except that +.B \-H +still follows a link named as an operand. +Junctions and app execution aliases are symbolic links for this purpose. +.PP +Without +.BR \-R , +any other source that is not a directory is copied by reading it, so a +device or standard input can be a source. +With +.BR \-R , +a source that is not a regular file, directory, or symbolic link, such +as a device, cannot be copied and is an error. +.SS Existing destinations +.B cp +never writes into an existing destination file. +It creates the destination as a new file, and when the name is taken it +deletes the old file, even a read-only one, and creates it again. +So other hard links to the old file keep its contents, a symbolic link +at the destination is replaced rather than followed, and the old file's +attributes are lost. +A file that cannot be deleted, such as a running program, is not +replaced, but loses any read-only attribute, and the copy fails with +.BR "File exists" . +.B \-n +and +.B \-u +skip some existing destinations, and +.B \-i +asks first. +.PP +A new file has the read-only attribute of its source and the current +time as its modification time; see +.BR \-p . +.SS Output +.B cp +reports each error on standard error as +.BI "cp: " message +and goes on with the remaining entries and operands. +Prompts go to standard error. +Only +.B \-v +writes to standard output. +.SH OPTIONS +Options may be grouped, as in +.BR \-rv . +They may follow operands unless +.B POSIXLY_CORRECT +is set. +The argument of +.B \-t +may be attached, as in +.BR \-tbin . +A long option may be abbreviated to any unambiguous prefix, and takes +its argument after +.B = +or as the next argument. +.B \-\- +ends the options. +.TP +.BR \-a ", " \-\-archive +Same as +.BR \-dpR . +.TP +.BR \-R ", " \-r ", " \-\-recursive +Copy directories recursively. +Implies +.BR \-d . +.TP +.BR \-d ", " \-P ", " \-\-no\-dereference +Copy symbolic links as links, not the files they point to, including +links named as operands unless +.B \-H +is given. +Overridden by +.BR \-L , +wherever it appears. +.TP +.BR \-L ", " \-\-dereference +Follow every symbolic link, including those found while recursing, and +copy the file it points to. +Overrides +.BR \-d , +.BR \-P , +and the +.B \-d +implied by +.B \-R +and +.BR \-a . +.TP +.B \-H +Follow symbolic links named as operands. +With +.BR \-R , +links found while recursing are still copied as links. +Has no effect when links are followed anyway. +.TP +.B \-p +Preserve attributes. +Set the access and modification times of each copied file and directory +to the source's modification time, in whole seconds, and its read-only +attribute to the source's. +A directory gets its time after its contents are copied, and never +becomes read-only. +Ownership is not changed. +A failure to set these is reported but does not change the exit status. +.TP +.BR \-f ", " \-\-force +Has no effect. +An existing destination is always replaced, as described above. +.TP +.BR \-i ", " \-\-interactive +Before replacing an existing destination file, write +.BI "cp: overwrite \(aq" dest "\(aq?\&" +on standard error and read a line from standard input. +The destination is replaced only if the first character of the line +that is not a space or tab is +.B y +or +.BR Y , +and otherwise it is skipped, which is not an error. +Existing directories are merged without asking. +The prompt appears whenever creating the destination fails, so it can +also appear for a destination that does not exist, and a +.B y +then reports the error. +.B \-i +and +.B \-n +override each other, and the last one given wins. +.TP +.BR \-n ", " \-\-no\-clobber +Skip, without a message, each source whose destination exists. +This includes directories: with +.BR \-R , +an existing destination directory is skipped whole, and nothing is +copied into it. +.TP +.BR \-l ", " \-\-link +Make hard links instead of copying files. +With +.BR \-R , +directories are created and the files in them linked. +The file system must support hard links, and both names must be on the +same volume. +Cannot be combined with +.BR \-s . +.TP +.BR \-s ", " \-\-symbolic\-link +Make symbolic links instead of copying files. +With +.BR \-R , +directories are created and the files in them linked. +Each link's target is +.I source +as written, so a relative +.I source +is resolved relative to the directory containing the link, not to the +current directory. +Cannot be combined with +.BR \-l . +.TP +.BR \-T ", " \-\-no\-target\-directory +Copy to +.I dest +itself, never into it. +With +.BR \-R , +a source directory is copied to +.IR dest , +and merged with it if it is an existing directory. +A source that is not a directory, and a +.I dest +that is, is an error. +Requires exactly two operands, and is ignored with +.BR \-t . +.TP +\fB\-t\fR \fIdirectory\fR, \fB\-\-target\-directory\fR=\fIdirectory\fR +Copy every operand into +.IR directory . +.TP +.BR \-u ", " \-\-update +Skip a source that is not a directory when its destination exists and +is not older, comparing modification times in whole seconds. +Directories are always entered, so their contents are compared one by +one. +.TP +.BR \-v ", " \-\-verbose +Write +.BI \(aq source "\(aq \-> \(aq" dest \(aq +on standard output for each file, directory, and symbolic link copied. +A directory is written after its contents. +Links made by +.B \-l +or +.BR \-s , +skipped files, and copies of devices are not written. +.TP +.B \-\-remove\-destination +Has no effect. +An existing destination is always replaced, as described above. +.TP +.B \-\-parents +Copy each source to the path formed by appending it, as written, to +.IR directory , +creating any missing directories on the way. +Leading slashes of +.I source +are dropped, and a drive letter makes the creation of the directories +fail. +When creating them fails, +.B cp +stops at once, without copying the remaining sources. +With two operands, +.I dest +must be an existing directory. +With more operands, or with +.BR \-t , +.I directory +is created when it does not exist. +An existing destination file is deleted before its source is opened, so +it is lost if the source cannot be opened. +With +.BR \-v , +.BI "removed \(aq" dest \(aq +is written for each one deleted. +.TP +.B \-\-help +As the first argument only, write a usage message on standard output +and exit with status 0. +The message omits the long options and +.BR \-v . +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when busybox starts, for a caller +such as +.B cmd.exe +that does not expand them. +When it is unset, busybox sets it to +.B 0 +for the programs it starts, so commands run from the kit's shell get the +shell's expansion only. +.TP +.B BB_UMASK +An octal file mode creation mask, applied before +.B cp +runs. +Only its owner write bit, +.BR 0200 , +matters here: new files are then created read-only, unless +.B \-p +sets the attribute from the source. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Messages written to a console also depend on +.BR BB_SKIP_ANSI_EMULATION , +.BR BB_TERMINAL_MODE , +.BR LANG , +.BR LC_ALL , +and +.BR LC_CTYPE , +as for every busybox applet; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, including sources skipped by +.BR \-n , +.BR \-u , +or an answer to +.BR \-i . +.TP +.B 1 +An invalid command line, with a usage message on standard error, or any +operand or directory entry that could not be copied. +.SH EXAMPLES +Keep a copy of a file before editing it, with its modification time: +.PP +.RS 4 +.EX +$ cp \-p config.h config.h.orig +.EE +.RE +.PP +Copy the C sources into a directory, listing each copy: +.PP +.RS 4 +.EX +$ cp \-v *.c backup +\(aqhello.c\(aq \-> \(aqbackup/hello.c\(aq +\(aqmain.c\(aq \-> \(aqbackup/main.c\(aq +.EE +.RE +.PP +Copy a directory tree with its times and symbolic links: +.PP +.RS 4 +.EX +$ cp \-a src src.orig +.EE +.RE +.PP +Merge one directory into another, replacing only the files that are +newer in the source: +.PP +.RS 4 +.EX +$ cp \-ruT assets build/assets +.EE +.RE +.PP +Copy only the files that do not exist in the destination: +.PP +.RS 4 +.EX +$ cp \-n *.txt backup +.EE +.RE +.PP +Copy headers into a directory tree of their own, keeping their relative +paths: +.PP +.RS 4 +.EX +$ cp \-\-parents \-t include src/*/*.h +.EE +.RE +.PP +Copy a program to a Windows path: +.PP +.RS 4 +.EX +$ cp hello.exe c:/tools/ +.EE +.RE +.SH NOTES +Differences from GNU +.BR cp : +.IP \(bu 2 +An existing destination file is deleted and created again, rather than +overwritten in place, even when it is read-only. +No prompt is shown unless +.B \-i +is given. +.IP \(bu 2 +.B \-f +and +.B \-\-remove\-destination +have no effect. +.IP \(bu 2 +.B \-n +skips an existing destination directory, instead of merging into it. +.IP \(bu 2 +A destination directory that is missing, or is not a directory, is not +detected before copying starts. +.IP \(bu 2 +Hard links among the sources are not kept, even with +.BR \-a : +each name is copied as a separate file. +.IP \(bu 2 +Copying a directory into itself copies it once, then stops with +.B recursion detected +and exit status 1. +.IP \(bu 2 +.B \-p +sets the access time to the modification time, drops fractions of a +second, and does not change ownership. +.IP \(bu 2 +.B \-v +writes a directory after its contents, and nothing for links made by +.B \-l +or +.BR \-s . +.IP \(bu 2 +Options not listed above, such as +.BR \-b , +.BR \-c , +.BR \-S , +.BR \-x , +.BR \-Z , +.BR \-\-backup , +.BR \-\-preserve , +.BR \-\-no\-preserve , +.BR \-\-reflink , +.BR \-\-sparse , +and +.BR \-\-strip\-trailing\-slashes , +are invalid. +.PP +Apart from the times set by +.BR \-p , +only a file's data and its read-only attribute are copied. +Alternate data streams, such as the +.B Zone.Identifier +stream that marks downloaded files, other attributes, such as hidden, +and security descriptors are not: a new file or directory gets the +permissions it inherits from its parent directory. +.PP +With +.BR \-R , +.BR \-d , +.BR \-P , +or +.BR \-a , +and without +.BR \-L , +a symbolic link, junction, or app execution alias is copied as a +symbolic link to the same target, never as a junction or alias. +Creating a symbolic link, here or with +.BR \-s , +needs Developer Mode or an elevated administrator, and otherwise fails +with +.BR "Permission denied" . +.PP +The Unix device names that busybox accepts, such as +.I /dev/null +and +.IR /dev/stdin , +work as a destination, and as a source without +.BR \-R ; +see +.BR busybox (1). +With +.BR \-R , +copying from a device fails with +.BR "Function not implemented" . +.I /dev/zero +and +.I /dev/urandom +have no end, and a copy of either runs until the disk is full. +.PP +Paths may have drive letters and backslashes. +Names in a directory are joined with +.BR / , +so +.B cp \-v x \(aqc:\etools\(aq +writes names such as +.IR c:\etools/x . +A bare drive such as +.I c: +names the current directory of that drive, so +.B cp x c: +writes +.IR c:x , +and +.B cp \-r c: dir +copies that directory to +.I dir +when +.I dir +does not exist. +Names may contain any Unicode character on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +A full path of 260 or more characters, or 248 or more for a directory +that +.B cp +creates, counting the current directory for a relative path, fails. +With +.BR \-R , +a source directory that cannot be listed, such as one whose full path is +258 or 259 characters, is created empty with no error message, though +.B \-v +lists it, and the exit status is 1. +.PP +From +.BR cmd.exe , +.B cp +expands wildcards in its arguments itself; see +.BR BB_GLOBBING . +Data are copied byte for byte, with no newline translation. +.SH SEE ALSO +.BR busybox (1), +.BR install (1), +.BR ln (1), +.BR mv (1) diff --git a/man/man1/cpio.1 b/man/man1/cpio.1 new file mode 100644 index 0000000..1cfd8eb --- /dev/null +++ b/man/man1/cpio.1 @@ -0,0 +1,671 @@ +.TH CPIO 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +cpio \- create, list, and extract newc cpio archives +.SH SYNOPSIS +.B cpio \-o \-H newc +.RB [ \-0L ] +.RB [ \-F +.IR file ] +.RB [ \-R +.IR owner ] +.RI [ options ] +.br +.B cpio \-i +.RB [ \-dmuv ] +.RB [ \-F +.IR file ] +.RB [ \-R +.IR owner ] +.RI [ options ] +.RI [ pattern ...] +.br +.B cpio \-t +.RB [ \-v ] +.RB [ \-F +.IR file ] +.RB [ \-R +.IR owner ] +.RI [ options ] +.RI [ pattern ...] +.SH DESCRIPTION +.B cpio +creates, lists, and extracts archives in the SVR4 cpio format with ASCII +headers, known as +.BR newc . +This is the busybox +.BR cpio . +Its three modes are chosen by +.BR \-o , +.BR \-i , +and +.BR \-t : +.TP +.B \-o +Create an archive. +It reads a list of file names from standard input and writes the archive +to standard output. +.TP +.B \-i +Extract the files in an archive read from standard input. +.TP +.B \-t +List the entries in an archive read from standard input. +.PP +.B \-F +names a file to use instead of standard input or output. +Archives are never compressed or decompressed, so a compressed archive +goes through a program such as +.BR gzip (1) +or +.BR zcat (1). +.SS Creating +Each line of standard input names one file, and a CR before the LF is +removed. +With +.BR \-0 , +names end with NUL bytes instead, and nothing else is removed. +Empty names are skipped, and leading +.B ./ +components are removed. +Other names are stored as given, with backslashes, drive letters, and +.B ..\& +components unchanged. +.PP +A directory is stored as an entry of its own, without its contents, so +the list usually comes from +.BR find (1). +A symbolic link is stored as a link, unless +.B \-L +is given. +.PP +Each entry holds the file's name, type, permissions, owner, inode number, +link count, modification time, and size, followed by its contents, or for +a symbolic link, the link's target. +The names of a file with a link count above 1 are held back and written +at the end of the archive in reverse order, with the contents only on the +last one, which is the name that was listed first. +The archive ends with an entry named +.BR TRAILER!!! , +and is not padded to a multiple of 512 bytes. +.PP +A name that does not exist or cannot be read, a file of 4 GiB or more, +or a file that becomes shorter while it is read ends the command with an +error. +The archive is then incomplete and has no trailer. +.SS Reading +.B \-i +and +.B \-t +read entries up to the +.B TRAILER!!!\& +entry and ignore anything after it. +An archive that ends between entries without a trailer is accepted. +They read +.B newc +headers, which begin with +.BR 070701 , +and +.B crc +headers, which begin with +.BR 070702 , +without checking the checksums. +Other cpio formats are rejected. +Leading slashes are removed from each name. +.PP +With +.I pattern +operands, only the entries whose names match at least one pattern are +extracted or listed. +A pattern that matches nothing is not an error. +A pattern is a shell wildcard that must match the whole name. +It is case-sensitive. +.B * +and +.B ?\& +also match +.B / +and a leading period. +A backslash quotes the next character, so a backslash in a name must be +doubled in a pattern. +.SS Listing +.B \-t +prints the name of each entry on a line of its own. +With +.BR \-v , +each line holds the permissions in the form used by +.BR "ls \-l" , +the user and group IDs separated by a slash, the size right-aligned in 9 +columns, the modification time as local time in the form +.IR "YYYY\-MM\-DD hh:mm:ss" , +and the name. +A symbolic link is shown with a size of 0, and its name is followed by +.B \-> +and the target. +.PP +After the trailer, both +.B \-t +and +.B \-i +print the size of the archive on standard error as +.IB n " blocks\fR," +counting 512-byte blocks and rounding up. +Nothing is printed for an archive with no trailer. +.SS Extracting +Each entry is created under its name, relative to the current +directory. +When a file of that name exists and its modification time is the same as +or later than the entry's, the file is kept, and for an entry that is not +a directory the message +.IB name " not created: newer or same age file exists" +is printed. +Otherwise the file is removed and replaced. +With +.BR \-u , +it is removed regardless of its age, unless the entry is a directory, +which then leaves it in place. +Failing to remove a file ends the command. +.PP +By type: +.IP \(bu 2 +A regular file is created with the archived contents. +.IP \(bu 2 +A directory is created. +An error creating it is reported without ending the command. +.IP \(bu 2 +A symbolic link is created as described in +.BR NOTES . +.IP \(bu 2 +A hard link, a regular file entry with a link count above 1 and no +contents, is created after all other entries, as a link to the entry +with the same inode number that has the contents, or as an empty file if +there is none. +It fails if a +.I pattern +leaves out the entry with the contents. +.IP \(bu 2 +A device node, FIFO, or socket cannot be created on Windows, and is +reported and skipped. +.PP +The parent directory of each entry must exist, unless +.B \-d +is given. +New files and directories get the current time, unless +.B \-m +is given. +The archived owner is ignored. +.SH OPTIONS +Options may be grouped, as in +.BR \-idv , +and may follow the +.I pattern +operands unless +.B POSIXLY_CORRECT +is set. +An option's argument may be attached, as in +.BR \-Fsrc.cpio , +or be the next argument. +Long options may be abbreviated to a unique prefix, and take their +argument after +.B = +or as the next argument. +.B \-\- +ends the options. +One of +.BR \-i , +.BR \-o , +and +.B \-t +is required, or the usage message is printed. +If several are given, +.B \-o +overrides the others, and +.B \-t +overrides +.BR \-i . +Options that do not apply to the mode are ignored. +.TP +.BR \-t ", " \-\-list +List the entries. +.TP +.BR \-i ", " \-\-extract +Extract the entries. +.TP +.BR \-o ", " \-\-create +Create an archive. +Requires +.BR "\-H newc" . +.TP +\fB\-H\fR \fIformat\fR, \fB\-\-format=\fR\fIformat\fR +Set the archive format for +.BR \-o . +Only +.B newc +is supported, and any +.I format +that begins with +.B n +is taken as +.BR newc . +Without +.BR \-o , +the format is ignored, since +.B newc +and +.B crc +archives are recognized by their headers. +.TP +.B \-d +With +.BR \-i , +create the missing parent directories of each entry. +Only +.B / +separates directory names here. +.TP +.B \-m +With +.BR \-i , +set the access and modification times of each extracted file and +directory, but not symbolic link, to the archived modification time. +A directory's times change again when files are extracted into it later. +.TP +.BR \-v ", " \-\-verbose +With +.BR \-t , +print a long listing. +With +.BR \-i , +print the name of each entry on standard output after processing it, +including entries not created because a newer file exists, but not hard +links without contents. +Names are printed in the form of a plain +.B \-t +listing. +With +.BR \-o , +it has no effect. +.TP +.B \-u +With +.BR \-i , +replace existing files regardless of their age. +.TP +\fB\-F\fR \fIfile\fR, \fB\-\-file=\fR\fIfile\fR +With +.B \-t +or +.BR \-i , +read the archive from +.I file +instead of standard input. +With +.BR \-o , +create or truncate +.I file +and write the archive to it instead of standard output. +.TP +\fB\-R\fR \fIowner\fR, \fB\-\-owner=\fR\fIowner\fR +With +.BR \-o , +store +.I owner +in place of each file's owner. +With +.B \-t +or +.BR \-i , +use it in place of each entry's owner, which matters only for the IDs +that +.B \-tv +shows. +.I owner +is +.IR user , +which sets the user ID, +.BI : group\fR, +which sets the group ID, +.IB user :\fR, +which sets both to the user's ID, or +.IB user : group\fR. +A +.I user +is a decimal ID, +.BR root , +which is 0, or the name of the current user, which is 4095. +A +.I group +must be a decimal ID. +Any other name is an error. +.TP +.B \-L +With +.BR \-o , +store the file that a symbolic link or junction refers to, instead of +the link. +.TP +.BR \-0 ", " \-\-null +With +.BR \-o , +read names that end with NUL bytes, as written by +.BR "find \-print0" , +instead of lines. +.TP +.B \-\-ignore\-devno +With +.BR \-o , +store device numbers as 0. +Device numbers are always 0 on Windows, so this has no effect. +.TP +.B \-\-renumber\-inodes +With +.BR \-o , +store inode numbers counting from 1 in the order the files are first +named in the list, instead of the files' own. +The names of a hard-linked file share one number. +.TP +.B \-\-quiet +Do not print the block count. +.TP +.B \-\-to\-stdout +With +.BR \-i , +write the contents of each matching entry to standard output, one after +another, instead of creating anything. +With +.BR \-v , +the names are mixed into the same output. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit. +The message shows the short options and only the long options +.B \-\-ignore\-devno +and +.BR \-\-renumber\-inodes . +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the command line are expanded at startup into matching file +names, even if quoted, for callers such as +.B cmd.exe +that do not expand them, so a +.I pattern +such as +.B *.c +may become a list of file names. +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +patterns as the shell passed them. +.TP +.B BB_UMASK +An octal file mode creation mask applied at startup. +The default is +.BR 0002 . +With +.BR \-o , +its group and other write bits are removed from the stored permissions. +If it includes the owner write bit, +.BR 0200 , +the +.I file +created by +.B \-F +is read-only. +.TP +.B POSIXLY_CORRECT +If set, options must precede the +.I pattern +operands. +.TP +.B TZ +The time zone of the times printed by +.BR "\-t \-v" . +The format is that of the Microsoft C runtime, such as +.BR EST5EDT . +When it is unset, the Windows time zone setting applies. +.PP +As for all busybox applets, critical-error dialogs depend on +.BR BB_CRITICAL_ERROR_DIALOGS , +and output to a console depends on +.BR BB_TERMINAL_MODE , +.BR BB_SKIP_ANSI_EMULATION , +.BR LC_ALL , +.BR LC_CTYPE , +and +.BR LANG ; +see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, including when some entries were reported and not created: a +directory that could not be made, a device node, FIFO, or socket, or a +file kept because a newer one exists. +.TP +.B 1 +An invalid command line, reported with a usage message on standard +error, an unknown +.B \-R +user or group, or an error that ends the command: a damaged or truncated +archive, or a file or link that could not be read, created, or removed. +.PP +Errors are reported on standard error as +.PP +.RS 4 +.EX +cpio: \fImessage\fR +.EE +.RE +.SH EXAMPLES +Archive a directory tree: +.PP +.RS 4 +.EX +$ find src | cpio \-o \-H newc >src.cpio +.EE +.RE +.PP +List it in detail: +.PP +.RS 4 +.EX +$ cpio \-tv src.cpio +.EE +.RE +.PP +Copy a directory tree into an existing directory, replacing files that +are already there. +This stands in for the pass-through mode: +.PP +.RS 4 +.EX +$ find src | cpio \-o \-H newc | (cd dest && cpio \-idu) +.EE +.RE +.PP +Build a compressed Linux initramfs image whose files belong to root: +.PP +.RS 4 +.EX +$ cd rootfs +$ find . | cpio \-o \-H newc \-R 0:0 | gzip >../initramfs.gz +.EE +.RE +.PP +Print one file from that image: +.PP +.RS 4 +.EX +$ zcat initramfs.gz | cpio \-i \-\-to\-stdout \-\-quiet init +.EE +.RE +.SH NOTES +Differences from GNU +.BR cpio : +.IP \(bu 2 +Only +.B newc +archives are written, and +.B "\-H newc" +is required. +Only +.B newc +and +.B crc +archives are read. +.IP \(bu 2 +There is no pass-through mode, +.BR \-p , +and options not described above, such as +.BR \-A , +.BR \-B , +.BR \-a , +.BR \-c , +.BR \-f , +.BR \-l , +and +.BR \-r , +are invalid. +.IP \(bu 2 +.B \-o +prints no block count, and does not pad the archive to a multiple of 512 +bytes. +.IP \(bu 2 +.B \-R +accepts only a colon between +.I user +and +.IR group , +not a period. +.IP \(bu 2 +.B \-t +and +.B \-v +do not list the names of a hard-linked file that have no contents. +.PP +Without +.BR \-u , +extracting a directory entry where an older directory exists fails with +.BR "can't remove old file" , +since removing a directory this way fails with +.BR "Permission denied" . +This includes the +.B .\& +entry written by +.BR "find ." , +when the current directory is older. +.B \-u +avoids it. +.PP +Names are stored and extracted byte for byte: UTF-8 on Windows 10 +version 1903 and later, and the system code page on earlier versions. +Backslashes are not converted to slashes. +Names are not checked when extracting. +A name with a drive letter, such as +.IR C:/x , +a leading backslash, or +.B ..\& +components is extracted at that location, even outside the current +directory, so list an archive from an untrusted source with +.B \-t +first. +A name that is not a valid Windows file name, or a path longer than +.BR MAX_PATH , +260 characters, fails like any other directory or file that cannot be +created. +.PP +Listings, including those of +.BR \-v , +show each control character as +.BR ? , +and on Windows 10 version 1903 and later, each byte of a non-ASCII +character as well. +.PP +With +.BR \-o , +the stored attributes come from busybox-w32's emulation of Unix file +information: +.IP \(bu 2 +Everyone may read, and write unless the file is read-only, less the +group and other write bits of the umask. +Directories, and files whose names end in +.BR .bat , +.BR .cmd , +.BR .com , +.BR .exe , +or +.BR .sh , +or that begin with +.B #!\& +or are PE executables other than DLLs, are executable. +.IP \(bu 2 +A file owned by the current user has user and group ID 4095. +For a file of another owner the ID is 0, or the relative ID of the +owner's account when that is from 500 to 4094. +.IP \(bu 2 +Device numbers are 0. +Inode numbers are the low 32 bits of the file index. +Hard links are recognized by the whole file index alone, whatever the +volume. +.IP \(bu 2 +Symbolic link targets are stored with slashes for backslashes. +Junctions are stored as symbolic links to their absolute targets, such +as +.IR C:/dir . +.IP \(bu 2 +Junctions and symbolic links to directories have a link count of 2, so +they are written at the end of the archive, as hard-linked files are. +.IP \(bu 2 +Modification times are stored in 32 bits, so only times from 1970 to +2106 are kept. +.PP +When extracting, the owner write permission alone has an effect: a file +without it is made read-only. +Directories are never read-only, and nothing is made executable. +A hard link needs a file system that supports them, such as NTFS. +A symbolic link is created as a Windows symbolic link, which requires +Developer Mode or administrator rights, with backslashes for slashes in +its target. +It is a directory link only if its target is an existing directory when +the link is made. +A link whose target begins with +.B / +or contains +.BR .. , +or that cannot be made at once, is made after all other entries, and +failing then ends the command with +.BR "can't create symlink" . +.PP +Standard input and output are in binary mode, so archives pass through +unchanged. +.SH SEE ALSO +.BR busybox (1), +.BR find (1), +.BR gzip (1), +.BR sh (1), +.BR tar (1), +.BR zcat (1) diff --git a/man/man1/crc32.1 b/man/man1/crc32.1 new file mode 100644 index 0000000..5aaf3c9 --- /dev/null +++ b/man/man1/crc32.1 @@ -0,0 +1,171 @@ +.TH CRC32 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +crc32 \- compute CRC-32 checksums +.SH SYNOPSIS +.B crc32 +.RI [ file ...] +.SH DESCRIPTION +.B crc32 +prints the CRC-32 of each +.IR file . +With no +.I file +operands, or for a +.I file +named +.BR \- , +it reads standard input. +.PP +The CRC is the one used by gzip, zip, and PNG, and stored in their files: +the reflected polynomial 0xEDB88320, with an initial value and a final +exclusive or of 0xFFFFFFFF. +The CRC-32 of the 9 bytes +.B 123456789 +is +.BR cbf43926 . +.PP +Each output line is the CRC as 8 lowercase hex digits, a space, and the +file name as given on the command line. +With no +.I file +operands, the line is the CRC alone. +.PP +A file that cannot be opened is reported on standard error, and the +remaining files are still processed. +An error reading a file ends the command at once. +Standard input is closed once it has been read, so naming it a second +time is a read error. +.SH OPTIONS +.B crc32 +takes no options other than +.BR \-\-help . +Any other argument that begins with +.BR \- , +except +.B \- +and +.BR \-\- , +is an invalid option, even after a +.IR file , +unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options, so that later arguments are file names. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options, so later arguments that +begin with +.B \- +are file names. +.PP +Variables that busybox-w32 reads in every applet, such as those that +control console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An option was invalid, a file could not be opened or read, or standard +output could not be written. +.TP +.B 141 +Standard output is a pipe whose reader has exited, and a write failed +before the end of the output. +Output is buffered, and when only the final write at exit fails, as +with short output, the status is 1. +.SH EXAMPLES +Print the CRC-32 of a file: +.PP +.RS 4 +.EX +$ crc32 hello.txt +363a3020 hello.txt +.EE +.RE +.PP +Print the CRC-32 of standard input: +.PP +.RS 4 +.EX +$ printf 123456789 | crc32 +cbf43926 +.EE +.RE +.PP +Print the CRC-32 of a file in a zip archive, to compare it with the +file on disk: +.PP +.RS 4 +.EX +$ unzip \-p hello.zip hello.txt | crc32 +363a3020 +.EE +.RE +.PP +Show the CRC-32 and size stored at the end of a gzip file: +.PP +.RS 4 +.EX +$ tail \-c 8 hello.txt.gz | od \-An \-tx4 + 363a3020 00000006 +.EE +.RE +.SH NOTES +There is no standard +.B crc32 +command. +POSIX +.B cksum +computes a different CRC, which also covers the file length, and prints +it in decimal, so its values do not match those of +.BR crc32 . +.PP +The usage message shows +.I file +as required, but it is optional. +.PP +Files and standard input are read in binary mode, so the CRC of a file +matches its CRC on other systems. +Output lines end with LF, not CRLF. +.PP +.I file +may be a Windows path, with a drive letter and either kind of slash, or +a busybox-w32 device name such as +.I /dev/null +or +.IR /dev/stdin . +The name is printed as given, backslashes included. +.I /dev/stdin +does not close standard input, unlike +.BR \- , +and cannot be opened after a +.B \- +operand. +A directory operand cannot be opened, and fails with +.BR "Permission denied" . +On Windows 10 version 1903 or later, file names may contain any Unicode +characters, and on older systems only those of the system code page. +.SH SEE ALSO +.BR busybox (1), +.BR cksum (1), +.BR gzip (1), +.BR md5sum (1), +.BR unzip (1) diff --git a/man/man1/cut.1 b/man/man1/cut.1 new file mode 100644 index 0000000..dc6fc98 --- /dev/null +++ b/man/man1/cut.1 @@ -0,0 +1,571 @@ +.TH CUT 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +cut \- print selected parts of lines +.SH SYNOPSIS +.B cut +.RB { \-b | \-c } +.I list +.RB [ \-nD ] +.RB [ \-O +.IR sep ] +.RI [ file ...] +.br +.B cut +.RB { \-f | \-F } +.I list +.RB [ \-d +.IR sep ] +.RB [ \-nsD ] +.RB [ \-O +.IR sep ] +.RI [ file ...] +.SH DESCRIPTION +.B cut +reads each +.I file +a line at a time and writes the selected parts of every line: bytes with +.B \-b +or +.BR \-c , +or fields with +.B \-f +or +.BR \-F . +Exactly one of these four options is required, and it may be given only +once. +Its argument is a +.IR list , +described below. +.PP +With no +.I file +operands, or for a +.I file +named +.BR \- , +.B cut +reads standard input. +A +.I file +that cannot be opened is reported on standard error and skipped, and the +remaining files are still read. +.PP +A line ends at an LF. +A CR directly before the LF is removed, so files with CRLF and LF line +endings give the same result. +A NUL byte also ends a line, and is not written. +Lines may be of any length. +Every output line ends with an LF, even when the last input line has +none. +Each input line produces one output line, which is empty when nothing in +the line is selected. +The exceptions are the lines dropped by +.BR \-s , +and the line selection described under +.BR "Selecting lines" . +.SS Lists +A +.I list +is one or more ranges separated by commas, such as +.BR 1,4\-6,9\- . +Positions are counted from 1. +A range is one of: +.TP +.I n +Position +.IR n . +.TP +\fIn\fB\-\fIm\fR +Positions +.I n +through +.IR m , +where +.I m +is not less than +.IR n . +.TP +\fIn\fB\-\fR +Position +.I n +and every position after it, to the end of the line. +.TP +\fB\-\fIm\fR +Positions 1 through +.IR m . +.PP +Each number is a string of decimal digits, with no sign or space, and +at most 2147483647. +Position 0 is not valid. +A malformed or too large number, and a range that starts at 0 or ends +before it starts, are errors. +An empty list, an empty range as in +.BR 1,,2 , +and a lone +.B \- +are usage errors, which print the usage message. +Positions past the end of the line select nothing. +.SS Bytes +With +.B \-b +or +.BR \-c , +which are the same, the list selects byte positions. +Bytes are not decoded, so a range can split a UTF-8 character. +The bytes are written in order of position, each once, so overlapping +ranges are merged. +Nothing is written between ranges unless +.B \-O +is given. +Then its argument is written between selected ranges that are not +adjacent in the line. +.SS Fields +With +.BR \-f , +a line is split into fields at each occurrence of the delimiter byte. +That is the first byte of the +.B \-d +argument, and TAB by default. +A line with +.I n +delimiters has +.IR n +1 +fields, any of which may be empty. +The selected fields are written in order, separated by the output +delimiter. +That is the +.B \-O +argument if given, otherwise all of the +.B \-d +argument, otherwise TAB. +.PP +A line that has no delimiter is written whole, whatever the list says, +unless +.B \-s +drops it. +A line that has a delimiter always produces a line of output, which is +empty when the line has too few fields. +.PP +With +.BR \-F , +the +.B \-d +argument is instead an extended regular expression, and each match of it +in a line is a delimiter. +The default is +.BR [[:space:]]+ , +a run of white space. +With it, white space at the start of a line makes field 1 empty. +Fields are numbered as with +.BR \-f , +with these differences. +.IP \(bu 2 +Empty fields are counted but never written, and a range whose text is +empty writes nothing, not even an output delimiter. +.IP \(bu 2 +A range \fIn\fB\-\fIm\fR is written as one piece of the line, from the +start of field +.I n +to the end of field +.IR m . +The delimiters between those fields are kept as they are in the input. +.IP \(bu 2 +The default output delimiter is one space. +.PP +The expression is matched against bytes, so +.B .\& +matches one byte of a UTF-8 character. +The anchors +.B ^ +and +.B $ +never match. +An expression that matches the empty string, such as +.BR x* , +cuts the line into empty fields. +.PP +The ranges of a list are sorted by their starting position, so fields +are written in line order. +With +.B \-f +and +.BR \-F , +ranges that overlap, or name a field twice, do not work reliably: they +can write a field that no range names, or an extra output delimiter. +Give ascending ranges that do not overlap, or use +.BR \-D . +.SS Selecting lines +With +.BR \-f , +when the first byte of the +.B \-d +argument is LF, the list selects lines instead of fields. +Lines are numbered from 1 in each file. +The selected lines are written in file order, separated by the output +delimiter, which by default is all of the +.B \-d +argument, and the last is followed by an LF. +A file with no selected lines produces no output. +.B \-s +has no effect. +With +.BR \-D , +lines are still written in file order, and a range that is out of order +in the list can select nothing. +.SH OPTIONS +Options may be grouped, as in +.BR \-sd: , +and may follow the +.I file +operands. +An option's argument may be attached, as in +.BR \-d: , +or be the next argument. +The long option may be abbreviated to any unique prefix, and its +argument may follow an +.BR = , +as in +.BR \-\-out=+ . +.B \-\- +ends the options. +.TP +.BI "\-b " list +Select the bytes at the positions in +.IR list . +.TP +.BI "\-c " list +The same as +.BR \-b . +Multibyte characters are not recognized. +.TP +.BI "\-d " sep +Set the input delimiter for +.B \-f +or +.BR \-F . +The default is TAB for +.BR \-f , +and +.B [[:space:]]+ +for +.BR \-F . +With +.BR \-f , +only the first byte of +.I sep +delimits fields, and an empty +.I sep +never matches, so that every line has no delimiter. +If that byte is LF, the list selects lines. +It is an error with +.B \-b +or +.BR \-c . +.TP +.BI "\-f " list +Select the fields in +.IR list , +split at a single-byte delimiter. +.TP +.BI "\-F " list +Select the fields in +.IR list , +split at matches of a regular expression. +.TP +.B \-s +Drop lines that have no delimiter, instead of writing them whole. +Empty lines have no delimiter, and are dropped. +It is an error with +.B \-b +or +.BR \-c . +With +.BR \-D , +only empty lines are dropped. +.TP +.B \-D +Do not sort the ranges. +Each range is applied to the line on its own, in the order given, so +that fields can be reordered or written twice: the output of +.B \-D \-f3,1 +is field 3 and then field 1. +With +.B \-f +or +.BR \-F , +a line that has no delimiter is then not written whole. +It has one field, field 1, so a list that does not select field 1 gives +an empty line. +.IP +With +.B \-b +or +.BR \-c , +each byte is still written at most once, in the order of the first +range that selects it. +The +.B \-O +delimiter is written before a byte whose preceding byte in the line has +not yet been written, but only after an earlier range has ended before +the end of the line, and never before byte 1. +So on the line +.BR abc , +.B "\-D \-O: \-b3,2" +writes +.BR c:b , +while +.B "\-D \-O: \-b3,1" +writes +.BR ca . +.TP +\fB\-O\fR \fIsep\fR, \fB\-\-output\-delimiter\fR \fIsep\fR +Write +.I sep +between the selected fields, byte ranges, or lines. +It may be empty. +The default for +.B \-f +is all of the +.B \-d +argument, or TAB without +.BR \-d . +For +.B \-F +it is one space, and for +.B \-b +and +.B \-c +it is nothing. +.TP +.B \-n +Accepted and ignored. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments, including option arguments, are expanded +against file names at startup, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options, so that later arguments such as +.B \-f +are file names. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, and the console interprets the +bytes in its own code page. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An error: an unknown option, an invalid list, a missing or repeated +.BR \-b , +.BR \-c , +.BR \-f , +or +.BR \-F , +or +.B \-d +or +.B \-s +without +.B \-f +or +.BR \-F ; +an invalid regular expression; a +.I file +that could not be opened; or a failure writing standard output. +.TP +.B 141 +Standard output is a pipe whose reader exited while +.B cut +was writing. +Output still buffered when +.B cut +finishes is written as it exits, and a broken pipe found then is instead +reported as a write error, with status 1. +.PP +Errors are reported on standard error, beginning with +.BR cut: . +An unknown option, a missing or repeated list option, and an empty list +or range also print the usage message there. +The remaining files are still read after one cannot be opened. +.SH EXAMPLES +Print the first and seventh colon-separated fields: +.PP +.RS 4 +.EX +$ echo root:x:0:0:root:/root:/bin/sh | cut \-d: \-f1,7 +root:/bin/sh +.EE +.RE +.PP +Print the value of each +.B KEY=VALUE +line, keeping any further equals signs in the value, and skipping lines +without one, which would otherwise be written whole: +.PP +.RS 4 +.EX +$ cut \-s \-d= \-f2\- settings.txt +.EE +.RE +.PP +Treat each run of spaces as one delimiter: +.PP +.RS 4 +.EX +$ printf \(aqa b c\en\(aq | cut \-F2,3 +b c +.EE +.RE +.PP +Reorder fields: +.PP +.RS 4 +.EX +$ echo a:b:c | cut \-d: \-D \-f3,1 +c:a +.EE +.RE +.PP +Print lines 2 through 3 of a file, using the shell's +.B $\(aq\en\(aq +for an LF: +.PP +.RS 4 +.EX +$ cut \-d $\(aq\en\(aq \-f2\-3 file.txt +.EE +.RE +.PP +Print the first three bytes of each line: +.PP +.RS 4 +.EX +$ cut \-c1\-3 file.txt +.EE +.RE +.PP +Print every field from the second on, separated by commas: +.PP +.RS 4 +.EX +$ echo one two three | cut \-d\(aq \(aq \-f2\- \-O, +two,three +.EE +.RE +.SH NOTES +Differences from GNU cut: +.IP \(bu 2 +.BR \-F , +.BR \-D , +the short form +.BR \-O , +and line selection are additions. +.IP \(bu 2 +There is no +.BR \-z , +no +.BR \-\-complement , +and no long options but +.B \-\-output\-delimiter +and +.BR \-\-help . +A NUL byte ends a line. +.IP \(bu 2 +GNU cut rejects a +.B \-d +argument of more than one character. +Here only its first byte delimits fields, and all of it is the default +output delimiter. +.IP \(bu 2 +A list cannot contain spaces. +.IP \(bu 2 +Overlapping ranges for +.B \-f +are not merged reliably; see +.BR Fields . +.PP +Text is handled as bytes, in whatever encoding it has. +A non-ASCII delimiter for +.B \-f +splits at its first byte, so use +.B \-F +for it, which matches the whole byte sequence. +Cut UTF-8 text by field where possible, not by byte position. +.PP +Files and the standard streams are binary, so the C runtime translates +no line endings. +.B cut +removes the CR of each CRLF itself, so input CRLF becomes LF in the +output. +To write CRLF line endings, pass the output through +.BR unix2dos (1). +.PP +File names may use drive letters and backslashes. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +The device names +.IR /dev/null , +.IR /dev/zero , +.IR /dev/urandom , +.IR /dev/stdin , +and +.I /dev/tty +(the console) work as on Unix. +A directory operand fails with +.BR "Is a directory" . +.PP +When standard output is a console, bytes above 0x7F are converted for +display from the ANSI code page, which is UTF-8 on Windows 10 version +1903 and later, to the console's code page. +.PP +From +.BR cmd.exe , +wildcard characters in an argument, even a quoted one or that of +.B \-d +or +.BR \-O , +are expanded against file names unless +.B BB_GLOBBING +is +.BR 0 , +so a delimiter of +.B * +or +.B ?\& +can be replaced by file names. +A pattern that matches no file is left as it is. +Commands run from the kit's shell normally get no such expansion; see +.B BB_GLOBBING +under +.BR ENVIRONMENT . +.SH SEE ALSO +.BR awk (1), +.BR busybox (1), +.BR grep (1), +.BR paste (1), +.BR sed (1), +.BR sh (1), +.BR sort (1), +.BR unix2dos (1) diff --git a/man/man1/date.1 b/man/man1/date.1 new file mode 100644 index 0000000..eb0138a --- /dev/null +++ b/man/man1/date.1 @@ -0,0 +1,871 @@ +.TH DATE 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +date \- print or set the date and time +.SH SYNOPSIS +.B date +.RB [ \-Ru ] +.RB [ \-D +.IR infmt ] +.RB [ \-d +.IR time ] +.RB [ \-r +.IR file ] +.RB [ \-I\c +.RI [ spec ]] +.RB [ + \c +.IR outfmt ] +.br +.B date +.RB [ \-u ] +.RB [ \-D +.IR infmt ] +.RB [ + \c +.IR outfmt ] +.RB [ \-s ] +.I time +.SH DESCRIPTION +.B date +prints a time on standard output, or sets the system clock. +With no operands it prints the current time. +.B \-d +prints a given time instead, and +.B \-r +prints the modification time of a file. +A +.I time +operand or +.B \-s +sets the system clock to that time and then prints it. +.PP +The output is the formatted time and a newline. +An operand that begins with +.B + +is the output format +.IR outfmt ; +see +.BR "Output formats" . +It must come before a bare +.I time +operand, and it overrides +.B \-R +and +.BR \-I . +With none of these, the format is +.BR "%a %b %e %H:%M:%S %Z %Y" , +as in +.PP +.RS 4 +.EX +Mon Oct 19 20:29:49 Eastern Daylight Time 2026 +.EE +.RE +.PP +With +.BR \-R , +the format is that of RFC 2822, as in +.BR "Mon, 19 Oct 2026 20:29:49 \-0400" , +and with +.BR \-I , +that of ISO 8601. +.SS Time zone +Times are read and printed in the local time zone, which is the Windows +time zone setting unless +.B TZ +is set. +With +.BR \-u , +the time zone is UTC. +.SS Time formats +.BR \-d , +.BR \-s , +and a +.I time +operand take a time in one of these forms. +It must match a form entirely. +Names are in English. +In the forms with separators, a field may be written with one or two +digits, except the year. +A date field that the time does not give is taken from the current date, +or from the modification time of the +.B \-r +file, and an hour, minute, or second field that it does not give is zero. +.TP +\fIhh\fB:\fImm\fR[\fB:\fIss\fR] +A time of day on the current date. +.TP +\fIMM\fB.\fIDD\fB\-\fIhh\fB:\fImm\fR[\fB:\fIss\fR] +A month, day, and time in the current year. +.TP +\fIYYYY\fB.\fIMM\fB.\fIDD\fB\-\fIhh\fB:\fImm\fR[\fB:\fIss\fR] +A full date and time. +.TP +\fIMon\fR \fIDD\fR \fIhh\fB:\fImm\fB:\fIss\fR \fIYYYY\fR +.I Mon +is a month name in full or abbreviated to 3 letters, in any case. +There is no weekday. +.TP +\fIYYYY\fB\-\fIMM\fB\-\fIDD\fR[ \fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]]] +A date with a time of day, an hour, or neither. +.TP +\fIYYYY\fB\-\fIMM\fB\-\fIDD\fR \fIhh\fB:\fImm\fR[\fB:\fIss\fR] \fIzone\fR +A date and time in another time zone, converted to the local one. +The space before +.I zone +is optional. +.I zone +is +.BI + hhmm +or +.BI \- hhmm +for a UTC offset of up to 12 hours, +.BI + hh +or +.BI \- hh +for whole hours, or +.B Z +for UTC. +An offset is accurate to only 36 seconds, so minutes that are not a +multiple of 3 are inexact. +.TP +\fB@\fIseconds\fR +Seconds since 1970-01-01 00:00:00 UTC, as decimal digits with an +optional minus sign and nothing else. +.TP +[[[[[\fIYY\fR]\fIYY\fR]\fIMM\fR]\fIDD\fR]\fIhh\fR]\fImm\fR[\fB.\fIss\fR] +Digits only, in one of these forms: +.IR mm , +.IR hhmm , +.IR DDhhmm , +.IR MMDDhhmm , +.IR YYMMDDhhmm , +or +.IR CCYYMMDDhhmm , +followed by an optional +.BI . ss\fR. +.I YY +is the year within 50 years of the current year. +Each field is checked against its maximum, so month 13 is an error, but +month or day 00 is carried back into the previous year or month. +.PP +A seconds field of 60 is carried into the next minute, and so is 61 +except in the digits-only form. +A day that the month lacks, such as February 30, is carried into the +next month. +An hour of 24 is an error. +.PP +.B \-D +replaces these forms with +.IR infmt , +a format for the C function +.BR strptime . +Its conversions are +.BR %a , +.BR %A , +.BR %b , +.BR %B , +.BR %c , +.BR %C , +.BR %d , +.BR %D , +.BR %e , +.BR %F , +.BR %g , +.BR %G , +.BR %h , +.BR %H , +.BR %I , +.BR %j , +.BR %k , +.BR %l , +.BR %m , +.BR %M , +.BR %n , +.BR %p , +.BR %q , +.BR %r , +.BR %R , +.BR %s , +.BR %S , +.BR %t , +.BR %T , +.BR %u , +.BR %U , +.BR %V , +.BR %w , +.BR %W , +.BR %x , +.BR %X , +.BR %y , +.BR %Y , +.BR %z , +.BR %Z , +and +.BR %% . +The +.B E +modifier is ignored before +.BR c , +.BR C , +.BR x , +.BR X , +.BR y , +or +.BR Y , +and +.B O +before +.BR d , +.BR e , +.BR H , +.BR I , +.BR m , +.BR M , +.BR q , +.BR S , +.BR U , +.BR V , +.BR w , +.BR W , +or +.BR y ; +elsewhere either is an error. +A numeric conversion skips leading spaces and reads at most 2 digits, +but 1 for +.BR %q , +.BR %u , +and +.BR %w , +3 for +.BR %j , +and 4 for +.BR %Y . +.B %G +and +.B %s +read any number of digits and do not skip spaces. +White space in +.I infmt +matches any amount of white space in the input, including none. +Input left over once +.I infmt +is matched is ignored, so the input is not checked to the end. +.B %y +reads 69 to 99 as 1969 to 1999, and 00 to 68 as 2000 to 2068. +.B %s +sets the entire time from seconds since the epoch, as +.B @ +does. +.BR %g , +.BR %G , +and +.B %V +have no effect, +.B %z +is parsed but its offset is ignored, and +.B %Z +matches nothing. +.BR %a , +.BR %A , +.BR %u , +and +.B %w +have an effect only along with +.B %U +or +.BR %W , +and the reverse. +.B %j +has an effect only along with a conversion that reads the year, month, +or day. +Fields that +.I infmt +does not set are as described above. +.SS Output formats +In +.IR outfmt , +each conversion beginning with +.B % +is replaced, and everything else is copied. +Weekday and month names are in English. +These conversions are supported: +.TP +.B %% +A percent sign. +.TP +.BR %a ", " %A +The weekday name, abbreviated to 3 letters or in full. +.TP +.BR %b ", " %B +The month name, abbreviated to 3 letters or in full. +.TP +.B %c +The date and time as +.BR "11/14/23 17:13:20" : +month, day, and two-digit year, then the time. +.TP +.B %d +The day of the month, 01 to 31. +.TP +.B %e +The day of the month, 1 to 31, padded with a space. +.TP +.B %H +The hour, 00 to 23. +.TP +.B %I +The hour, 01 to 12. +.TP +.B %j +The day of the year, 001 to 366. +.TP +.B %m +The month, 01 to 12. +.TP +.B %M +The minute, 00 to 59. +.TP +.B %N +The nanoseconds, as 9 digits. +.TP +.BI % n N +The first +.I n +digits of +.BR %N , +truncated, for +.I n +from 1 to 9. +A larger +.I n +pads +.B %N +on the left with zeros to +.I n +digits, and 0 means 9. +.IP +The nanoseconds are zero with +.BR \-d , +.BR \-s , +or a +.I time +operand, and with +.B \-r +they are those of the modification time. +.TP +.B %p +.B AM +or +.BR PM . +.TP +.B %s +Seconds since 1970-01-01 00:00:00 UTC. +.TP +.B %S +The second, 00 to 59. +.TP +.B %T +The same as +.BR %H:%M:%S . +.TP +.B %U +The week of the year, 00 to 53, with weeks starting on Sunday. +.TP +.B %w +The weekday, 0 to 6, with Sunday as 0. +.TP +.B %W +The week of the year, 00 to 53, with weeks starting on Monday. +.TP +.B %x +The date as +.BR 11/14/23 . +.TP +.B %X +The time as +.BR 17:13:20 . +.TP +.B %y +The year within the century, 00 to 99. +.TP +.B %Y +The year. +.TP +.B %z +The UTC offset as +.BI + hhmm +or +.BI \- hhmm\fR. +.TP +.B %Z +The time zone name. +With the Windows time zone it is the Windows name, such as +.BR "Eastern Daylight Time" . +With +.B TZ +it is the name in +.BR TZ , +and with +.B \-u +it is +.BR UTC . +.PP +A +.B \- +after the +.B % +removes the padding of +.BR %d , +.BR %H , +.BR %I , +.BR %j , +.BR %m , +.BR %M , +.BR %S , +.BR %U , +.BR %w , +.BR %W , +.BR %y , +and +.BR %Y , +so +.B %\-d +is +.B 5 +on the fifth. +A +.B # +does the same, and also gives +.B %c +and +.B %x +long forms such as +.BR "Tuesday, November 14, 2023" . +It is ignored with +.BR %a , +.BR %A , +.BR %b , +.BR %B , +.BR %p , +.BR %X , +and +.BR %Z , +and +.B %#z +is the same as +.BR %Z . +.PP +No other conversion, flag, or field width is supported. +If +.I outfmt +has one, or the result is longer than 1023 bytes, +.B date +prints an empty line and exits with status 0. +An empty +.I outfmt +also prints an empty line. +.PP +The output of +.B \-I +depends on +.IR spec , +and the offset is +.B +00:00 +with +.BR \-u : +.PP +.RS 4 +.EX +date 2026\-10\-19 +hours 2026\-10\-19T20\-04:00 +minutes 2026\-10\-19T20:29\-04:00 +seconds 2026\-10\-19T20:29:49\-04:00 +ns 2026\-10\-19T20:29:49,033721000\-04:00 +.EE +.RE +.SS Setting the clock +A +.I time +operand or +.B \-s +sets the system clock, reading the time as local time, or as UTC with +.BR \-u . +The new time is then printed as usual. +Setting the clock needs administrator rights. +Without them, +.B date +prints +.PP +.RS 4 +.EX +date: can\(aqt set date: Operation not permitted +.EE +.RE +.PP +and exits with status 1. +That message is printed whenever Windows refuses to set the clock. +.PP +A bare +.I time +operand that is only digits, with an optional +.BI . ss +of exactly two digits, is read differently from the digits-only form +above: as +\fIMMDDhhmm\fR[[\fICC\fR]\fIYY\fR][\fB.\fIss\fR], +with the year last, which is the POSIX form. +It must have 8, 10, or 12 digits, and any other count is an error. +For example, +.B 1019123420 +is 12:34 on 19 October 2020, but +.B \-s 1019123420 +is an error, since it is read as +.IR YYMMDDhhmm , +with month 19. +.B \-s 2010191234 +sets the same time. +Such an operand is checked and reordered this way even with +.BR \-D , +before +.I infmt +reads it. +.SH OPTIONS +Options may be grouped, as in +.BR \-uR , +and may follow the operands unless +.B POSIXLY_CORRECT +is set. +An option's argument may be attached, as in +.BR \-d@0 , +or be the next argument. +The exception is the optional argument of +.BR \-I , +which must be attached, so in a group +.B \-I +comes last. +A long option may be abbreviated to any unambiguous prefix, and its +argument is attached with +.B = +or is the next argument. +.B \-\- +ends the options. +.TP +.BR \-u ", " \-\-utc +Print or set the time in UTC. +For this command only, it sets +.B TZ +to +.BR UTC0 , +overriding any +.BR TZ . +.TP +\fB\-s\fR \fItime\fR, \fB\-\-set\fR \fItime\fR +Set the system clock to +.IR time ; +see +.BR "Setting the clock" . +Incompatible with +.BR \-d . +.TP +\fB\-d\fR \fItime\fR, \fB\-\-date\fR \fItime\fR +Print +.I time +instead of the current time. +Incompatible with +.BR \-s . +.TP +.BI "\-D " infmt +Read +.I time +with the +.B strptime +format +.I infmt +instead of the forms in +.BR "Time formats" . +It applies to the argument of +.B \-d +and +.BR \-s , +and to a bare +.I time +operand, which sets the clock. +.TP +\fB\-r\fR \fIfile\fR, \fB\-\-reference\fR \fIfile\fR +Print the modification time of +.I file +instead of the current time. +If +.I file +cannot be examined, it is an error. +With a +.I time +to print or set, it only supplies the fields that +.I time +leaves out. +.TP +.BR \-R ", " \-\-rfc\-2822 +Print the time in the form of RFC 2822: +.BR "%a, %d %b %Y %H:%M:%S %z" . +.B \-\-rfc\-822 +is a synonym. +Incompatible with +.BR \-I . +.TP +\fB\-I\fR[\fIspec\fR] +Print the time in the form of ISO 8601, to the precision +.IR spec : +.B date +(the default), +.BR hours , +.BR minutes , +.BR seconds , +or +.BR ns , +which adds nanoseconds after a comma. +All but +.B date +end with the UTC offset, as in +.BR \-04:00 . +.I spec +may be abbreviated to any unambiguous prefix, such as +.B h +or +.BR n . +Any other value is an error. +Incompatible with +.BR \-R . +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +If set, options must precede the operands. +.TP +.B TZ +The local time zone. +The format is that of the Microsoft C runtime: a three-letter zone name, +the hours to add to local time to give UTC, optionally followed by +minutes and seconds after colons, and an optional three-letter daylight +saving zone name, as in +.BR EST5EDT , +.BR JST\-9 , +or +.BR IST\-5:30 . +The offset is read from the fourth character, so a longer standard name +is misread: in +.B CEST\-2 +the zone is +.B CES +at UTC and the daylight saving name is +.BR T\-2 . +A longer daylight saving name is cut to three letters. +Daylight saving time in a +.B TZ +that names it follows the United States rules, whatever the zone. +A value the C runtime rejects, such as +.B Europe/Paris +or one beginning with a colon, is ignored, as is an empty value. +Then the Windows time zone setting applies. +.B \-u +sets it to +.B UTC0 +for the command. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid option or operand, with a usage message on standard error. +That includes +.B \-d +with +.BR \-s , +.B \-R +with +.BR \-I , +an unknown +.B \-I +argument, and an extra operand. +Also a +.I time +that matches no form, or is outside the supported range, reported as +an invalid date; a +.B \-r +file that cannot be examined; and a clock that cannot be set. +.SH EXAMPLES +Print the current time in UTC in ISO 8601 form: +.PP +.RS 4 +.EX +$ date \-u +%Y\-%m\-%dT%H:%M:%SZ +.EE +.RE +.PP +Print the time of a number of seconds since the epoch: +.PP +.RS 4 +.EX +$ date \-u \-d @1700000000 +Tue Nov 14 22:13:20 UTC 2023 +.EE +.RE +.PP +Print the seconds since the epoch of a time in UTC, then the current +time in milliseconds since the epoch: +.PP +.RS 4 +.EX +$ date \-u \-d \(aq2026\-10\-19 12:00\(aq +%s +1792411200 +$ date +%s%3N +.EE +.RE +.PP +Read a date in another form, and print one in another form: +.PP +.RS 4 +.EX +$ date \-D %d/%m/%Y \-d 19/10/2026 +%Y\-%m\-%d +2026\-10\-19 +$ date \-u \-d @1700000000 \(aq+%A, %B %\-d, %Y\(aq +Tuesday, November 14, 2023 +.EE +.RE +.PP +Print the modification time of a file with its UTC offset: +.PP +.RS 4 +.EX +$ date \-r main.c \-Iseconds +.EE +.RE +.PP +Print a time in the time zone of Japan: +.PP +.RS 4 +.EX +$ TZ=JST\-9 date \-d @1700000000 +Wed Nov 15 07:13:20 JST 2023 +.EE +.RE +.PP +Set the clock, from an elevated console, in two ways: +.PP +.RS 4 +.EX +$ date \-s \(aq2026\-10\-19 12:00:00\(aq +$ date 101912002026 +.EE +.RE +.SH NOTES +Differences from GNU +.BR date : +.IP \(bu 2 +The only long options are +.BR \-\-date , +.BR \-\-reference , +.BR \-\-rfc\-2822 , +.BR \-\-rfc\-822 , +.BR \-\-set , +and +.BR \-\-utc . +There is no +.BR \-f , +.BR \-\-iso\-8601 , +.BR \-\-rfc\-3339 , +or +.BR \-\-universal . +.IP \(bu 2 +A time is not free-form text. +Words such as +.B now +and +.BR yesterday , +relative times such as +.BR "1 day ago" , +weekday names, a +.B T +between date and time, fractional seconds, time zone names, and +.B AM +or +.B PM +are errors. +.IP \(bu 2 +.B \-D +is a busybox extension. +.IP \(bu 2 +The output conversions are only those above. +Others that GNU +.B date +has print an empty line, such as +.BR %C , +.BR %D , +.BR %F , +.BR %g , +.BR %G , +.BR %h , +.BR %k , +.BR %l , +.BR %n , +.BR %P , +.BR %r , +.BR %R , +.BR %t , +.BR %u , +and +.BR %V , +as do the +.BR _ , +.BR 0 , +and +.B ^ +flags and field widths. +.PP +Only times from 1970-01-01 00:00:00 UTC to 3001-01-01 07:59:59 UTC, +which are 0 through 32535244799 seconds since the epoch, can be +converted. +A +.I time +outside that range, written in a form other than +.BR @ , +is an invalid date. +In the form with a +.IR zone , +the latest time is 3000-12-31 23:59:59 UTC. +An +.BI @ seconds +outside the range, including every negative value, or a +.B %s +value outside it with +.BR \-D , +is not an error but is taken to be the epoch, 1970-01-01 00:00:00 UTC, +which is then printed, or with +.B \-s +set. +.PP +The names of the days and months are English whatever the system +language, and +.BR %c , +.BR %x , +and +.B %X +have fixed forms. +.PP +The nanoseconds of the current time are those of the Windows system +clock, in multiples of 100. +.PP +Paths for +.B \-r +may use forward or back slashes. +.PP +Lines end with LF, not CRLF. +.SH SEE ALSO +.BR busybox (1), +.BR cal (1), +.BR stat (1), +.BR touch (1) diff --git a/man/man1/dc.1 b/man/man1/dc.1 new file mode 100644 index 0000000..c3f44be --- /dev/null +++ b/man/man1/dc.1 @@ -0,0 +1,945 @@ +.TH DC 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +dc \- reverse-Polish arbitrary-precision calculator +.SH SYNOPSIS +.B dc +.RB [ \-x ] +.RB [ \-e +.IR script ]... +.RB [ \-f +.IR file ]... +.RI [ file ...] +.SH DESCRIPTION +.B dc +runs commands written in reverse-Polish notation on a stack of +arbitrary-precision decimal numbers and strings. +Numbers and strings are pushed on the stack, and most other commands pop +their operands and push their results. +Only the print commands write to standard output. +.PP +This is the busybox +.B dc +applet, which shares its number code with +.BR bc (1). +It accepts the GNU extensions +.B ~ +and +.BR | , +the FreeBSD extensions +.BR ( , +.BR { , +.BR G , +and +.BR N , +and, with +.BR \-x , +extended register names. +Some commands behave unexpectedly; see +.BR NOTES . +.PP +.B dc +runs each +.B \-e +script and +.B \-f +file in the order given, then each +.I file +operand. +With none of these, or with only +.BR \-x , +it reads standard input instead. +A +.I file +named +.B \- +is a file of that name; standard input is +.IR /dev/stdin . +The stack, the registers, and the scale and bases carry over from one +input to the next. +.B dc +reads its input a line at a time, and runs each command as soon as it +has read the start of the next one. +It stops at the end of the last input or when a quit command exits. +.PP +When standard input is a console, +.B dc +is interactive. +It prints no banner and no prompt, and reads lines with line editing and +history as in +.BR sh (1), +but with no completion. +After an error in a typed line, +.B dc +discards the rest of the line and the stack, keeps the registers, and +reads the next line. +Ctrl-C at the prompt ends +.BR dc , +as does Ctrl-D on an empty line. +Ctrl-C while a typed command is running stops it, prints +.BR "interrupted execution" , +and reads the next line. +.PP +A console on standard input also changes how scripts and files run. +An error in a +.I file +operand clears the stack and skips the rest of that file, and +.B dc +goes on with the next one. +An error in a +.B \-e +script or a +.B \-f +file still ends +.B dc +with status 1. +Ctrl-C while a script or file runs ends +.BR dc . +.PP +When standard input is not a console, the first error ends +.B dc +with status 1. +.SS Syntax +Whitespace may separate any two commands, and is needed only where two +numbers would otherwise run together, and before an extended register +name. +A +.B # +starts a comment that runs to the end of the line. +.PP +A number is a run of the digits +.B 0 +to +.B 9 +and +.B A +to +.BR F , +with at most one decimal point. +The letters must be uppercase, since lowercase letters are commands. +A second decimal point starts a new number, so +.B 1.2.3 +is +.B 1.2 +followed by +.BR .3 . +A backslash directly followed by a newline inside a number is skipped, +so +.B dc +reads back the long numbers it prints. +A number starts with +.B _ +to be negative, as in +.BR _5 ; +.B \- +is only the subtraction command. +.PP +A digit counts as its own value when it is the only digit after any +leading zeros, so +.B A +and +.B 0A +are 10 in any input base. +In a longer number, a digit not less than the input base counts as one +less than the base, so with input base 10, +.B FF +is 99. +.PP +A number is converted from its digits the first time a command uses it, +not when it is pushed. +A change of input base therefore changes the value of numbers pushed +earlier that no command has used yet, so +.B FF 16 i p +prints 255, not 99. +.PP +A string is the text between +.B [ +and +.BR ] , +which may span lines and may contain nested pairs of brackets. +It has no escape sequences, so it cannot contain an unbalanced bracket. +A string is also a macro, which +.B x +and the conditional commands run as commands. +.PP +Any character that is not whitespace, a digit, part of a string, or a +command is an error. +.SS Registers +The commands +.BR s , +.BR l , +.BR S , +.BR L , +.BR : , +.BR ; , +and the conditionals are followed by a register name. +The name is a single character, any character, even a space or a digit: +in +.BR "s a" , +the register is named by the space, and +.B a +is a command. +.PP +With +.BR \-x , +a command that is followed by whitespace other than a newline skips it +and takes the following run of lowercase letters, digits, and +underscores as the name, +as in +.B "s total" +and +.BR "l total" . +A command followed directly by a character still takes that character, +so with +.BR \-x , +.B sa +is the register +.BR a . +.PP +A register holds a stack of values, each a number or a string. +A register that was never set holds the number 0. +Arrays are separate from registers, so an array and a register may share +a name. +.SS Arithmetic +The binary commands pop the top number as +.I b +and the next as +.IR a , +and push the result of +.I a +operated on by +.IR b . +.TP +.B + +Push the sum. +.TP +.B \- +Push the difference, +.I a +minus +.IR b . +.TP +.B * +Push the product. +.TP +.B / +Push the quotient. +.TP +.B % +Push the remainder, +.I a +minus the product of +.I b +and the quotient from +.BR / . +.TP +.B ~ +Push the quotient, then the remainder, so that the remainder is on top. +.TP +.B ^ +Push +.I a +raised to the power +.IR b . +.I b +must be an integer; a fractional part is accepted only if all its digits +are zero. +A negative +.I b +gives the reciprocal of the power. +.TP +.B | +Pop three numbers, +.IR a , +.IR b , +and the modulus +.I m +on top, and push +.I a +raised to +.I b +modulo +.IR m . +All three must be integers with a scale of 0, so +.B 2.0 +is rejected. +The exponent must not be negative, and the modulus must not be zero. +.TP +.B v +Pop one number and push its square root. +A negative number is an error. +.PP +Results are truncated, not rounded. +The scale, set by +.BR k , +is the number of digits after the point that +.B / +and +.BR ~ , +and a negative power, keep. +A remainder, as from +.B % +or +.BR ~ , +keeps the larger of the scale plus the scale of +.I b +and the scale of +.IR a . +Sums and differences keep every digit. +A product keeps the smaller of the sum of the operands' scales and the +largest of the scale and the operands' scales. +A power with a non-negative exponent +.I n +keeps the smaller of +.I n +times the scale of +.I a +and the larger of the scale and the scale of +.IR a . +A square root keeps the larger of the scale and the scale of its +operand. +.SS Stack +.TP +.B c +Empty the stack. +.TP +.B d +Push a copy of the top value. +.TP +.B r +Swap the top two values. +.TP +.B R +Pop and discard the top value. +.TP +.B z +Push the number of values on the stack, counted before the push. +.SS "Registers and arrays" +.TP +.BI s r +Pop a value and store it in register +.IR r , +replacing the register's top value. +.TP +.BI l r +Push a copy of register +.IR r 's +top value. +.TP +.BI S r +Pop a value and push it on register +.IR r 's +own stack. +A string is pushed there but also stays on the main stack. +.TP +.BI L r +Pop the top value of register +.IR r 's +stack and push it on the main stack. +A register's stack never becomes empty, so it is an error unless +.B S +has pushed more values on the register than +.B L +has popped. +.TP +.BI : r +Pop an index +.I i +and a value, and store the value as element +.I i +of array +.IR r . +The value must be a number. +.TP +.BI ; r +Pop an index +.I i +and push element +.I i +of array +.IR r . +Elements that were never stored are 0. +What is pushed refers to the element instead of holding its value, so +a later store to that element changes it. +.PP +An index is a non-negative integer no greater than 2147483647. +Any fractional part is dropped. +.SS "Macros and conditionals" +.TP +.B x +Pop a value. +If it is a string, run it as commands. +A number is left on the stack and nothing runs. +.TP +\fB<\fIr\fR, \fB>\fIr\fR, \fB=\fIr\fR, \fB!<\fIr\fR, \fB!>\fIr\fR, \fB!=\fIr\fR +Pop two numbers, and run the string in register +.I r +as a macro if the top number compares to the second as the operator says: +less, greater, equal, not less, not greater, or not equal. +For example, +.B 3 5 >a +runs register +.B a +because 5 is greater than 3. +The register is not examined when the test fails. +It is an error if it is run and its top value is not a string. +.IP +The register may be followed by +.B e +and a second register, as in +.BR "3 5 >a eb" , +whose macro runs when the test fails. +The +.B e +must be on the same line, though whitespace may come before it. +.TP +.B ( +Pop two numbers and push 1 if the top is less than the second, else 0. +.TP +.B { +Pop two numbers and push 1 if the top is less than or equal to the +second, else 0. +.TP +.B G +Pop two numbers and push 1 if they are equal, else 0. +.TP +.B N +Pop one number and push 1 if it is zero, else 0. +.TP +.B ?\& +Read a line from standard input and run it as commands. +When the script itself is standard input, that is the next line of the +script. +At the end of input it runs nothing. +.TP +.B q +Exit +.B dc +if at most one macro is running. +Otherwise stop the two innermost running macros. +.TP +.B Q +Pop a number +.I n +and stop the +.I n +innermost running macros. +If +.I n +is one more than the number running, +.B dc +exits. +A larger +.I n +is an error, and 0 does nothing. +.SS "Scale and bases" +.TP +.B k +Pop a number and make it the scale, from 0 to 4294967295. +The default is 0. +.TP +.B K +Push the scale. +.TP +.B i +Pop a number and make it the input base, from 2 to 36. +The default is 10. +.TP +.B I +Push the input base. +.TP +.B o +Pop a number and make it the output base, from 2 to 999. +The default is 10. +.TP +.B O +Push the output base. +.PP +These commands drop any fractional part of the number. +.SS Printing +A number is printed in the output base, with a leading +.B \- +if negative and with no zero before the point. +With an output base above 16, each digit is a decimal number padded with +zeros to the width of the largest digit, and preceded by a space, or by +the point for the first digit after it. +Output bases 16 and below use the digits +.B 0 +to +.B 9 +and +.B A +to +.BR F . +.TP +.B p +Print the top value followed by LF, without popping it. +In a string, the sequences +.BR \en , +.BR \ea , +.BR \eb , +.BR \ef , +.BR \er , +and +.B \et +stand for the control characters, and +.B \ee +and +.B \e\e +for a single backslash. +A backslash before any other character is printed with it. +An empty string prints a NUL byte before the LF. +.TP +.B n +The same as +.BR p . +.TP +.B f +Print every value from the top down, as +.B p +does. +.TP +.B P +Print the top value with no LF, without popping it. +A string is written as it is, without translating backslashes, and an +empty string writes nothing. +A number is written as the bytes of its integer part in base 256, most +significant first, followed by its fractional part as further base 256 +digits; 0 is one NUL byte. +A negative number is an error. +.TP +.B a +Pop a value and push a one-byte string: for a number, the remainder of +its integer part divided by 256, which must not be negative, and for a +string, its first byte. +A zero byte gives an empty string instead. +.TP +.B Z +Pop a value and push its length: for a number, its count of digits, +not counting zeros before the first nonzero digit and at least 1, and +for a string, its length in bytes. +.TP +.B X +Pop a number and push its scale, the count of digits after the point. +A string is an error. +.SS Errors +An error is reported on standard error as +.PP +.RS 4 +.EX +dc: \fImessage\fR +.EE +.RE +.PP +or, for input from a +.B \-f +file or a +.I file +operand, as +.PP +.RS 4 +.EX +dc: \fIfile\fR:\fIline\fR: \fImessage\fR +.EE +.RE +.PP +where +.I line +counts from 1. +A message may end with +.BI "at '" text ' +for the rest of the line from the faulty command. +A file that cannot be opened is reported as +.PP +.RS 4 +.EX +dc: can\(aqt open \(aq\fIfile\fR\(aq: \fIreason\fR +.EE +.RE +.PP +The other messages are as follows. +.TP +.B stack has too few elements +A command needs more values than the stack holds. +.TP +.B variable is wrong type +A command was given a string where it needs a number, or the reverse, +or a string was stored in an array. +.TP +.BI "bad character '" c ' +The character is not a command. +.TP +.B bad token +A command is in the wrong place, such as an +.B e +with no conditional before it, or a +.B _ +that is not followed by a number. +.TP +.B unterminated string +A +.B [ +has no closing +.BR ] . +.TP +.B divide by zero +The divisor of +.BR / , +.BR % , +or +.BR ~ , +or the modulus of +.BR | , +is zero. +.TP +.B not an integer +The exponent of +.B ^ +has a nonzero fractional part, or an operand of +.B | +has a scale other than 0. +.TP +.B negative number +A negative value where one is not allowed: the square root, the +exponent of +.BR | , +the values for +.BR k , +.BR i , +.BR o , +and +.BR Q , +an array index, and the operands of +.B a +and +.BR P . +.TP +.B overflow +A value is too large for 32 bits, as for +.BR k , +.BR Q , +or the exponent of +.BR ^ . +.TP +.B array too long; must be [1,2147483647] +An array index is too large. +.TP +.B bad ibase; must be [2,16] +The value for +.B i +is out of range. +The upper limit is 36, not 16 as the message says. +.TP +.B bad obase; must be [2,999] +The value for +.B o +is out of range. +.TP +.BI "illegal character 0x" NN +The input has a byte that is not text; see +.BR NOTES . +.TP +.BI "file '" name "' is not text" +With a console on standard input, +.B dc +reports each such byte on a line of a file, then ends with this message. +.TP +.BR "input error" ", " "output error" +Reading or writing failed, for the reason that follows. +.TP +.B out of memory +Memory ran out, as a very large array index does. +.SH OPTIONS +Options may be grouped, as in +.BR \-xe , +and an option's argument may be attached, as in +.BR \-e1p , +or be the next argument. +.B \-\- +ends the options, and so does the first operand, so in +.B dc a.dc \-x +the +.B \-x +is a file name. +.B dc +runs each +.B \-e +and +.B \-f +as soon as it reads it. +.TP +.B \-x +Allow extended register names; see +.BR Registers . +It applies to the scripts and files after it. +.TP +.BI "\-e " script +Run +.I script +as commands. +It may contain newlines. +A command cannot continue from one script to the next. +.TP +.BI "\-f " file +Run the commands in +.IR file . +An error opening it ends +.B dc +with status 1. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the C runtime replaces each argument containing wildcards with the names +of the files it matches, if any, even when the argument is quoted. +From +.BR cmd.exe , +a script argument such as +.B * +may become a list of files. +When it is unset, busybox sets it to +.B 0 +for its child processes, so commands run from the busybox shell, which +expands wildcards itself, receive their arguments as given. +.TP +.B COLUMNS +The console width for line editing, instead of the console's actual +width. +.TP +.B DC_LINE_LENGTH +A printed number is broken into lines of at most this many characters, +each but the last ending in a backslash. +The default is 70, so a full line has 69 digits and a backslash. +The value 0, or a value over 2147483647, disables breaking. +The value 1, a value over 4294967295, and anything that is not an +unsigned decimal number select the default. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +The input ended, or a quit command ran. +.TP +.B 1 +An invalid option, a file that cannot be opened, an error in the +commands, input that is not text, a read or write error, or running out +of memory. +.PP +With a console on standard input, errors in the commands of typed lines, +or of a +.I file +operand other than the last, do not change the status. +.SH EXAMPLES +Evaluate an expression: +.PP +.RS 4 +.EX +$ dc \-e \(aq2 3 + 4 * p\(aq +20 +.EE +.RE +.PP +Divide to 10 decimal places: +.PP +.RS 4 +.EX +$ dc \-e \(aq10k 22 7 / p\(aq +3.1428571428 +.EE +.RE +.PP +Read commands from a pipe: +.PP +.RS 4 +.EX +$ echo \(aq72 9 / 8 * p\(aq | dc +64 +.EE +.RE +.PP +Convert 255 to hexadecimal, and back: +.PP +.RS 4 +.EX +$ dc \-e \(aq16 o 255 p\(aq +FF +$ dc \-e \(aq16 i FF p\(aq +255 +.EE +.RE +.PP +Compute 20! with a recursive macro in register +.BR f : +.PP +.RS 4 +.EX +$ dc \-e \(aq[d1\-d1count.dc <<\(aqEOF\(aq +# Print 1 to 5. +[li p li 1 + si li 6 >a]sa +1 si lax +EOF +$ dc count.dc +1 +2 +3 +4 +5 +.EE +.RE +.PP +Say whether 7 is even or odd: +.PP +.RS 4 +.EX +$ dc \-e \(aq[[even]p]sa [[odd]p]sb 7 2 % 0 =a eb\(aq +odd +.EE +.RE +.PP +Use a long register name: +.PP +.RS 4 +.EX +$ dc \-x \-e \(aq5 s count l count p\(aq +5 +.EE +.RE +.PP +Compute 4 to the 13th power modulo 497: +.PP +.RS 4 +.EX +$ dc \-e \(aq4 13 497 | p\(aq +445 +.EE +.RE +.PP +Print a string followed by an LF (10): +.PP +.RS 4 +.EX +$ dc \-e \(aq[hello, world]P 10P\(aq +hello, world +.EE +.RE +.SH NOTES +Behavior that may surprise a user of another dc: +.IP \(bu 2 +.B n +is the same as +.BR p : +it prints a newline and leaves the value on the stack, where the usual +command pops the value and prints no newline. +.IP \(bu 2 +.B p +and +.B f +translate backslash sequences in a string and print an empty string as +a NUL byte. +.B P +does neither. +.IP \(bu 2 +.B P +does not pop the value, rejects a negative number, and writes the +fractional part of a number. +.IP \(bu 2 +.B S +leaves a string on the main stack as well. +.IP \(bu 2 +Arrays hold numbers only, and the value that +.B ; +pushes follows later stores to its element. +.IP \(bu 2 +A register's stack never becomes empty, and +.B L +cannot pop its last value, so +.B La +after +.B 5 sa +is an error. +.IP \(bu 2 +The input base may be up to 36, though the error message says 16, and +only the digits +.B 0 +to +.B F +can be written. +.IP \(bu 2 +Strings have no escapes, and FreeBSD's backslash escapes for brackets +are not implemented. +.IP \(bu 2 +There is no shell escape +.RB ( ! ), +and the FreeBSD commands +.B J +and +.B M +are not implemented. +.PP +Scale, exponents, and the count for +.B Q +are 32-bit values on Windows, so the largest is 4294967295. +An array takes memory up to its largest index, so a large index can +exhaust memory. +A macro that ends by calling itself is not turned into a loop: every call +level uses memory until the macro returns. +.PP +Files and standard input must be ASCII text. +Any byte other than tab, carriage return, newline, and printable ASCII +is an error, including UTF-8 in comments and strings, except that NUL +bytes are ignored. +A script given with +.B \-e +is not checked. +A carriage return is whitespace, so CRLF line endings work, except after +a backslash that continues a number. +A carriage return inside a string stays in it. +Output lines end with LF, and +.B P +writes bytes unchanged to a file or pipe. +.PP +The characters that +.B p +prints for strings count toward the line length of the next number +printed, because the LF that +.B p +adds after a string does not restart the count. +That number is therefore broken early, or not at all once the count +reaches the line length. +.B P +does not count the characters of a string. +.PP +Interactive mode requires a Windows console. +In a terminal that connects programs through pipes, such as mintty, +.B dc +behaves as with redirected input: no line editing, and the first error +ends it. +The history holds up to 16384 lines and is not saved. +.PP +.I file +operands may use drive letters and backslashes, and messages show them +as given. +The names +.IR /dev/stdin , +.IR /dev/fd/N , +and +.I /dev/null +work as on Unix. +.SH SEE ALSO +.BR bc (1), +.BR busybox (1), +.BR sh (1) diff --git a/man/man1/dd.1 b/man/man1/dd.1 new file mode 100644 index 0000000..d1bbf6f --- /dev/null +++ b/man/man1/dd.1 @@ -0,0 +1,580 @@ +.TH DD 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +dd \- copy a file, converting and formatting it +.SH SYNOPSIS +.B dd +.RB [ if=\c +.IR file ] +.RB [ of=\c +.IR file ] +.RB [ bs=\c +.IR n ] +.RB [ ibs=\c +.IR n ] +.RB [ obs=\c +.IR n ] +.RB [ count=\c +.IR n ] +.RB [ skip=\c +.IR n ] +.RB [ seek=\c +.IR n ] +.RB [ conv=\c +.IR list ] +.RB [ iflag=\c +.IR list ] +.RB [ oflag=\c +.IR list ] +.RB [ status=\c +.IR word ] +.br +.B dd \-\-help +.SH DESCRIPTION +.B dd +copies its input to its output in blocks, and can skip, limit, pad, and +byte-swap the data on the way. +It reads standard input unless +.BI if= file +is given, and writes standard output unless +.BI of= file +is given. +Its arguments are operands, described under +.BR OPTIONS . +.PP +When the copy ends, normally or after a write error, +.B dd +writes two lines on standard error: +.PP +.RS 4 +.EX +2+1 records in +2+1 records out +.EE +.RE +.PP +Each line is a count of complete blocks, a plus sign, and a count of +partial blocks. +The first line counts blocks read, in units of +.B ibs +bytes, and the second counts blocks written, in units of +.B obs +bytes. +A block read or written short, as at the end of the input, is partial. +A write to a closed pipe, or any other error, ends +.B dd +at once without the counts. +.B status=none +also suppresses them. +.SS Copying +.B dd +opens the input and then the output, and positions them as +.B skip +and +.B seek +ask. +It then repeats: read one block of up to +.B ibs +bytes, apply the conversions, and write the data. +It stops at the end of the input, or after +.B count +blocks. +.PP +A read from a pipe or a console can return less than +.B ibs +bytes. +Without +.BR iflag=fullblock , +.B dd +counts that as a block and, if +.B ibs +and +.B obs +are equal, writes it as it is. +When they differ, +.B dd +collects the data and writes blocks of exactly +.B obs +bytes, then the remainder at the end. +.SS Numbers +A number is decimal digits with an optional suffix that multiplies it. +Signs, white space, and hexadecimal and octal notation are not accepted; +.B 010 +is ten. +Suffixes are case-sensitive: +.BR c " (1), " w " (2), " b " (512)," +.BR k " or " K " (1024), " kB " or " KB " (1000)," +.BR M " (1048576), " MB " (1000000)," +.BR G " (1073741824), and " GB " (1000000000)." +.BR kD ", " KD ", " MD ", and " GD +are synonyms for +.BR kB ", " KB ", " MB ", and " GB . +A number that is malformed or out of range ends +.B dd +with a message and status 1. +The range is 1 to 2147483647 for +.BR bs , +.BR ibs , +and +.BR obs , +and 0 to 9223372036854775807 for +.BR count , +.BR skip , +and +.BR seek . +.SH OPTIONS +Every argument is an operand of the form +\fIkeyword\fB=\fIvalue\fR. +Keywords and the words in their values are case-sensitive. +An argument without an +.B = +or with an unknown keyword prints the usage message on standard error and +exits with status 1. +The operands apply in order, so a repeated keyword takes its last value, +except that +.BR conv , +.BR iflag , +.BR oflag , +and +.B status +accumulate. +The first three take a comma-separated list, as in +.BR conv=notrunc,sync ; +an unknown or empty item is an error. +The argument +.B \-\- +is ignored wherever it appears. +.TP +.BI if= file +Read +.I file +instead of standard input. +A +.I file +named +.B \- +is an ordinary file, not standard input. +.TP +.BI of= file +Write +.I file +instead of standard output. +The file is created if it does not exist. +It is truncated when opened, unless +.B seek +is nonzero or +.B conv=notrunc +is given. +.TP +.BI bs= n +Read and write +.I n +bytes at a time. +This sets both +.B ibs +and +.BR obs , +so +.B ibs=512 bs=4k +reads 4096 bytes at a time, and +.B bs=4k ibs=512 +reads 512 and writes 4096. +.TP +.BI ibs= n +Read +.I n +bytes at a time. +The default is 512. +.TP +.BI obs= n +Write +.I n +bytes at a time. +The default is 512. +.TP +.BI count= n +Copy at most +.I n +input blocks. +A block read short counts as a block. +With +.BR iflag=count_bytes , +.I n +is a number of bytes. +Without +.BR count , +.B dd +copies until the end of the input, and +.B count=0 +copies nothing. +.TP +.BI skip= n +Skip +.I n +blocks of input before copying. +A seekable input is repositioned. +Any other input, such as a pipe, is read and the data discarded, stopping +early at the end of the input. +Each read counts as a block, so without +.B iflag=fullblock +a short read from a pipe skips fewer bytes. +With +.BR iflag=skip_bytes , +.I n +is a number of bytes, and an input that cannot seek is read one byte at a +time. +.TP +.BI seek= n +Skip +.I n +blocks of +.B obs +bytes on the output before writing. +Unless +.B conv=notrunc +is given, an output file is first truncated, or extended with zero +bytes, to exactly that offset, so only the data before it survives. +Seeking past the end of a file on NTFS makes the file sparse. +With +.BR oflag=seek_bytes , +.I n +is a number of bytes. +The output must be seekable: standard output that is a pipe fails with +.B Invalid seek +and status 1. +.TP +.B conv=notrunc +Do not truncate the output file when opening it or seeking. +Data beyond what is written stays in the file. +.TP +.B conv=noerror +Continue after a read error. +.B dd +reports the error, seeks +.B ibs +bytes forward in the input, and goes on, counting a partial block read. +With +.BR sync , +that block is written as +.B ibs +zero bytes; without it, nothing is written for it. +If the input cannot seek, +.B dd +stops with an error. +Without +.BR noerror , +a read error ends +.B dd +at once with status 1. +.TP +.B conv=sync +Pad a short input block with zero bytes to +.B ibs +bytes before writing it. +.TP +.B conv=fsync +Flush the output file to disk before finishing. +With different +.B ibs +and +.BR obs , +the flush comes before the final short output block is written. +It fails when the output is +.I /dev/null +or a console. +.TP +.B conv=swab +Swap each pair of bytes of the input. +An odd byte at the very end is left as it is. +Every block but the last must have an even size, or +.B dd +stops with +.BI "can't swab " n " byte buffer" +and status 1. +Use an even +.B ibs +with +.B iflag=fullblock +when the input is a pipe. +.TP +.B iflag=skip_bytes +Count +.B skip +in bytes instead of blocks. +.TP +.B iflag=count_bytes +Count +.B count +in bytes instead of blocks. +The last block is shortened to fit. +.TP +.B oflag=seek_bytes +Count +.B seek +in bytes instead of blocks. +.TP +.B iflag=fullblock +Repeat reads until the block is full or the input ends, so that only the +last block can be partial. +.TP +.B oflag=append +Open the output file in append mode, so every write goes to the end of +the file. +Without +.BR conv=notrunc , +the file is still truncated first, to the +.B seek +offset, which is 0 by default. +It has no effect on standard output. +.TP +.B status=noxfer +Accepted and ignored. +This +.B dd +never writes a transfer rate. +.TP +.B status=none +Do not write the record counts. +Error messages are still written. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when busybox starts, as needed +when run from +.BR cmd.exe . +Each operand begins with a keyword and +.BR = , +so only file names that begin that way can match. +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B BB_UMASK +A file mode creation mask in octal. +When it includes the owner write bit, +.BR 200 , +an output file that +.B dd +creates is read-only. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES . +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid operand, number, or list item, a file that could not be +opened, read, written, positioned, truncated, flushed, or closed, a swab +failure, or too little memory. +.TP +.B 141 +The output is a pipe that was closed before all data was written. +No record counts are written. +.SH EXAMPLES +Write one mebibyte of zero bytes to a file: +.PP +.RS 4 +.EX +$ dd if=/dev/zero of=blank.img bs=1M count=1 +1+0 records in +1+0 records out +.EE +.RE +.PP +Print 16 random bytes as a hex string: +.PP +.RS 4 +.EX +$ dd if=/dev/urandom bs=16 count=1 status=none | xxd \-p +.EE +.RE +.PP +Copy 100 bytes from offset 1000 of a file: +.PP +.RS 4 +.EX +$ dd if=in of=out skip=1000 count=100 iflag=skip_bytes,count_bytes +.EE +.RE +.PP +Overwrite the bytes at offset 0x1000 of a file with the contents of +another, leaving the rest of the file alone: +.PP +.RS 4 +.EX +$ dd if=new of=data seek=4096 oflag=seek_bytes conv=notrunc +.EE +.RE +.PP +Extract the first sector of a compressed disk image. +A pipe can deliver less than a full block, and +.B iflag=fullblock +keeps the one block that +.B count=1 +allows from coming up short. +.B gzip +may report a broken pipe, since +.B dd +stops reading after that block: +.PP +.RS 4 +.EX +$ gzip \-dc disk.gz | dd bs=512 count=1 iflag=fullblock >sector +.EE +.RE +.PP +Swap the bytes of each 16-bit word in a file: +.PP +.RS 4 +.EX +$ dd if=big of=little bs=64k conv=swab +.EE +.RE +.SH NOTES +Differences from GNU +.BR dd : +.IP \(bu 2 +There is no transfer rate line, and no status report on a signal. +.IP \(bu 2 +Numbers take no +.B x +multiplier, as in +.BR 2x512 , +and the only suffixes are those listed under +.BR Numbers . +.IP \(bu 2 +.B bs +sets +.B ibs +and +.B obs +where it appears, so a later +.B ibs +or +.B obs +overrides it. +.IP \(bu 2 +Operands and values not described above are rejected, such as +.BR cbs , +.BR status=progress , +the +.B direct +flags, and the +.B conv +values +.BR ucase , +.BR lcase , +.BR block , +.BR unblock , +.BR ascii , +.BR ebcdic , +.BR excl , +.BR nocreat , +.BR fdatasync , +and +.BR sparse . +.PP +Standard input and output are binary, so CR LF pairs and Ctrl-Z +characters are copied unchanged. +.PP +File names may use drive letters and backslashes. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +A directory as +.B if +fails with +.BR "Permission denied" , +and as +.B of +with +.BR "Is a directory" . +.PP +For both +.B if +and +.BR of , +the names +.IR /dev/null , +.IR /dev/tty , +.IR /dev/stdin , +.IR /dev/stdout , +and +.I /dev/stderr +work as on Unix, with +.I /dev/tty +the console. +.I /dev/fd/n +gives descriptor +.I n +itself rather than a copy, and +.B dd +closes it once it has moved it to standard input or output, so +.B of=/dev/fd/2 +loses the record counts and later error messages. +.I /dev/zero +and +.I /dev/urandom +are sources of zero bytes and of random bytes from the system's +cryptographic generator; +as +.B of +they discard the data, like +.IR /dev/null . +.PP +An +.B of +that names a physical drive, such as +.I \e\e.\ePhysicalDrive1 +or +.IR //./PhysicalDrive1 , +is opened without creating or truncating it. +A drive cannot be truncated, so +.B seek +on a drive needs +.BR conv=notrunc , +or +.B dd +stops with an error before copying. +.PP +When the output is a console, each block is converted for display from +the ANSI code page, which is UTF-8 on Windows 10 version 1903 and later, +and escape sequences, such as those for color, take effect. +A block that contains a NUL byte is written unconverted. +Redirect the output to a file or a pipe when copying binary data. +Data read from a console is converted from the console's input code page +to the ANSI code page, unless the ANSI code page is UTF-8. +.PP +The buffers for +.B ibs +and +.B obs +are allocated before copying starts, and a size that exceeds the +available memory ends +.B dd +with +.B out of memory +and status 1. +.SH SEE ALSO +.BR busybox (1), +.BR cat (1), +.BR cp (1), +.BR head (1), +.BR od (1), +.BR truncate (1), +.BR xxd (1) diff --git a/man/man1/df.1 b/man/man1/df.1 new file mode 100644 index 0000000..3a79c96 --- /dev/null +++ b/man/man1/df.1 @@ -0,0 +1,409 @@ +.TH DF 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +df \- report the size and free space of drives +.SH SYNOPSIS +.B df +.RB [ \-PkmhHTa ] +.RB [ \-B +.IR size ] +.RB [ \-t +.IR type ] +.RI [ file ...] +.SH DESCRIPTION +.B df +prints the size, used space, and available space of drives on standard +output. +It prints a header line, then a line for each drive it reports. +.PP +With no +.I file +operands, it reports each drive letter, in alphabetical order, whose +drive is fixed, removable, CD-ROM, or network and whose volume +information can be read. +A drive of another type, such as a RAM disk, and a drive that cannot be +read, such as one with no disk in it, are left out. +So is a drive whose size is 0, unless +.B \-a +is given. +.PP +With operands, +.B df +reports one drive for each +.IR file , +in order. +An operand that starts with a drive letter and a colon, such as +.B D: +or +.IR d:/src , +selects that drive. +Any other operand, such as a relative path or one starting with a slash, +selects the drive of the current directory. +The operand must exist, but is otherwise not examined. +A drive named this way is reported even when its size is 0. +It is also reported when its type is not listed above, with an empty +Type. +.SS Output format +The header names the fields of each line: +.TP +.B Filesystem +The drive, such as +.BR C: , +or, when the root of the drive resolves to another path, as for a +network drive, that path, as in +.IR //server/share . +.TP +.B Type +Only with +.BR \-T : +the name Windows gives the file system, such as +.BR NTFS , +.BR FAT32 , +or +.BR exFAT . +.TP +.B 1K\-blocks +The size of the drive. +Its header is the unit, so it varies as described below, and with +.B \-h +or +.B \-H +it is +.BR Size . +.TP +.B Used +The size minus the free space. +.TP +.B Available +The free space available to the current user. +It can be less than the free space of the drive when disk quotas apply. +.TP +.B Use% +Used as a percentage of Used plus Available, rounded to the nearest +whole number. +With +.B \-P +the header is +.BR Capacity . +.TP +.B Mounted on +The root directory of the drive, such as +.IR C:/ . +.PP +Sizes are numbers of blocks of 1024 bytes, each rounded to the nearest +whole number, unless +.BR \-B , +.BR \-h , +.BR \-H , +.BR \-m , +or +.B POSIXLY_CORRECT +selects another unit. +Without +.B \-h +or +.BR \-H , +the size header gives the block size as a plain number when it is under +1024, as in +.BR 512\-blocks . +Otherwise it is a whole number of K, M, or G, each 1024 times the last, +so that +.B \-B 1500 +is headed +.BR 2K\-blocks . +With +.B \-P +it is always a plain number, as in +.BR 1500\-blocks . +.PP +A space separates the fields. +Filesystem is padded to 20 columns, Type to 10, and numbers are +right-aligned in 9, or in 3 for the percentage, which is followed by a +percent sign. +A number wider than 9 columns shifts the fields after it. +A Filesystem value wider than 20 columns, or a Type value wider than 10, +is followed by a line break, and the remaining fields continue on the +next line in their usual columns. +With +.B \-P +such a value stays on the line, followed by one extra space for each +column over the limit. +.SH OPTIONS +Options may be grouped, as in +.BR \-hT , +and may follow the operands unless +.B POSIXLY_CORRECT +is set. +An option's argument may be attached, as in +.BR \-B1M , +or be the next argument. +.B \-\- +ends the options. +Of +.BR \-B , +.BR \-k , +and +.BR \-m , +the last one given applies, and +.B \-h +or +.B \-H +overrides all three. +.TP +.B \-P +POSIX output format: a block size in the size header is in bytes, the +percentage is headed +.BR Capacity , +and long Filesystem and Type values do not wrap. +The unit does not change. +.TP +.B \-k +Use blocks of 1024 bytes. +This is the default, unless +.B POSIXLY_CORRECT +is set. +.TP +.B \-m +Use blocks of 1048576 bytes. +.TP +.B \-h +Print sizes in human-readable form: a number with one decimal place and +a +.BR K , +.BR M , +.BR G , +.BR T , +or larger suffix for a power of 1024, as in +.BR 932.7G . +A size of zero is printed as +.BR 0 . +.TP +.B \-H +The same as +.BR \-h . +Sizes still use powers of 1024. +.TP +.B \-T +Print the Type field. +.TP +.BI "\-t " type +Report only drives whose file system name, as printed by +.BR \-T , +is exactly +.IR type , +including case, such as +.BR NTFS . +This applies to operands too, and other drives are skipped without an +error. +Only the last +.B \-t +applies. +.TP +.B \-a +Also list drives whose size is 0. +.TP +.BI "\-B " size +Use blocks of +.I size +bytes. +.I size +is a decimal number with an optional suffix, or a suffix alone, which +counts as 1 of that unit: +.BR K , +.BR k , +.BR KiB , +or +.B kiB +for 1024; +.BR M , +.BR m , +.BR MiB , +or +.B miB +for 1048576; +.BR G , +.BR g , +.BR GiB , +or +.B giB +for 1073741824; +.B KB +for 1000; +.B MB +for 1000000; and +.B GB +for 1000000000. +The result must be from 1 to 4294967295, so +.B 4G +is too large. +An invalid +.I size +is an error even with +.B \-h +or +.BR \-H , +but not when a later +.B \-k +or +.B \-m +overrides +.BR \-B . +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_CRITICAL_ERROR_DIALOGS +When it is +.BR 1 , +Windows may show its critical-error dialog for a drive with no disk in +it. +Otherwise busybox suppresses the dialog, and +.B df +treats the drive as unreadable. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +console output is not converted to the console code page, and when the +ANSI code page is UTF-8, each non-ASCII byte in the Filesystem and Type +fields is replaced by a question mark. +Otherwise, with a UTF-8 code page, only invalid UTF-8 and nonprintable +characters are replaced, and a wide character counts as two columns when +padding. +.TP +.B POSIXLY_CORRECT +When set, the default block size is 512 bytes, and the first operand +ends the options. +.PP +Variables that affect every busybox applet, such as +.BR BB_TERMINAL_MODE , +are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, even when +.B \-t +leaves nothing to report. +.TP +.B 1 +An invalid option, with a usage message on standard error; an invalid +.B \-B +size; an operand that does not exist or has no drive; or a drive whose +space cannot be read. +The first two end +.B df +before it prints anything. +After the others the remaining operands or drives are still reported. +.PP +An operand that does not exist or has no drive is reported on standard +error as the first line below, and a drive whose space cannot be read as +the second, where +.I root +is the root of the drive, such as +.IR D:/ : +.PP +.RS 4 +.EX +df: \fIfile\fR: can\(aqt find mount point +df: \fIroot\fR: \fIreason\fR +.EE +.RE +.SH EXAMPLES +Show the space on every drive in human-readable form: +.PP +.RS 4 +.EX +$ df \-h +Filesystem Size Used Available Use% Mounted on +C: 932.7G 718.6G 214.1G 77% C:/ +D: 466.1G 245.9G 220.2G 53% D:/ +F: 10.9T 6.3T 4.6T 58% F:/ +.EE +.RE +.PP +Show the drive that holds the current directory: +.PP +.RS 4 +.EX +$ df . +.EE +.RE +.PP +Print the space available on drive +.BR D: , +in MiB, for use in a script. +The +.B \-P +option keeps a long Filesystem value on the same line: +.PP +.RS 4 +.EX +$ df \-P \-m D: | awk \(aqNR == 2 { print $4 }\(aq +225460 +.EE +.RE +.PP +List only the NTFS drives, with their types: +.PP +.RS 4 +.EX +$ df \-T \-t NTFS +.EE +.RE +.SH NOTES +Differences from GNU +.BR df : +.IP \(bu 2 +Only drive letters are listed. +Volumes mounted in folders, and network shares without a drive letter, +are not. +.IP \(bu 2 +The drive comes from the text of the operand, not from where the file +is. +A UNC operand, such as +.IR //server/share/dir , +reports the drive of the current directory, and when the current +directory is a UNC path, every operand without a drive letter fails. +A path through a junction, symbolic link, or volume mount point to +another volume reports the drive that the path starts on. +.IP \(bu 2 +There is no +.B \-i +for inodes, no +.BR \-l , +.BR \-x , +or +.BR \-\-total , +and no long options other than +.BR \-\-help . +.IP \(bu 2 +.B \-H +uses powers of 1024, not 1000. +.IP \(bu 2 +.B \-t +cannot be repeated to select several types. +.PP +Windows reports sizes in bytes, but not the block size. +.B df +assumes blocks of 4 KiB for a drive under 16 TiB, and 8, 16, 32, or +64 KiB for a drive under 32, 64, or 128 TiB, or larger. +The size, the free space, and the available space are each rounded down +to whole blocks of this size before conversion to the output unit, so +even +.B \-B 1 +does not give exact byte counts. +.PP +Operands may use drive letters in either case and backslashes. +Lines end with LF, not CRLF. +.SH SEE ALSO +.BR busybox (1), +.BR du (1), +.BR stat (1) diff --git a/man/man1/diff.1 b/man/man1/diff.1 new file mode 100644 index 0000000..e14b070 --- /dev/null +++ b/man/man1/diff.1 @@ -0,0 +1,566 @@ +.TH DIFF 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +diff \- compare files line by line +.SH SYNOPSIS +.B diff +.RB [ \-abBdiNqrTstw ] +.RB [ \-L +.IR label ] +.RB [ \-S +.IR file ] +.RB [ \-U +.IR lines ] +.RB [ \-\-binary ] +.I file1 +.I file2 +.SH DESCRIPTION +.B diff +compares +.I file1 +with +.I file2 +line by line and writes the differences as a unified diff, the format +that +.BR patch (1) +reads. +It writes nothing when the files are the same. +There must be exactly two operands. +A file named +.B \- +is standard input. +.PP +Lines are compared as octets, and a line ends at LF. +Options can make the comparison ignore case or white space, but they do +not change how lines are written. +A CR before an LF is also ignored, unless +.B \-\-binary +is given; see +.BR NOTES . +.PP +If the files differ and a NUL octet appears in either of them, within +the length of the shorter file, +.B diff +does not compare lines, and writes +.PP +.RS 4 +.EX +Files \fIfile1\fR and \fIfile2\fR differ +.EE +.RE +.PP +on standard output instead. +.B \-a +compares them as text. +.SS "Output format" +Output begins with two header lines naming the files: +.PP +.RS 4 +.EX +\-\-\- \fIfile1\fR ++++ \fIfile2\fR +.EE +.RE +.PP +The names are the operands as given, or the +.B \-L +labels, with no timestamps. +Each hunk, a group of changes with their surrounding lines, follows as a +line +.PP +.RS 4 +.EX +@@ \-\fIstart\fR,\fIcount\fR +\fIstart\fR,\fIcount\fR @@ +.EE +.RE +.PP +and the lines it covers. +The first range is in +.IR file1 , +the second in +.IR file2 . +A +.I count +of 1 is omitted. +A range of no lines is written as the number of the line before it, or +0 at the start of the file, and a +.I count +of 0. +.PP +Each line of a hunk starts with one character. +A space marks a context line, which is in both files. +A +.B \- +marks a line only in +.IR file1 , +and a +.B + +marks a line only in +.IR file2 . +A hunk has +.B 3 +context lines around each change, or the number given by +.BR \-U . +Changes separated by no more than twice that many unchanged lines share +a hunk. +A line that ends without a newline, which only the last line of a file +can, is followed by +.PP +.RS 4 +.EX +\e No newline at end of file +.EE +.RE +.SS Directories +If both operands are directories, +.B diff +compares the files that have the same name in both, and writes the diff +of each pair that differs. +Names are sorted in byte order and match case-sensitively. +In messages and headers a file is named by the operand as given, a +slash unless the operand ends in one, and the name. +Other output is one of these lines: +.TP +.BI "Only in " dir ": " name +.I name +exists only in +.IR dir . +With +.BR \-r , +.I name +is a path relative to the operand. +.B \-N +suppresses this line. +.TP +.BI "Common subdirectories: " path1 " and " path2 +Without +.BR \-r , +a subdirectory in both is not entered. +.TP +.BI "File " path1 " is a directory while file " path2 " is a regular file" +Without +.BR \-r . +The reverse, with the kinds exchanged, also occurs. +.TP +.BI "File " path " is not a regular file or directory and was skipped" +For a device, or another special file. +.TP +.BI "Files " path1 " and " path2 " differ" +With +.BR \-q , +or for binary files. +.TP +.BI "Files " path1 " and " path2 " are identical" +With +.BR \-s . +.PP +Without +.BR \-r , +only the entries of the two directories are compared. +With +.BR \-r , +every subdirectory is entered, through symbolic links too, and files are +matched by path relative to the operands. +A subdirectory that is missing from the other operand, or is not a +directory there, is not entered and is not reported, but sets exit +status 1. +With +.BR \-N , +it is entered, and its files are compared with empty files. +An entry that cannot be examined, such as a broken symbolic link, is +reported on standard error and left out, and the exit status does not +change. +.PP +If only one operand is a directory, +.B diff +compares the other operand with the file in that directory that has its +name: the part after the last forward slash, or all of the operand if it +has none. +That file must exist, even with +.BR \-N . +Standard input cannot be compared with a directory. +.SH OPTIONS +Options may be grouped, as in +.BR \-rN , +and may follow the operands, unless +.B POSIXLY_CORRECT +is set. +An option's argument may be attached, as in +.BR \-U5 , +or be the next argument. +Long options may be abbreviated to a unique prefix, and the argument of +a long option may follow +.B = +or be the next argument. +.B \-\- +ends the options. +.TP +.BR \-a ", " \-\-text +Treat all files as text, even if they contain NUL octets. +.TP +.BR \-b ", " \-\-ignore\-space\-change +Ignore changes in the amount of white space: compare each run of white +space as a single space. +White space at the end of a line, and a missing newline at the end of +the file, are ignored. +A line with white space at its start differs from one without. +White space is space, tab, CR, LF, VT, and FF. +.TP +.BR \-B ", " \-\-ignore\-blank\-lines +Omit a hunk whose changed lines, in both files, are all empty. +A line is empty when it contains only its newline. +A line of white space, or one ending in CR LF, is not empty. +If every hunk is omitted, the files count as the same. +.TP +.BR \-d ", " \-\-minimal +Try harder to find a small set of changes. +Without +.BR \-d , +.B diff +limits the effort spent on a line that occurs many times in the other +file, so the result can be larger than necessary. +.TP +.BR \-i ", " \-\-ignore\-case +Ignore differences in case. +Only the ASCII letters are folded. +.TP +\fB\-L\fR \fIlabel\fR, \fB\-\-label=\fIlabel\fR +Use +.I label +instead of the file name in a header line. +Give +.B \-L +twice to label both files: the first labels +.IR file1 , +the second +.IR file2 . +A single label applies to +.IR file1 . +Of more than two, only the first and last are used. +When directories are compared, the labels apply to every pair of files +that differs. +.TP +.BR \-N ", " \-\-new\-file +Treat absent files as empty. +An operand or directory entry that does not exist, or cannot be opened, +is compared as an empty file. +In a directory, a file that is in only one of the two is diffed against +an empty file named +.I /dev/null +instead of being reported as +.BR "Only in" . +Without +.BR \-r , +a subdirectory that is in only one of the two is reported as common to +both. +A missing operand keeps its name in the header. +.TP +.BR \-q ", " \-\-brief +Write only +.BI "Files " file1 " and " file2 " differ" +for files that differ, and no diff. +Binary files are always reported this way. +.TP +.BR \-r ", " \-\-recursive +Compare directories recursively. +Has no effect unless both operands are directories. +.TP +\fB\-S\fR \fIfile\fR, \fB\-\-starting\-file=\fIfile\fR +When comparing directories, start with +.IR file : +skip each entry whose name sorts before +.I file +in byte order. +With +.BR \-r , +an entry's name is its path relative to the operand. +.I file +need not exist. +.TP +.BR \-T ", " \-\-initial\-tab +Write a tab after the space, +.BR \- , +or +.B + +that starts each line of a hunk, so that tab stops in the text keep +their columns. +.TP +.BR \-s ", " \-\-report\-identical\-files +Write +.BI "Files " file1 " and " file2 " are identical" +when two files compared are the same. +.TP +.BR \-t ", " \-\-expand\-tabs +Expand tabs to spaces in the output, to tab stops every 8 columns. +Columns count octets from the start of the text of the line. +.TP +\fB\-U\fR \fIlines\fR, \fB\-\-unified=\fIlines\fR +Use +.I lines +as the number of lines of context around each change. +The default is 3. +.I lines +is a decimal number from 0 to 2147483647, and anything else is an error. +Values of 1073741824 or more overflow and give wrong hunks. +.TP +.BR \-w ", " \-\-ignore\-all\-space +Ignore white space: compare lines with all white space removed, so that +.B "a b" +and +.B ab +are equal. +A missing newline at the end of the file is also ignored. +.TP +.B \-\-binary +Compare lines exactly, without ignoring a CR before an LF. +See +.BR NOTES . +.TP +.BR \-E ", " \-\-ignore\-tab\-expansion +Accepted for compatibility and ignored. +.TP +.BR \-p ", " \-\-show\-c\-function +Accepted for compatibility and ignored. +The hunk headers never name a function. +.TP +.B \-u +Accepted for compatibility and ignored. +The output is always unified. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit with status 0. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when +.B diff +starts, as needed when it is run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.TP +.B TMPDIR +The directory for the temporary copy of an input that cannot seek, such +as a pipe. +When it is unset, +.B TMP +and then +.B TEMP +are used. +If none is set, see +.BR NOTES . +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +No differences were found, including when the files differ only in what +an option ignores, or in a CR before an LF (see +.BR NOTES ). +.TP +.B 1 +The files differ, including binary files, an +.B Only in +line, and a subdirectory skipped under +.BR \-r . +Also an invalid command line, with a message on standard error, and any +error other than a missing operand, such as a temporary file that cannot +be created, a file missing from the directory when only one operand is a +directory, or standard input compared with a directory. +.TP +.B 2 +An operand does not exist, and +.B \-N +was not given. +.TP +.B 141 +Standard output is a pipe whose reader has exited. +.PP +Messages about common subdirectories, files of different kinds, and +skipped files do not change the status. +Nor does a file that cannot be opened, which is reported on standard +error as +.PP +.RS 4 +.EX +diff: can't open '\fIfile\fR': \fIreason\fR +.EE +.RE +.PP +The pair of files then counts as the same. +.SH EXAMPLES +Compare two files: +.PP +.RS 4 +.EX +$ diff old.txt new.txt +\-\-\- old.txt ++++ new.txt +@@ \-1,3 +1,3 @@ + one +\-two ++2 + three +.EE +.RE +.PP +Test in a script whether two files are the same: +.PP +.RS 4 +.EX +$ if diff \-q old.txt new.txt >/dev/null; then echo same; fi +.EE +.RE +.PP +Ignore changes in white space, and show 10 lines of context: +.PP +.RS 4 +.EX +$ diff \-w \-U 10 old.c new.c +.EE +.RE +.PP +Compare the output of a program with the expected output: +.PP +.RS 4 +.EX +$ ./prog | diff \- expected.txt +.EE +.RE +.PP +List the files that differ between two build trees: +.PP +.RS 4 +.EX +$ diff \-rq build1 build2 +.EE +.RE +.PP +Write a patch that turns tree +.I a +into tree +.IR b , +including new files, and apply it to a copy of +.IR a : +.PP +.RS 4 +.EX +$ diff \-rN a b >fix.patch +$ cp \-r a c +$ cd c +$ patch \-p1 <../fix.patch +.EE +.RE +.PP +Compare files with their CR LF line endings significant: +.PP +.RS 4 +.EX +$ diff \-\-binary dos.txt unix.txt +.EE +.RE +.SH NOTES +Differences from GNU diff: +.IP \(bu 2 +Only the unified format is written. +Options such as +.BR \-c , +.BR \-e , +.BR \-y , +.BR \-x , +.BR \-X , +and +.B \-I +are not accepted. +.IP \(bu 2 +The header lines have no timestamps. +.IP \(bu 2 +The message for binary files begins with +.BR Files , +not +.BR "Binary files" . +.IP \(bu 2 +With +.BR \-r , +a file in only one tree is reported as +.BI "Only in " dir ": " sub/name +with the subdirectory in the file part, where GNU diff puts it in the +directory part, and a subdirectory in only one tree is not reported. +.IP \(bu 2 +Status 2 is for a missing operand only, and other errors give status 1. +.PP +Files and standard input are read in binary mode. +Unless +.B \-\-binary +is given, a CR directly before an LF is removed when lines are compared, +so text with CR LF line endings and the same text with LF line endings +are the same: nothing is written, and the exit status is 0. +Lines that are written keep their CRs. +Output lines that +.B diff +writes itself end with LF, not CR LF. +.PP +Operands may be Windows paths, with a drive letter and either kind of +slash, and are named in output as given. +.I /dev/null +is accepted as an operand, but the Windows name +.I nul +is not. +When directories are compared, names are joined to the directory operand +with a forward slash, which is added even after a trailing backslash. +When only one operand is a directory, only a forward slash ends the +directory part of the other operand, so +.B diff +appends all of an operand such as +.I sub\ef.txt +to the directory, and looks for +.IR dir/sub\ef.txt . +A bare drive such as +.I c: +names the current directory of that drive, and names are joined to it +with no slash, as +.IR c:name . +File names may contain any Unicode characters on Windows 10 version 1903 +and later, and are limited to the ANSI code page on earlier versions. +.PP +An input that cannot seek, such as a pipe, is first copied to a +temporary file in +.BR TMPDIR , +named +.B dif +and six more characters, which +.B diff +removes when it finishes. +It reads such an input to its end before it writes anything. +If none of +.BR TMPDIR , +.BR TMP , +and +.B TEMP +is set, +.B diff +does not compare the pair of files, writes no message, and counts them +as the same: the exit status is 0, and +.B \-s +reports them as identical. +.PP +If both operands name the same file, such as one path spelled two ways, +.B diff +exits with status 0 at once, and writes nothing even with +.BR \-s . +Two +.B \- +operands also count as the same. +.SH SEE ALSO +.BR busybox (1), +.BR cmp (1), +.BR comm (1), +.BR patch (1) diff --git a/man/man1/dirname.1 b/man/man1/dirname.1 new file mode 100644 index 0000000..f9e47fe --- /dev/null +++ b/man/man1/dirname.1 @@ -0,0 +1,253 @@ +.TH DIRNAME 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +dirname \- strip the last component from a path +.SH SYNOPSIS +.B dirname +.I path +.SH DESCRIPTION +.B dirname +prints +.I path +without its last component, followed by a newline: the name of the +directory that contains +.IR path . +It works on the string alone and does not access the file system, so +.I path +need not exist. +.PP +Both slash and backslash separate components, and a run of separators +counts as one. +Trailing separators are ignored, and then the last component and the +separators before it are removed. +Other separators are kept as they are, so +.B a//b/c/ +gives +.BR a//b . +No component is special, so +.B a/..\& +gives +.BR a . +If nothing remains, the result is +.B .\& +for a relative path, including an empty one, and a single separator for +an absolute path, so +.B /usr +gives +.BR / . +.PP +A drive, an ASCII letter and a colon at the start of +.IR path , +is kept, and the rest of +.I path +is handled as above. +So +.B C:/foo +gives +.BR C:/ , +and the drive-relative +.B C:foo +gives +.BR C:. , +which names the current directory of drive C. +.PP +A path that begins with two separators, of either kind, is a UNC path. +Its first two components after them, normally a host and a share, are a +root that is kept like a drive, and the result is never shorter than +that root and a separator. +So +.B //host/share/dir +and +.B //host/share +both give +.BR //host/share/ . +Device paths are UNC paths too: +.B \e\e?\eC:\edir +gives +.BR \e\e?\eC:\e . +.PP +A separator that +.B dirname +adds after a root is a copy of one in +.IR path : +the one that follows the drive or, for any other absolute path, the +first character. +So +.B C:\eusr +gives +.BR C:\e , +and +.B //host/share\edir +gives +.BR //host/share/ . +.SH OPTIONS +.B \-\-help +is the only option, so any other argument that begins with a dash, +such as +.B \-h +or +.BR \-\-version , +is a +.IR path . +A first argument of +.B \-\- +is skipped, which matters only for a +.I path +of +.B \-\- +or +.BR \-\-help . +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the C runtime expands the wildcards +.B * +and +.B ?\& +in the last component of each argument when busybox starts, even in +quoted arguments, as needed for commands typed in +.BR cmd.exe . +A pattern that matches nothing is left as it is. +When the variable is unset, busybox sets it to +.BR 0 , +so that busybox programs it starts do not expand their arguments again. +.PP +Variables that affect every busybox program, such as +.B BB_TERMINAL_MODE +and +.B LC_ALL +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Invalid command line: no +.IR path , +or more than one, with a usage message on standard error. +.TP +.B 141 +Standard output is a pipe whose reader has exited, and the result is +4096 bytes or longer. +No message is printed. +.TP +.B 255 +Standard output could not be written, as when it is closed or is a pipe +whose reader has exited, and the result is shorter than 4096 bytes. +No message is printed. +.SH EXAMPLES +Print the directory of a file: +.PP +.RS 4 +.EX +$ dirname C:/w64devkit/bin/gcc.exe +C:/w64devkit/bin +.EE +.RE +.PP +Strip a Windows path, quoted to protect the backslashes: +.PP +.RS 4 +.EX +$ dirname \(aqC:\eUsers\eme\eDocuments\e\(aq +C:\eUsers\eme +.EE +.RE +.PP +A name with no directory part is in the current directory: +.PP +.RS 4 +.EX +$ dirname main.c +\&. +.EE +.RE +.PP +The directory of a file in a root is the root: +.PP +.RS 4 +.EX +$ dirname C:/pagefile.sys +C:/ +$ dirname //server/share/dir +//server/share/ +.EE +.RE +.PP +Create the directory of an output file before writing it: +.PP +.RS 4 +.EX +$ out=build/x64/app.exe +$ mkdir \-p "$(dirname "$out")" +$ cc \-o "$out" main.c +.EE +.RE +.SH NOTES +Differences from Unix +.BR dirname : +.IP \(bu 2 +Backslashes are separators, and drives and UNC paths have roots. +.IP \(bu 2 +Leading double separators begin a UNC path, so +.B dirname //usr +prints +.BR //usr/ , +and +.B dirname // +prints +.BR /// . +.IP \(bu 2 +It takes exactly one +.IR path , +as POSIX specifies, not several as GNU +.B dirname +does. +.IP \(bu 2 +There is no +.BR \-z , +and no long option other than +.BR \-\-help . +.IP \(bu 2 +A write error gives no message. +When the result is 4096 bytes or longer, a write error other than to a +pipe whose reader has exited goes unreported, with status 0. +.PP +The wildcard expansion described under +.B BB_GLOBBING +can turn one argument into several. +Started from +.BR cmd.exe , +.B dirname *.c +fails with a usage message when more than one file matches. +.PP +On Windows 10 version 1903 and later, +.I path +may contain any Unicode characters. +On older versions it is limited to the ANSI code page, and in a +double-byte code page, such as Shift JIS, the second byte of a character +is never taken for a separator. +.PP +The output line ends with LF, not CRLF. +.PP +The kit's +.B sh +runs +.B dirname +inside the shell process, without starting a new one, except where the +shell needs a separate process anyway, as for a command substitution or +a pipeline. +Exit status 141 then ends the shell too. +.SH SEE ALSO +.BR basename (1), +.BR busybox (1), +.BR realpath (1), +.BR sh (1) diff --git a/man/man1/dos2unix.1 b/man/man1/dos2unix.1 new file mode 100644 index 0000000..e4e1121 --- /dev/null +++ b/man/man1/dos2unix.1 @@ -0,0 +1,208 @@ +.TH DOS2UNIX 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +dos2unix, unix2dos \- convert text between DOS and Unix line endings +.SH SYNOPSIS +.B dos2unix +.RB [ \-u | \-d ] +.RI [ file ...] +.br +.B unix2dos +.RB [ \-u | \-d ] +.RI [ file ...] +.SH DESCRIPTION +.B dos2unix +converts DOS line endings, a carriage return (CR) followed by a line +feed (LF), to Unix line endings, a lone LF. +.B unix2dos +converts the other way. +Each +.I file +is converted in place. +With no +.I file +operands, the command reads standard input and writes standard output. +.PP +The conversion works on bytes. +.B dos2unix +deletes every CR, and +.B unix2dos +deletes every CR and writes a CR before every LF. +So a CR that is not followed by LF is deleted in both directions, +.B unix2dos +leaves CR LF pairs unchanged, and converting a file twice has no further +effect. +All other bytes are copied unchanged. +.PP +Each +.I file +is written to a temporary file next to it, named +.I file +with six characters appended, which then replaces +.IR file . +If +.I file +is a symbolic link, the file it refers to is converted in this way and +the link is kept. +Files are converted in order, and the first error stops the command, +leaving the remaining files unconverted. +A +.I file +named +.B \- +is a file, not standard input. +.SH OPTIONS +The command's name selects the default direction, and an option +overrides it. +.B \-u +and +.B \-d +cannot be combined: giving both is a usage error. +Options may follow +.I file +operands, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +.TP +.B \-u +Convert to Unix line endings, as +.B dos2unix +does by default. +.TP +.B \-d +Convert to DOS line endings, as +.B unix2dos +does by default. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options, so that later arguments such as +.B \-d +are file names. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B BB_UMASK +When it has the owner write bit, +.BR 200 , +each converted +.I file +is read-only. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted to the console's code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Invalid usage, or a +.I file +could not be opened, written, or replaced. +.TP +.B 141 +Standard output is a pipe that was closed before all output was written. +.SH EXAMPLES +Convert C sources to Unix line endings in place: +.PP +.RS 4 +.EX +$ dos2unix *.c *.h +.EE +.RE +.PP +Do the same for a whole source tree: +.PP +.RS 4 +.EX +$ find src \-name \(aq*.[ch]\(aq \-exec dos2unix {} + +.EE +.RE +.PP +Write a copy of a file with DOS line endings, leaving the original +unchanged: +.PP +.RS 4 +.EX +$ unix2dos notes\-dos.txt +.EE +.RE +.SH NOTES +Differences from the standalone +.B dos2unix +and +.B unix2dos +commands common on Linux: +.IP \(bu 2 +Binary files are not detected and skipped, so they are corrupted. +.IP \(bu 2 +Every CR is deleted, not only those before LF, so text with old Mac line +endings loses its line breaks. +.IP \(bu 2 +Text in UTF-8 or another ASCII-compatible encoding converts correctly, +and a byte order mark is copied unchanged, but UTF-16 text is corrupted. +.IP \(bu 2 +Besides +.BR \-\-help , +the only options are +.B \-u +and +.BR \-d . +There is no option to write a new file or to keep the date. +.PP +Standard input and output are in binary mode, so line endings are +exactly as described above. +Without +.I file +operands, an error writing standard output is not reported, and the +exit status is 0 unless the output was a closed pipe. +.PP +A converted +.I file +is always a new file, even when nothing changed. +It gets the current modification time, attributes such as read-only and +hidden are not kept, and other hard links to the original keep the old +contents. +A read-only +.I file +is converted anyway. +If +.I file +cannot be replaced, for example because another program has it open, +the command fails and leaves the temporary file behind. +A read error partway through a +.I file +is taken as its end, so the part read before it replaces +.I file +and no error is reported. +.PP +File names may use drive letters and backslashes. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +.SH SEE ALSO +.BR busybox (1), +.BR tr (1), +.BR xxd (1) diff --git a/man/man1/du.1 b/man/man1/du.1 new file mode 100644 index 0000000..1d6dcf4 --- /dev/null +++ b/man/man1/du.1 @@ -0,0 +1,411 @@ +.TH DU 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +du \- report the disk space used by files and directories +.SH SYNOPSIS +.B du +.RB [ \-abchHklLmsx ] +.RB [ \-d +.IR N ] +.RI [ file ...] +.SH DESCRIPTION +.B du +prints the disk space used by each +.I file +and, for a directory, by everything below it. +With no +.IR file , +it reports on the current directory. +This +.B du +is the busybox applet; see +.BR busybox (1). +.PP +Each line of output is a size, a tab, and a name. +The name of a +.I file +is as given. +The name of an entry below a directory is the directory's name, a +.BR / , +and the entry's name, with no second +.B / +when the directory's name already ends in one, and none after a bare +drive such as +.BR c: . +A directory's line comes after the lines of the entries below it, which +appear in the order Windows lists them. +.PP +There is a line for each +.IR file , +and for each directory below one. +.B \-a +adds a line for each other file, and +.B \-d +and +.B \-s +remove lines. +A directory's size includes everything below it, whether or not that +has a line of its own. +.PP +The size of a file is an estimate of the space allocated to it, described +under +.BR NOTES , +not the length of its data. +A size counts units of 1024 bytes, or of 512 bytes when +.B POSIXLY_CORRECT +is set. +.BR \-b , +.BR \-h , +.BR \-k , +and +.B \-m +change the unit or the size. +.SS What is counted +.IP \(bu 2 +A file with several hard links is counted once, under the first of its +names that +.B du +reaches. +Its other names add nothing and get no line, even with +.BR \-a . +.IP \(bu 2 +A directory that +.B du +has already reached is skipped: it is not counted and gets no line. +So +.B "du a a/b" +prints the same as +.BR "du a" , +and +.B "du a/b a" +prints the lines for +.B a/b +and then those for +.BR a , +whose size leaves out +.BR a/b . +.IP \(bu 2 +A symbolic link counts as itself, and +.B du +does not enter a linked directory, unless +.B \-H +or +.B \-L +says to follow it. +.PP +.B \-l +turns off the first two rules. +.SH OPTIONS +Options may be grouped, as in +.BR \-sh , +and may follow the operands unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +The argument of +.B \-d +may be attached, as in +.BR \-d1 , +or be the next argument. +There are no long options. +Of +.B \-H +and +.BR \-L , +of +.BR \-h , +.BR \-k , +and +.BR \-m , +and of +.B \-d +and +.BR \-s , +the one given last applies. +.TP +.B \-a +Print a line for each file, not only for each directory. +Ignored with +.BR \-s . +.TP +.B \-b +Print apparent sizes: the length of each file in bytes, not the space +allocated. +Without +.BR \-h , +.BR \-k , +or +.BR \-m , +sizes are in bytes, and with +.B \-k +or +.B \-m +they are rounded to the nearest unit. +A symbolic link counts the length of its target's name. +.TP +.B \-L +Follow all symbolic links. +A link counts as what it points to, and a link to a directory is +entered. +A link whose target cannot be examined is an error. +A directory reached again through a link is skipped, so a link that +points to its own directory does not loop. +With +.B \-l +it does, until the path is too long to examine, which is an error. +.TP +.B \-H +Follow symbolic links named as operands. +Once one is followed, links below it are followed too, as with +.BR \-L . +This applies to each operand separately. +.TP +.BI "\-d " N +Print a line only for an entry at most +.I N +levels below an operand. +.I N +is a decimal integer from 0 to 2147483647. +.B \-d 0 +prints only the operands, and +.B \-d 1 +adds the entries directly in them. +Sizes still include everything below. +.TP +.B \-c +After all operands, print a line named +.B total +with the sum of the operands' sizes. +Anything skipped as already counted is not in the sum. +.TP +.B \-l +Count and print a file once for each of its hard links, and do not skip +a directory that has been reached before. +.TP +.B \-s +Print only a line for each operand. +This is the same as +.BR "\-d 0" . +.TP +.B \-x +Skip any entry on a different volume from the operand it is below: it +is not counted and gets no line. +Volumes are told apart by serial number, and a link is on the volume +that holds the link, not the one that holds its target. +So with +.BR \-L , +a link to a directory on another volume gets a line, but nothing in +that directory is counted, even when the link is an operand. +.TP +.B \-h +Print sizes as a number with one decimal place and the suffix +.BR K , +.BR M , +.BR G , +.BR T , +.BR P , +or +.B E +for the largest power of 1024 that fits, as in +.BR 1.4M . +A size under 1024 bytes, possible only with +.BR \-b , +is a plain number of bytes, and a size of 0 is +.BR 0 . +.TP +.B \-m +Print sizes in units of 1048576 bytes. +Without +.BR \-b , +a size that is not a whole number of units is rounded up, so a nonzero +size is at least 1. +.TP +.B \-k +Print sizes in units of 1024 bytes. +This is the default unless +.B POSIXLY_CORRECT +is set, which +.B \-k +overrides. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted to its code page. +.TP +.B POSIXLY_CORRECT +When set, even to an empty value, the default unit is 512 bytes, and +the first operand ends the options. +.PP +Variables that affect every busybox applet, such as +.BR BB_GLOBBING , +are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +A +.I file +or an entry below one could not be examined, a directory could not be +opened, an option or the argument of +.B \-d +was invalid, or standard output could not be written. +.TP +.B 141 +Standard output is a pipe that was closed before all output was written. +A closed pipe found only when +.B du +flushes its output at exit gives status 1 instead. +.PP +After a failure to examine or open something, +.B du +reports it on standard error and carries on. +A file that cannot be examined is reported as +.PP +.RS 4 +.EX +du: \fIname\fR: \fIreason\fR +.EE +.RE +.PP +A directory that cannot be opened is reported as +.PP +.RS 4 +.EX +du: can\(aqt open \(aq\fIname\fR\(aq: \fIreason\fR +.EE +.RE +.PP +and gets no line. +An invalid option prints a message and the usage on standard error. +.SH EXAMPLES +Show the size of each directory directly under +.IR project : +.PP +.RS 4 +.EX +$ du \-hd 1 project +3.4M project/build +4.0K project/docs +60.0K project/src +3.4M project +.EE +.RE +.PP +Find the largest entries, in KiB: +.PP +.RS 4 +.EX +$ du \-a project | sort \-rn | head \-4 +3512 project +3444 project/build +3324 project/build/obj/main.o +3324 project/build/obj +.EE +.RE +.PP +Total several directories: +.PP +.RS 4 +.EX +$ du \-sc project/src project/docs +60 project/src +4 project/docs +64 total +.EE +.RE +.PP +Add up the lengths of files in bytes: +.PP +.RS 4 +.EX +$ du \-bc project/src/*.c +48000 project/src/main.c +9500 project/src/util.c +57500 total +.EE +.RE +.SH NOTES +The size of a file is its length rounded up to a multiple of 4096 +bytes, the cluster size that +.B du +assumes whatever the volume uses. +An empty file is 0. +A compressed or sparse NTFS file counts the space it occupies on disk +instead of its length, rounded the same way, which can be much less. +A directory counts the length Windows reports for it, which is 0 for a +small NTFS directory but not for one with many entries. +.B \-b +counts lengths instead. +.PP +.B du +treats a symbolic link, a junction, a volume mount point, and an app +execution alias alike, as a symbolic link. +One that is not followed counts as 4096 bytes, or with +.B \-b +the length of its target's name. +.PP +Paths may use +.B / +or +.BR \e , +but +.B du +adds +.B / +after a name that ends in a backslash, so the entries of +.B dir\e +are named +.BR dir\e/sub . +A drive-relative path such as +.B c:dir +works, and its entries are named +.BR c:dir/sub . +A bare drive such as +.B c: +is the current directory of that drive, and its entries are named +.BR c:sub . +A full path of 260 characters or more is reported as not found. +.PP +When started from +.BR cmd.exe , +.B du +expands wildcards in its operands; see +.BR busybox (1). +.PP +Differences from GNU +.BR du : +.IP \(bu 2 +There are no long options, such as +.BR \-\-max\-depth , +and no +.BR \-0 , +.BR \-B , +.BR \-D , +.BR \-P , +.BR \-S , +.BR \-t , +or +.BR \-X . +.IP \(bu 2 +.B \-a +is ignored with +.BR \-s , +where GNU +.B du +rejects the combination. +.IP \(bu 2 +Lines end with LF, not CRLF. +.SH SEE ALSO +.BR busybox (1), +.BR df (1), +.BR find (1), +.BR ls (1) diff --git a/man/man1/echo.1 b/man/man1/echo.1 new file mode 100644 index 0000000..a3059c2 --- /dev/null +++ b/man/man1/echo.1 @@ -0,0 +1,340 @@ +.TH ECHO 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +echo \- write arguments to standard output +.SH SYNOPSIS +.B echo +.RB [ \-neE ] +.RI [ arg ...] +.SH DESCRIPTION +.B echo +writes its arguments to standard output, separated by single spaces and +followed by a newline. +With no arguments it writes only the newline. +It reads no input. +.PP +Arguments are written byte for byte. +In particular, a backslash is an ordinary character unless +.B \-e +is given. +.PP +The kit's shell has +.B echo +as a builtin that runs this same code, so scripts see the behavior +described here; see +.BR sh (1). +Outside the shell, the +.I echo.exe +launcher runs the +.B busybox +applet; see +.BR busybox (1). +.SS Escape sequences +With +.BR \-e , +a backslash in an argument starts an escape sequence, which is replaced +as follows. +.TP +.B \ea +Alert (BEL, 0x07). +.TP +.B \eb +Backspace (0x08). +.TP +.B \ec +Stop: write nothing more, not even the newline. +Output from before it is kept, but the rest of this argument and all +later arguments are dropped. +.TP +.B \ee +Escape (0x1B). +.TP +.B \ef +Form feed (0x0C). +.TP +.B \en +Line feed (0x0A). +.TP +.B \er +Carriage return (0x0D). +.TP +.B \et +Tab (0x09). +.TP +.B \ev +Vertical tab (0x0B). +.TP +.B \e\e +Backslash. +.TP +\fB\e0\fInnn\fR, \fB\e\fInnn\fR +The octet whose octal value is +.IR nnn . +Either a +.B \e0 +and up to three octal digits, or one to three octal digits the first of +which is 1 to 7. +A value above 255 ends the sequence before the digit that would exceed +it, so +.B \e400 +is a space (octal 40) followed by +.BR 0 . +A +.B \e0 +that is not followed by an octal digit is a NUL octet. +.TP +.BI \ex HH +The octet whose hexadecimal value is +.IR HH , +one or two digits in either case. +A +.B \ex +not followed by a hexadecimal digit is written as is. +.PP +A backslash followed by any other character, or ending an argument, is +written as is, and the character after it is then read normally. +So +.B \eE +and +.B \eu0041 +are written unchanged. +.SH OPTIONS +Options are recognized only at the start of the arguments, and may be +grouped, as in +.BR \-ne . +An argument is an option only if it is a dash followed by one or more of +the letters +.BR n , +.BR e , +and +.BR E . +The first argument that is not, such as +.BR \-\- , +a lone +.BR \- , +.BR \-x , +or +.BR \-nx , +ends the options: it and all later arguments are written as ordinary +arguments. +Neither +.B \-\- +nor +.B \-\-help +is special: they are written like any other argument. +.TP +.B \-n +Do not write the trailing newline. +.TP +.B \-e +Interpret backslash escape sequences, as described under +.BR "Escape sequences" . +.TP +.B \-E +Do not interpret backslash escape sequences. +This is the default. +It does not cancel an earlier +.BR \-e : +both +.B "echo \-e \-E" +and +.B "echo \-E \-e" +interpret escapes. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.BR BB_TERMINAL_MODE ", " BB_SKIP_ANSI_EMULATION +When standard output is a console, decide whether the console or busybox +interprets the escape sequences in the output, such as for color. +See +.BR busybox (1). +.TP +.B CONEMUPID +When it is set and neither of the above is, busybox uses terminal mode +0: it turns virtual terminal output off and emulates escape sequences +itself. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Standard output could not be written. +A message such as +.B "echo: write error: Bad file descriptor" +is written to standard error. +In the shell's builtin the message begins with the shell's name, such as +.BR sh: , +instead. +.TP +.B 141 +Standard output is a pipe that was closed before the output was written. +In the shell's builtin, the shell process running it exits with this status. +.SH EXAMPLES +Write a line: +.PP +.RS 4 +.EX +$ echo hello world +hello world +.EE +.RE +.PP +Write a prompt, leaving the cursor on the same line: +.PP +.RS 4 +.EX +$ echo \-n \(aqContinue? \(aq +.EE +.RE +.PP +Without +.BR \-e , +backslashes are written as is: +.PP +.RS 4 +.EX +$ echo \(aqone\entwo\(aq +one\entwo +$ echo \-e \(aqone\entwo\(aq +one +two +.EE +.RE +.PP +Write a file with CR LF line endings: +.PP +.RS 4 +.EX +$ echo \-e \(aqfirst\er\(aq >dos.txt +$ echo \-e \(aqsecond\er\(aq >>dos.txt +.EE +.RE +.PP +Write a word in red on a console: +.PP +.RS 4 +.EX +$ echo \-e \(aq\ee[31mred\ee[0m\(aq +.EE +.RE +.PP +Write a string that +.B echo +would take as an option, using +.BR printf (1) +instead: +.PP +.RS 4 +.EX +$ printf \(aq%s\en\(aq \-n +\-n +.EE +.RE +.SH NOTES +Differences from GNU +.B echo +and bash: +.IP \(bu 2 +A later +.B \-E +does not turn off an earlier +.BR \-e . +.IP \(bu 2 +An octal value above 255 ends the escape sequence early instead of +wrapping modulo 256. +.IP \(bu 2 +As in GNU +.B echo +but not bash, an octal escape may omit the leading zero: +.B \e101 +is +.BR A . +.IP \(bu 2 +The bash escapes +.BR \eE , +.BR \eu , +and +.B \eU +are not recognized. +.IP \(bu 2 +Unlike GNU +.BR echo , +there are no +.B \-\-help +or +.B \-\-version +options. +.PP +Standard output is binary, so the newline is a bare LF. +To end a line with CR LF, use +.B \-e +and +.BR \er . +.PP +In +.BR cmd.exe , +.B echo +is a built-in command that runs instead of the applet, and in PowerShell +it is an alias for +.BR Write-Output . +Run +.B echo.exe +or +.B busybox echo +there. +Since the C runtime then expands wildcards, even in quoted arguments, +.B echo.exe *.c +lists the matching files; set +.B BB_GLOBBING +to +.B 0 +to prevent that. +.PP +With +.BR \-e , +a backslash in a Windows path is an escape: in +.BR C:\etemp , +.B \et +is a tab. +Write such paths with forward slashes, or leave out +.BR \-e . +In the kit's shell, quote such an argument in single quotes: unquoted, +the shell removes the backslash before +.B echo +sees it. +.PP +Arguments may contain any Unicode character on Windows 10 version 1903 +and later, and are limited to the system code page on earlier versions. +When standard output is a console, the output is converted for display +from the ANSI code page, which is UTF-8 on Windows 10 version 1903 and +later. +Escape sequences, such as those for color, take effect, and busybox +emulates them on consoles without virtual terminal support. +The whole output is one block, so on a console a NUL octet in it, such +as from +.BR \e0 , +makes busybox write all of it unconverted and without escape sequence +emulation. +.SH SEE ALSO +.BR busybox (1), +.BR printf (1), +.BR sh (1) diff --git a/man/man1/ed.1 b/man/man1/ed.1 new file mode 100644 index 0000000..f12496c --- /dev/null +++ b/man/man1/ed.1 @@ -0,0 +1,667 @@ +.TH ED 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +ed \- line-oriented text editor +.SH SYNOPSIS +.B ed +.RB [ \-p +.IR prompt ] +.RB [ \-s ] +.RI [ file ] +.SH DESCRIPTION +.B ed +is the original Unix text editor. +It reads a file into a buffer of lines, changes the buffer with commands +read from standard input, and writes the file only when told to. +This one is a small implementation with a subset of the usual commands; +see +.BR NOTES . +.PP +With a +.I file +operand, +.B ed +reads the file into the buffer, prints the number of bytes read unless +.B \-s +is given, and remembers the name for +.B w +and +.BR f . +The last line becomes the current line. +If the file cannot be read, +.B ed +reports the error and exits with status 0 without reading any command, +so it cannot start a new file. +Start +.B ed +with no operand and name the file with +.B w +instead. +Operands after the first are ignored. +With no +.IR file , +the buffer is empty and has no file name. +.PP +Each line of input is one command: optional addresses, a command letter, +and its argument. +Blanks may surround addresses and precede the command letter, and +trailing blanks on the line are dropped. +A command that fails prints a message on standard error and +.B ed +reads the next command. +There is no +.B ?\& +response and no help command. +.PP +Lines printed by commands, byte counts, and the answers to +.B f +and +.B = +go to standard output. +Error messages, the +.B \-p +prompt, and the +.B Really quit?\& +prompt go to standard error. +.SS Addresses +An address names a line. +.TP +.I n +A decimal line number, counting from 1. +Line 0 stands for the position before the first line. +The +.B a +and +.B r +commands accept it, and most others report an error. +.TP +.B . +The current line. +.TP +.B $ +The last line. +.TP +.BI \(aq x +The line marked with the lowercase letter +.I x +by the +.B k +command. +.TP +.BI / text / +The first line from the current line to the last that contains +.IR text . +The search starts at the current line itself, so repeating it finds the +same line, and it does not wrap around. +The text is matched literally, not as a regular expression, and cannot +contain a slash. +If the closing slash is missing, the rest of the line is the text. +An empty +.I text +repeats the last string searched for by an address or by +.BR s . +.PP +Addresses can be added and subtracted, as in +.BR $\-2 , +.BR .+1 , +and +.BR /text/+3 . +Blanks are allowed around operands and operators. +A leading +.B + +or +.B \- +is not an address. +Whether the result lies in the buffer is checked by the command that +uses it. +.PP +A range is two addresses separated by a comma. +A missing first address means 1 and a missing second means +.BR $ , +so a lone comma means the whole buffer. +There are no semicolon ranges. +Both addresses are evaluated from the current line, so a search in the +second does not start after the first. +Given one address, a command that takes a range applies to that line +alone. +.SS Text input +The +.BR a , +.BR c , +and +.B i +commands read lines of text and add them to the buffer. +Input ends at a line holding only a period, which is not added, so a +line of text cannot be a lone period. +It also ends at the end of input, and in a console at Ctrl\-D on an empty +line or at Ctrl\-C, which discards the line being typed. +The last line added becomes the current line. +The prompt is not shown in this mode. +.PP +The insertion point is checked only when the first line of text +arrives. +If it is out of range, +.B ed +reports +.BR "inserting at bad line number" , +discards that line, and reads the lines after it as commands. +.SS Commands +In the forms below, omitting an address in brackets uses the current line +unless noted. +The commands +.BR a , +.BR c , +.BR d , +.BR i , +.BR l , +.BR p , +and +.B = +ignore any text after the command letter. +The commands +.BR f , +.BR r , +and +.B w +need a space, not a tab, before their argument. +Any other command letter is reported as +.BR "unimplemented command" . +.TP +\fR[\fIaddr\fR]\fBa\fR +Read text and insert it after line +.IR addr . +With a range, the first address is used. +.TP +\fR[\fIrange\fR]\fBc\fR +Delete the lines, then read text and insert it where they were. +If the range is invalid, nothing is deleted, but +.B ed +still reads text and inserts it before the first address. +.TP +\fR[\fIrange\fR]\fBd\fR +Delete the lines. +If the current line was deleted, the line after them becomes current, or +the new last line when none follows, or line 0 when the buffer is empty. +Otherwise the same line stays current. +.TP +\fBf\fR [\fIname\fR] +With +.IR name , +make it the remembered file name, which +.B w +uses when given none. +The name is the rest of the line after the blanks, so it may contain +spaces. +Without +.IR name , +print the current file name in double quotes, or +.B No file name +if there is none. +.TP +\fR[\fIaddr\fR]\fBi\fR +Read text and insert it before line +.IR addr . +With a range, the first address is used. +In an empty buffer with no address, the text becomes line 1. +.TP +\fR[\fIaddr\fR]\fBk\fIx\fR +Mark a line with the lowercase letter +.IR x . +With a range, the last address is used. +The address is not checked. +A mark is a line number, so it does not follow its line when lines are +added or deleted. +An unset mark is line 0. +.TP +\fR[\fIrange\fR]\fBl\fR +Print the lines unambiguously. +A control character appears as +.B ^ +and a character, such as +.B ^I +for a tab, +.B ^M +for a carriage return, and +.B ^[ +for escape. +Delete appears as +.BR ^? . +A byte above 127 appears as +.B M\- +followed by the byte with its high bit cleared, shown the same way, so +UTF-8 text appears as +.B M\- +sequences. +Each line ends with +.BR $ , +long lines are not folded, and a backslash or dollar sign in the text +appears as itself. +The last line printed becomes current. +.TP +\fR[\fIrange\fR]\fBp\fR +Print the lines exactly as stored. +A final line that has no newline is printed without one. +The last line printed becomes current. +.TP +.B q +Quit. +No address or argument is allowed. +If the buffer has changed since it was read or last written by +.B w +without an address, +.B ed +prints +.B Really quit?\& +and reads a line. +It quits if the first non-blank character of that line is +.B y +or +.BR Y , +and otherwise continues. +End of input at that prompt quits, and Ctrl\-C continues. +The commands +.BR a , +.BR c , +.BR d , +.BR i , +.BR r , +and a +.B s +that replaces something change the buffer. +End of input or Ctrl\-C at the ordinary command prompt exits without the +check, losing any changes. +.TP +\fR[\fIaddr\fR]\fBr \fIfile\fR +Read +.I file +and insert its lines after line +.IR addr , +which is the first address of a range and defaults to the last line. +Address 0 inserts before the first line. +The byte count is printed unless +.B \-s +is given. +The last line read becomes current. +The file name is the rest of the line after the blanks. +It is required: the remembered file name is not used, and there is no +form that runs a command. +.TP +\fR[\fIrange\fR]\fBs/\fIold\fB/\fInew\fB/\fR[\fIflags\fR] +Replace the first occurrence of +.I old +in each line of the range by +.IR new . +Any character except a space or tab may replace the slashes. +The strings are literal: there are no regular expressions, and +.BR & , +.BR \e1 , +and backslash have no special meaning. +The delimiter cannot appear in either string. +An empty +.I old +repeats the last string searched for by an address or by +.BR s , +and an empty +.I new +deletes. +The final delimiter may be omitted when there are no flags, and +trailing blanks on the command line are dropped, so end +.I new +with the delimiter to keep trailing blanks. +The flags are +.BR g , +to replace every occurrence, left to right, without rescanning the +replacement, and +.BR p , +to print each changed line. +It is an error if no line changed. +The current line does not change, except that with +.B p +the last line printed becomes current. +.TP +\fR[\fIrange\fR]\fBw\fR [\fIfile\fR] +Write the lines to +.IR file , +or when it is omitted to the remembered file name, replacing the +contents of the file. +With no address, the whole buffer is written and counts as saved, even if +the write fails, so a following +.B q +quits without asking. +With an address, only those lines are written and the saved state is +unchanged. +The name given does not become the remembered name. +The byte count is printed unless +.B \-s +is given. +An empty buffer cannot be written. +There is no +.B wq +command. +.TP +\fBz\fR[\fB.\fR|\fB\-\fR] +Print 22 lines: with no argument, from the current line; +with +.BR . , +from 11 lines before it to 10 after; +with +.BR \- , +ending at it. +The last line printed becomes current. +An address, and any other text after +.BR z , +is ignored. +All 22 lines must lie inside the buffer, or the command fails. +.TP +\fR[\fIaddr\fR]\fB=\fR +Print the line number that +.I addr +gives, which is the first address of a range and defaults to the current +line. +.B $= +prints the number of lines. +.TP +.B \- +Make the previous line current and print it. +Text after it is ignored, so +.B \-3 +also goes back one line. +.TP +\fR[\fIrange\fR] +A line with no command letter prints the last line of the range, which +becomes current. +With no address, it prints the line after the current line, which +becomes current. +.SH OPTIONS +.B ed +accepts options before or after the file operand, unless +.B POSIXLY_CORRECT +is set. +The last of repeated options wins. +An argument may follow +.B \-p +attached or as the next argument. +.B \-\- +ends the options. +.TP +.BI "\-p " prompt +Show +.I prompt +on standard error before reading each command, even when input is not a +console. +It is not shown in text input mode. +Backslash sequences in it are expanded as in the shell prompts described +in +.BR sh (1), +such as +.B \eu +for the user name, +.B \e$ +for a dollar sign, or a number sign when elevated, and +.B \et +for the time. +.B \ew +and +.BR \eW , +the current directory, work only when standard input is not a console: +in a console they crash +.BR ed . +Parameters and commands in it are not expanded. +The default is no prompt. +.TP +.B \-s +Do not print the byte counts for reading and writing files. +Error messages and all other output are unchanged. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when +.B ed +starts, as needed when it is run from +.BR cmd.exe . +Quoted arguments are expanded too, so a prompt such as +.B * +given to +.B \-p +may become file names. +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.B BB_UMASK +The file mode creation mask, in octal. +When it includes the owner write bit, +.BR 200 , +files that +.B w +creates are read-only, so a later +.B w +cannot replace them. +.TP +.B COLUMNS +The console width that the line editor wraps and redraws lines to. +The default is the width of the console window of standard output or +standard error, or 80 when neither is a console. +.TP +.B HOME +The directory that +.B \ew +and +.B \eW +in the +.B \-p +prompt show as +.BR ~ . +When it is unset or empty, +.B ed +uses the user's profile directory. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +The first of these that is set decides how the line editor handles text. +When its value is +.BR C , +text is single bytes, and console output is written without code page +conversion. +Otherwise text is UTF-8 when the ANSI code page is UTF-8, and single +bytes when it is not. +.TP +.B POSIXLY_CORRECT +When set, the +.I file +operand ends the options, so that a later argument such as +.B \-s +is an ignored extra operand. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every normal end: the +.B q +command, end of input, Ctrl\-C or Ctrl\-D at the command prompt, or +.BR \-\-help . +Errors in commands, and a file operand that cannot be read, do not change +the status. +.TP +.B 1 +An invalid option or a missing option argument, with a usage message on +standard error, or out of memory. +.SH EXAMPLES +Replace every +.B old +with +.B new +in a file, from a script: +.PP +.RS 4 +.EX +$ ed \-s config.h <<\(aqEOF\(aq +,s/old/new/g +w +q +EOF +.EE +.RE +.PP +Print lines 10 to 20 of a file: +.PP +.RS 4 +.EX +$ printf \(aq10,20p\en\(aq | ed \-s file.txt +.EE +.RE +.PP +Insert a line at the top of a file, and save it: +.PP +.RS 4 +.EX +$ printf \(aq0a\en#include \en.\enw\enq\en\(aq | ed \-s main.c +.EE +.RE +.PP +Create a file: +.PP +.RS 4 +.EX +$ printf \(aqa\enhello\en.\enw hello.txt\enq\en\(aq | ed \-s +.EE +.RE +.PP +Print the number of lines in a file: +.PP +.RS 4 +.EX +$ printf \(aq$=\en\(aq | ed \-s file.txt +.EE +.RE +.SH NOTES +This is the +.B ed +of busybox, derived from a small 2002 implementation, not GNU +.BR ed . +It differs from POSIX +.B ed +in many ways: +.IP \(bu 2 +Searches and substitutions are literal text. +There are no regular expressions, no backward search, and no semicolon +ranges. +.IP \(bu 2 +Only the commands above exist. +There is no undo, no +.BR g , +.BR v , +.BR j , +.BR m , +.BR t , +.BR u , +.BR e , +.BR E , +.BR n , +.BR h , +.BR H , +.BR P , +.BR Q , +or +.BR ! , +and no suffix such as +.B p +or +.B n +after a command other than +.BR s . +.IP \(bu 2 +Errors are messages on standard error, and the exit status does not +report them. +.IP \(bu 2 +Commands that take one address accept a range and use its first address, +except +.BR k , +which uses the last. +.B = +without an address prints the current line number rather than the number +of lines. +.IP \(bu 2 +A successful +.B r +does not set the remembered file name, but a failed +.B r +sets it when there is none. +.B w +never sets it. +.PP +The whole buffer is held in memory. +Files are read and written in binary mode, so +.B ed +never translates line endings or character sets. +A line from a file with CR LF endings keeps its carriage return, which +.B p +sends to the output, +.B l +shows as +.BR ^M , +and +.B s +patterns can match. +.PP +When standard input is not a console, a carriage return before a newline +is dropped from each line read. +A lone period ended by CR LF is still not recognized as the end of text +input, so the rest of the input becomes text. +Scripts for +.B ed +need LF line endings, as made by +.BR dos2unix (1). +.PP +In a console, lines are edited with the line editor of +.BR sh (1), +using the keys in its Line editing section, but with no history, no +completion, and no vi mode. +Up, Down, and Tab do nothing, so a tab cannot be typed. +Typing into the history search that Ctrl\-R starts crashes +.BR ed , +losing the buffer. +Ctrl\-Z changes backslashes in the line to slashes. +Ctrl\-C, or Ctrl\-D on an empty line, at the command prompt exits +.BR ed , +discarding unsaved changes. +.PP +A command holds at most 1021 characters, and a line of text 1022, not +counting the newline. +A console ignores further typing. +From a pipe or file, the excess is read as a separate command or line of +text, and pieces of text rejoin when written. +.PP +File names may use drive letters and either kind of slash. +The file operand and +.B r +also accept the device names listed in +.BR busybox (1), +such as +.IR /dev/null , +but +.B w +does not: it treats +.I /dev/null +as an ordinary path, which usually fails. +.PP +On a console, escape sequences in the text of a line take effect when +.B p +prints it, so use +.B l +to look at them. +.SH SEE ALSO +.BR busybox (1), +.BR dos2unix (1), +.BR sed (1), +.BR sh (1), +.BR vim (1) diff --git a/man/man1/egrep.1 b/man/man1/egrep.1 new file mode 100644 index 0000000..6a74c5d --- /dev/null +++ b/man/man1/egrep.1 @@ -0,0 +1 @@ +.so man1/grep.1 diff --git a/man/man1/env.1 b/man/man1/env.1 new file mode 100644 index 0000000..be44b31 --- /dev/null +++ b/man/man1/env.1 @@ -0,0 +1,383 @@ +.TH ENV 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +env \- run a program in a modified environment, or print the environment +.SH SYNOPSIS +.B env +.RB [ \-i0 ] +.RB [ \-u +.IR name ]...\& +.RB [ \- ] +[\fIname\fB=\fIvalue\fR]...\& +.RI [ prog +.RI [ arg ...]] +.SH DESCRIPTION +.B env +changes the environment it inherited, then either runs +.I prog +in the changed environment or, when there is no +.IR prog , +prints it. +It makes the changes in this order: +.IP 1. 4 +With +.B \-i +or a lone +.BR \- , +every inherited variable is removed. +.IP 2. 4 +Each +.B \-u +.I name +is removed. +.IP 3. 4 +Each +.IB name = value +operand sets a variable, from left to right. +So an assignment overrides a +.B \-u +of the same name. +.PP +After the options and any lone +.BR \- , +an operand that contains an +.B = +is an assignment, and the first operand that does not is +.IR prog . +The operands after +.I prog +are its arguments and reach it unchanged, even if they contain an +.BR = . +.PP +With +.IR prog , +.B env +runs it with its own standard input, standard output, and standard +error, waits for it, and exits with its exit status. +The lookup of +.I prog +uses the changed environment, so a +.B PATH +assignment takes effect, and with no +.B PATH +only applets and names that include a directory are found. +The lookup follows +.B Running commands +in +.BR busybox (1), +with one difference from the shell: a +.I prog +of +.IR /bin/name , +.IR /usr/bin/name , +.IR /sbin/name , +or +.I /usr/sbin/name +runs the applet +.I name +if there is one, or else that file if it exists, or else the program +.I name +in +.BR PATH . +.PP +Without +.IR prog , +.B env +writes the changed environment to standard output, one variable per +line as +.IB name = value\fR. +The variables it inherited come first, in the order Windows supplied +them. +New variables follow in the order they were added, starting with any +.B BB_GLOBBING +that busybox added; see +.BR ENVIRONMENT . +.SH OPTIONS +Options may be grouped, as in +.BR \-i0 . +They are recognized only before the first operand: everything from the +first operand on, even one that begins with a dash, is an operand. +.B \-\- +ends the options. +Long options may be shortened to any unambiguous prefix. +.TP +.BR \-i ", " \-\-ignore\-environment +Start with an empty environment. +.TP +.B \- +Same as +.BR \-i , +but an operand, not an option. +It counts only as the first operand. +In any later position it is an ordinary operand. +.TP +.BR \-0 ", " \-\-null +Write each variable of the listing followed by a NUL octet instead of a +LF. +It has no effect when +.I prog +runs. +.TP +\fB\-u\fR \fIname\fR, \fB\-\-unset\fR \fIname\fR +Remove the variable +.I name +from the environment. +The option may be repeated. +Removing a variable that is not set is not an error. +The argument of the short option may be attached, as in +.BR \-uPATH , +and the long option also takes it as +.BI \-\-unset= name\fR. +An argument that contains an +.B = +is not a name: it sets that variable, as an assignment would, and +removes nothing. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are ignored. +.SH ENVIRONMENT +Except for +.BR BB_GLOBBING , +these are read from the changed environment, so the options and +assignments affect them. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +busybox expands wildcards in the arguments of +.B env +itself when it starts, as needed when run from +.BR cmd.exe . +If the variable is not set then, busybox sets it to +.BR 0 . +Because +.B env +passes its environment on, the listing then includes +.B BB_GLOBBING=0 +and so does +.IR prog 's +environment, unless +.B \-i +or +.B \-u +removed it. +Without it, an applet run as +.I prog +expands wildcards in its arguments again, so +.B env \-i ls \(aq*.c\(aq +lists the matching files. +.TP +.B BB_OVERRIDE_APPLETS +Which names run an applet and which run a program from +.BR PATH ; +see +.BR busybox (1). +.TP +.BR BB_TERMINAL_MODE ", " BB_SKIP_ANSI_EMULATION +When standard output is a console, decide whether the console or busybox +interprets the escape sequences in the listing, such as for color. +See +.BR busybox (1). +.TP +.B CONEMUPID +When it is set and neither of the above is, busybox uses terminal mode +0: it turns virtual terminal output off and emulates escape sequences +itself. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +the listing is written to a console without code page conversion, and +the console interprets the bytes in its own code page. +.TP +.B PATH +Where +.I prog +is looked up. +Directories are separated by semicolons. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +The environment was printed. +.TP +.B 1 +An invalid option, or an option without its argument, with a usage +message on standard error. +Also an operand that cannot be set as a variable, such as one that +begins with +.BR = , +with the message +.BR "env: putenv: Invalid argument" , +or an error writing standard output. +.TP +.B 126 +.I prog +was found but could not be started. +.TP +.B 127 +.I prog +was not found. +.PP +For both of the last two, standard error gets +.PP +.RS 4 +.EX +env: can\(aqt execute \(aq\fIprog\fR\(aq: \fIreason\fR +.EE +.RE +.PP +Otherwise the status is that of +.IR prog ; +see +.BR NOTES . +.SH EXAMPLES +Run +.B make +with a variable set for that run only: +.PP +.RS 4 +.EX +$ env CFLAGS=\-O2 make +.EE +.RE +.PP +Run a command with a minimal environment: +.PP +.RS 4 +.EX +$ env \-i PATH="$PATH" make +.EE +.RE +.PP +Run a command without a variable: +.PP +.RS 4 +.EX +$ env \-u MAKEFLAGS make +.EE +.RE +.PP +Show the environment that the options and assignments build: +.PP +.RS 4 +.EX +$ env \-i FOO=1 BAR=2 +FOO=1 +BAR=2 +.EE +.RE +.PP +Count the variables, correctly even for values that contain newlines: +.PP +.RS 4 +.EX +$ env \-0 | tr \-cd \(aq\e0\(aq | wc \-c +.EE +.RE +.SH NOTES +Windows has no exec. +.B env +starts +.I prog +as a child process, waits for it, and exits with its exit code. +A code above 255, such as an NTSTATUS value, is reduced to its low +byte, or to 255 when that is zero, after +.B env +writes a message giving the code in hex to standard error. +The codes that busybox treats as signals, such as an access violation +and Ctrl+C, are passed on unchanged. +.PP +While +.I prog +runs, Ctrl+C and Ctrl+Break do not end +.BR env . +A +.I prog +attached to the console receives them itself, and any other +.I prog +is ended, with its child processes, as if by +.BR SIGINT . +.PP +A +.I prog +that is not found is reported with status 127. +So is one that busybox does not consider executable: a directory, or a +file that has none of the suffixes +.BR .com , +.BR .exe , +.BR .sh , +.BR .bat , +and +.BR .cmd , +does not begin with +.BR #!\& , +and is not a PE image. +A file that busybox considers executable but that Windows cannot run, +such as an +.I .exe +that is not a valid program, gives status 126. +.PP +Variable names are case-insensitive. +An assignment to +.B Path +replaces +.BR PATH , +and +.B \-u path +removes it. +The name takes the spelling of the assignment. +.PP +A variable may have an empty value, as in +.IB name =\fR, +which +.B env +keeps and passes on. +A name may not be empty: an operand that begins with +.B = +fails. +.PP +busybox runs this applet for a +.B #!/usr/bin/env +line in a script, so a line such as +.B #!/usr/bin/env sh +works; see +.BR busybox (1). +The rest of the line after the interpreter is a single argument, so +.B #!/usr/bin/env \-i sh +fails. +.PP +Differences from GNU +.BR env : +only +.BR \-i , +.BR \-0 , +.BR \-u , +and their long forms exist, so there is no +.BR \-C , +.BR \-S , +or +.BR \-v , +and there is no +.BR \-\-version . +An argument of +.B \-u +that contains an +.B = +sets a variable, and +.B \-0 +with +.I prog +is accepted. +An invalid option gives status 1, not 125. +.PP +The listing ends each line with a bare LF, not CR LF. +.SH SEE ALSO +.BR busybox (1), +.BR printenv (1), +.BR sh (1), +.BR tr (1), +.BR wc (1) diff --git a/man/man1/expand.1 b/man/man1/expand.1 new file mode 100644 index 0000000..885861c --- /dev/null +++ b/man/man1/expand.1 @@ -0,0 +1,216 @@ +.TH EXPAND 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +expand \- convert tabs to spaces +.SH SYNOPSIS +.B expand +.RB [ \-i ] +.RB [ \-t +.IR N ] +.RI [ file ...] +.SH DESCRIPTION +.B expand +copies files to standard output, replacing each tab with the spaces that +reach the next tab stop. +Tab stops are every 8 columns, or every +.I N +columns with +.BR \-t . +It reads each +.I file +in order, and reads standard input when there are no +.I file +operands, or for a +.I file +named +.BR \- . +.PP +Bytes other than tabs and NULs are copied unchanged, including carriage +returns. +Line endings are not converted, and a last line without a newline gets +none. +.BR unexpand (1) +converts in the other direction. +.PP +A tab pads the text before it on the line to the next multiple of +.I N +columns, and a tab that is already at a tab stop moves to the following +one. +After a tab, the count continues from that tab stop. +Text is measured in columns, not bytes. +In UTF-8 text, a wide character such as an ideograph is 2 columns, a +combining or other zero-width character is 0, and an invalid sequence +is 1. +In single-byte text, every byte is 1 column; see +.BR ENVIRONMENT . +Every control character is 1 column, including backspace, carriage +return, and escape. +Backspace does not move the column back, and the bytes of an escape +sequence count. +.PP +A NUL byte is deleted from the output and starts the count over, as if +a new line began there. +.SH OPTIONS +Options may be grouped, as in +.BR \-it4 , +and the argument of +.B \-t +may be attached, as in +.BR \-t4 , +or be the next argument. +Long options may be abbreviated to a unique prefix, and the argument of +.B \-\-tabs +may follow +.B = +or be the next argument. +Options may follow operands, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +If +.B \-t +is repeated, the last one applies. +.TP +.BR \-i ", " \-\-initial +Convert only tabs at the start of a line. +Conversion stops at the first character that is not a space or tab, and +later tabs are copied unchanged. +Spaces and tabs before it count toward the column. +.TP +\fB\-t\fR \fIN\fR, \fB\-\-tabs=\fIN\fR +Set tab stops every +.I N +columns. +The default is 8. +.I N +is a decimal integer from 1 to 4294967295, with no sign, prefix, or +suffix, and a leading zero does not make it octal. +It is a single number, not a list. +Any other value is an error, reported before any input is read. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when +.B expand +starts, as needed when it is run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +The first of these that is set, even to an empty value, decides how text +is measured. +If its value is +.BR C , +text is single bytes, each 1 column, and output to a console is not +converted. +Otherwise text is UTF-8 when the ANSI code page is UTF-8, and single +bytes when it is not. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An unknown option, a missing option argument, or an invalid +.IR N ; +a +.I file +that could not be opened or read, including a directory; or a failure +writing standard output. +.TP +.B 141 +Standard output is a pipe whose reader has exited. +.PP +Error messages begin with +.B expand: +and go to standard error. +An unknown option or a missing option argument also prints the usage +message. +The remaining files are still processed after one cannot be opened or +read. +.SH EXAMPLES +Expand the tabs in a stream: +.PP +.RS 4 +.EX +$ printf \(aqa\etb\en\etc\en\(aq | expand +a b + c +.EE +.RE +.PP +Put tab stops every 4 columns, writing a new file: +.PP +.RS 4 +.EX +$ expand \-t 4 main.c >main4.c +.EE +.RE +.PP +Replace indentation tabs in a file, leaving the tabs inside lines: +.PP +.RS 4 +.EX +$ expand \-i main.c >main.tmp && mv main.tmp main.c +.EE +.RE +.PP +Expand several files into one: +.PP +.RS 4 +.EX +$ expand a.txt b.txt >both.txt +.EE +.RE +.SH NOTES +Differences from GNU expand: +.IP \(bu 2 +.B \-t +takes one number, not a list of tab stops. +.IP \(bu 2 +There is no +.BI \- N +form of +.BR \-t , +and there is no +.BR \-\-version . +.IP \(bu 2 +Backspace is one column. +GNU expand moves the column back. +.IP \(bu 2 +NUL bytes are deleted. +GNU expand keeps them. +.PP +A tab interval above 2147483647 is accepted but does not pad correctly, +because the padding width is a signed int. +.PP +Files and standard streams are binary, with no CRLF translation. +The ANSI code page of busybox is UTF-8 on Windows 10 version 1903 and +later, so text is UTF-8 there unless one of the variables above says +otherwise. +.PP +Each +.I file +may be a Windows path, with a drive letter and either kind of slash, or +a busybox-w32 device name such as +.IR /dev/null . +On Windows 10 version 1903 or later, file names may contain any Unicode +characters, and on older systems only those of the system code page. +.SH SEE ALSO +.BR busybox (1), +.BR unexpand (1) diff --git a/man/man1/expr.1 b/man/man1/expr.1 new file mode 100644 index 0000000..9671f02 --- /dev/null +++ b/man/man1/expr.1 @@ -0,0 +1,586 @@ +.TH EXPR 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +expr \- evaluate an expression +.SH SYNOPSIS +.B expr +.IR arg ... +.SH DESCRIPTION +.B expr +evaluates an expression and writes its value and a newline to standard +output. +It reads no input. +The expression is the command-line arguments, and each operator, +operand, keyword, and parenthesis must be a separate argument: +.B expr 1+2 +is the string +.BR 1+2 , +but +.B expr 1 + 2 +is 3. +Many operator characters are special to shells, so quote them; see +.BR NOTES . +.SS Values +A value is a string or a 64-bit signed integer. +Every argument is a string. +Arithmetic and comparisons use a string as an integer when the whole +string is one: optional leading white space, an optional +.B + +or +.BR \- , +and decimal digits, with nothing after them. +A leading zero does not make a number octal, so +.B 010 +counts as 10. +Hexadecimal and floating-point numbers are not integers. +A number outside the 64-bit range is replaced by the nearest limit, +and arithmetic that overflows wraps around without an error. +.PP +An integer is printed in decimal, and a string as it is, so +.B expr 007 +prints +.BR 007 , +and +.B expr 007 + 0 +prints +.BR 7 . +.PP +A value is null if it is the empty string, the string +.BR 0 , +or the integer 0. +Other strings, such as +.B 00 +and +.BR \-0 , +are not null. +.SS Operators +Operators are listed from the lowest precedence to the highest, and +operators of equal precedence group from left to right. +The comparison operators share a precedence, as do +.B + +and +.BR \- , +and as do +.BR * , +.BR / , +and +.BR % . +No operator skips an operand: in +.BR "expr 1 \e| 1 / 0" , +the division by zero is reported. +.TP +.IB arg1 " | " arg2 +.I arg1 +if it is not null, otherwise +.IR arg2 . +.TP +.IB arg1 " & " arg2 +.I arg1 +if neither argument is null, otherwise the integer 0. +.TP +.IB arg1 " < " arg2 +1 if the relation holds, otherwise 0. +The comparison operators are +.BR < , +.BR <= , +.BR = , +.BR == , +.BR != , +.BR >= , +and +.BR > , +and +.B = +is the same as +.BR == . +When both arguments are integers, they are compared as integers. +Otherwise both are compared as strings, byte by byte as unsigned values. +An integer is then converted back to decimal text first, so +.B 007 +compares as +.BR 7 . +.TP +.IB arg1 " + " arg2 +The sum. +Like the other arithmetic operators, it fails with the error +.B non\-numeric argument +unless both arguments are integers. +.TP +.IB arg1 " \- " arg2 +The difference. +.TP +.IB arg1 " * " arg2 +The product. +.TP +.IB arg1 " / " arg2 +The quotient, rounded toward zero. +A zero divisor is the error +.BR "division by zero" . +.TP +.IB arg1 " % " arg2 +The remainder, which has the sign of +.IR arg1 . +A zero divisor is the error +.BR "division by zero" . +.TP +.IB string " : " regexp +The result of matching +.I regexp +against the start of +.IR string ; +see +.BR "Pattern matching" . +.PP +The keywords below bind more tightly than any operator. +A keyword is recognized wherever an operand is expected. +Each takes the arguments after it as its operands, and an operand is a +word, a keyword with its own operands, or a parenthesized expression. +So +.B expr length abc + 1 +is 4. +.TP +.BI "match " string " " regexp +The same as the +.B : +operator with these arguments. +.TP +.BI "substr " string " " pos " " length +The substring of +.I string +that starts at byte +.IR pos , +counting from 1, and has at most +.I length +bytes. +It is empty, with no error, when +.I pos +or +.I length +is less than 1, when +.I pos +is beyond the end of +.IR string , +or when either is not an integer. +.TP +.BI "index " string " " chars +The position, counting from 1, of the first byte of +.I string +that is any of the bytes of +.IR chars , +or 0 if there is none. +.TP +.BI "length " string +The number of bytes in +.IR string . +.TP +.BI "quote " token +.I token +as a string, even if it is a keyword or a parenthesis. +Any other word is already a string where an operand is expected, even +one that looks like an operator, so +.B expr \(aq*\(aq +prints +.BR * . +.TP +.BI "( " expression " )" +The value of +.IR expression , +which overrides precedence. +Each parenthesis must be an argument by itself, so the argument +.B (1) +is only a string. +A +.B ) +where an operand is expected is a syntax error. +.SS Pattern matching +The +.B : +operator and +.B match +treat +.I regexp +as a POSIX basic regular expression, as implemented by the GNU regex +library that busybox carries. +It has intervals, +\fB\e{\fIm\fB,\fIn\fB\e}\fR, +back-references, and bracket expressions with character classes such as +.BR [[:digit:]] . +It also has the GNU extensions +.BR \e+ , +.BR \e? , +.BR \e| , +.BR \ew , +.BR \eW , +.BR \es , +.BR \eS , +.BR \eb , +.BR \eB , +.BR \e< , +.BR \e> , +.BR \e\(ga , +and +.BR \e\(aq , +the last two anchoring the start and end of +.IR string . +The characters +.BR + , +.BR ? , +.BR | , +.BR { , +and +.B } +are ordinary unless escaped. +Matching is case sensitive, and +.B .\& +matches any byte, including a newline. +.PP +The match must begin at the first byte of +.IR string , +but it need not reach the end, so end +.I regexp +with +.B $ +to require that. +The value is: +.IP \(bu 2 +With no match, the empty string if +.I regexp +has a group, +.BR \e( ...\e) , +and otherwise the integer 0. +.IP \(bu 2 +With a match and a group that took part in it, the text matched by the +first group, which may be empty. +.IP \(bu 2 +Otherwise, the number of bytes matched, as an integer. +.PP +A +.I regexp +that begins with +.B ^ +draws a warning on standard error: +.PP +.RS 4 +.EX +expr: warning: \(aq^a\(aq: using \(aq^\(aq as the first character +of a basic regular expression is not portable; it is ignored +.EE +.RE +.PP +Despite the message, the +.B ^ +is the usual start anchor and the evaluation continues. +Write a literal +.B ^ +there as +.BR \e^ . +A +.I regexp +that does not compile is an error; see +.BR "EXIT STATUS" . +.SH OPTIONS +.B expr +has no options. +Every argument, even one that starts with a dash, is part of the +expression, and +.B \-\- +is an ordinary string, so +.B expr \-\- 1 +is a syntax error. +Only one argument is special. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and exit +with status 0, ignoring the rest of the command line. +To write the string +.B \-\-help +first in an expression, use +.BR "quote \-\-help" . +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when +.B expr +starts, which can break expressions that contain +.B * +or +.BR ? ; +see +.BR NOTES . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.BR BB_TERMINAL_MODE ", " BB_SKIP_ANSI_EMULATION +When standard output is a console, decide whether the console or busybox +interprets the escape sequences in the output, such as for color. +See +.BR busybox (1). +.TP +.B CONEMUPID +When it is set and neither of the above is, busybox uses terminal mode +0: it turns virtual terminal output off and emulates escape sequences +itself. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +The value is not null, or the first argument was +.BR \-\-help . +.TP +.B 1 +The value is null. +This is not an error. +.TP +.B 2 +An error. +It is reported on standard error as +.BI "expr: " message +with one of these messages: +.RS +.TP +.B syntax error +An argument is missing, misplaced, or left over, or the parentheses do +not pair. +.TP +.B too few arguments +There are no arguments. +.TP +.B non\-numeric argument +An arithmetic operator was given an argument that is not an integer. +.TP +.B division by zero +The divisor of +.B / +or +.B % +is 0. +.TP +.BI "bad regex \(aq" regexp "\(aq: " reason +The regular expression does not compile, for a reason such as an +unmatched +.BR \e( . +.TP +.BI "standard output: " reason +Standard output could not be written, such as when it is closed or is +a pipe whose reader has exited. +.RE +.SH EXAMPLES +Add two numbers: +.PP +.RS 4 +.EX +$ expr 2 + 3 +5 +.EE +.RE +.PP +Quote an operator that the shell treats specially: +.PP +.RS 4 +.EX +$ expr 6 \e* 7 +42 +.EE +.RE +.PP +Increment a shell variable: +.PP +.RS 4 +.EX +$ i=$(expr $i + 1) +.EE +.RE +.PP +Count the bytes in a string: +.PP +.RS 4 +.EX +$ expr length "hello world" +11 +.EE +.RE +.PP +Take the first three bytes of a string: +.PP +.RS 4 +.EX +$ expr substr abcdef 1 3 +abc +.EE +.RE +.PP +Print the part of a name after the last dot: +.PP +.RS 4 +.EX +$ expr file.tar.gz : \(aq.*\e.\e(.*\e)\(aq +gz +.EE +.RE +.PP +Test a name against a pattern with the exit status: +.PP +.RS 4 +.EX +$ expr "$f" : \(aq.*\e.c$\(aq >/dev/null && echo C source +.EE +.RE +.PP +Use a default for an empty value: +.PP +.RS 4 +.EX +$ name= +$ expr "$name" \e| anonymous +anonymous +.EE +.RE +.SH NOTES +Differences from GNU +.BR expr : +.IP \(bu 2 +Integers are 64-bit, with no arbitrary-precision arithmetic. +.IP \(bu 2 +Strings are bytes, not multibyte characters. +.IP \(bu 2 +Every error exits with status 2, where GNU uses 3 for some of them. +.IP \(bu 2 +.B | +and +.B & +always evaluate both operands, so +.B expr 1 \e| 1 / 0 +fails instead of printing 1. +.IP \(bu 2 +When both operands of +.B | +are null, the value is the second operand, such as the empty string, +where POSIX and GNU give 0. +.IP \(bu 2 +There is no +.B + +prefix to force a string, only +.BR quote , +no +.BR \-\-version , +and no +.B \-\- +to end options. +.PP +In the kit's shell, quote or backslash +.BR * , +.BR ( , +.BR ) , +.BR < , +.BR > , +.BR & , +and +.BR | , +and write a regular expression in single quotes so that the shell keeps +its backslashes. +In +.BR cmd.exe , +put +.BR < , +.BR > , +.BR & , +and +.B | +in double quotes or precede each with +.BR ^ , +and write +.B % +as +.B %% +in a batch file. +.PP +When busybox is started from +.B cmd.exe +or PowerShell, the C runtime expands wildcards in its arguments, quoted +or not, before +.B expr +runs. +An argument containing +.B * +or +.BR ? , +such as the operator in +.BR "expr 6 * 7" , +is replaced by the names of the files it matches, and +.B expr +reports a syntax error. +An argument that matches no file is left as it is, so whether it fails +depends on the directory. +Set +.B BB_GLOBBING +to +.B 0 +first. +The kit's shell does its own expansion and is not affected. +.PP +Arguments may contain any Unicode character on Windows 10 version 1903 +and later, and are limited to the system code page on earlier versions. +.B expr +works on bytes, so +.BR length , +.BR substr , +.BR index , +and regular expressions count a UTF-8 character outside ASCII as 2 to 4 +bytes, and +.B .\& +matches one byte of it. +Strings are ordered by byte value. +.PP +Dividing +.B \-9223372036854775808 +by +.BR \-1 , +with +.B / +or +.BR % , +raises a processor exception. +Windows ends +.B expr +with status +.BR 0xC0000095 , +and +.B expr +prints no message. +The kit's shell then prints the Windows error message and +.B Error 0xc0000095 +on standard error, and sets +.B $?\& +to 149, the low byte. +.PP +Standard output is binary, so the newline is a bare LF. +When standard output is a console, the output is converted for display +from the ANSI code page, which is UTF-8 on Windows 10 version 1903 and +later. +Escape sequences, such as those for color, take effect, and busybox +emulates them on consoles without virtual terminal support. +.PP +The shell computes integer expressions itself with +.BR $((...)) , +without starting a process; see +.BR sh (1). +.SH SEE ALSO +.BR awk (1), +.BR bc (1), +.BR busybox (1), +.BR grep (1), +.BR sed (1), +.BR sh (1), +.BR test (1) diff --git a/man/man1/factor.1 b/man/man1/factor.1 new file mode 100644 index 0000000..6a893e9 --- /dev/null +++ b/man/man1/factor.1 @@ -0,0 +1,175 @@ +.TH FACTOR 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +factor \- print the prime factors of integers +.SH SYNOPSIS +.B factor +.RI [ number ...] +.SH DESCRIPTION +.B factor +writes the prime factorization of each +.IR number , +or, with no operands, of each number on standard input. +Standard input is read to the end of the file. +Each line holds any number of numbers, separated by white space, and +blank lines are ignored. +With operands, standard input is not read. +.PP +Each +.I number +is a decimal integer from 0 to +.BR 18446744073709551615 , +which is 2^64 \- 1. +It may start with a plus sign, and an operand may have white space +before that. +A leading zero does not make a number octal: +.B 010 +is ten. +Anything else is invalid: a minus sign, a +.B 0x +prefix, an exponent or a fraction, other text after the digits (even +white space, in an operand), an empty operand, or a value above the +maximum. +.PP +The results are written to standard output in input order, one line per +number. +Each line has the number, a colon, and the prime factors in ascending +order, each after a space. +A prime that divides the number several times is repeated. +A prime is its own only factor, and 0 and 1 have none, so their lines +end after the colon. +The number is written in plain decimal, without a plus sign or leading +zeros. +.PP +On an invalid number, +.B factor +writes a usage message on standard error and exits with status 1. +The results for the numbers before it are still written, and the +numbers after it are not examined. +The message does not say which number is at fault. +.SH OPTIONS +.B factor +has no options. +Apart from a first argument of +.BR \-\-help , +an argument that begins with a dash is an invalid number, and +.B \-\- +is not special. +.TP +.B \-\-help +Print the busybox version and a usage message on standard output, and +exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +In any other position it is an invalid number. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when +.B factor +starts, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.PP +Every applet also reads +.B BB_CRITICAL_ERROR_DIALOGS +and +.B BB_UMASK +at startup, and +.BR BB_SKIP_ANSI_EMULATION , +.BR BB_TERMINAL_MODE , +.BR CONEMUPID , +.BR LANG , +.BR LC_ALL , +and +.B LC_CTYPE +when writing to a console. +None of these changes what +.B factor +writes. +They are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, including an empty input, or a first argument of +.BR \-\-help . +.TP +.B 1 +An invalid number, with a usage message on standard error. +.TP +.B 141 +Standard output is a pipe whose reader has exited, found when a write +fails. +No message is printed. +.SH EXAMPLES +Factor a number: +.PP +.RS 4 +.EX +$ factor 360 +360: 2 2 2 3 3 5 +.EE +.RE +.PP +Factor the numbers on a line of standard input: +.PP +.RS 4 +.EX +$ echo 91 1001 | factor +91: 7 13 +1001: 7 11 13 +.EE +.RE +.PP +List the primes up to 30, the numbers whose line has a single factor: +.PP +.RS 4 +.EX +$ seq 2 30 | factor | awk \(aqNF == 2 { print $2 }\(aq +.EE +.RE +.PP +Print the largest prime factor of a number: +.PP +.RS 4 +.EX +$ factor 600851475143 | awk \(aq{ print $NF }\(aq +6857 +.EE +.RE +.SH NOTES +Differences from GNU factor: +.IP \(bu 2 +Numbers are limited to 64 bits. +.IP \(bu 2 +There are no options other than +.BR \-\-help , +so no +.BR \-h , +.BR \-\-exponents , +or +.BR \-\-version . +.IP \(bu 2 +An invalid number ends the program, where GNU factor reports it and +goes on to the next. +.PP +Factoring is by trial division. +The slowest numbers, such as a prime near 2^64 or the product of two +different primes near 2^32, take seconds. +.PP +Output lines end with LF, not CRLF. +On standard input, a CR before the LF is removed, and a CR elsewhere is +white space. +.PP +Write errors other than a closed pipe are ignored, and so is any error +when the output buffer is flushed at exit: a short result written to a +pipe whose reader has exited is lost, with status 0. +.SH SEE ALSO +.BR awk (1), +.BR busybox (1), +.BR seq (1) diff --git a/man/man1/false.1 b/man/man1/false.1 new file mode 100644 index 0000000..a652809 --- /dev/null +++ b/man/man1/false.1 @@ -0,0 +1,97 @@ +.TH FALSE 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +false \- do nothing, unsuccessfully +.SH SYNOPSIS +.B false +.RI [ argument ...] +.SH DESCRIPTION +.B false +exits with status 1. +It does nothing else: it reads no input, writes no output, and ignores +its arguments. +It does not use the standard streams, so a closed one makes no +difference. +This +.B false +is a busybox applet; see +.BR busybox (1). +.PP +Nothing on the command line is an option. +.BR \-\-help , +.BR \-\-version , +and +.B \-\- +are ignored like any other argument. +.SH ENVIRONMENT +.B false +reads no environment variables. +The startup code shared by all applets reads +.BR BB_CRITICAL_ERROR_DIALOGS , +.BR BB_GLOBBING , +and +.BR BB_UMASK , +and may trim a trailing semicolon from +.BR PATH . +None of these changes what +.B false +does; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 1 +Always. +.SH EXAMPLES +Show the exit status of +.BR false : +.PP +.RS 4 +.EX +$ false; echo $? +1 +.EE +.RE +.PP +Run a command only when the previous one fails: +.PP +.RS 4 +.EX +$ false || echo failed +failed +.EE +.RE +.SH NOTES +Unlike the GNU +.BR false , +this one has no +.B \-\-help +or +.B \-\-version +and never prints anything. +.B busybox \-\-help false +prints the busybox version and +.B No help available +on standard output, and exits with status 0. +.PP +In the kit's shell, +.B false +is a builtin, so typing it does not start the applet. +Programs that run commands by name, such as +.BR env , +run the applet by starting +.IR busybox.exe , +unless +.B BB_OVERRIDE_APPLETS +says otherwise; see +.BR busybox (1). +From +.BR cmd.exe , +the launcher +.I false.exe +or +.B busybox false +runs it. +.SH SEE ALSO +.BR busybox (1), +.BR env (1), +.BR sh (1), +.BR true (1) diff --git a/man/man1/fgrep.1 b/man/man1/fgrep.1 new file mode 100644 index 0000000..6a74c5d --- /dev/null +++ b/man/man1/fgrep.1 @@ -0,0 +1 @@ +.so man1/grep.1 diff --git a/man/man1/find.1 b/man/man1/find.1 new file mode 100644 index 0000000..446ed27 --- /dev/null +++ b/man/man1/find.1 @@ -0,0 +1,939 @@ +.TH FIND 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +find \- search for files in a directory hierarchy +.SH SYNOPSIS +.B find +.RB [ \-HLP ] +.RI [ path ...] +.RI [ expression ] +.br +.B find \-\-help +.SH DESCRIPTION +.B find +searches the directory tree below each +.I path +for files that satisfy an +.IR expression , +and acts on them. +This +.B find +is the busybox applet; see +.BR busybox (1). +.PP +The operands before the first one that begins with +.BR \- , +or is +.B !\& +or +.BR ( , +are the paths, and the rest is the expression. +A path cannot begin with +.BR \- ; +write +.B ./\-name +instead. +With no +.IR path , +.B find +searches the current directory. +A +.I path +that is not a directory is tested by itself. +.PP +For each file, the expression is true or false. +Actions in it can print the file's name, run a command, or delete the file. +When the expression contains none of +.BR \-print , +.BR \-print0 , +.BR \-exec , +.BR \-ok , +or +.BR \-delete , +.B find +adds a +.B \-print +for the whole expression, so it prints the name of each file for which the +expression is true. +With no expression, it prints every file. +.PP +Names are written on standard output, one per line, each ending in LF. +The name of a path is as given. +The name of an entry in a directory is the directory's name, a +.BR / , +and the entry's name, with no second +.B / +when the directory's name already ends in one, and none after a bare +drive such as +.BR c: . +.PP +The expression is checked before the search starts. +An unrecognized argument, or a primary with a missing or invalid argument, +is reported on standard error, and the exit status is 1. +A file that cannot be examined, or a directory that cannot be opened, is +reported on standard error, and the search goes on. +.SS Traversal +.B find +searches the paths in the order given. +It tests a directory before the entries in it, unless +.B \-depth +or +.B \-delete +says otherwise. +The entries of a directory come in the order the file system lists them; +.B find +does not sort them. +The entries +.B .\& +and +.B ..\& +are never visited. +.PP +A symbolic link is tested as itself and not entered, unless +.BR \-H , +.BR \-L , +or +.B \-follow +says to follow it. +.B find +does not detect loops. +.SS Operators +Operators combine tests and actions. +They are listed from the highest precedence to the lowest. +.TP +\fB(\fR \fIexpression\fR \fB)\fR +Group. +Each parenthesis is a separate argument, and the shell needs both quoted. +.TP +\fB!\fR, \fB\-not\fR \fIexpression\fR +True when +.I expression +is false. +Negations may be stacked. +.TP +\fIexpr1\fR [\fB\-a\fR | \fB\-and\fR] \fIexpr2\fR +True when both are true. +If +.I expr1 +is false, +.I expr2 +is not evaluated. +Two expressions side by side mean this. +.TP +\fIexpr1\fR \fB\-o\fR | \fB\-or\fR \fIexpr2\fR +True when either is true. +If +.I expr1 +is true, +.I expr2 +is not evaluated. +.PP +There is no +.B , +operator. +.SS Global options +These apply to the whole search wherever they appear in the expression. +They are not tests, so put them before the tests. +A +.B !\& +before one applies to the next test instead. +An alternative of +.B \-o +that holds only global options is empty, and an empty alternative ends +the expression: +.B "\-name a \-o \-xdev \-o \-name b" +never tests +.BR "\-name b" , +and +.B "\-xdev \-o \-name b" +is true for every file. +The argument of +.B \-maxdepth +or +.B \-mindepth +is a decimal integer from 0 to 2147483647. +.TP +.B \-follow +The same as +.BR \-L , +but may appear in the expression. +.TP +.B \-xdev +Enter a directory only if it is on the same volume as one of the paths. +Volumes are told apart by serial number, and a directory whose volume +busybox cannot read counts as another volume. +A directory on another volume is still tested. +With +.BR \-L , +this keeps +.B find +from crossing a junction or symbolic link to another volume. +.TP +.BI "\-maxdepth " n +Do not descend below level +.IR n . +A directory at level +.I n +is tested but not entered. +.B "\-maxdepth 0" +tests only the paths. +.TP +.BI "\-mindepth " n +Do not test files fewer than +.I n +levels below the paths. +A path is at level 0, and the entries directly in it are at level 1. +.TP +.B \-depth +Test the entries in a directory before the directory itself. +.B \-prune +then has no effect. +.SS Tests +Where a test takes a number +.IR n , +.BI + n +means more than +.IR n , +.BI \- n +means less than +.IR n , +and a plain +.I n +means exactly +.IR n . +Numbers are decimal. +.TP +.BI "\-name " pattern +The last component of the path matches the shell +.IR pattern . +The last component is the part after the last +.BR / , +.BR \e , +or +.BR : . +When a path ends in one of these, trailing slashes are dropped and only a +.B / +counts, so +.B a/dir/ +is tested as +.BR dir , +and +.BR c:src/ , +.BR src\e , +and +.B c: +as +.BR c:src , +.BR src\e , +and +.BR c: . +In the pattern, +.B * +matches any string, +.B ?\& +matches any one byte, and +.B [ +starts a set of bytes, as in +.BR [a\-f] , +.BR [!0\-9] , +or +.BR [[:alpha:]] , +with +.B !\& +or +.B ^ +first for the complement. +A backslash quotes the next character. +The match is case-sensitive, and a leading period is not special. +.TP +.BI "\-iname " pattern +Like +.BR \-name , +but ASCII letters match in either case. +.TP +\fB\-path\fR, \fB\-wholename\fR \fIpattern\fR +The whole path, as printed, matches +.IR pattern . +Here +.B * +and +.B ?\& +also match +.BR / . +.TP +.BI "\-ipath " pattern +Like +.BR \-path , +but ASCII letters match in either case. +.TP +.BI "\-regex " pattern +The whole path, as printed, matches the POSIX basic regular expression +.IR pattern , +which may use the GNU operators +.BR \e| , +.BR \e+ , +and +.BR \e? . +The match is case-sensitive. +An invalid expression is an error. +.TP +.BI "\-type " c +The file is of type +.IR c : +.B f +for a regular file, +.B d +for a directory, +.B l +for a symbolic link, +.B c +for a character device, +.B b +for a block device, +.B p +for a named pipe, or +.B s +for a socket. +See +.B NOTES +for what these are on Windows. +.TP +.B \-executable +The file is executable: a directory, a file whose name ends in +.BR .com , +.BR .exe , +.BR .sh , +.BR .bat , +or +.BR .cmd , +a file that begins with +.BR #! , +or a Windows program. +.TP +.BI "\-perm " mode +The file's permission bits equal +.IR mode , +which is octal, up to 7777, or symbolic as for +.BR chmod , +starting from no permissions. +With a leading +.BR \- , +all the bits of +.I mode +must be set, and with a leading +.B / +or +.BR + , +at least one. +.TP +.BI "\-mtime " n +The file's data was last modified +.I n +days ago. +The age is the time since then in whole days of 24 hours, with any +remainder dropped. +So +.B \-mtime 0 +is an age under 1 day, +.B \-mtime 1 +is from 1 day to under 2, and +.B \-mtime +1 +is 2 days or more. +.TP +.BI "\-atime " n +Like +.BR \-mtime , +for the time of last access. +.TP +.BI "\-ctime " n +Like +.BR \-mtime , +for the time of creation. +.TP +.BI "\-mmin " n +Like +.BR \-mtime , +in minutes. +.TP +.BI "\-amin " n +Like +.BR \-atime , +in minutes. +.TP +.BI "\-cmin " n +Like +.BR \-ctime , +in minutes. +.TP +.BI "\-newer " file +The file was modified later than +.IR file , +comparing whole seconds. +.I file +is examined once, before the search starts, and a link is followed. +If it cannot be examined, that is an error. +.TP +.BI "\-inum " n +The file's index on its volume is +.IR n . +.TP +.BI "\-samefile " file +The file has the same volume and index as +.IR file : +it is +.IR file , +or another name for it. +.I file +is examined before the search starts, and a link is not followed unless +.BR \-L , +.BR \-H , +or an earlier +.B \-follow +says to. +.TP +\fB\-size \fIn\fR[\fBcwbk\fR] +The file's length is +.I n +units. +The unit is +.B c +for 1 byte, +.B w +for 2, +.B b +for 512, or +.B k +for 1024, and is +.B b +when omitted. +The length is compared exactly, not rounded up to whole units, so +.B "\-size 1k" +matches only a file of 1024 bytes. +.TP +.BI "\-links " n +The file has +.I n +links. +.TP +.B \-empty +The file is a regular file of length 0, or a directory with no entries. +A directory that cannot be opened is reported on standard error and is +not empty, and the exit status is not affected. +.SS Actions +.TP +.B \-prune +Always true. +If the file is a directory, do not enter it. +.TP +.B \-print +Print the file's name. +Always true. +.TP +.B \-print0 +Print the file's name followed by a NUL instead of a newline. +Always true. +.TP +\fB\-exec \fIcommand\fR [\fIargument\fR ...] \fB;\fR +Run +.I command +with its arguments, replacing each +.B {} +in them, including in +.IR command , +by the file's name as printed. +True if the command exits with status 0. +The +.B ; +is an argument of its own, and the shell needs it quoted. +The first argument that is +.B ; +or +.B + +alone ends the command, so neither can be passed to it. +.IP +The command runs in the current directory of +.BR find , +sharing its standard input, output, and error. +It is found as +.BR busybox (1) +describes under Running commands, which prefers an applet to a program in +.BR PATH . +If it cannot be started, +.B find +reports that on standard error, the action is false, and the exit status +is not affected. +.TP +\fB\-exec \fIcommand\fR [\fIargument\fR ...] \fB+\fR +Run +.I command +once for many files. +.B {} +must appear exactly once in the whole command, alone or within an argument. +That argument is repeated for each saved file, with +.B {} +replaced by the file's name. +The action saves the file's name and is true. +When the saved names, counting 9 more bytes for each (5 in the x86 kit), +reach 30720 bytes, it runs the command on them and is true if the command +succeeds. +.IP +After the search, the command runs once more on the names still saved, if +any. +If it exits with a nonzero status, +.B find +runs no further +.B "\-exec +" +commands and exits with status 1. +The names saved by an +.B "\-exec +" +inside parentheses are never run after the search. +.B \-quit +discards the names still saved. +Otherwise it is as above. +.TP +\fB\-ok \fIcommand\fR [\fIargument\fR ...] \fB;\fR +Like +.BR "\-exec ;" , +but first writes the command line to standard error, each argument followed +by a space, then a +.BR ? , +and reads a line from standard input. +The command runs only if the first character on the line that is not a +space or tab is +.B y +or +.BR Y . +Otherwise the action is false. +Only +.B ; +ends the command. +At end of file the answer is no. +A command that reads standard input competes with the answers. +.TP +.B \-delete +Delete the file or directory. +Always true, even when the deletion fails: the failure is reported on +standard error and the exit status is not affected. +A read-only file is deleted too, and a directory must be empty. +The read-only attribute is cleared first, and stays cleared when the +deletion then fails. +A path named exactly +.B .\& +is not deleted. +Implies +.BR \-depth . +.TP +.B \-quit +Exit at once, without visiting any more files. +The exit status is 1 only if a path before the current one had an error: +errors below the current path are not counted. +.SH OPTIONS +These options, if any, come before the paths. +They may be grouped, as in +.BR \-HL , +and +.B \-\- +ends them. +There are no long options. +.TP +.B \-L +Follow all symbolic links. +A link counts as what it points to, and a link to a directory is entered. +A link whose target does not exist counts as the link itself, so +.B "\-type l" +matches only such links. +With both +.B \-H +and +.BR \-L , +.B \-L +applies. +.TP +.B \-H +Follow symbolic links named as paths, but no others. +.TP +.B \-P +Ignored. +Not following symbolic links is the default, and +.B \-P +does not cancel +.B \-H +or +.BR \-L . +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +busybox expands wildcards in its arguments when it starts, even quoted +ones, which serves commands typed in +.BR cmd.exe . +There, +.B \-name \(dq*.c\(dq +becomes +.B \-name +followed by the matching names in the current directory, which gives +wrong results or an invalid expression, so set it to +.B 0 +first. +When it is unset, busybox sets it to +.B 0 +for the programs it starts, so the kit's shell is not affected. +See +.BR busybox (1). +.TP +.B BB_OVERRIDE_APPLETS +Applets that +.B \-exec +and +.B \-ok +should not run by name; see +.BR busybox (1). +.TP +.B BB_UMASK +Its group and other write bits are cleared from the permissions that +.B \-perm +tests; see +.BR NOTES . +.TP +.B PATH +Where +.B \-exec +and +.B \-ok +look for commands that are not applets. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +A path or an entry below one could not be examined, a directory could not be +opened, the expression or an option was invalid, a file named by +.B \-newer +or +.B \-samefile +could not be examined, or a command run by +.B "\-exec +" +after the search failed. +See +.B \-quit +for an exception. +.PP +An unrecognized argument is reported with the usage on standard error: +.PP +.RS 4 +.EX +find: unrecognized: \fIargument\fR +.EE +.RE +.PP +A file that cannot be examined or opened is reported as +.PP +.RS 4 +.EX +find: \fIname\fR: \fIreason\fR +.EE +.RE +.PP +and the search goes on. +.SH EXAMPLES +Print the C source files below the current directory: +.PP +.RS 4 +.EX +$ find . \-name \(aq*.c\(aq +.EE +.RE +.PP +Print the source and header files in +.IR src , +quoting the parentheses and the patterns: +.PP +.RS 4 +.EX +$ find src \e( \-name \(aq*.c\(aq \-o \-name \(aq*.h\(aq \e) +.EE +.RE +.PP +Print the regular files below the current directory, skipping +.I .git +directories: +.PP +.RS 4 +.EX +$ find . \-name .git \-prune \-o \-type f \-print +.EE +.RE +.PP +Search the users' directories for pictures, ignoring case: +.PP +.RS 4 +.EX +$ find c:/Users \-iname \(aq*.png\(aq +.EE +.RE +.PP +List files larger than 1 MiB, without crossing to another volume: +.PP +.RS 4 +.EX +$ find c:/ \-xdev \-type f \-size +1048576c +.EE +.RE +.PP +List the source files that mention +.BR main , +running +.B grep +on many files at once: +.PP +.RS 4 +.EX +$ find src \-name \(aq*.c\(aq \-exec grep \-l main {} + +.EE +.RE +.PP +Remove log files, passing the names safely to +.BR xargs : +.PP +.RS 4 +.EX +$ find . \-name \(aq*.log\(aq \-print0 | xargs \-0 rm +.EE +.RE +.PP +Remove object files directly: +.PP +.RS 4 +.EX +$ find build \-name \(aq*.o\(aq \-delete +.EE +.RE +.PP +Ask before removing each backup file: +.PP +.RS 4 +.EX +$ find . \-name \(aq*.bak\(aq \-ok rm {} \e; +.EE +.RE +.PP +Find the empty directories modified in the last hour: +.PP +.RS 4 +.EX +$ find . \-type d \-empty \-mmin \-60 +.EE +.RE +.SH NOTES +Paths may use +.B / +or +.BR \e , +but in the shell a backslash quotes the next character, so prefer +.BR / . +The names +.B find +prints begin with the path as given, and only +.B / +is added, so +.B "find \(aqsrc\esub\(aq" +prints names such as +.BR src\esub/a.c . +Paths such as +.IR c:/dir +and +.I //server/share/dir +work. +A bare drive, +.BR c: , +is the current directory of that drive, and its entries are named +.BR c:name . +A file whose full path, including the current directory when the path is +relative, reaches about 260 characters is reported as not found. +.PP +Matching is bytewise. +Names are UTF-8 on Windows 10 version 1903 or later, so +.B ?\& +and a regular expression's +.B .\& +match one byte, and a non-ASCII character takes two or more of them. +Case folding by +.B \-iname +and +.B \-ipath +is ASCII only. +.BR \-name , +.BR \-path , +and +.B \-regex +are case-sensitive, though NTFS is not. +A backslash in a pattern quotes the next character and is not a path +separator, so write +.B / +in a +.B \-path +pattern. +.PP +.B find +treats a symbolic link, a junction, a volume mount point, and an app +execution alias alike, as a symbolic link of type +.BR l . +Type +.B c +matches only the Unix device names that busybox provides, such as +.IR /dev/null . +Types +.BR b , +.BR p , +and +.B s +never match. +With +.BR \-L , +a junction that points to its own parent is entered again and again until +the path is too long. +.PP +Owners and permissions are synthesized; see +.BR busybox (1). +The owner, the group, and others each get read permission, write +permission except for a read-only regular file, and execute permission as +.B \-executable +says. +Then +.BR BB_UMASK , +002 by default, may clear write permission for the group and others. +So a file you own usually has mode 664, a read-only file 444, and an +executable file or a directory 775. +A symbolic link has mode 777, and a device 666. +A file owned by someone else, when you have full access to it and busybox +is not elevated, gets the owner's permissions for others too, so a +directory such as +.I c:/Users/name +may have mode 777. +When busybox cannot read a file's security information, others get no +permissions. +There are no setuid, setgid, or sticky bits. +The tests +.B \-user +and +.B \-group +are not built in. +.PP +Times come from the file system. +.B \-ctime +and +.B \-cmin +test the time of creation, not of the last change of status. +.PP +The index tested by +.B \-inum +and +.B \-samefile +is the file index of the volume, and +.B \-xdev +compares volume serial numbers. +.B \-links +counts the hard links to a file, and is always 2 for a directory, and for +a junction or other link to a directory. +.PP +To decide whether a regular file is executable, busybox reads the first +bytes of each one whose name ends in neither an executable suffix nor +.BR .dll , +so a search over many files is slower than a plain listing. +.PP +When standard output is not a console, the names written by +.B \-print +wait in a buffer until it fills or +.B find +exits, and are not flushed before +.B \-exec +runs a command, so the output of commands can come first. +.B \-ok +flushes before it asks. +.PP +Windows has its own +.B find.exe +in +.IR System32 , +a tool that searches text. +In +.BR cmd.exe , +make the kit's +.I bin +directory come first in +.BR PATH , +or run +.BR "busybox find" . +.PP +Differences from GNU +.BR find : +.IP \(bu 2 +Only +.BR \-H , +.BR \-L , +and +.B \-P +are options, and they cannot follow a path. +.IP \(bu 2 +There is no +.B , +operator, and no +.BR \-mount , +.BR \-iregex , +.BR \-newerXY , +.BR \-anewer , +.BR \-cnewer , +.BR \-printf , +.BR \-ls , +.BR \-fprint , +.BR \-readable , +.BR \-writable , +.BR \-true , +.BR \-false , +.BR \-daystart , +or +.BR \-regextype . +.IP \(bu 2 +.B \-size +does not round up, and accepts only the units +.BR c , +.BR w , +.BR b , +and +.BR k . +.IP \(bu 2 +.B "\-exec +" +accepts +.B {} +anywhere in the command, once, and +.B \-ok +does not accept +.BR + . +.IP \(bu 2 +.B \-quit +does not run the commands saved by +.BR "\-exec +" . +.IP \(bu 2 +The global options are not tests that are always true; see +.BR "Global options" . +.IP \(bu 2 +.B \-P +does not cancel an earlier +.B \-H +or +.BR \-L . +.SH SEE ALSO +.BR busybox (1), +.BR du (1), +.BR grep (1), +.BR ls (1), +.BR sh (1), +.BR xargs (1) diff --git a/man/man1/fold.1 b/man/man1/fold.1 new file mode 100644 index 0000000..86d6f37 --- /dev/null +++ b/man/man1/fold.1 @@ -0,0 +1,291 @@ +.TH FOLD 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +fold \- wrap input lines to a given width +.SH SYNOPSIS +.B fold +.RB [ \-bs ] +.RB [ \-w +.IR width ] +.RI [ file ...] +.SH DESCRIPTION +.B fold +copies each +.I file +to standard output, starting a new line wherever a line would otherwise +be wider than +.I width +columns. +The default width is 80. +.PP +With no +.I file +operands, or for a +.I file +named +.BR \- , +.B fold +reads standard input. +A +.I file +that cannot be opened is reported on standard error and skipped, and the +remaining files are still read. +.PP +A line ends at an LF. +Each file starts at column 0. +Apart from the LF bytes it adds, the output is the input byte for byte, +including NUL and CR bytes. +A last line with no LF is written without one, so it runs into the first +line of the next file. +.SS Columns +Without +.BR \-b , +each byte moves the column, counted from 0, as follows: +.IP \(bu 2 +A tab moves to the next multiple of 8. +.IP \(bu 2 +A backspace moves back one column, but not before column 0. +.IP \(bu 2 +A CR returns to column 0. +.IP \(bu 2 +Any other byte, including other control characters and NUL, moves +forward one column. +.PP +In UTF-8 mode, described under +.BR ENVIRONMENT , +a byte from 0x80 to 0xBF, which can only continue a UTF-8 character, +does not move the column. +Each character is then one column wide, so a break never splits a +character. +Wide and combining characters are not treated specially, and the input +is not checked for being valid UTF-8. +.PP +With +.BR \-b , +every byte is one column, including tab, backspace, and CR, and a break +can split a UTF-8 character. +.PP +A byte that would end in a column past +.I width +starts a new line instead. +The first byte of an output line is never moved, so a tab at the start of +a line stays there even when +.I width +is less than 8. +.SS Breaking at spaces +Without +.BR \-s , +a line is broken exactly at +.IR width , +which can split a word. +.PP +With +.BR \-s , +when a byte would go past +.IR width , +.B fold +looks for the last blank, a space or tab, among the bytes already on the +line. +If there is one, the line ends just after it, and the bytes that followed +it, plus the new byte, begin the next line. +Their columns are counted again from column 0. +If there is no blank, the line is broken at +.IR width , +as without +.BR \-s . +Only a space or a tab is a blank: other white space, such as the +no-break space, is not. +.SH OPTIONS +Options may be grouped, as in +.BR \-sw72 , +and may follow the +.I file +operands. +An option's argument may be attached, as in +.BR \-w72 , +or be the next argument. +.B \-\- +ends the options. +Long options and the obsolete +.BI \- width +form are not accepted. +.TP +.B \-b +Count bytes rather than columns, as described under +.BR Columns . +.TP +.B \-s +Break at blanks, as described under +.BR "Breaking at spaces" . +.TP +.BI "\-w " width +Wrap at +.I width +columns instead of 80. +The +.I width +is a decimal number from 1 to 10000, with no sign, space, or prefix. +Leading zeros are allowed, and the number is still decimal. +A +.I width +that is not a number, or does not fit in 32 bits, is reported as +.BR "invalid number" , +and any other value out of range as +.BR "not in 1..10000 range" , +with exit status 1. +If +.B \-w +is given more than once, the last one applies. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.PP +An unknown option, or a missing option argument, prints the usage +message on standard error and exits with status 1. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options, so that later arguments such as +.B \-w +are file names. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +The first of these that is set decides whether UTF-8 mode is on. +When its value is +.BR C , +UTF-8 mode is off, and every byte except tab, backspace, and CR is one +column. +Otherwise UTF-8 mode is on when the ANSI code page is UTF-8, which it +is on Windows 10 version 1903 and later, and off when it is not. +The value +.B C +also turns off the conversion of console output described in +.BR busybox (1). +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when +.B fold +starts, as needed when it is run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid option or +.IR width , +a +.I file +could not be opened (a directory is reported as +.BR "Is a directory" ) +or read, memory ran out, or standard output could not be written. +.TP +.B 141 +Standard output is a pipe that was closed while +.B fold +was writing to it. +Output is buffered, and when the closed pipe is found only by the final +flush at exit, as with short output, the status is 1 instead. +.SH EXAMPLES +Wrap a text file at word boundaries to 72 columns: +.PP +.RS 4 +.EX +$ fold \-s \-w 72 notes.txt >notes.wrapped +.EE +.RE +.PP +Without +.BR \-s , +words are split at the width: +.PP +.RS 4 +.EX +$ echo The quick brown fox jumps over the lazy dog | fold \-w 18 +The quick brown fo +x jumps over the l +azy dog +.EE +.RE +.PP +Break a long line of hex digits into lines of 64 digits: +.PP +.RS 4 +.EX +$ fold \-b \-w 64 key.hex >key.txt +.EE +.RE +.PP +List a directory as a block of text wrapped at word boundaries: +.PP +.RS 4 +.EX +$ ls | tr \(aq\en\(aq \(aq \(aq | fold \-s \-w 78 +.EE +.RE +.SH NOTES +With +.BR \-s , +the byte that would go past the width is never itself the blank searched +for. +A blank just past the width therefore starts the next line instead of +ending the current one. +For example, +.B "abcd efgh" +with +.B "\-s \-w 4" +becomes +.BR abcd , +a line holding only a space, and +.BR efgh . +.PP +Files and standard streams are binary, with no CRLF translation, and +breaks are written as a bare LF. +A CR returns to column 0, so the CR of a CRLF line ending does not count +toward the width, and a line of exactly +.I width +columns followed by CRLF is not broken. +Wrapping a file with CRLF line endings leaves the original CRLF endings +and adds LF-only ones. +Filter the output through +.BR unix2dos (1) +to make them all CRLF. +.PP +When standard output is a console, a NUL byte hides the rest of its +output line, usually including the LF. +.PP +In UTF-8 mode the column count is in characters, not display cells. +A console shows an East Asian wide character in two cells, and +.B fold +counts it as one. +.PP +.B fold +holds the current output line in memory. +A line in which CR or backspace bytes keep the column within the width, +such as a very long overstruck line, is held whole. +.PP +File names may contain any Unicode characters on Windows 10 version 1903 +and later, may use backslashes, and may start with a drive letter. +The device names that busybox accepts, such as +.IR /dev/null , +work as operands; see +.BR busybox (1). +.SH SEE ALSO +.BR busybox (1), +.BR dos2unix (1), +.BR expand (1), +.BR unix2dos (1) diff --git a/man/man1/free.1 b/man/man1/free.1 new file mode 100644 index 0000000..89874c8 --- /dev/null +++ b/man/man1/free.1 @@ -0,0 +1,255 @@ +.TH FREE 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +free \- show the amount of free and used memory +.SH SYNOPSIS +.B free +.RB [ \-b | \-k | \-m | \-g | \-h ] +.SH DESCRIPTION +.B free +prints the amount of physical memory and paging file space in the system +on standard output. +It takes a single sample and exits. +.PP +The output is three lines: a header, a +.B Mem: +line for physical memory, and a +.B Swap: +line for the paging files. +Each line starts with its label padded to 7 columns, which is blank in +the header, and then has fields that are 12 characters wide and right +aligned. +A value too wide for its field is not truncated, and pushes the rest of +the line to the right. +The header names six columns: +.BR total , +.BR used , +.BR free , +.BR shared , +.BR buff/cache , +and +.BR available . +The +.B Mem: +line has a value for each, and the +.B Swap: +line has only the first three. +.PP +The columns of the +.B Mem: +line are: +.TP +.B total +The physical memory in the system. +.TP +.B used +The total less +.B free +and +.BR buff/cache . +.TP +.B free +The physical memory that Windows reports as available, less +.BR buff/cache . +It is 0 when the system cache is at least as large as the available +memory. +Otherwise the sum of +.B free +and +.B buff/cache +is the memory that Windows reports as available. +.TP +.B shared +Always 0. +.TP +.B buff/cache +The size of the system cache. +.TP +.B available +Always 0. +This port has no value for it. +.PP +The columns of the +.B Swap: +line are: +.TP +.B total +The sum of the sizes of the paging files. +.TP +.B used +The sum of the space in use in the paging files. +.TP +.B free +The total less the space in use. +.PP +All three are 0 when there is no paging file. +.PP +Sizes are in kibibytes (units of 1024 bytes), unless an option selects +another unit. +Each size is the number of bytes divided by the unit and rounded to the +nearest integer, with halves rounded up. +A size smaller than half a unit is shown as 0, and the rounded columns +may not add up. +.PP +With +.BR \-h , +each size is scaled by powers of 1024 to the largest unit that keeps it +below 1024, and written with one decimal digit and a suffix: +.BR K , +.BR M , +.BR G , +or +.BR T . +For example, 33271988 KiB is written +.BR 31.7G . +A size of 0 is written as a plain +.BR 0 , +with no suffix. +.SH OPTIONS +Only the first argument is examined, and only if it begins with a dash. +The character after the dash selects the option, and any further +characters in the argument are ignored, so +.B \-mk +is the same as +.BR \-m , +and +.B \-bytes +is the same as +.BR \-b . +Options cannot be grouped, a second option has no effect, and arguments +that follow the first are ignored. +A first argument that does not begin with a dash is ignored too. +Any other first argument that begins with a dash, including a lone +.B \- +and +.B \-\- +but not +.BR \-\-help , +prints a usage message on standard error and exits with status 1. +.TP +.B \-b +Show sizes in bytes. +.TP +.B \-k +Show sizes in kibibytes. +This is the default. +.TP +.B \-m +Show sizes in mebibytes (1048576 bytes). +.TP +.B \-g +Show sizes in gibibytes (1073741824 bytes). +.TP +.B \-h +Show sizes in a human-readable form, as described above. +It does not print a usage message. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any arguments that +follow are ignored. +.SH ENVIRONMENT +.B free +reads no environment variables. +The variables that busybox reads for every applet, such as +.BR BB_GLOBBING , +are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, or +.B \-\-help +was given. +.TP +.B 1 +Invalid option. +.PP +Failure to read a statistic is not an error. +A value that the system does not supply is shown as 0. +.SH EXAMPLES +Show sizes in a human-readable form: +.PP +.RS 4 +.EX +$ free \-h +.EE +.RE +.PP +Print the percentage of physical memory in use: +.PP +.RS 4 +.EX +$ free | awk \(aq/^Mem:/ { printf "%d%%\en", 100 * $3 / $2 }\(aq +32% +.EE +.RE +.PP +Show the memory in mebibytes every two seconds: +.PP +.RS 4 +.EX +$ watch \-n 2 free \-m +.EE +.RE +.SH NOTES +The figures are for the whole system. +.B free +gets physical memory and the system cache from +.BR GetPerformanceInfo , +and the paging files from +.BR EnumPageFilesA , +both in +.IR psapi.dll , +which busybox loads when +.B free +runs. +It does not read +.IR /proc/meminfo . +.PP +Differences from +.B free +on Linux: +.IP \(bu 2 +The only options are +.BR \-b , +.BR \-k , +.BR \-m , +.BR \-g , +.BR \-h , +and +.BR \-\-help . +There is no +.BR \-t ", " \-s ", " \-c ", " \-l ", " \-w ", or " \-\-si , +and no other long option. +.IP \(bu 2 +The +.B shared +and +.B available +columns are always 0, so a script that reads +.B available +gets 0. +.IP \(bu 2 +The extra +.B \-/+ buffers/cache +line, which busybox prints on Linux kernels that lack +.B MemAvailable +in +.IR /proc/meminfo , +is never printed. +.PP +Output lines end in LF. +The output has no escape sequences, on a console or not. +.PP +In the x86 kit, +.B free +multiplies page counts by the page size in 32 bits, so a quantity of +4 GiB or more wraps around modulo 4 GiB. +On a machine with 4 GiB or more of memory, or of paging file space, the +figures are wrong. +.SH SEE ALSO +.BR busybox (1), +.BR df (1), +.BR ps (1), +.BR uptime (1), +.BR watch (1) diff --git a/man/man1/fsync.1 b/man/man1/fsync.1 new file mode 100644 index 0000000..d1c4213 --- /dev/null +++ b/man/man1/fsync.1 @@ -0,0 +1,202 @@ +.TH FSYNC 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +fsync \- request that files be flushed to disk +.SH SYNOPSIS +.B fsync +.RB [ \-d ] +.IR file ... +.SH DESCRIPTION +.B fsync +opens each +.I file +read-only, requests that its buffered data be written to disk, and +closes it, in the order given. +A +.I file +that cannot be opened is reported on standard error and skipped, and the +remaining files are still processed. +Nothing is written to standard output. +.PP +On Windows, a file opened read-only cannot be flushed. +The request fails with an access error, which +.B fsync +treats as success, so naming a file flushes nothing. +See +.B NOTES +for a way to flush. +.SH OPTIONS +Options may be grouped, as in +.BR \-dd , +and may follow +.I file +operands. +.B \-\- +ends the options. +.TP +.B \-d +Avoid syncing metadata, by calling +.B fdatasync +instead of +.BR fsync . +This build has no +.B fdatasync +and calls +.B fsync +either way, so +.B \-d +changes nothing. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_CRITICAL_ERROR_DIALOGS +When it is +.BR 1 , +Windows may show a critical-error dialog for a +.I file +on a drive with no disk in it. +Otherwise busybox suppresses the dialog, and the file fails to open. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A pattern that matches nothing is left as it is, and fails to open with +.BR "Invalid argument" . +A busybox process started with the variable unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options, so that a later +.B \-d +is a file name. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every +.I file +was opened and processed. +.TP +.B 1 +An invalid option, no +.I file +operand, or a +.I file +that could not be opened or flushed. +.PP +A usage message for an invalid option or a missing operand is written to +standard error. +A file that cannot be opened is reported on standard error as +.PP +.RS 4 +.EX +fsync: can\(aqt open \(aq\fIfile\fR\(aq: \fIreason\fR +.EE +.RE +.PP +and one that cannot be flushed as +.PP +.RS 4 +.EX +fsync: \fIfile\fR: \fIreason\fR +.EE +.RE +.SH EXAMPLES +Flush a file through a handle that the shell opens for appending, which, +unlike one that +.B fsync +opens itself, has write access: +.PP +.RS 4 +.EX +$ fsync /dev/stdout >>data.db +.EE +.RE +.PP +A file that cannot be opened is reported, and the exit status is 1: +.PP +.RS 4 +.EX +$ fsync data.db missing.db; echo $? +fsync: can\(aqt open \(aqmissing.db\(aq: No such file or directory +1 +.EE +.RE +.PP +Copy a file and flush the copy. +Unlike +.BR fsync , +.B dd +flushes through the handle it wrote with: +.PP +.RS 4 +.EX +$ dd if=in.bin of=out.bin conv=fsync +.EE +.RE +.SH NOTES +For a named file, opening it for reading is all that +.B fsync +does. +Windows allows +.B FlushFileBuffers +only on a handle with write access, and +.B fsync +opens each file read-only. +The flush fails with an access-denied error, which busybox's emulation +of the C function +.B fsync +deliberately reports as success. +The exit status therefore shows only that each file could be opened for +reading. +.PP +To get data to disk, flush through a handle with write access. +.B dd\ conv=fsync +does so for its output file. +.I /dev/stdout +and +.I /dev/fd/N +reuse an open descriptor, with its access rights, so the shell's +redirection in the first example under +.B EXAMPLES +gives +.B fsync +a handle it can flush. +.PP +A directory operand fails with +.BR "Permission denied" . +.PP +File names may use drive letters and backslashes. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +The device names +.IR /dev/null , +.IR /dev/tty , +.IR /dev/zero , +and +.I /dev/urandom +are accepted, and succeed. +.IR /dev/stdin , +.IR /dev/stdout , +.IR /dev/stderr , +and +.I /dev/fd/N +name open descriptors, and one that is open for writing to a console +fails with +.BR "Invalid argument" . +.SH SEE ALSO +.BR busybox (1), +.BR dd (1), +.BR sync (1) diff --git a/man/man1/getopt.1 b/man/man1/getopt.1 new file mode 100644 index 0000000..31c6ab2 --- /dev/null +++ b/man/man1/getopt.1 @@ -0,0 +1,457 @@ +.TH GETOPT 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +getopt \- parse command-line options for shell scripts +.SH SYNOPSIS +.B getopt +.B \-o +.I optstring +.RI [ options ] +.RB [ \-\- ] +.RI [ parameter ...] +.br +.B getopt +.RI [ options ] +.RB [ \-\- ] +.I optstring +.RI [ parameter ...] +.br +.B getopt +.I optstring +.RI [ parameter ...] +.br +.B getopt \-T +.SH DESCRIPTION +.B getopt +sorts its +.I parameters +into options and operands, and writes them on standard output in a fixed +form. +A shell script passes its own arguments, then hands the output back to the +shell with +.BR "eval set \-\-" , +so that a simple loop can read the options; see +.BR EXAMPLES . +.PP +.I optstring +lists the short options to recognize, and +.B \-l +lists the long options. +Without +.BR \-o , +.I optstring +is the first argument after the options of +.B getopt +itself. +Those options end at the first argument that is not an option, or at +.BR \-\- . +Every later argument is +.I optstring +or a parameter, even if it begins with a dash. +If the first argument after the options begins with a dash, precede it +with +.BR \-\- . +When the first argument is not an option or +.BR \-\- , +as in +.BR "getopt ab \-a" , +the traditional form described below applies instead. +.SS Option strings +Each letter of +.I optstring +is a short option. +A letter followed by a colon takes an argument, which is attached to the +option, as in +.BI \-b value\fR, +or is the next parameter. +A letter followed by two colons takes an optional argument, which must be +attached. +Options may be grouped, as in +.BR \-ab , +and +.B \-\- +ends the options. +A lone +.B \- +is an operand. +.PP +Unless told otherwise, options and operands may be mixed, and the output +lists every operand after the options. +These characters at the start of +.I optstring +change the scan: +.TP +.B + +Stop at the first operand. +It and everything after it are operands. +Setting the environment variable +.B POSIXLY_CORRECT +has the same effect, unless +.I optstring +starts with +.BR \- . +.TP +.B \- +Do not move operands to the end. +Each operand appears in its place among the options, as a quoted argument. +.TP +.B : +Print no error messages, as with +.BR \-q . +It must follow any +.B + +or +.BR \- . +.PP +An unknown or ambiguous option, a missing argument, or an argument given +to a long option that takes none is reported on standard error, left out +of the output, and makes the exit status 1. +Scanning continues after it. +.SS Long options +.B \-l +gives a list of long option names, separated by commas or white space. +A name followed by a colon takes an argument, and a name followed by two +colons takes an optional argument. +.B \-l +may be repeated, and the lists add up. +.PP +On the command line a long option is written +.BI \-\- name\fR. +A required argument follows an equals sign, as in +.BI \-\- name = value\fR, +or is the next parameter. +An optional argument can only follow an equals sign. +A name may be shortened to a prefix, and the output has the full name. +An exact match always wins. +A prefix of several names is ambiguous only when they differ in whether +they take an argument; otherwise the first of them in the order given to +.B \-l +is used. +.PP +With +.BR \-a , +a long option may also start with a single dash. +Such an argument, or the rest of a group after a short option, is read +as a long option if it matches one, unless it is a single letter that is +also a short option. +Otherwise its first letter is read as a short option, or, if it is not +one, the whole remainder is reported as an unknown option. +.SS Output +Each item of the output is preceded by a space, and the output ends with +a line feed. +The items are the options in the order given, each as +.BI \- c +or +.BI \-\- name +(the full name of a long option), followed by its argument if it takes one. +An optional argument that is absent is written as an empty argument. +Then comes +.BR \-\- , +then the operands. +.PP +Each option argument and each operand is enclosed in single quotes, and +each single quote inside it is written as +.BR \(aq\e\(aq\(aq , +so that the shell reads back the original string. +A newline inside an argument is written as it is. +.B \-u +turns quoting off. +With +.B \-s csh +or +.BR "\-s tcsh" , +each exclamation mark and each white-space character other than newline is +also written as a closing quote, a backslash, the character, and an opening +quote, and a newline is written as a backslash and the letter +.BR n . +.SS Traditional form +If the first argument does not begin with a dash, or if +.B GETOPT_COMPATIBLE +is set, the first argument is +.I optstring +and all the rest are parameters, and no option of +.B getopt +is recognized. +There are no long options, and the output is not quoted, as with +.BR \-u . +Leading +.B + +and +.B \- +characters of +.I optstring +are ignored. +Error messages carry the name the program was started under. +With no arguments at all, it reports a missing +.IR optstring , +except that when +.B GETOPT_COMPATIBLE +is set it writes the output for no parameters, which is just +.BR \-\- , +and exits 0. +.SH OPTIONS +These are the options of +.B getopt +itself. +They may be grouped, as in +.BR \-uq . +A short option's argument may be attached, as in +.BR \-oab , +or be the next argument. +A long option's argument follows an equals sign or is the next argument. +Long options may be shortened to a unique prefix. +An error in these options prints a message and the usage text on +standard error, and exits with status 1. +.TP +\fB\-a\fR, \fB\-\-alternative\fR +Allow long options to start with a single dash. +.TP +\fB\-l\fR, \fB\-\-longoptions\fR \fIlongopts\fR +Recognize the long options in +.IR longopts . +May be repeated. +.TP +\fB\-n\fR, \fB\-\-name\fR \fIname\fR +Use +.I name +as the program name in the error messages about the parameters. +The default is the name the program was started under, normally +.BR getopt . +Messages about the command line of +.B getopt +itself are not affected. +.TP +\fB\-o\fR, \fB\-\-options\fR \fIoptstring\fR +Recognize the short options in +.IR optstring . +Without +.BR \-o , +the first operand is +.IR optstring . +If repeated, the last one wins. +.TP +.BR \-q ", " \-\-quiet +Print no error messages about the parameters. +An error still makes the exit status 1. +Errors in the command line of +.B getopt +itself are still reported. +.TP +.BR \-Q ", " \-\-quiet\-output +Write nothing on standard output. +Use it to test parameters by the exit status alone. +.TP +\fB\-s\fR, \fB\-\-shell\fR \fIshell\fR +Set the quoting convention to that of +.IR shell , +which is +.B bash +or +.B sh +(the default), +.BR csh , +or +.BR tcsh . +The names are case-sensitive. +Any other name produces a warning on standard error and is treated as +.BR bash . +Has no effect with +.BR \-u . +.TP +.BR \-T ", " \-\-test +Exit with status 4 without writing anything, as a test for this +.BR getopt . +The other options are still checked first. +When +.B GETOPT_COMPATIBLE +is set, +.B \-T +is the +.I optstring +of the traditional form instead, so the output is +.B \-\- +and the exit status 0. +.TP +.BR \-u ", " \-\-unquoted +Do not quote the output. +An empty argument, or one with white space or characters special to the +shell, then does not survive the shell's word splitting. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and exit +with status 0. +There is no +.B \-h +or +.BR \-V . +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Read when +.B busybox.exe +starts. +Unless it is +.BR 0 , +the C runtime expands wildcards in the command-line arguments before +.B getopt +sees them. +If it is unset, startup sets it to +.B 0 +in the environment of child processes, so that they do not expand wildcards +again. +.TP +.BR BB_TERMINAL_MODE ", " BB_SKIP_ANSI_EMULATION +When standard output is a console, decide whether the console or busybox +interprets escape sequences in the output. +See +.BR busybox (1). +.TP +.B CONEMUPID +When it is set and neither of the above is, busybox uses terminal mode +0: it turns virtual terminal output off and emulates escape sequences +itself. +.TP +.B GETOPT_COMPATIBLE +If set, even to an empty value, use the traditional form. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.TP +.B POSIXLY_CORRECT +If set, even to an empty value, stop scanning the parameters at the first +operand, as with a leading +.B + +in +.IR optstring . +It has no effect when +.I optstring +starts with +.BR \- . +The C runtime reads it. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +The parameters contained an error, or the command line of +.B getopt +is invalid: an unknown or ambiguous option, a missing option argument or +.IR optstring , +or an empty long option name. +.TP +.B 4 +.B \-T +was given. +.SH EXAMPLES +Read the options of a script. +The loop ends at the +.B \-\- +that +.B getopt +writes after the options: +.PP +.RS 4 +.EX +$ cat opts.sh +args=$(getopt \-n opts \-o vo: \-l verbose,output: \-\- "$@") || exit 1 +eval set \-\- "$args" +while :; do + case $1 in + \-v|\-\-verbose) verbose=1; shift;; + \-o|\-\-output) output=$2; shift 2;; + \-\-) shift; break;; + esac +done +echo "verbose=$verbose output=$output files: $*" +$ sh opts.sh \-v \-\-out=a.txt "my file" b.c +verbose=1 output=a.txt files: my file b.c +$ sh opts.sh \-x +opts: unknown option \-\- x +.EE +.RE +.PP +Show what +.B getopt +writes for a short option, a short option with an attached argument, a +long option with an optional argument, and operands, one of which holds a +quote: +.PP +.RS 4 +.EX +$ getopt \-o ab: \-l long:: \-\- \-a \-bfoo \-\-long=x "it\(aqs" rest + \-a \-b \(aqfoo\(aq \-\-long \(aqx\(aq \-\- \(aqit\(aq\e\(aq\(aqs\(aq \(aqrest\(aq +.EE +.RE +.PP +Check parameters without writing anything or printing errors: +.PP +.RS 4 +.EX +$ getopt \-qQ \-o ab \-\- \-a \-z || echo bad +bad +.EE +.RE +.PP +Use the traditional form, whose output is not quoted: +.PP +.RS 4 +.EX +$ set \-\- \-a x +$ set \-\- $(getopt ab "$@") +$ echo "$@" +\-a \-\- x +.EE +.RE +.SH NOTES +The parameters are scanned by the getopt functions of the mingw-w64 C +runtime, not by the GNU C library, so some details differ from util-linux +.BR getopt : +.IP \(bu 2 +The error messages are the runtime's, such as +.BR "getopt: unknown option \-\- x" , +.BR "getopt: option requires an argument \-\- b" , +.BR "getopt: option doesn\(aqt take an argument \-\- alpha" , +and +.BR "getopt: ambiguous option \-\- al" . +.IP \(bu 2 +A prefix that matches several long options is an error only when they +differ in whether they take an argument; otherwise the first of them is +used. +.IP \(bu 2 +With +.BR \-a , +the rest of a group after a short option may be read as a long option. +.IP \(bu 2 +Every failure exits with status 1, where util-linux also uses 2 and 3. +.PP +The output ends in a line feed, not CRLF. +Arguments are copied byte for byte, and paths are not converted: drive +letters and backslashes stay as typed, and the single quotes keep +backslashes literal for the shell. +When standard output is a console, the output is converted for display +from the ANSI code page, which is UTF-8 on Windows 10 version 1903 and +later, and escape sequences in it take effect. +Only a POSIX shell such as +.BR sh (1) +can read the quoted output, not +.BR cmd.exe . +The shell builtin +.BR getopts , +also described in +.BR sh (1), +needs no external program but has no long options. +.PP +When started from outside the kit shell, as from +.BR cmd.exe , +the program expands wildcards in its arguments first; see +.BR BB_GLOBBING . +.SH SEE ALSO +.BR busybox (1), +.BR sh (1) diff --git a/man/man1/grep.1 b/man/man1/grep.1 new file mode 100644 index 0000000..f447cf6 --- /dev/null +++ b/man/man1/grep.1 @@ -0,0 +1,580 @@ +.TH GREP 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +grep, egrep, fgrep \- print lines that match patterns +.SH SYNOPSIS +.B grep +.RI [ options ] +.I pattern +.RI [ file ...] +.br +.B grep +.RI [ options ] +.BI "\-e " pattern +.RI ...\& +.RI [ file ...] +.br +.B grep +.RI [ options ] +.BI "\-f " patfile +.RI ...\& +.RI [ file ...] +.br +.B egrep +.RI [ options ] +.I pattern +.RI [ file ...] +.br +.B fgrep +.RI [ options ] +.I pattern +.RI [ file ...] +.SH DESCRIPTION +.B grep +searches each +.I file +for lines that match any of the patterns, and writes those lines to +standard output. +With no +.I file +operands, or for a +.I file +named +.BR \- , +it reads standard input. +.B egrep +is +.BR "grep \-E" , +and +.B fgrep +is +.BR "grep \-F" . +This is the busybox +.BR grep . +.PP +The patterns are those given with +.B \-e +and +.BR \-f , +or when neither is given, the +.I pattern +operand. +A pattern containing newlines is several patterns, one per line, and an +empty pattern matches every line. +Patterns are basic regular expressions, extended regular expressions +with +.BR \-E , +or fixed strings with +.BR \-F . +.PP +A line of input ends at an LF or at a NUL byte, and a CR before an LF is +removed, so CRLF text is matched as if it had LF line endings. +Lines may be any length. +Every file is searched as text; there is no binary file detection. +.PP +Each selected line is written followed by an LF. +When more than one +.I file +is given, or a directory is searched with +.BR \-r , +the line is preceded by its file name and a colon; +.B \-H +and +.B \-h +override this. +Standard input is named +.BR "(standard input)" . +With +.BR \-n , +the line number and a colon come next. +Context lines, requested with +.BR \-A , +.BR \-B , +or +.BR \-C , +have a +.B \- +in place of each colon, and a line containing only +.B \-\- +separates groups of lines that are not adjacent. +.BR \-c , +.BR \-l , +.BR \-L , +and +.B \-q +replace this output, and they disable +.B \-n +and context. +.SS Regular expressions +Regular expressions are POSIX basic or extended regular expressions, as +implemented by the GNU regex code built into busybox, with its +extensions. +In a basic expression, +.BR \e? , +.BR \e+ , +and +.B \e| +are the optional, repetition, and alternation operators that +.BR ? , +.BR + , +and +.B | +are in an extended expression, and +.BR ? , +.BR + , +and +.B | +match themselves. +An interval is +.BI \e{ m , n \e} +in a basic expression and +.BI { m , n } +in an extended one. +Both kinds accept back-references +.B \e1 +to +.BR \e9 , +.B \ew +for a word character, which is an ASCII letter, digit, or underscore, +.B \eW +for any other character, +.B \es +and +.B \eS +for whitespace and anything else, +.B \eb +and +.B \eB +for a word boundary and its absence, and +.B \e< +and +.B \e> +for the start and end of a word. +.PP +Matching works on bytes. +A +.B .\& +or a bracket expression matches one byte, not one non-ASCII character, +and character classes such as +.B [:alpha:] +contain only ASCII characters. +.SH OPTIONS +Options may be grouped, as in +.BR \-in , +and may follow operands unless +.B POSIXLY_CORRECT +is set. +An option's argument may be attached, as in +.BR \-m1 , +or be the next argument. +.B \-\- +ends the options. +The +.I num +arguments are decimal integers from 0 to 2147483647. +.TP +.B \-H +Precede each line with its file name, even for a single file. +When both +.B \-H +and +.B \-h +are given, the later one wins. +.TP +.B \-h +Never precede lines with file names. +.TP +.B \-n +Precede each line with its line number, starting at 1. +.TP +.B \-l +Print only the name of each file that has a selected line, and stop +reading the file at that line. +.TP +.B \-L +Print only the name of each file that has no selected line. +.TP +.B \-c +Print only the number of selected lines in each file, after the file +name and a colon when names are shown. +.TP +.B \-o +Print only the matched part of each selected line, each match on its own +line. +Empty regular expression matches are not printed. +See +.B NOTES +for how this differs from GNU +.BR grep . +.TP +.B \-q +Print no lines, and exit with status 0 at the first selected line, even +if there were errors. +With +.B \-c +or +.BR \-L , +files with no selected line are still reported until then. +.TP +.B \-v +Select the lines that do not match. +.TP +.B \-s +Do not report files that cannot be opened. +The exit status still reports the error. +Directories that +.B \-r +or +.B \-R +cannot read are reported anyway, and do not affect the exit status. +.TP +.B \-r +Search the files under each directory operand, recursively. +Below the operands, symbolic links and junctions are followed if they +lead to files and skipped if they lead to directories. +File operands are searched as usual, and with no +.I file +operands +.B grep +reads standard input. +Without +.B \-r +or +.BR \-R , +a directory operand is an error. +.TP +.B \-R +Like +.BR \-r , +but also follow symbolic links and junctions to directories. +.TP +.B \-i +Ignore case, for ASCII letters only. +.TP +.B \-w +Select a line only if a match is a whole word: one that is neither +preceded nor followed by an ASCII letter, digit, or underscore. +.TP +.B \-x +Select a line only if a pattern matches the whole line. +Overrides +.BR \-w . +.TP +.B \-F +Patterns are fixed strings. +Takes precedence over +.BR \-E , +including for +.BR egrep . +.TP +.B \-E +Patterns are extended regular expressions. +.TP +.BI "\-m " num +Stop reading a file after its +.IR num th +selected line. +Trailing context is still printed after it, up to the next selected line. +With a +.I num +of 0, only the first line is read; it is never printed, but if it is +selected, it counts as such for +.BR \-c , +.BR \-l , +.BR \-L , +.BR \-q , +and the exit status. +.TP +.BI "\-A " num +Print +.I num +lines of trailing context after each selected line. +.TP +.BI "\-B " num +Print +.I num +lines of leading context before each selected line. +.TP +.BI "\-C " num +Same as +.BI "\-A " num +.BI "\-B " num +at this position, so it overrides an earlier +.B \-A +or +.BR \-B , +and a later one overrides it. +.TP +.BI "\-e " pattern +Use +.IR pattern . +May be repeated, and combined with +.BR \-f . +.TP +.BI "\-f " patfile +Read patterns from +.IR patfile , +one per line, ignoring a CR before each LF. +A +.I patfile +of +.B \- +is standard input. +May be repeated. +When the files hold no patterns and there is no +.BR \-e , +no line matches. +.TP +.BR \-a ", " \-I +Accepted and ignored. +.TP +\fB\-\-color\fR[\fB=\fIwhen\fR] +Accepted and ignored. +There is no color output. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit with status 0. +.B egrep +and +.B fgrep +print that no help is available instead. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the C runtime replaces each argument containing wildcards with the names +of the files it matches, if any, even when the argument is quoted. +From +.BR cmd.exe , +a pattern such as +.B \(dqa*\(dq +may become a list of files. +When it is unset, busybox sets it to +.B 0 +for its child processes, so commands run from the busybox shell, which +expands wildcards itself, receive their arguments as given. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.TP +.B POSIXLY_CORRECT +If set, options must come before operands. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +A line was selected, or with +.BR \-L , +a file name was printed. +.TP +.B 1 +No line was selected. +.TP +.B 2 +An error: an invalid option or argument, an invalid regular expression, +a pattern file that cannot be read, or a file that cannot be opened, +even if lines were selected in others. +With +.BR \-q , +a selected line ends the search with status 0 regardless of earlier +errors. +.TP +.B 141 +Standard output is a pipe that was closed while +.B grep +was writing to it. +Output is buffered, and a closed pipe found only by the final flush at +exit, as with short output, is ignored. +.SH EXAMPLES +Show where +.B main +is defined, with line numbers and a line of context: +.PP +.RS 4 +.EX +$ grep \-n \-C1 main hello.c +2\- +3:int main(void) +4\-{ +.EE +.RE +.PP +Search a source tree for the whole word +.BR count : +.PP +.RS 4 +.EX +$ grep \-rnw count src +src/count.c:1:static int count; +src/count.c:5: return count++; +.EE +.RE +.PP +Find errors and warnings in a build log, using an extended regular +expression, then the same with a basic one: +.PP +.RS 4 +.EX +$ grep \-E \(aqerror|warning\(aq build.log +$ grep \(aqerror\e|warning\(aq build.log +.EE +.RE +.PP +Search for a pattern that begins with a dash: +.PP +.RS 4 +.EX +$ grep \-e \-Wall Makefile +.EE +.RE +.PP +List the C files that do not include +.IR stdio.h : +.PP +.RS 4 +.EX +$ grep \-L \(aq#include \(aq *.c +.EE +.RE +.PP +Test for a match in a script: +.PP +.RS 4 +.EX +$ grep \-q \(aq^CFLAGS\(aq Makefile && echo configured +.EE +.RE +.SH NOTES +Differences from GNU +.BR grep : +.IP \(bu 2 +.B \-r +with no +.I file +operands reads standard input, not the current directory. +.IP \(bu 2 +There is no binary file detection, a NUL byte ends a line, and +.B \-a +and +.B \-I +have no effect. +.IP \(bu 2 +With +.BR \-F , +.B \-o +prints the pattern as given, once per line, however often and in +whatever case it occurs. +With several patterns, +.B \-o +prints the matches of only one of them on each line; join them with +.B \e| +or +.B | +instead. +With +.BR \-w , +.B \-o +prints every match on a selected line, whole word or not, and prints the +wrong text when the first match on the line is not a whole word. +Each later match on a line is found as if the line began where the +previous match ended, which changes the result of +.BR \eb , +.BR \eB , +.BR \e< , +and +.BR \e> . +Context lines are printed whole, and with +.BR \-v , +.B \-o +prints only the file name and line number prefixes of context lines, +without their text or a newline. +.IP \(bu 2 +A regular expression is compiled when first needed, so an invalid one is +not reported if no input is read. +.IP \(bu 2 +Read errors end a file silently. +.IP \(bu 2 +An empty +.B \-f +file, with no other patterns, selects no line, except that with +.B \-F +and +.B \-x +it selects every line except one reading +.BR .* , +and with +.B \-w +but neither +.B \-F +nor +.BR \-x , +every line that begins with an ASCII letter, digit, or underscore. +.IP \(bu 2 +With +.B \-w +but not +.BR \-x , +an empty pattern, such as a blank line in a +.B \-f +file, matches every line if +.B \-F +is given, and otherwise only lines that are empty or begin with a +character other than an ASCII letter, digit, or underscore. +.IP \(bu 2 +GNU options not listed above, such as +.BR \-P , +.BR \-z , +.BR \-\-include , +and long forms such as +.BR \-\-ignore\-case , +are invalid. +.PP +Output lines end with LF, not CRLF, even when the input has CRLF line +endings. +.PP +Patterns and input are compared as bytes, so their encodings must agree. +On Windows 10 version 1903 and later, busybox runs with UTF-8 as its code +page, and patterns and file names from the command line are UTF-8. +On earlier versions they are in the ANSI code page. +When standard output is a console, output is converted from that code +page to the console's for display, and escape sequences in it take +effect. +.PP +File operands may use drive letters and backslashes, and are printed as +given. +.B \-r +joins the names it finds with +.BR / , +so +.B grep \-r x \(aqC:\esrc\(aq +prints names such as +.IR C:\esrc/main.c . +A bare drive such as +.I C: +names the current directory of that drive, and +.B \-r +prints names such as +.I C:name +for the files below it. +The device names +.IR /dev/null , +.IR /dev/stdin , +and +.I /dev/tty +(the console) work as on Unix. +.SH SEE ALSO +.BR busybox (1), +.BR find (1), +.BR less (1), +.BR sed (1), +.BR sh (1), +.BR xargs (1) diff --git a/man/man1/groups.1 b/man/man1/groups.1 new file mode 100644 index 0000000..c469300 --- /dev/null +++ b/man/man1/groups.1 @@ -0,0 +1,251 @@ +.TH GROUPS 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +groups \- print the group of a user +.SH SYNOPSIS +.B groups +.RI [ user ] +.SH DESCRIPTION +.B groups +prints the name of the group that the current user, or +.IR user , +belongs to, followed by a newline, on standard output. +It is the +.BR id (1) +applet run under another name, and it prints what +.B id \-Gn +prints. +.PP +Windows has no Unix users or groups, so busybox emulates two users. +Each is the only member of a group with the same name and ID: +.IP \(bu 2 +The current Windows user, with ID 4095. +Its name is the account name that Windows reports, without a domain, with +each space replaced by an underscore. +.IP \(bu 2 +.BR root , +with ID 0. +.PP +A process is +.BR root , +and not the current user, when it is elevated and the Administrators +group is enabled in its access token. +With no +.IR user , +.B groups +therefore prints +.B root +in an elevated process, and the user name otherwise. +With a +.IR user , +whether the process is elevated does not matter. +The current user's name, compared case-sensitively, gives that name, +.B root +gives +.BR root , +and any other name is an error. +.PP +The Windows groups that the account belongs to, such as Administrators +and Users, are never reported. +Further operands after +.I user +are ignored. +.SH OPTIONS +Apart from +.BR \-\-help , +.B groups +takes no options. +Any other argument that begins with a dash, other than +.B \-\- +and a lone +.BR \- , +is an unknown option and is rejected with a usage message. +.B \-\- +ends the options, and a lone +.B \- +is taken as a +.IR user , +which is unknown. +Options are recognized after the first operand too, unless +.B POSIXLY_CORRECT +is set. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +When set, the first operand ends the options, so that a later argument +such as +.B \-x +is an operand and is ignored. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when +.B groups +starts, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An unknown option, a +.I user +that is neither the current user nor +.BR root , +an error writing standard output, or a group with no name, as described +in +.BR NOTES . +.PP +Each failure is reported on standard error, and an unknown option is +followed by a usage message: +.PP +.RS 4 +.EX +groups: unknown option \-\- \fIx\fR +groups: unknown user \fIuser\fR +groups: standard output: \fIreason\fR +groups: unknown ID \fIid\fR +.EE +.RE +.PP +The unknown option message begins with the command as it was invoked, +in lowercase, with forward slashes, and without +.BR .exe , +so it includes a directory when the caller gave one. +.SH EXAMPLES +Print the group of the current user, here a user named +.BR jdoe : +.PP +.RS 4 +.EX +$ groups +jdoe +.EE +.RE +.PP +Print the group of +.BR root , +which is known whether or not the process is elevated: +.PP +.RS 4 +.EX +$ groups root +root +.EE +.RE +.PP +Any other user is unknown: +.PP +.RS 4 +.EX +$ groups alice +groups: unknown user alice +.EE +.RE +.PP +Tell a script whether it runs as +.BR root : +.PP +.RS 4 +.EX +$ test "$(groups)" = root && echo elevated +.EE +.RE +.SH NOTES +Differences from GNU +.BR groups : +.IP \(bu 2 +It reports one emulated group, not the account's groups. +.IP \(bu 2 +It takes one +.IR user . +GNU +.B groups +takes several, and starts each line with the user name and a colon. +.IP \(bu 2 +Only the current user and +.B root +are known. +.IP \(bu 2 +There is no +.BR \-\-version , +and +.B \-\-help +is recognized only as the first argument. +.PP +The name comes from Windows, not from +.BR USER , +.BR USERNAME , +or +.BR LOGNAME . +It is that of the account without its domain, so +.IB domain \e name +is unknown. +A name with spaces, such as +.BR "Jane Doe" , +becomes +.BR Jane_Doe , +and +.B "Jane Doe" +is then an unknown user. +.PP +Elevated means started with administrator rights, as from a console +opened with Run as administrator, or by +.BR su (1). +A command that +.BR drop , +.BR cdrop , +or +.B pdrop +starts from an elevated console is not +.BR root , +because those commands run it with a reduced token. +.PP +When Windows does not report a user name, the group of the current user +has no name. +.B groups +with no +.I user +in a process that is not +.B root +then prints the ID, +.BR 4095 , +reports +.B unknown ID +on standard error, and exits with status 1. +.PP +The user name is read in the ANSI code page, which is UTF-8 on Windows 10 +version 1903 and later, so on those versions it may contain any Unicode +characters. +On older versions it is limited to the system code page. +When standard output is a console, the name is converted from the ANSI +code page for display. +The output line ends with LF, not CRLF. +.SH SEE ALSO +.BR busybox (1), +.BR id (1), +.BR sh (1), +.BR su (1), +.BR whoami (1) diff --git a/man/man1/hd.1 b/man/man1/hd.1 new file mode 100644 index 0000000..71fc064 --- /dev/null +++ b/man/man1/hd.1 @@ -0,0 +1 @@ +.so man1/hexdump.1 diff --git a/man/man1/head.1 b/man/man1/head.1 new file mode 100644 index 0000000..d665c64 --- /dev/null +++ b/man/man1/head.1 @@ -0,0 +1,365 @@ +.TH HEAD 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +head \- print the first part of files +.SH SYNOPSIS +.B head +.RB [ \-qv ] +.RB [ \-n +.RI [\-] count ] +.RB [ \-c +.RI [\-] count ] +.RI [ file ...] +.br +.B head +.BI \- count +.RI [ options ] +.RI [ file ...] +.SH DESCRIPTION +.B head +writes the first part of each +.I file +to standard output: by default the first 10 lines. +With no +.I file +operands, or for a +.I file +named +.BR \- , +it reads standard input. +This +.B head +is a busybox applet; see +.BR busybox (1). +.PP +A +.I file +that cannot be opened or read is reported on standard error, and the +remaining files are still written. +.SS Counts +A count is a decimal number, optionally followed by one of the suffixes +.BR b , +.BR k , +or +.BR m , +which multiply it by 512, 1024, or 1048576. +Suffixes are lowercase. +The result must be from 0 to 4294967295. +Hexadecimal, a leading +.BR + , +and white space are not accepted. +A count that is malformed or out of range is an error, reported before +any file is read. +.PP +With +.BR \-n , +.B head +counts lines, which end at an LF. +A CR is an ordinary byte. +A last line without an LF is written as it is, without adding one. +With +.BR \-c , +it counts bytes. +A count of 0 writes nothing. +.PP +A count that begins with +.B \- +counts from the end: everything except the last +.I count +lines or bytes is written. +.B head +must read all of its input to find the end, and keeps the last +.I count +plus 1 lines or bytes in memory. +When the input has no more than +.I count +lines or bytes, nothing is written. +In this mode with +.BR \-n , +a NUL byte also ends a line, and is not written. +.PP +If counts are given more than once, the last one is used. +If any of them is given with +.BR \-c , +it counts bytes, and if any begins with +.BR \- , +it counts from the end. +.SS Headers +With more than one +.I file +operand, or with +.BR \-v , +.B head +writes a header before the output of each file: a line of the form +.PP +.RS 4 +.EX +==> name <== +.EE +.RE +.PP +where +.I name +is the operand as given, or +.B standard input +for standard input. +Each header after the one for the first operand starts with an LF. +That gives an empty line between files, or ends the last line of a file +that had no final LF. +This holds even when the first operand could not be opened. +.B \-q +turns headers off. +.SH OPTIONS +Options may be grouped, as in +.BR \-qn5 , +and an option's argument may be attached or be the next argument. +.B \-\- +ends the options. +The first operand also ends them: a later argument such as +.B \-n +is a file name. +A lone +.B \- +is an operand. +.TP +.BI "\-n " count +Write the first +.I count +lines. +The default is 10. +With a leading +.BR \- , +write all but the last +.I count +lines. +See +.BR Counts . +.TP +.BI "\-c " count +Write the first +.I count +bytes instead of lines. +With a leading +.BR \- , +write all but the last +.I count +bytes. +.TP +.B \-q +Never write headers. +.TP +.B \-v +Always write headers, even for one operand or for standard input with no +operands. +The last of +.B \-q +and +.B \-v +on the command line wins. +.TP +.BI \- count +As the first argument only, the same as +.BI "\-n " count +except that +.I count +cannot begin with +.BR \- . +Other options may follow, as in +.BR "head \-5 \-q a.txt b.txt" , +but the digits cannot be grouped with them: +.B \-5q +is an error. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid option or count, a +.I file +could not be opened or read, memory ran out, or standard output could not +be written. +.TP +.B 141 +Standard output is a pipe that was closed while +.B head +was writing to it. +Output is buffered, and when the closed pipe is found only by the final +flush at exit, as with short output, the status is 1 instead. +.SH EXAMPLES +Write the first 3 lines of a file: +.PP +.RS 4 +.EX +$ head \-n 3 notes.txt +.EE +.RE +.PP +Write the first line of each of two files, with headers: +.PP +.RS 4 +.EX +$ head \-n 1 a.txt b.txt +==> a.txt <== +first line of a + +==> b.txt <== +first line of b +.EE +.RE +.PP +Write the first line of every text file, without headers: +.PP +.RS 4 +.EX +$ head \-qn1 *.txt +.EE +.RE +.PP +Write all but the last line of a file: +.PP +.RS 4 +.EX +$ head \-n \-1 data.csv +.EE +.RE +.PP +Copy the first 64 KiB of a file to another file: +.PP +.RS 4 +.EX +$ head \-c 64k big.bin >first.bin +.EE +.RE +.PP +Show the first 16 bytes of a program in hex: +.PP +.RS 4 +.EX +$ head \-c 16 program.exe | xxd +.EE +.RE +.PP +Keep the five smallest numbers of a list: +.PP +.RS 4 +.EX +$ sort \-n sizes.txt | head \-5 +.EE +.RE +.SH NOTES +Differences from GNU +.BR head : +.IP \(bu 2 +There are no long options other than +.BR \-\-help , +no +.BR \-\-version , +and no +.BR \-z . +.IP \(bu 2 +Options are not accepted after the first operand. +.IP \(bu 2 +Counts are decimal with the lowercase suffixes +.BR b , +.BR k , +and +.B m +only. +GNU suffixes such as +.BR K , +.BR kB , +and +.BR MB , +and a leading +.BR + , +are errors. +.IP \(bu 2 +Counts are limited to 4294967295, in the 64-bit kit too. +.PP +With a leading +.BR \- , +.B head +allocates memory in proportion to +.I count +before it reads any input, so a large count can fail with +.B out of memory +even for short input. +A count of 268435455 or more, or 536870911 or more in the 32-bit kit, +also prints +.B count is too big +as a warning, and +.B head +still runs. +A count of 4294967295, or in the 32-bit kit a line count of 1073741823 +or more, can crash it. +.PP +.B head +reads its input in blocks, and leaves a seekable standard input at the +end of the last block it read, not after the last byte it used. +A command that shares the redirected standard input with +.B head +continues from there. +.PP +Files and standard input and output are binary, so CR LF line endings +and Ctrl-Z characters are copied unchanged. +.PP +File names may use drive letters, backslashes, and forward slashes, and +a header shows the name as given. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +The device names +.IR /dev/null , +.IR /dev/zero , +.IR /dev/urandom , +.IR /dev/stdin , +.I /dev/tty +(the console), and +.I /dev/fd/N +work as on Unix. +A directory operand fails with +.BR "Is a directory" . +.PP +When standard output is a console, text is converted for display from +the ANSI code page, which is UTF-8 on Windows 10 version 1903 and later, +to the console's code page, unless +.BR LC_ALL , +.BR LC_CTYPE , +or +.B LANG +is +.BR C . +.SH SEE ALSO +.BR busybox (1), +.BR cat (1), +.BR less (1), +.BR sed (1), +.BR sort (1), +.BR tail (1), +.BR xxd (1) diff --git a/man/man1/hexdump.1 b/man/man1/hexdump.1 new file mode 100644 index 0000000..60cc470 --- /dev/null +++ b/man/man1/hexdump.1 @@ -0,0 +1,479 @@ +.TH HEXDUMP 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +hexdump, hd \- dump files in hexadecimal or a custom format +.SH SYNOPSIS +.B hexdump +.RB [ \-bcdoxCv ] +.RB [ \-e +.IR format ] +.RB [ \-f +.IR file ] +.RB [ \-n +.IR length ] +.RB [ \-s +.IR offset ] +.RI [ file ...] +.br +.B hd +.RI [ options ] +.RI [ file ...] +.SH DESCRIPTION +.B hexdump +writes the bytes of each +.I file +to standard output in one or more formats. +With no +.I file +operands, or for a +.I file +named +.BR \- , +it reads standard input. +The files form a single input: offsets run on from one file to the next, +and +.B \-s +and +.B \-n +apply to the whole. +A file that cannot be opened is reported on standard error and skipped. +.PP +.B hd +is +.B hexdump +with +.B \-C +given before any other option. +.PP +The options +.BR \-b , +.BR \-c , +.BR \-d , +.BR \-o , +.BR \-x , +.BR \-C , +.BR \-e , +and +.B \-f +each add formats, and may be repeated. +Input is read in blocks, 16 bytes for the built-in formats, and each +block is written in every format in the order given, so +.B \-bc +writes two lines for each 16 bytes. +With none of these options, each line is a 7-digit hexadecimal offset +and eight 2-byte values, each as a space and 4 hexadecimal digits. +.PP +Multibyte values are read little-endian. +The built-in formats write offsets in hexadecimal, widening them past +their minimum width as needed, and after the last line, the offset just +past the end of the input. +In the last block, a value only partly present is completed with zero +bytes, and the line is padded with spaces where the input ran out. +Empty input produces no output. +.PP +Unless +.B \-v +is given, a block identical to the one before it is not written, and +each run of such blocks is replaced by a line holding a single +.BR * . +A partial last block is always written, but when it matches the start of +the block before it, a +.B * +line comes first even if no block was left out. +.SS Format strings +A format string, the argument of +.B \-e +or a line of a +.B \-f +file, is a sequence of units, each of the form +.PP +.RS 4 +.EX +[\fIiterations\fR][\fB/\fIbytes\fR] \fB"\fIformat\fB"\fR +.EE +.RE +.PP +A unit writes +.I format +.I iterations +times, by default once. +Each conversion in +.I format +converts +.I bytes +bytes of input, or without +.IR bytes , +the default for the conversion. +A byte count must be followed by whitespace, as in +.BR "16/1\ \(dq%02x\(dq" . +.PP +The block size is the most input any one format string converts, and +every format string starts at the beginning of the block. +When the last unit of a format string has no +.I iterations +and converts input, it repeats as often as fits in the block. +On the last of several iterations, a whitespace character at the end of +.I format +is not written, so +.B "4/1\ \(dq%02x\ \(dq" +ends without a space. +In a partial last block, conversions past the end of the input are +written as spaces filling their field width, while the text around them +is still written. +.PP +Text in +.I format +is written as is, after these escape sequences are replaced: +.BR \ea , +.BR \eb , +.BR \ee , +.BR \ef , +.BR \en , +.BR \er , +.BR \et , +.BR \ev , +.BR \e\e , +.BI \e ooo +with 1 to 3 octal digits, and +.BI \ex hh +with 1 or 2 hexadecimal digits. +An escape that gives a NUL byte ends the format. +Any other backslash is written as is. +.I format +cannot contain a double quote, but +.B \e042 +writes one. +.PP +A conversion is +.B % +followed by optional flags, field width, and precision, as in +.BR printf , +and one of the following. +Integer conversions also accept the length modifiers +.B l +and +.BR ll , +but +.B ll +is correct only in an 8-byte +.B %d +or +.BR %i . +Only the first conversion in each quoted format works: the format is +cut off before its second +.BR % , +but the block size still counts the input of the dropped conversions, +so that much input is never shown. +With a byte count, a format with two conversions other than offsets is +rejected. +Put each conversion in a quoted format of its own. +.TP +.B %c +One byte as a character. +.TP +.BR %d ", " %i +A signed decimal integer of 1, 2, 4, or 8 bytes, with +.B %lld +or +.B %lli +for 8. +Always give a byte count: without one, +.B %d +prints 4 bytes but advances 8, so a later conversion in the same format +string prints garbage, and +.B %lld +counts as no input, so alone it writes nothing. +.TP +.BR %o ", " %u ", " %x ", " %X +An unsigned integer of 1, 2, or 4 bytes, by default 4, in octal, +decimal, or hexadecimal. +.TP +.BR %e ", " %E ", " %f ", " %g ", " %G +A floating-point number of 4 or 8 bytes, by default 8. +.TP +.B %s +A string of +.I bytes +bytes. +Without a byte count, a precision, as in +.BR %.8s , +is required and gives the length. +The string stops at a NUL byte, and without a precision it runs on past +its bytes to the next NUL byte in memory, so always give one. +.TP +.BR %_ad ", " %_ao ", " %_ax +The offset of the next byte, in decimal, octal, or hexadecimal. +It converts no input. +.TP +.BR %_Ad ", " %_Ao ", " %_Ax +The offset just past the end of the input, written once, after the last +block. +Its unit is written only then, and the units after it in the same format +string never are. +Only the last format string to use it, counting the built-in formats, +is written. +.TP +.B %_c +One byte as +.B \-c +writes it. +.TP +.B %_p +One byte as a character if it is printable ASCII, otherwise a period. +.TP +.B %_u +One byte as a character if it is printable ASCII, a control character as +its lowercase ASCII name, such as +.BR nul , +.BR lf , +or +.BR esc , +0x7f as +.BR del , +and other bytes in hexadecimal. +.PP +Conversions of one byte accept only a byte count of 1. +.B %% +is rejected, so a format cannot write a literal percent sign. +.SH OPTIONS +Options may be grouped, as in +.BR \-bc , +and an option's argument may be attached, as in +.BR \-n16 . +Options must come before the file operands, and +.B \-\- +ends them. +.B \-n +and +.B \-s +take a number in decimal, in hexadecimal with a +.B 0x +prefix, or in octal with a leading +.BR 0 , +optionally followed by a multiplier: +.BR K , +.BR M , +or +.B G +for 1024, 1048576, or 1073741824, and +.BR KB , +.BR MB , +or +.B GB +for 1000, 1000000, or 1000000000. +.BR K , +.BR M , +and +.B G +may be lowercase, and may be followed by +.BR iB , +as in +.BR MiB . +.TP +.B \-b +One-byte octal: 16 bytes per line, each as a space and 3 octal digits. +.TP +.B \-c +One-byte characters: 16 bytes per line, each right-aligned in 4 +columns. +Printable ASCII is written as itself; NUL, BEL, BS, TAB, LF, VT, FF, and +CR as +.BR \e0 , +.BR \ea , +.BR \eb , +.BR \et , +.BR \en , +.BR \ev , +.BR \ef , +and +.BR \er ; +and other bytes as 3 octal digits. +.TP +.B \-d +Two-byte unsigned decimal: 8 values per line, each as 3 spaces and 5 +digits with leading zeros. +.TP +.B \-o +Two-byte octal: 8 values per line, each as 2 spaces and 6 octal digits. +.TP +.B \-x +Two-byte hexadecimal: 8 values per line, each as 4 spaces and 4 +hexadecimal digits. +.TP +.B \-C +Canonical hexadecimal and ASCII: an 8-digit offset, 16 bytes as pairs of +hexadecimal digits in two groups of 8, and the same bytes as text +between +.B | +characters, with a period for each byte that is not printable ASCII. +.TP +.B \-v +Write every block, including repeated ones. +.TP +.BI "\-e " format +Add the format string +.IR format . +.TP +.BI "\-f " file +Add each line of +.I file +as a format string. +Leading whitespace is ignored, and so are empty lines and lines whose +first other character is +.BR # . +CRLF line endings are accepted. +.TP +.BI "\-n " length +Read at most +.I length +bytes of input, from 0 to 2147483647. +.TP +.BI "\-s " offset +Skip +.I offset +bytes from the start of the input. +A file lying wholly within the skip is not read. +The offsets written include the skipped bytes. +When the skip covers all of the input, the built-in formats write only +the final offset. +See +.B NOTES +for limits. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit. +.SH ENVIRONMENT +.B hexdump +reads no environment variables of its own. +For those that affect every busybox applet, see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An input file could not be opened, or there was an invalid option, +number, or format string, an unreadable +.B \-f +file, or a failed seek. +.PP +An input file that cannot be opened is skipped, and the others are still +dumped. +The other errors stop +.B hexdump +at once. +.SH EXAMPLES +Dump a file in hexadecimal and ASCII: +.PP +.RS 4 +.EX +$ hd program.exe +.EE +.RE +.PP +Show a file as 2-byte values, whose bytes appear swapped because they +are read little-endian: +.PP +.RS 4 +.EX +$ hexdump hello.txt +0000000 6548 6c6c 2c6f 7720 726f 646c 0a21 +000000e +.EE +.RE +.PP +Show 64 bytes starting at offset 0x200: +.PP +.RS 4 +.EX +$ hd \-s 0x200 \-n 64 program.exe +.EE +.RE +.PP +Print the 4-byte value at offset 0x3c of an EXE, the offset of its PE +header: +.PP +.RS 4 +.EX +$ hexdump \-s 0x3c \-n 4 \-e \(aq/4 "%x\en"\(aq xxd.exe +80 +.EE +.RE +.PP +Print a file as unsigned 2-byte integers, one per line, with decimal +offsets: +.PP +.RS 4 +.EX +$ hexdump \-v \-e \(aq"%_ad: " /2 "%u\en"\(aq samples.raw +.EE +.RE +.PP +Write a file as a list of C hexadecimal constants: +.PP +.RS 4 +.EX +$ hexdump \-v \-e \(aq/1 "0x%02x, "\(aq key.bin +.EE +.RE +.PP +Print 16 random bytes as 32 hexadecimal digits: +.PP +.RS 4 +.EX +$ hexdump \-n 16 \-e \(aq16/1 "%02x" "\en"\(aq /dev/urandom +.EE +.RE +.SH NOTES +Differences from the util-linux +.BR hexdump : +.IP \(bu 2 +Options must come before the file operands. +.IP \(bu 2 +There are no long options, and no +.B \-L +or +.BR \-X . +.IP \(bu 2 +Each quoted format writes only its first conversion. +.IP \(bu 2 +.B %d +and +.B %i +need a byte count. +.PP +.B \-s +seeks with a 32-bit offset. +A skip that ends 2 GiB or more into a file either fails with +.B Invalid argument +or lands at the wrong position, though the offsets written assume the +right one. +On a pipe, the seek does nothing, so the dump starts at the beginning of +the input while its offsets include the skip. +When the bytes left to skip equal the size of a file exactly, that file +is dumped from its start instead of skipped, with wrong offsets. +.PP +Floating-point conversions use the Microsoft C runtime: exponents have +three digits, as in +.BR 1.000000e+000 , +and infinities and NaNs are written in forms such as +.B 1.#INF00 +and +.BR 1.#QNAN0 . +.PP +Input files are read in binary mode, and output lines end with LF, not +CRLF. +The busybox device names, such as +.I /dev/zero +and +.IR /dev/urandom , +work as input files; see +.BR busybox (1). +A file whose full path reaches +.BR MAX_PATH , +260 characters, cannot be opened. +.SH SEE ALSO +.BR busybox (1), +.BR od (1), +.BR xxd (1) diff --git a/man/man1/httpd.1 b/man/man1/httpd.1 new file mode 100644 index 0000000..b8cc6a3 --- /dev/null +++ b/man/man1/httpd.1 @@ -0,0 +1,966 @@ +.TH HTTPD 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +httpd \- serve files and CGI programs over HTTP +.SH SYNOPSIS +.B httpd +.RB [ \-fv ] +.RB [ \-c +.IR file ] +.RB [ \-h +.IR home ] +.RB [ \-p +.RI [ ip :] port ] +.RB [ \-r +.IR realm ] +.br +.B httpd \-d +.I string +.br +.B httpd \-e +.I string +.SH DESCRIPTION +.B httpd +is a small web server. +It answers HTTP requests with the files below a home directory and with +the output of CGI programs. +Each connection carries one request, and the server closes it after the +reply. +.PP +Without +.BR \-f , +.B httpd +starts a copy of itself detached from the console, and the original +exits at once. +The server changes to the home directory, which is the directory it was +started in unless +.B \-h +or an +.B H +line in the configuration file names another. +It listens on port 80 unless +.B \-p +names another. +.PP +With +.B \-d +or +.BR \-e , +.B httpd +does not serve. +It writes the decoded or encoded +.I string +to standard output, with no newline added, and exits. +These options are for shell scripts that handle CGI input. +.SS Requests +A request line is a method, a path that begins with a slash, and a +version that begins with +.BR HTTP/ , +separated by single spaces. +Anything else is answered with +.BR 400 , +except that an empty line, or none, closes the connection without a +reply. +The rest of the version is not checked, and replies are always +.BR HTTP/1.1 . +.PP +Methods are case-sensitive. +.B GET +and +.B HEAD +serve files, and both send the body. +.B POST +is accepted only for CGI programs, and a +.B POST +for a file is answered with +.BR 501 . +Any other method is answered with +.BR 400 . +.PP +The path is the text before the first +.BR ? . +It is percent-decoded, and then cleaned: repeated slashes and +.B .\& +components are removed, and a +.B ..\& +component removes the one before it. +A +.B ..\& +that would climb above the root, or a malformed escape, is answered with +.BR 400 , +and an escaped slash or NUL is answered with +.BR 404 . +The text after the first +.B ?\& +is the query string, which is never decoded. +The cleaned path names a file below the home directory; +.B NOTES +says what that does not guarantee. +.PP +A header line of 8192 bytes or more, or one with a control character +other than a tab, is answered with +.BR 400 . +Headers that total 32768 bytes or more are answered with +.BR 413 . +A client that sends nothing for 30 seconds while the headers are read is +answered with +.BR 408 , +and one that stops reading a reply for 60 seconds is dropped. +Headers other than those described here are ignored, except that CGI +programs receive them. +.SS Files +A path that names a directory, without a final slash, is answered with +.B 302 +and a +.B Location +of the decoded path with a slash added, keeping the query string. +A path with a final slash names the index file of the directory, +.I index.html +unless an +.B I +line says otherwise. +If that file does not exist but +.I cgi\-bin/index.cgi +is executable, that program runs in its place, and the requested path is +in its +.BR REQUEST_URI ; +otherwise the answer is +.BR 404 . +.B httpd +never makes a directory listing. +.PP +A file is sent with the headers +.BR Date , +.BR "Connection: close" , +.BR Content\-type , +.BR Accept\-Ranges , +.BR Last\-Modified , +.BR ETag , +and +.BR Content\-Length . +Dates are in GMT. +The +.B Content\-type +comes from the suffix of the path, the text from its last dot. +Suffixes match case-sensitively, first against this built-in table and +then against the type lines of the configuration file, which win. +A file with no known suffix is sent without a +.B Content\-type +header. +.PP +.RS 4 +.EX +\&.txt .h .c .cc .cpp text/plain +\&.htm .html text/html +\&.jpg .jpeg image/jpeg +\&.gif image/gif +\&.png image/png +\&.svg image/svg+xml +\&.css text/css +\&.js application/javascript +\&.wav audio/wav +\&.avi video/x\-msvideo +\&.qt .mov video/quicktime +\&.mpe .mpeg video/mpeg +\&.mid .midi audio/midi +\&.mp3 audio/mpeg +.EE +.RE +.PP +A +.B Range +header of the form +.BI bytes= first \- +or +.BI bytes= first \- last +is answered with +.B 206 +and the bytes asked for, with +.I last +cut back to the end of the file. +A +.I last +of 0 also means the end of the file. +Any other form, such as a suffix range like +.BR bytes=\-500 , +is ignored, and the whole file is sent. +.PP +An +.B If\-None\-Match +header that contains the file's +.B ETag +is answered with +.BR 304 . +The +.B ETag +is the modification time in seconds and the size, each in hexadecimal and +joined by a hyphen, in double quotes. +.B If\-Modified\-Since +is ignored. +.PP +If the +.B Accept\-Encoding +header contains +.B gzip +and a file named like the requested one with +.I .gz +added exists, it is sent instead, with +.B Content\-Encoding: gzip +and its own size, and without range support. +The +.B Content\-type +is still that of the requested name, and the uncompressed file need not +exist. +.PP +An error answer carries a short HTML page, built in or named by an +.B E +line, and a +.B 302 +or +.B 304 +answer has no body. +A file that cannot be opened is +.BR 404 . +A request for a file named +.IR httpd.conf , +in any directory, is answered with +.BR 403 . +.SS CGI programs +A path that begins with +.I cgi\-bin/ +runs a program. +The file must exist and be executable to Windows: it has one of the +suffixes +.BR .com , +.BR .exe , +.BR .sh , +.BR .bat , +or +.BR .cmd , +or it begins with +.B #!\& +or is a Windows program. +A file that is not executable is sent as an ordinary file by +.B GET +and +.BR HEAD . +A directory is answered with +.BR 403 , +and a program that is not there or cannot be started with +.BR 404 . +Directories below +.I cgi\-bin +are allowed, and the path components after the program's name arrive in +.BR PATH_INFO . +.PP +A script runs under the interpreter named on its +.B #!\& +line, found as described in +.BR busybox (1), +so +.B #!/bin/sh +runs the busybox shell. +Only an interpreter in +.IR /bin , +.IR /usr/bin , +.IR /sbin , +or +.I /usr/sbin +can be an applet or be found in +.BR PATH : +.B #!/usr/local/bin/perl +fails unless that file exists. +A file whose name ends in +.B .sh +and that has no +.B #!\& +line runs under +.BR sh . +A +.BI *. ext : interpreter +line in the configuration file makes any file with that suffix outside +.I cgi\-bin +a CGI program as well, run by the interpreter. +.PP +The program starts with its own directory as the current directory. +Its standard input receives the body of a +.BR POST , +and its standard output is the reply. +Its standard error is that of the server, never the client. +It inherits the environment of +.BR httpd , +with the variables listed under +.B ENVIRONMENT +added. +A +.B HEAD +request runs the program too, and all of its output is sent. +.PP +The program writes its headers, a blank line, and the body. +.B httpd +adds nothing to them but the status line, chosen from the first bytes of +the output. +If the output begins with +.BR Status: , +that header becomes the status line, as in +.BR "Status: 404 Gone" . +If it begins with +.BR Location: , +the status is +.BR 302 . +If it begins with +.BR HTTP/1.1 , +the output is sent as it is. +Otherwise the status is +.BR 200 . +These are recognized only at the start of the output and spelled exactly +so. +The program must write its own +.B Content\-Type +and the blank line. +.SS Configuration file +At startup, and again for each connection, +.B httpd +reads +.I /etc/httpd.conf +on the system drive, or the file named by +.BR \-c . +If it cannot open +.IR /etc/httpd.conf , +it reads +.I httpd.conf +in the home directory instead. +A +.B \-c +file that cannot be opened is an error. +Changes take effect with the next connection. +.PP +Each line is one directive. +Spaces and tabs are removed from the whole line, including inside paths +and passwords. +A +.B # +starts a comment that runs to the end of the line. +Blank lines are ignored. +A line may end in LF or CR LF. +A line longer than 159 characters is read as several lines. +A line that is not a directive is reported on standard error as +.B config error +and skipped. +.PP +The directives are: +.TP +\fBA:\fR\fIaddress\fR +Allow clients with this IPv4 address. +.I address +is one of: +.RS +.IP \(bu 2 +.B * +for every address. +An +.B A:* +line has no effect. +.IP \(bu 2 +Four numbers with dots, such as +.BR 10.0.0.7 , +for one host. +.IP \(bu 2 +One to three numbers, such as +.B 172.20.\& +or +.BR 10.10 , +for every address that begins with them. +.IP \(bu 2 +.IB address / bits +or +.IB address / mask +for a network, where +.I mask +has four numbers with dots. +.I address +must have no bits set outside the mask, or the line never matches. +.RE +.IP +A line whose address cannot be read denies every client, and one whose +mask cannot be read has no effect. +An IPv6 client is checked as the address 0.0.0.0, unless it is an +IPv4-mapped address, which is checked as its IPv4 address. +.TP +\fBD:\fR\fIaddress\fR +Deny clients, with the same addresses as +.BR A: . +.B D:* +denies every client that no rule matched. +A client that matches any +.B D +rule is denied even if it also matches an +.B A +rule. +Only the first character of the +.BR A , +.BR D , +.BR H , +and +.B I +directives counts, and it may be lower case, so +.B allow: +and +.B deny: +work. +.TP +\fBE\fInnn\fB:\fIfile\fR +Send +.I file +as the body of every answer with status +.IR nnn , +instead of the built-in page. +.I file +is relative to the home directory, or absolute with a drive letter. +A leading slash is the root of the current drive, not of the home +directory. +The answer carries no +.B Content\-Length +and is +.BR text/html . +A status that +.B httpd +never sends is ignored. +.TP +\fBH:\fR\fIdirectory\fR +Use +.I directory +as the home directory, in place of +.BR \-h . +Each connection starts in the new home directory and reads the file +again, so +.I directory +and a +.B \-c +file must be absolute paths, or every connection is closed without a +reply. +.TP +\fBI:\fR\fIfile\fR +Use +.I file +as the index file of directories, in place of +.IR index.html . +.TP +\fB.\fIext\fB:\fImime\-type\fR +Send files whose suffix is exactly +.BI . ext +with this +.BR Content\-type . +Later lines win over earlier ones. +.TP +\fB*.\fIext\fB:\fIinterpreter\fR +Run files with this suffix as CGI programs, by +.IR interpreter , +which receives the file name as its argument. +The interpreter is started by exactly the name given: nothing adds +.I .exe +or searches +.BR PATH , +so write +.I C:/tools/php/php\-cgi.exe +rather than +.BR php . +Files in +.I cgi\-bin +ignore these lines. +.TP +\fB/\fIpath\fB:\fIuser\fB:\fIpassword\fR +Require this user and password, sent with Basic authentication, for +.I path +and everything below it. +A path matches whole components and ignores case. +Several lines with the same path allow several users. +When lines with different paths match, only those with the longest path +count. +If no line matches a request's path, no password is required. +The password is plain text, compared as is, and can contain colons. +A path of +.B / +protects the whole server. +Without a valid password the answer is +.BR 401 . +.PP +The +.B H +and +.B E +lines are valid only in the first file that is read: the +.B \-c +file, or +.I /etc/httpd.conf +on the system drive. +In the fallback +.I httpd.conf +of the home directory, and in the files below, they are errors. +.PP +A file named +.I httpd.conf +in a directory below the home directory is read for each request that +reaches that directory or one below it, and its lines are merged with +the others. +An index line replaces the index file. +Type, interpreter, and password lines are added to the existing ones, +with the paths of password lines relative to that directory. +Its +.B A +and +.B D +lines replace the IP rules instead, and the client is checked against +them again; the main file's rules have already been applied, so a +subdirectory can only narrow access. +.SS Logging +Messages go to standard error, with the prefix +.BR httpd: . +Configuration errors are always reported. +With +.BR \-v , +messages about a connection begin with the client's address and port +instead, as in +.BR "127.0.0.1:61085: response:200" . +.SH OPTIONS +Options may be grouped, as in +.BR \-fvv , +and an argument may be attached, as in +.BR \-p8080 , +or be the next argument. +.B \-\- +ends the options. +Operands are ignored. +.TP +.B \-f +Run in the foreground, and serve until the process is killed. +Without it, +.B httpd +detaches, and cannot report errors or log; see +.BR NOTES . +.TP +.B \-v +Log to standard error. +Repeat it for more. +One +.B \-v +logs the status of each reply, two also log each request's method and +path without the query string, and three also log each connection as it +opens and closes. +.TP +\fB\-p\fR [\fIip\fR:]\fIport\fR +Listen on +.I port +(1 to 65535), on the address +.I ip +if one is given. +A port alone listens on all interfaces over IPv4 and IPv6. +A number outside that range is read as an IPv4 address instead, so +.B \-p\ 0 +listens on port 80 of every IPv4 interface. +An +.I ip +is a numeric IPv4 address, or an IPv6 address in brackets, and limits the +server to that address. +Host names are not looked up. +Without a port the port is 80. +The default is port 80 on all interfaces. +.TP +.BI "\-r " realm +Name the realm in the password prompt. +The default is +.BR "Web Server Authentication" . +.TP +.BI "\-h " home +Use +.I home +as the home directory. +The default is the current directory. +A relative +.I home +is used as given, which leaves +.B SCRIPT_FILENAME +unset. +An +.B H +line in the configuration file overrides it. +.TP +.BI "\-c " file +Read the configuration from +.I file +instead of +.IR /etc/httpd.conf . +A relative +.I file +is relative to the home directory, since +.B httpd +changes to it first. +.TP +.BI "\-e " string +Write +.I string +to standard output with every byte that is not an ASCII letter or digit +replaced by +.BI &# n ;, +where +.I n +is the byte in decimal, so that the output is safe in an HTML page. +Non-ASCII characters become one such reference for each byte. +.TP +.BI "\-d " string +Write +.I string +to standard output with each +.BI % XX +escape replaced by its byte and each +.B + +by a space. +An escape that is not valid is left as it is. +.TP +.BI "\-I " fd +Internal. +.B httpd +uses it to start the process that serves one accepted connection, passing +the socket's descriptor, and, with a descriptor of 0, the process that +starts a CGI program. +The server's other options follow it. +It is not meant to be typed. +.SH ENVIRONMENT +.TP +.B PATH +Where to look for the interpreter named on the +.B #!\& +line of a CGI script, as described in +.BR busybox (1). +.TP +.B BB_SYSTEMROOT +A drive, such as +.BR D: , +to use instead of the system drive when looking for +.IR /etc/httpd.conf . +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in arguments are expanded when run from +.BR cmd.exe , +including the strings given to +.B \-d +and +.BR \-e . +A busybox process started with it unset sets it to +.B 0 +for its children, so the processes that the server starts for each +connection do not expand their arguments again. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output and messages written to a console are not converted from the +ANSI code page, and the console interprets the bytes in its own code +page. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.PP +For each CGI program, +.B httpd +adds these to the environment it inherits: +.TP +.B AUTH_TYPE +.B Basic +when +.B REMOTE_USER +is set. +.TP +.B CONTENT_LENGTH +The length of a +.BR POST 's +body, when the request gave a positive +.BR Content\-Length . +.TP +.B CONTENT_TYPE +The request's +.B Content\-Type +header, when it has one. +.TP +.B GATEWAY_INTERFACE +.BR CGI/1.1 . +.TP +\fBHTTP_\fR\fINAME\fR +Each other request header, with its name in capitals and every character +that is not a letter or digit replaced by an underscore, as in +.BR HTTP_USER_AGENT . +A Basic +.B Authorization +header, and +.BR Range , +.BR Accept\-Encoding , +.BR If\-None\-Match , +and a +.BR POST 's +.BR Content\-Length , +are not passed. +.TP +.B PATH_INFO +The path components after the program's name, with a leading slash, or +an empty string. +.TP +.B QUERY_STRING +The query string as the client sent it, or an empty string. +.TP +.B REMOTE_ADDR +The client's address. +An IPv6 address is in brackets, as is an IPv4 client of a server that +listens on both families. +.TP +.B REMOTE_USER +The user name, when the request matched a password line. +.TP +.B REQUEST_METHOD +.BR GET , +.BR HEAD , +or +.BR POST . +.TP +.B REQUEST_URI +The decoded and cleaned path, followed by +.B ?\& +and the query string if there was one. +.TP +.B SCRIPT_FILENAME +The home directory joined to +.BR SCRIPT_NAME , +set only when the home directory is not a relative path. +.TP +.B SCRIPT_NAME +The path of the program, without +.BR PATH_INFO . +For the directory index program it is +.IR /cgi\-bin/index.cgi . +.TP +.B SERVER_PROTOCOL +.BR HTTP/1.1 . +.TP +.B SERVER_SOFTWARE +.B busybox httpd/ +and the busybox version. +.PP +There is no +.BR SERVER_NAME , +.BR SERVER_PORT , +or +.BR REMOTE_PORT . +To have a +.B SERVER_NAME +in the programs, set it in the environment of +.BR httpd . +.SH EXIT STATUS +.TP +.B 0 +Success: the string of +.B \-d +or +.B \-e +was written, or the background server was started. +.TP +.B 1 +An invalid option, or a background server that cannot be started. +With +.BR \-f , +also a home directory that cannot be entered, a +.B \-c +file that cannot be opened, or an address that cannot be read or bound. +.PP +The foreground server runs until it is killed, unless it cannot start +the process for a connection, when it exits with status 0. +.SH EXAMPLES +Serve the directory +.I public +on the loopback interface, in the foreground, logging each request: +.PP +.RS 4 +.EX +$ httpd \-f \-vv \-p 127.0.0.1:8080 \-h public +.EE +.RE +.PP +Start a server in the background, and later stop every +.BR httpd : +.PP +.RS 4 +.EX +$ httpd \-p 127.0.0.1:8080 \-h public +$ pkill httpd +.EE +.RE +.PP +Allow only this machine and the 192.168.1 network, ask for a password +under +.IR /private , +and add a type, in the +.I httpd.conf +of the home directory: +.PP +.RS 4 +.EX +$ cat >public/httpd.conf < A:127.0.0.1 +> A:192.168.1. +> D:* +> /private:alice:secret +> .wasm:application/wasm +> EOF +.EE +.RE +.PP +Write a CGI program, and call it while a server from the first example +is running: +.PP +.RS 4 +.EX +$ mkdir public/cgi\-bin +$ cat >public/cgi\-bin/hello.cgi <<\(aqEOF\(aq +> #!/bin/sh +> echo "Content\-Type: text/plain" +> echo +> echo "Hello, $REMOTE_ADDR" +> EOF +$ wget \-qO \- http://127.0.0.1:8080/cgi\-bin/hello.cgi +Hello, 127.0.0.1 +.EE +.RE +.PP +Decode a value that came in a query string, and encode text for HTML: +.PP +.RS 4 +.EX +$ name=$(httpd \-d \(aqHello%2C+World%21\(aq) +$ echo "$name" +Hello, World! +$ httpd \-e \(aq&\(aq +<b>&</b> +.EE +.RE +.SH NOTES +Differences from busybox +.B httpd +on Unix: +.IP \(bu 2 +There are no +.BR \-i , +.BR \-M , +.BR \-K , +.BR \-u , +or +.BR \-m : +no inetd mode, connection limit, CGI time limit, change of user, or MD5 +passwords. +A CGI program, and a client sending one a +.B POST +body, are never timed out. +.IP \(bu 2 +Passwords are compared as plain text, so a +.B * +is an ordinary character, not a wildcard for system users or passwords. +.IP \(bu 2 +There are no +.B P +reverse proxy lines and no +.B REMOTE_PORT +variable. +.IP \(bu 2 +There is no reload on a signal, since every connection reads the +configuration. +.PP +The server process accepts connections and starts a new busybox process +for each, with +.BR \-I , +which reads the configuration and serves the request. +A CGI program is started through another busybox process. +Nothing limits how many connections are served at once. +.PP +In the background, standard input, output, and error of the server are +the null device. +Nothing is logged, and a failure such as a bad address or a missing +.B \-c +file is not reported: the starting process has already exited with status +0. +Use +.B \-f +to see them. +The listening socket allows address reuse, which on Windows lets a second +server bind a port that is in use. +.PP +A reply of +.B 206 +or +.B 304 +has the +.B Content\-type +.BR text/html , +whatever the file is. +The code means to pass other methods, such as +.BR PUT , +to CGI programs, but this version answers them with +.BR 400 . +The built-in +.B 408 +page says 60 seconds, but the limit is 30. +.PP +.B httpd +is not meant to face untrusted clients. +It keeps requests inside the home directory only by rejecting +.B ..\& +components between forward slashes. +A backslash, written raw or as +.BR %5C , +is also a separator to Windows, and a path that starts with a drive +letter, as in +.IR /C:/data/file.txt , +is absolute, so a client can read any file that the user running the +server can read. +The checks that compare the request path with a pattern see only forward +slashes: password lines, subdirectory configuration files, and the +.I cgi\-bin/ +prefix, which is also case-sensitive although Windows file names are not. +A request for +.I /adm\ehome.htm +is not asked for the password that +.I /adm/home.htm +needs, and +.I /CGI\-BIN/hello.cgi +sends the source of the program. +Windows also ignores a final dot in a directory name, a final dot or +space in a file name, and a +.B ::$DATA +suffix, which names the file's contents. +So +.I /adm./home.htm +skips the password, +.I /cgi\-bin./hello.cgi +sends the source, and +.I /httpd.conf.\& +sends the configuration file, passwords included. +Passwords cross the network in the clear, and there is no TLS. +.PP +The decoded bytes of a URL path are the file name in the ANSI code page, +which is UTF-8 on Windows 10 version 1903 and later. +On earlier versions it is the system code page, and a file whose name +has other characters cannot be served. +Windows file names are not case-sensitive, so +.I /A.TXT +finds +.IR a.txt . +The match of suffixes for +.B Content\-type +and of the +.I cgi\-bin/ +prefix are case-sensitive, and the match of +.I httpd.conf +and of password paths is not. +.SH SEE ALSO +.BR busybox (1), +.BR nc (1), +.BR pkill (1), +.BR sh (1), +.BR wget (1) diff --git a/man/man1/iconv.1 b/man/man1/iconv.1 new file mode 100644 index 0000000..49d35fb --- /dev/null +++ b/man/man1/iconv.1 @@ -0,0 +1,503 @@ +.TH ICONV 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +iconv \- convert text between character encodings +.SH SYNOPSIS +.B iconv +.RB [ \-c ] +.RB [ \-o +.IR outfile ] +.RB [ \-f +.IR fromcode ] +.RB [ \-t +.IR tocode ] +.RI [ file ...] +.br +.B iconv \-l +.SH DESCRIPTION +.B iconv +reads text in one character encoding, converts it to another, and writes +the result. +It is the busybox-w32 applet derived from win-iconv, and it does the work +with the Windows API, so the encodings it knows are the code pages that +Windows provides. +Each character is converted to UTF\-16 and then to the output encoding. +.PP +With no +.IR file , +or for a +.I file +named +.BR \- , +.B iconv +reads standard input. +It writes standard output, or with +.B \-o +a file. +Operands are converted in order, each on its own, so the byte order mark +and any other conversion state start afresh with each. +But every operand other than +.B \- +opens the first operand and not itself, so give a single +.IR file ; +see +.BR NOTES . +.PP +The input encoding +.I fromcode +and the output encoding +.I tocode +default to the ANSI code page, which is UTF\-8 on Windows 10 version 1903 +and later. +The locale plays no part in the conversion. +.SS Encoding names +A name is one of these, tried in this order: +.IP \(bu 2 +Empty, or +.BR char : +the ANSI code page. +.IP \(bu 2 +.BR wchar_t : +UTF\-16 little endian, with no byte order mark. +.IP \(bu 2 +A decimal Windows code page number, optionally preceded by +.B CP +or +.B XX +in any case, as in +.BR CP1252 , +.BR 437 , +or +.BR cp65001 . +Any text after the digits is ignored, so +.B CP850x +means 850. +The code page must be one that Windows reports as valid. +.IP \(bu 2 +An alias from the list that +.B \-l +prints, such as +.BR UTF\-8 , +.BR UTF\-16LE , +.BR ASCII , +.BR ISO\-8859\-1 , +.BR WINDOWS\-1252 , +.BR SJIS , +.BR EUC\-JP , +.BR GB18030 , +.BR BIG5 , +or +.BR KOI8\-R . +Case does not matter. +.PP +The names +.B char +and +.B wchar_t +must be lowercase. +Since the number test comes before the list, aliases in the list that +begin with +.B CP +are read as numbers, and five of them fail: +.BR CP367 , +.BR CP819 , +and +.B cp1025 +mean code pages 367, 819, and 1025 instead of 20127, 1252, and 21025, +and +.B CP\-IS +and +.B CP\-GR +mean code page 0. +A name that does not resolve, or whose code page Windows lacks, makes +.B iconv +print +.PP +.RS 4 +.EX +iconv: iconv_open error: Invalid argument +.EE +.RE +.PP +and exit. +.SS Name suffixes +A name may end in suffixes that begin with +.BR // , +such as +.BR ASCII//TRANSLIT . +They may be combined and are matched without regard to case. +An unknown suffix is ignored. +Only suffixes on +.I tocode +matter, except as noted for +.BR //NOCOMPAT . +.TP +.B //TRANSLIT +Convert a character that has no equivalent in the code page to its +nearest equivalent by the system's best-fit table, such as an accented +letter to its base letter, or else to the code page's default +character, usually +.BR ? , +instead of failing. +It has no effect on the UTF encodings, ISO\-2022\-JP, or EUC\-JP. +.TP +.B //IGNORE +Discard what cannot be converted, as +.B \-c +does. +.TP +.B //NOCOMPAT +Turn off a compatibility mapping. +By default, when the output is code page 932 (SJIS), 51932 (EUC\-JP), or +50220 to 50222 (ISO\-2022\-JP), nine characters are first replaced by +their CP932 equivalents: +U+00A5 becomes U+005C, U+203E becomes U+007E, U+2014 becomes U+2015, +U+301C becomes U+FF5E, U+2016 becomes U+2225, U+2212 becomes U+FF0D, and +U+00A2, U+00A3, and U+00AC become U+FFE0, U+FFE1, and U+FFE2. +Code page 20932 has its own table, which also applies to its input, +so this is the one suffix that matters on +.IR fromcode . +.SS Byte order marks +.BR UTF\-16 , +.BR UTF16 , +.BR UCS\-2 , +.BR UCS2 , +and +.B UCS\-2\-INTERNAL +mean UTF\-16 little endian with a byte order mark (BOM). +On input, a leading BOM of +.B FF FE +or +.B FE FF +is removed and sets the byte order, which is little endian without one. +On output, +.B FF FE +is written before the first character, so empty input gives empty +output. +.BR UTF\-32 , +.BR UTF32 , +.BR UCS\-4 , +and +.B UCS4 +do the same with 32-bit units and the BOM +.BR "FF FE 00 00" . +.PP +Names that give a byte order, such as +.BR UTF\-16LE , +.BR UTF\-16BE , +.BR UTF\-32LE , +and +.BR UTF\-32BE , +neither write nor remove a BOM, so a BOM in the input becomes the +character U+FEFF. +.B UTF\-8 +neither writes nor removes one. +.SS Errors +Input is rejected if it is invalid for +.IR fromcode , +such as an unpaired UTF\-16 surrogate, a UTF\-32 value above 10FFFF, or a +byte above 7F in ASCII. +Output is rejected if +.I tocode +cannot represent a character. +On the first such failure +.B iconv +writes what it has converted so far, prints +.PP +.RS 4 +.EX +iconv: conversion error: \fIreason\fR +.EE +.RE +.PP +on standard error, and exits with status 1. +The message gives no position. +.I reason +is +.B Illegal byte sequence +for the cases above, and +.B Invalid argument +when the input ends inside a character or is invalid GB18030. +.B \-c +and +.B //IGNORE +turn these failures into discards. +.SH OPTIONS +Options may be grouped, as in +.BR \-cfUTF\-8 , +and an option's argument may be attached or be the next argument. +There are no long options. +Options may follow operands, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +Of an option given more than once, the last counts. +.TP +.B \-l +Print the name of each encoding the program knows, one per line, and +exit, ignoring any other options and operands. +The names are in the order of the program's table and not sorted, and +some appear more than once. +The list has neither the numeric forms nor +.B char +and +.BR wchar_t , +and it includes names that do not work: the five +.B CP +names described above, the code pages that convert nothing (see +.BR NOTES ), +and code pages that not every system has, such as +.B CP154 +and +.BR CP1133 . +.TP +.B \-c +Discard characters that +.I tocode +cannot represent, and bytes that are invalid in +.IR fromcode , +without a message. +An invalid sequence is discarded one byte at a time. +This is the same as adding +.B //IGNORE +to +.IR tocode . +.TP +.BI "\-o " outfile +Write to +.I outfile +instead of standard output. +The output goes to a temporary file in the same directory, named +.I outfile +with six characters appended, which replaces +.I outfile +when every operand has been converted, even if +.I outfile +is read-only. +So +.I outfile +may also be an input. +.TP +.BI "\-f " fromcode +Read text in the encoding +.IR fromcode . +The default is the ANSI code page. +.TP +.BI "\-t " tocode +Write text in the encoding +.IR tocode . +The default is the ANSI code page. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit with status 0. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +When set, the first operand ends the options, so that later arguments +such as +.B \-t +are file names. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when +.B iconv +starts, even in quoted operands, as needed when run from +.BR cmd.exe . +A pattern that matches nothing is left as it is. +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, or +.B \-l +or +.BR \-\-help . +.TP +.B 1 +An invalid option or a missing option argument, an unknown encoding, a +file that could not be opened or replaced, or a conversion error. +.SH EXAMPLES +Convert a Windows\-1252 file to UTF\-8: +.PP +.RS 4 +.EX +$ iconv \-f CP1252 \-t UTF\-8 old.txt >new.txt +.EE +.RE +.PP +Convert a file in place: +.PP +.RS 4 +.EX +$ iconv \-f LATIN1 \-t UTF\-8 \-o names.txt names.txt +.EE +.RE +.PP +Convert UTF\-16 text, with or without a BOM, to UTF\-8: +.PP +.RS 4 +.EX +$ iconv \-f UTF\-16 \-t UTF\-8 log.txt >log\-utf8.txt +.EE +.RE +.PP +Write UTF\-16 with a BOM, for programs that expect one: +.PP +.RS 4 +.EX +$ iconv \-f UTF\-8 \-t UTF\-16 notes.txt >notes\-utf16.txt +.EE +.RE +.PP +Discard the characters that ASCII cannot hold: +.PP +.RS 4 +.EX +$ iconv \-c \-f UTF\-8 \-t ASCII names.txt +.EE +.RE +.PP +Approximate them instead: +.PP +.RS 4 +.EX +$ printf \(aqcaf\e303\e251\en\(aq | iconv \-f UTF\-8 \-t ASCII//TRANSLIT +cafe +.EE +.RE +.PP +List the ISO 8859 encodings: +.PP +.RS 4 +.EX +$ iconv \-l | grep \-i 8859 +.EE +.RE +.SH NOTES +Differences from GNU iconv: +.IP \(bu 2 +The encodings are Windows code pages, not libiconv's converters. +ISO\-2022\-JP and EUC\-JP work, through MLang. +Other code pages whose characters can exceed two bytes, apart from +UTF\-8 and GB18030, are accepted but convert nothing: ISO\-2022\-KR +(50225), HZ\-GB\-2312 (52936), UTF\-7 (65000, which has no alias), the +ISCII pages (57002 to 57011), and others. +Without +.BR \-c , +output in them fails at the first character, and input fails or hangs +as described below. +With +.BR \-c , +everything is discarded. +.IP \(bu 2 +There are no long options, no +.BR \-s , +and no +.BR \-\-verbose . +.IP \(bu 2 +The defaults for +.B \-f +and +.B \-t +are the ANSI code page, not the locale's. +.IP \(bu 2 +.B //TRANSLIT +is Windows' best-fit mapping, not libiconv's transliteration. +.IP \(bu 2 +Conversion errors give no position. +.PP +Only the first operand can be a file. +An operand other than +.B \- +is never opened by its own name: the first operand is opened instead. +So +.B iconv a b +converts +.I a +twice and never opens +.IR b , +and +.B iconv \- a +looks for a file named +.BR \- . +Run +.B iconv +once for each file. +.PP +Input is converted in blocks of 512 bytes. +Normally a character that straddles a block boundary is carried over to +the next block, but with +.B \-c +or +.B //IGNORE +it is not: the part at the end of the block is discarded as invalid, and +so is the rest of the character at the start of the next block. +So +.B \-c +corrupts any multibyte character that falls across a boundary. +.PP +Without +.BR \-c , +some input makes +.B iconv +loop forever instead of failing with +.BR "Invalid argument" : +input of 512 bytes or more in a code page that converts nothing, and +GB18030 input with an invalid byte sequence followed by 511 or more +bytes. +.PP +With +.BR \-o , +the temporary file stays behind after any failure, including a bad +encoding name or an input that cannot be opened, and +.I outfile +is left as it was. +If +.I outfile +is a directory, the command fails with +.BR "Is a directory" . +.PP +Standard input, standard output, and files are read and written in +binary mode, so CR LF line endings and Ctrl-Z characters are ordinary +characters to convert. +.B iconv +does not change line endings. +Convert UTF\-16 text to an ASCII-compatible encoding before changing its +line endings with +.BR dos2unix (1). +.PP +File names may use drive letters and backslashes. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +A directory operand fails with +.BR "Permission denied" . +.PP +When standard output is a console, the output is treated as text in the +ANSI code page and converted for display, so only output in that +encoding is readable there. +Each block of up to 512 output bytes is also cut short at its first NUL +byte, as found in UTF\-16 output. +Write to a file or a pipe for any other encoding. +.SH SEE ALSO +.BR busybox (1), +.BR dos2unix (1), +.BR od (1), +.BR xxd (1) diff --git a/man/man1/id.1 b/man/man1/id.1 new file mode 100644 index 0000000..f55dd8f --- /dev/null +++ b/man/man1/id.1 @@ -0,0 +1,259 @@ +.TH ID 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +id \- print the user and group identity +.SH SYNOPSIS +.B id +.RB { \-u | \-g | \-G } +.RB [ \-nr ] +.RI [ user ] +.br +.B id +.RI [ user ] +.SH DESCRIPTION +.B id +prints the user id and group id of the current user, or of +.I user +when one is given. +Without options it prints the user id, the group id, and the groups, +each with its name, and with +.BR \-u , +.BR \-g , +or +.B \-G +only the id that option selects. +.PP +Windows has no Unix user and group ids, so busybox supplies fixed ones: +.IP \(bu 2 +The current user is user 4095 in group 4095, whoever the account is. +.IP \(bu 2 +A process that is elevated and has the Administrators group enabled is +instead user 0 in group 0, both named +.BR root . +.IP \(bu 2 +There are no supplementary groups, and no difference between real and +effective ids. +.PP +The user's name is the one the Windows function +.B GetUserName +returns, without a domain, with each space replaced by an underscore. +The group has the same name. +.PP +.I user +is a name, never a number. +Only two names are known: the current user's name, spelled as above, +which is user 4095 even in an elevated process, and +.BR root , +which is user 0. +The current user's name must match exactly, case included. +Any other name fails. +.B id +takes at most one +.IR user . +.SS Output +Without options, +.B id +prints one line: +.PP +.RS 4 +.EX +uid=4095(name) gid=4095(name) groups=4095(name) +.EE +.RE +.PP +A name that is not known is left out of this line, with its parentheses. +With +.BR \-u , +.BR \-g , +or +.BR \-G , +the line holds only the id, as a number or, with +.BR \-n , +as a name. +.SH OPTIONS +Options may be grouped, as in +.BR \-rGn , +and may follow +.IR user . +.B \-\- +ends the options. +At most one of +.BR \-u , +.BR \-g , +and +.B \-G +is allowed, and +.B \-n +and +.B \-r +are allowed only with one of them. +Apart from +.BR \-\-help , +there are no long options. +.TP +.B \-u +Print only the user id. +.TP +.B \-g +Print only the group id. +.TP +.B \-G +Print the ids of all the groups, separated by spaces. +There is only one, so the output is that of +.BR \-g . +.TP +.B \-n +Print names instead of numbers. +If the name is not known, print the number, report the error, and exit +with status 1. +.TP +.B \-r +Print the real id instead of the effective id. +Windows makes no difference, so it changes nothing. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +The C library's option parser reads it. +When it is set, even to an empty value, options are recognized only +before the first operand. +So +.B id root \-u +is then an error, since +.B \-u +is a second operand. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An error: an invalid command line, with a usage message on standard +error, an unknown +.IR user , +a name that is not known for an id printed as a name, or a failure to +write standard output. +.PP +An unknown +.I user +is reported on standard error, as in +.PP +.RS 4 +.EX +$ id bob +id: unknown user bob +.EE +.RE +.PP +An id that +.B \-n +prints as a name, but has none, is printed as a number instead, and +.B id: unknown ID +.I number +goes to standard error. +This happens only when Windows does not supply the user name. +.SH EXAMPLES +Show the identity of the current user: +.PP +.RS 4 +.EX +$ id +uid=4095(alice) gid=4095(alice) groups=4095(alice) +.EE +.RE +.PP +In an elevated process, such as a shell started by +.BR su : +.PP +.RS 4 +.EX +$ id +uid=0(root) gid=0(root) groups=0(root) +.EE +.RE +.PP +Do something only when elevated: +.PP +.RS 4 +.EX +$ [ "$(id \-u)" = 0 ] && echo elevated +.EE +.RE +.PP +Print the name of the current user: +.PP +.RS 4 +.EX +$ id \-un +alice +.EE +.RE +.SH NOTES +All users get the same numbers, so +.B id +does not tell users apart. +It does not report Windows security identifiers or group memberships. +The Administrators group only decides whether the process is +.BR root . +A command started by +.BR drop , +.BR cdrop , +or +.B pdrop +runs with reduced privileges and is not +.BR root , +even from an elevated process. +.PP +.B whoami +prints the same name as +.BR "id \-un" , +and +.B groups +prints what +.B id \-Gn +prints. +.B logname +prints the user's name even when elevated. +The name does not come from +.BR USER , +.BR USERNAME , +or +.BR LOGNAME . +.PP +Differences from GNU +.BR id : +.IP \(bu 2 +There is no +.BR \-a , +.BR \-z , +or +.BR \-Z , +and no long option other than +.BR \-\-help . +.IP \(bu 2 +The operand is one name, never a numeric id. +.PP +The user name is read in the ANSI code page, which is UTF-8 on Windows +10 version 1903 and later. +When standard output is a console, the output is converted from that +code page for display. +Output lines end with LF, not CRLF. +.SH SEE ALSO +.BR busybox (1), +.BR groups (1), +.BR logname (1), +.BR su (1), +.BR whoami (1) diff --git a/man/man1/inotifyd.1 b/man/man1/inotifyd.1 new file mode 100644 index 0000000..f03077f --- /dev/null +++ b/man/man1/inotifyd.1 @@ -0,0 +1,389 @@ +.TH INOTIFYD 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +inotifyd \- run a program when the contents of a directory change +.SH SYNOPSIS +.B inotifyd +.I prog +.IR dir [\fB:\fImask\fR]... +.SH DESCRIPTION +.B inotifyd +watches directories for changes. +When an entry in a watched directory changes in a way that the +directory's mask selects, it runs +.I prog +to report the change, and waits for +.I prog +to exit. +It runs until every watched directory has been deleted. +.PP +The name comes from the Linux inotify interface, but this +.B inotifyd +is a Windows implementation and differs from the Linux one; see +.BR NOTES . +It watches only directories, and only their direct entries, not the +contents of their subdirectories. +.SS Operands +.I prog +is the command to run for each change. +It is a single command name or path, not split into words or run by a +shell, so it cannot carry arguments of its own. +A +.I prog +of +.B \- +runs nothing and prints each change instead; see +.BR Output . +.PP +Each +.I dir +is an existing directory to watch, optionally followed by a colon and a +.IR mask . +A mask is a string of the event letters listed under +.BR Events , +in any order and with repeats allowed. +It selects the events reported for that directory, and with no mask all +of them are. +Other characters in a mask are ignored. +A mask with no event letter, or with only +.BR x , +is an error. +.PP +The mask follows the last colon in the operand, except that a colon in +the second position is a drive letter's. +Both +.B C:/work +and +.B C:/work:cn +are accepted, and the second has the mask +.BR cn . +A directory named by a single character cannot take a mask, because +.B d:c +is a path on drive D. +Write +.B ./d:c +instead. +.SS Running prog +.I prog +is run as +.PP +.RS 4 +.EX +\fIprog event dir\fR [\fIname\fR] +.EE +.RE +.PP +once for each event, with these arguments: +.TP +.I event +A letter that says what happened, from the list under +.BR Events . +.TP +.I dir +The operand as given, without the mask. +It is not made absolute or otherwise changed, so a relative +.I dir +is relative to the working directory of +.BR inotifyd , +which +.I prog +also inherits. +.TP +.I name +The name of the entry that changed, without a directory part. +It is omitted when there is none. +.PP +.I prog +is found as for any command that busybox runs: an applet, a program in +.BR PATH , +a file with a +.B #!\& +line, or a +.B .sh +file; see +.B Running commands +in +.BR busybox (1). +Its standard input, standard output, standard error, and working +directory are those of +.BR inotifyd . +Its exit status is ignored. +If it cannot be run, nothing is printed and +.B inotifyd +carries on. +.PP +.B inotifyd +waits for each +.I prog +to exit before it looks at the next event. +Changes made in the meantime are queued, within the limit described in +.BR NOTES . +.SS Events +Each event is one of these letters. +One action can cause several events: creating and writing a file causes +an +.B n +event and then a +.B c +event, and a rename causes an +.B m +event and then a +.B y +event. +.TP +.B c +An entry was modified: its attributes, size, last write time, last +access time, creation time, or security descriptor changed. +.TP +.B d +An entry was deleted, or was moved out of the directory to another one. +.TP +.B m +An entry was renamed within the directory. +.I name +is the old name. +.TP +.B n +An entry was created, or was moved into the directory from another one. +.TP +.B x +The directory can no longer be watched, usually because it was deleted. +This ends the watch. +There is no +.IR name . +An +.B x +event is also reported when changes were lost, and that does not end the +watch; see +.BR NOTES . +.TP +.B y +An entry was renamed within the directory. +.I name +is the new name. +.SS Output +With +.B \- +as +.IR prog , +.B inotifyd +writes each event to standard output as a line of fields separated by +tabs: the +.IR event , +the +.IR dir , +and the +.IR name , +which is left out, with its tab, when there is none. +Standard output is flushed after each line, so a pipe sees the events +as they happen. +.SH OPTIONS +.B inotifyd +takes no options. +Every argument is an operand, including one that begins with a dash, and +.B \-\- +has no special meaning. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when busybox starts, as needed +when run from +.BR cmd.exe . +A pattern that matches nothing is left as it is, and a +.I dir +that is such a pattern is then not a directory. +When the variable is unset, busybox sets it to +.B 0 +for the programs it starts, such as +.IR prog , +so that they do not expand their arguments again. +.TP +.B BB_OVERRIDE_APPLETS +Applets that busybox should not run when +.I prog +names them, so that a program in +.B PATH +runs instead; see +.BR busybox (1). +.TP +.B PATH +Where a +.I prog +with no directory part is looked up; see +.BR busybox (1). +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every watched directory was deleted, or the first argument was +.BR \-\-help . +.TP +.B 1 +Fewer than two operands, with a usage message on standard error; a mask +that selects no event; a +.I dir +that is not an existing directory; a directory that cannot be opened for +watching; or a failure while waiting for changes. +.PP +These errors are reported on standard error as +.PP +.RS 4 +.EX +inotifyd: \fIdir\fR: invalid mask +inotifyd: \fIdir\fR: not a directory +inotifyd: add watch (\fIdir\fR) failed: \fIreason\fR +inotifyd: watch failed: \fIreason\fR +.EE +.RE +.PP +The first of these is followed by an empty line. +The last is reported when waiting for changes fails, as it does at once +when there are more than 64 directories. +.PP +Otherwise +.B inotifyd +runs until it is interrupted, such as by Ctrl+C. +.SH EXAMPLES +Print the changes to a directory as they happen. +Another console created +.I work/a.txt +and wrote to it, renamed it to +.IR b.txt , +deleted it, and then deleted +.IR work , +which ended +.BR inotifyd : +.PP +.RS 4 +.EX +$ inotifyd \- work +n work a.txt +c work a.txt +m work a.txt +y work b.txt +d work b.txt +x work +.EE +.RE +.PP +Run +.B make +when a C source or header file in +.I src +is created, renamed to, or modified. +The script ignores other names: +.PP +.RS 4 +.EX +$ cat rebuild +#!/bin/sh +case $3 in +*.c|*.h) make ;; +esac +$ inotifyd ./rebuild src:cny +.EE +.RE +.PP +Print only new entries in one directory, and only deletions in another, +using a drive letter in the first: +.PP +.RS 4 +.EX +$ inotifyd \- C:/spool:n archive:d +.EE +.RE +.SH NOTES +This +.B inotifyd +is built on the Windows function +.BR ReadDirectoryChangesW . +Differences from the Linux +.BR inotifyd : +.IP \(bu 2 +Only directories can be watched, not files, and a watch does not extend +into subdirectories. +.IP \(bu 2 +Only the events +.BR c , +.BR d , +.BR m , +.BR n , +.BR x , +and +.B y +exist. +The Linux events +.BR a , +.BR e , +.BR w , +.BR 0 , +.BR r , +.BR D , +.BR M , +.BR u , +and +.B o +are ignored in a mask, and nothing is reported when a watched directory +is itself renamed. +.IP \(bu 2 +.I prog +gets one event letter per run, never several together. +.PP +A rename within a directory is an +.B m +event and a +.B y +event. +A move between two directories is a +.B d +event in the one it left and an +.B n +event in the one it entered, even when both are watched. +.PP +Windows holds the changes that occur while +.I prog +runs in a buffer of 2048 bytes for each directory. +That is room for about 100 changes to entries with 4-character names, +and fewer with longer names. +When more changes arrive, all of those queued are discarded, and a +single +.B x +event with no name is reported in place of them, unless the mask leaves +out +.BR x . +Watching continues. +.PP +A deleted directory ends its watch, whether or not its mask reports +.BR x , +and a new directory of the same name is not watched. +.B inotifyd +keeps a deleted directory open until it exits, so on older versions of +Windows its name stays in use until then. +A directory can be deleted or renamed while it is watched, and a +renamed one is still watched and still reported under the +name given on the command line. +At most 64 directories can be watched at once. +.PP +Entry names are converted to bytes with the ANSI code page, which is +UTF-8 on Windows 10 version 1903 and later because busybox declares it +in its manifest. +A name that takes more than 260 bytes in that encoding is reported as if +it had no name, and one of exactly 260 bytes is followed by stray bytes. +.PP +A +.I dir +may use a drive letter and either kind of slash. +One that is a symbolic link or a junction is rejected as not a directory +unless it ends in a slash. +.SH SEE ALSO +.BR busybox (1), +.BR sh (1) diff --git a/man/man1/install.1 b/man/man1/install.1 new file mode 100644 index 0000000..c935690 --- /dev/null +++ b/man/man1/install.1 @@ -0,0 +1,488 @@ +.TH INSTALL 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +install \- copy files and set their mode, or create directories +.SH SYNOPSIS +.B install +.RI [ options ] +.I source dest +.br +.B install +.RI [ options ] +.IR source ...\& +.I directory +.br +.B install +.RI [ options ] +.BI "\-t " directory +.IR source ...\& +.br +.B install \-d +.RI [ options ] +.IR directory ...\& +.SH DESCRIPTION +.B install +copies files and sets the mode of each copy, or with +.B \-d +creates directories. +It is the +.BR busybox (1) +applet, which has fewer options than GNU +.BR install ; +see +.BR NOTES . +.SS Operands +With +.BR \-d , +every operand is a directory to create. +With +.BR \-t , +every operand is a +.I source +and is copied into +.IR directory . +Otherwise the last operand is +.IR dest , +and at least one +.I source +must precede it. +With too few operands, +.B install +prints a usage message on standard error and exits with status 1. +.PP +When +.I dest +is an existing directory, each +.I source +is copied into it, named after the last component of the source, the +part after the last +.BR / , +.BR \e , +or +.BR : . +Otherwise +.I source +is copied to +.I dest +itself. +.B install +does not check that several sources have a directory to go into: +each copy then replaces the one before it, no error is reported, and +only the last source remains. +.PP +There is no option to copy a directory. +A +.I source +that is a directory is reported as omitted, and the exit status is 1. +.SS What is copied +A regular file is copied, and a symbolic link as a source is followed. +Only its data is copied, byte for byte. +The copy has the current time as its modification time unless +.B \-p +is given, and its read-only attribute is set from the mode, not from the +source; see +.BR \-m . +.PP +A source of +.B \- +is a file of that name, not standard input. +The device names listed in +.BR busybox (1) +are read as devices, so +.I /dev/null +gives an empty file and +.I /dev/stdin +copies standard input. +Such a copy keeps the current time even with +.BR \-p , +and +.B \-v +does not list it. +.SS Existing destinations +.B install +never writes into an existing destination file. +It creates the destination as a new file, and when the name is taken it +deletes the old file, even a read-only one, and creates it again. +So other hard links to the old file keep its contents, and a symbolic +link at the destination is replaced rather than followed. +A file that cannot be deleted, such as a running program, is not +replaced, and the copy fails with +.BR "File exists" , +but a read-only one is left writable. +.PP +It is an error for a destination to be the same file as its source. +.B install +compares the volume and file index, so names that differ only in case, +names that reach the file by different routes, and hard links to one +file are all detected, and nothing is changed. +.SS Attributes +After copying each file, +.B install +runs +.B strip +if +.B \-s +is given, and then sets the mode. +The mode is always set, to 0755 unless +.B \-m +gives another. +So the copy is writable even when its source is read-only. +Directories made by +.B \-d +get the same mode. +.SS Output +.B install +reports each error on standard error as +.BI "install: " message +and goes on with the remaining operands. +The exit status is then 1. +Only +.B \-v +and +.B \-\-help +write to standard output. +.SH OPTIONS +Options may be grouped, as in +.BR \-pm444 , +and may follow operands, unless +.B POSIXLY_CORRECT +is set. +The argument of a short option may be attached, as in +.BR \-m444 , +or be the next argument. +A long option may be abbreviated to any unambiguous prefix, and takes +its argument after +.B = +or as the next argument. +.B \-\- +ends the options. +.TP +.B \-c +Accepted and ignored. +Copying is the default. +.TP +.BR \-d ", " \-\-directory +Create each operand as a directory, with any missing parent +directories, instead of copying files. +A directory that exists is not an error. +Incompatible with +.B \-s +and +.BR \-t , +and +.B \-D +has no effect with it. +.TP +.B \-D +Before copying, create the missing parent directories of +.IR dest . +With +.BR \-t , +create +.I directory +and its missing parents instead. +Failure to create them is reported, and then the copy fails on its own. +.TP +.BR \-s ", " \-\-strip +After copying each file, run +.B strip \-p +on it. +.B strip +is found by searching +.BR PATH , +and is not an applet. +It fails when +.B BB_UMASK +has the owner write bit set. +If it cannot be run, or exits with a nonzero status, +.B install +reports +.B install: strip +on standard error, followed by a reason when there is one, and the exit +status is 1. +The copy is kept, and the mode is still set. +Incompatible with +.BR \-d . +.TP +.BR \-p ", " \-\-preserve\-timestamps +Set the access and modification times of each copy to the source's +modification time, in whole seconds. +A failure to do so is reported, but does not change the exit status. +With +.BR \-s , +.B strip +is asked to keep the times. +.TP +\fB\-o\fR \fIowner\fR, \fB\-\-owner\fR=\fIowner\fR +Accepted for compatibility, but ownership is never changed. +The +.I owner +must be a number, the name +.BR root , +or the name of the current user, written with underscores in place of +spaces. +Any other name is reported as +.BR "unknown user" , +and +.B install +exits with status 1 before it copies anything. +.TP +\fB\-g\fR \fIgroup\fR, \fB\-\-group\fR=\fIgroup\fR +Accepted for compatibility, but the group is never changed. +The +.I group +must be a number. +Any name, even +.BR root , +is reported as +.BR "unknown group" , +and +.B install +exits with status 1 before it copies anything. +.TP +\fB\-m\fR \fImode\fR, \fB\-\-mode\fR=\fImode\fR +Set the mode of each file or directory to +.I mode +instead of 0755. +The mode is an octal number from 0 to 7777, or a symbolic mode as in +.BR chmod (1) +that modifies 0755. +Only the owner write bit, 0200, has an effect: when it is clear the file +is made read-only, and otherwise writable. +A directory is never made read-only. +A mode that cannot be parsed is not reported, and leaves the file +writable. +A symbolic mode with no +.BR u , +.BR g , +.BR o , +or +.B a +before its operator is limited by the umask; see +.BR BB_UMASK . +.TP +\fB\-t\fR \fIdirectory\fR, \fB\-\-target\-directory\fR=\fIdirectory\fR +Copy every operand into +.IR directory . +It is not created unless +.B \-D +is given. +Incompatible with +.BR \-d . +.TP +.BR \-v ", " \-\-verbose +Write +.BI \(aq source "\(aq \-> \(aq" dest \(aq +on standard output for each file copied, and +.BI "created directory: \(aq" path \(aq +for each directory created by +.B \-d +or +.BR \-D , +including each missing parent. +An intermediate directory is written with a trailing slash. +.TP +.B \-b +Accepted and ignored. +No backup is made. +.TP +.B \-\-help +As the first argument only, write a usage message on standard output +and exit with status 0. +The message omits the long options, +.BR \-b , +and +.BR \-v . +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when busybox starts, for a caller +such as +.B cmd.exe +that does not expand them. +When it is unset, busybox sets it to +.B 0 +for the programs it starts, so commands run from the kit's shell get the +shell's expansion only. +.TP +.B BB_UMASK +An octal file mode creation mask, applied before +.B install +runs. +With the owner write bit, +.BR 0200 , +set, each copy is created read-only until its mode is set, so +.B strip +cannot rewrite it and +.B \-s +fails. +The mask also limits a symbolic +.B \-m +mode with no +.BR u , +.BR g , +.BR o , +or +.B a +before its operator, such as +.BR =rw : +it adds or removes only bits that the mask leaves clear. +With +.B 0200 +set, for example, +.B \-m\ =rw +makes the file read-only, and +.B \-m\ \-w +leaves it writable. +.TP +.B PATH +Where +.B \-s +looks for +.BR strip . +An empty element stands for the current directory. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Messages written to a console also depend on +.BR BB_SKIP_ANSI_EMULATION , +.BR BB_TERMINAL_MODE , +.BR LANG , +.BR LC_ALL , +and +.BR LC_CTYPE , +and Windows error dialogs on +.BR BB_CRITICAL_ERROR_DIALOGS , +as for every busybox applet; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid command line, with a usage message on standard error; an +unknown user or group; or any operand that could not be copied, +stripped, or given its mode. +.SH EXAMPLES +Install a program, creating the directory it goes in, and strip it: +.PP +.RS 4 +.EX +$ install \-D \-s hello.exe out/bin/hello.exe +.EE +.RE +.PP +Create several directories: +.PP +.RS 4 +.EX +$ install \-d out/bin out/lib out/include +.EE +.RE +.PP +Install libraries into a directory, keeping their times and listing +each copy: +.PP +.RS 4 +.EX +$ install \-pv \-t out/lib libfoo.a libbar.a +\(aqlibfoo.a\(aq \-> \(aqout/lib/libfoo.a\(aq +\(aqlibbar.a\(aq \-> \(aqout/lib/libbar.a\(aq +.EE +.RE +.PP +Install headers as read-only files: +.PP +.RS 4 +.EX +$ install \-m 444 foo.h bar.h out/include +.EE +.RE +.PP +Install a program into a Windows directory: +.PP +.RS 4 +.EX +$ install hello.exe c:/tools +.EE +.RE +.SH NOTES +Differences from GNU +.BR install : +.IP \(bu 2 +Ownership is never changed. +.B \-o +and +.B \-g +only check that their argument is acceptable. +.IP \(bu 2 +The mode sets only the read-only attribute of a file. +A file is executable on Windows by its name or contents, not by its +mode; see +.BR busybox (1). +.IP \(bu 2 +An existing destination is deleted and created again, rather than +overwritten in place, and no backup is made. +.IP \(bu 2 +Several sources with a +.I dest +that is not a directory are not an error: each replaces the one before. +.IP \(bu 2 +A +.B \-m +mode that does not parse is not an error. +.IP \(bu 2 +.B \-v +is accepted although the usage message omits it. +.IP \(bu 2 +Options not listed above, such as +.BR \-C , +.BR \-S , +.BR \-T , +.BR \-Z , +.BR \-\-backup , +.BR \-\-compare , +.BR \-\-suffix , +and +.BR \-\-no\-target\-directory , +are invalid. +.PP +Only a file's data, and with +.B \-p +its modification time, are copied. +Alternate data streams, such as the +.B Zone.Identifier +stream that marks downloaded files, other attributes, such as hidden, +and security descriptors are not: a new file or directory gets the +permissions it inherits from its parent directory. +.PP +Paths may have drive letters and backslashes. +Names in a directory are joined with +.BR / , +so +.B install x \(aqc:\etools\(aq +installs to +.IR c:\etools/x . +A bare drive such as +.I c: +names the current directory of that drive, so +.B install x c: +installs to +.IR c:x . +Names may contain any Unicode character on Windows 10 version 1903 and +later; see +.BR busybox (1). +.PP +From +.BR cmd.exe , +.B install +expands wildcards in its arguments itself; see +.BR BB_GLOBBING . +.SH SEE ALSO +.BR busybox (1), +.BR chmod (1), +.BR cp (1), +.BR mkdir (1) diff --git a/man/man1/ipcalc.1 b/man/man1/ipcalc.1 new file mode 100644 index 0000000..5000318 --- /dev/null +++ b/man/man1/ipcalc.1 @@ -0,0 +1,314 @@ +.TH IPCALC 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +ipcalc \- calculate IPv4 network settings from an address +.SH SYNOPSIS +.B ipcalc +.RB [ \-bnmphs ] +.I address\c +.RB [ /\c +.IR prefix ] +.RI [ netmask ] +.SH DESCRIPTION +.B ipcalc +works out properties of an IPv4 network from an address and its netmask. +It prints the ones selected by its options, one per line, or looks up +the host name of the address. +.PP +The first operand is the +.IR address , +in dotted decimal, such as +.BR 192.168.1.5 . +The netmask that divides it into network and host bits is given in one +of two ways, but not both: a slash and a prefix length attached to the +address, as in +.BR 192.168.1.5/26 , +or a second operand in dotted decimal, as in +.BR 255.255.255.192 . +With neither, the netmask is the default for the class of the address: +.B 255.0.0.0 +when its first bit is 0, which is a first octet of 0 to 127; +.B 255.255.0.0 +when its first two bits are 10, which is 128 to 191; +and +.B 255.255.255.0 +otherwise, which is 192 to 255, including the multicast and reserved +ranges. +.PP +At least one of the options +.BR \-b , +.BR \-n , +.BR \-m , +.BR \-p , +and +.B \-h +is required. +.SS Output format +Each item selected by an option is a line +.IB name = value +on standard output. +The lines appear in the order below whatever the order of the options, +and the output suits the shell's +.B eval +for setting variables. +.TP +.BI NETMASK= address +The netmask, in dotted decimal, from +.BR \-m . +.TP +.BI BROADCAST= address +The broadcast address, from +.BR \-b . +.TP +.BI NETWORK= address +The network address, from +.BR \-n . +.TP +.BI PREFIX= length +The prefix length, in decimal, from +.BR \-p . +.TP +.BI HOSTNAME= name +The host name, in lowercase, from +.BR \-h . +.SH OPTIONS +Options may be grouped, as in +.BR \-bn , +and may follow the operands unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +A long option may be abbreviated to any unambiguous prefix. +The +.I netmask +operand is accepted only when one of +.BR \-b , +.BR \-n , +or +.B \-p +is given, and is otherwise a usage error. +.TP +.BR \-b ", " \-\-broadcast +Print the broadcast address: the address with every bit outside the +netmask set to 1. +.TP +.BR \-n ", " \-\-network +Print the network address: the address with every bit outside the +netmask set to 0. +.TP +.BR \-m ", " \-\-netmask +Print the netmask in effect: the one given by the prefix or the +.I netmask +operand, or else the default for the class of the address. +.TP +.BR \-p ", " \-\-prefix +Print the prefix length: the number of 1 bits in the netmask. +A netmask whose 1 bits are not contiguous is counted all the same, so +.B 255.0.255.0 +gives 16. +.TP +.BR \-h ", " \-\-hostname +Print the host name of the address, as the Windows name resolver reports +it, converted to lowercase. +Only the first name is printed. +The prefix and the netmask play no part. +If the resolver finds no name, this is an error. +This option is not a request for help; see +.BR \-\-help . +.TP +.BR \-s ", " \-\-silent +Do not print error messages. +The exit status is unchanged. +Wrong arguments are still reported, with a usage message. +Give at least one other option with it. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +When set, options must come before the operands. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when +.B ipcalc +starts, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Wrong arguments, or a failure. +.PP +Wrong arguments are an unknown or ambiguous option, no option from +.BR \-bnmph , +a +.I netmask +operand where it is not accepted, or no operand or more than two. +They are reported with a usage message on standard error. +.PP +A failure is an +.I address +or +.I netmask +that cannot be read, a prefix that is not a number from 0 to 32, both a +prefix and a +.IR netmask , +or no host name for the address. +It is reported on standard error as +.PP +.RS 4 +.EX +ipcalc: \fIreason\fR +.EE +.RE +.PP +unless +.B \-s +is given. +.SH EXAMPLES +Show the network and broadcast addresses of a host on a network whose +prefix length is 26: +.PP +.RS 4 +.EX +$ ipcalc \-bn 192.168.1.5/26 +BROADCAST=192.168.1.63 +NETWORK=192.168.1.0 +.EE +.RE +.PP +Do the same with a dotted netmask, and also show the prefix length: +.PP +.RS 4 +.EX +$ ipcalc \-bnp 192.168.1.5 255.255.255.192 +BROADCAST=192.168.1.63 +NETWORK=192.168.1.0 +PREFIX=26 +.EE +.RE +.PP +Convert a prefix length to a netmask: +.PP +.RS 4 +.EX +$ ipcalc \-m 10.0.0.0/20 +NETMASK=255.255.240.0 +.EE +.RE +.PP +Show the default netmask of a class B address: +.PP +.RS 4 +.EX +$ ipcalc \-m 172.16.5.9 +NETMASK=255.255.0.0 +.EE +.RE +.PP +Set shell variables from the results: +.PP +.RS 4 +.EX +$ eval "$(ipcalc \-bn 172.16.5.9/12)" +$ echo $NETWORK $BROADCAST +172.16.0.0 172.31.255.255 +.EE +.RE +.PP +Test whether an address is valid, with no output from +.B ipcalc +itself: +.PP +.RS 4 +.EX +$ ipcalc \-sn 10.0.0.256 >/dev/null || echo invalid +invalid +.EE +.RE +.PP +Look up the name of an address: +.PP +.RS 4 +.EX +$ ipcalc \-h 192.168.1.1 +.EE +.RE +.SH NOTES +Addresses and netmasks are read by the Windows +.B inet_addr +function. +Besides four decimal parts, it accepts fewer parts, where the last part +fills all the remaining bytes, so +.B 10.1 +is +.B 10.0.0.1 +and +.B 10 +is +.BR 0.0.0.10 . +Each part may be hexadecimal with a +.B 0x +prefix or octal with a leading +.BR 0 , +so +.B 010.010.010.010 +is +.BR 8.8.8.8 . +Everything from the first white-space character on is ignored, except +that an operand of a single space reads as +.BR 0.0.0.0 . +Host names and IPv6 addresses are rejected, since only IPv4 is handled. +.PP +.B 255.255.255.255 +is rejected, as an address and as a netmask, because +.B inet_addr +returns that value to report an error. +Write the prefix length instead, as in +.BR 10.0.0.1/32 . +.PP +The prefix is decimal digits only, with no sign, space, or other +characters, and leading zeros do not make it octal. +A slash with nothing after it is ignored. +A netmask operand is not checked for contiguous 1 bits. +.PP +The default netmask is chosen after the address is read, so an address +written with fewer than four parts, such as +.BR 200 , +is +.B 0.0.0.200 +and gets +.BR 255.0.0.0 . +.PP +Error messages name the address without the slash and prefix that may +follow it. +.PP +The host name is looked up with the Windows +.B gethostbyaddr +function, so it uses whatever the system resolver is configured to use, +including the hosts file. +Its failure message ends in +.BR "Unknown error" , +because the Winsock error code is passed to the C library's message +table, which does not know it. +.PP +Output lines end with LF, not CRLF. +A write error on standard output is not detected, so the exit status is +still 0. +.SH SEE ALSO +.BR busybox (1), +.BR sh (1) diff --git a/man/man1/jn.1 b/man/man1/jn.1 new file mode 100644 index 0000000..f71d68e --- /dev/null +++ b/man/man1/jn.1 @@ -0,0 +1,275 @@ +.TH JN 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +jn \- create a directory junction +.SH SYNOPSIS +.B jn +.I dir junc +.SH DESCRIPTION +.B jn +creates +.IR junc , +a directory junction to the existing directory +.IR dir . +A junction is a reparse point that redirects a directory to another +directory on the same computer, so a path under +.I junc +names the same file as the path at the same place under +.IR dir . +Unlike a symbolic link, a junction needs no special privilege or system +setting to create. +.PP +.I dir +must exist and be a directory. +The junction stores the name that +.BR realpath (1) +prints for it. +A relative +.I dir +is taken from the current directory, not from the directory of +.IR junc . +The +.B .\& +and +.B ..\& +components are removed by name before links are followed, so +.I link/..\& +is the directory that contains +.IR link , +not the parent of its target. +Every symbolic link and junction is then replaced with its target, so +the junction never refers to another link, and each name gets the case +and the long form that it has on disk. +The resolved name must begin with a drive letter. +.PP +.I junc +must not exist, but its parent directory must. +.B jn +creates +.I junc +as an empty directory and then turns it into a junction. +If that fails, it removes +.I junc +again. +.PP +On success +.B jn +writes nothing. +.SH OPTIONS +.B jn +has no options other than +.BR \-\-help . +Any other argument that begins with +.BR \- , +other than +.B \- +itself, is an unknown option and an error, even after the operands +unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options, so a +.I junc +named +.B \-x +is created with +.BI "jn \-\- " dir " \-x\fR." +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and the arguments after it +are ignored. +.SH ENVIRONMENT +.TP +.B BB_CRITICAL_ERROR_DIALOGS +When it is +.BR 1 , +Windows may show a critical-error dialog for a path on a drive with no +disk in it. +Otherwise busybox suppresses the dialog, and the operation fails. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when busybox starts, for a caller +such as +.B cmd.exe +that does not expand them. +When it is unset, busybox sets it to +.B 0 +for the programs it starts, so commands run from the kit's shell get the +shell's expansion only. +.TP +.B POSIXLY_CORRECT +When set, the first operand ends the options, so that a later argument +such as +.B \-x +is a name. +.PP +Messages written to a console also depend on +.BR BB_SKIP_ANSI_EMULATION , +.BR BB_TERMINAL_MODE , +.BR LANG , +.BR LC_ALL , +and +.BR LC_CTYPE , +as for every busybox applet; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +The junction was created, or +.B \-\-help +printed the usage message. +.TP +.B 1 +An invalid command line, with a usage message on standard error, or a +junction that could not be created. +.PP +A failure is reported on standard error as +.PP +.RS 4 +.EX +jn: can\(aqt create junction \(aq\fIjunc\fR\(aq to \(aq\fIdir\fR\(aq: \fIreason\fR +.EE +.RE +.PP +with the operands as typed. +Common reasons are +.B No such file or directory +when +.I dir +or the parent of +.I junc +is missing, +.B Not a directory +when +.I dir +is a file, +.B File exists +when +.I junc +exists, and +.B Invalid argument +when +.I dir +resolves to a name without a drive letter, as a UNC path or a path on +a mapped network drive does. +.SH EXAMPLES +Make a library directory available under a second name, then show where +the junction points: +.PP +.RS 4 +.EX +$ jn C:/src/zlib\-1.3.1 vendor/zlib +$ readlink vendor/zlib +C:/src/zlib\-1.3.1 +.EE +.RE +.PP +Give a directory whose name contains a space a path without one: +.PP +.RS 4 +.EX +$ jn "C:/Program Files/Some Tool" C:/tools/some +.EE +.RE +.PP +Remove a junction, leaving its target directory alone: +.PP +.RS 4 +.EX +$ rm vendor/zlib +.EE +.RE +.PP +A junction cannot replace an existing file or directory: +.PP +.RS 4 +.EX +$ jn src build; echo $? +jn: can\(aqt create junction \(aqbuild\(aq to \(aqsrc\(aq: File exists +1 +.EE +.RE +.SH NOTES +Differences from a symbolic link made by +.BR "ln \-s" : +.IP \(bu 2 +The target must be a directory. +.IP \(bu 2 +A relative target is taken from the current directory, not from the +directory of the junction. +.IP \(bu 2 +The target is stored as an absolute path, so moving the junction does +not change where it points. +.IP \(bu 2 +A UNC path such as +.I //server/share/dir +is rejected as a target, and so is a directory on a mapped network +drive, which resolves to a UNC path. +.PP +Other busybox programs treat a junction as a symbolic link. +.B ls \-l +shows it as +.IB junc " \-> " path +and +.B readlink +prints the stored path, with forward slashes. +.B rm +removes only the junction, with or without +.BR \-r , +and leaves the directory it points to alone. +.B rmdir +refuses, with +.BR "Not a directory" . +In +.BR cmd.exe , +.B dir +lists a junction as +.BR , +and +.B rmdir +removes it. +.PP +.B jn +.I dir junc +is like the +.B cmd.exe +command +.B mklink /J +.IR "junc dir" , +with the operands in the other order, except that +.B mklink +only makes +.I dir +absolute: it does not check that +.I dir +is an existing directory, and does not resolve links in it. +.PP +The volume that holds +.I junc +must support reparse points, as NTFS does. +.PP +Operands may use drive letters and either kind of slash. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +The absolute name of +.I dir +is limited to 259 characters, and a longer one fails with +.BR "No such file or directory" . +When the resolved name would be longer than 255 characters, links are +not followed, and the junction stores the absolute name as typed. +.PP +On Windows XP, which lacks the API for finding a final name, a junction +in +.I dir +is followed only when it is the last component, and names keep the +case and form in which they were typed. +.SH SEE ALSO +.BR busybox (1), +.BR ln (1), +.BR ls (1), +.BR readlink (1), +.BR realpath (1), +.BR rm (1), +.BR rmdir (1) diff --git a/man/man1/join.1 b/man/man1/join.1 new file mode 100644 index 0000000..889b3b8 --- /dev/null +++ b/man/man1/join.1 @@ -0,0 +1,422 @@ +.TH JOIN 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +join \- join two sorted files on a common field +.SH SYNOPSIS +.B join +.RB [ \-a +.I fnum +.RB "| " \-v +.IR fnum ]...\& +.RB [ \-e +.IR str ] +.RB [ \-o +.IR list ] +.RB [ \-t +.IR sep ] +.RB [ \-1 +.IR field ] +.RB [ \-2 +.IR field ] +.I file1 +.I file2 +.SH DESCRIPTION +.B join +combines the lines of two files that have a field in common. +It writes one line for each pair of a line of +.I file1 +and a line of +.I file2 +whose join fields are equal. +Both files must be sorted on the join field. +Either file may be +.BR \- , +for standard input, but not both. +.PP +The join field is field 1 of each line, unless +.B \-1 +or +.B \-2 +chooses another field of +.I file1 +or +.IR file2 . +.SS Fields +Without +.BR \-t , +blanks, meaning spaces and tabs, separate fields. +A run of blanks is one separator, and blanks at the start or end of a +line are ignored, so no field is empty and a blank line has no fields. +With +.BR \-t , +each occurrence of the separator character ends a field. +Fields can then be empty, and a line has one more field than it has +separators. +A line with fewer fields than the join field number has an empty join +field, which matches the empty join field of a line in the other file. +.SS Joining +.B join +reads the files in order, and compares the join fields of their current +lines as byte strings, not by the collation order of a locale. +Consecutive lines of a file with equal join fields form a group. +.PP +When the join fields of two groups are equal, +.B join +writes the output described below for every pairing of a line of the +group of +.I file1 +with a line of the group of +.IR file2 : +for each line of +.IR file1 , +all the lines of +.IR file2 , +in order. +Groups of 2 and 3 lines give 6 output lines. +It then goes on to the next group of both files. +.PP +Otherwise it goes on to the next group of the file with the lesser join +field, first writing the lines of the group it leaves as unpaired lines +if +.B \-a +or +.B \-v +asks for the unpaired lines of that file. +When one file ends, the groups left in the other are handled in the same +way. +.PP +The order of the input is not checked. +Where the files are not sorted, lines that should pair are skipped or +written as unpaired lines, with no message and exit status 0. +.SS Output +Every output line ends with LF. +Without +.BR \-o , +a joined line is the join field, then the fields of the +.I file1 +line other than its join field, then those of the +.I file2 +line, separated by a space or, with +.BR \-t , +by the separator character. +An unpaired line is written the same way from its own file alone, so its +join field moves to the front. +With +.BR \-o , +the fields named by the list are written instead. +An empty field is written as the +.B \-e +string, which is empty by default. +.SH OPTIONS +Every option takes an argument, which may be attached, as in +.BR \-a1 , +or be the next argument, so options cannot be grouped. +Options may follow the operands, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +A repeated option replaces its earlier values, except +.B \-a +and +.BR \-v , +which accumulate. +.TP +.BI "\-a " fnum +Also write the unpaired lines of file number +.IR fnum , +which is +.B 1 +or +.BR 2 , +among the joined lines in input order. +Repeat the option to write the unpaired lines of both files. +Incompatible with +.BR \-v . +.TP +.BI "\-v " fnum +Like +.BR \-a , +but write only unpaired lines: the joined lines are not written. +Incompatible with +.BR \-a . +.TP +.BI "\-e " str +Write +.I str +in place of each empty field. +This includes an empty join field, and with +.B \-o +each listed field that the line does not have. +Without +.BR \-o , +fields that a line does not have are not written at all. +The default is the empty string. +.TP +.BI "\-o " list +Write the fields named by +.I list +instead of the default output, in the order given, separated like the +default output. +The items of +.I list +are separated by commas, spaces, or tabs. +An item is +.B 0 +for the join field, or +.BI 1. n +or +.BI 2. n +for field +.I n +of the +.I file1 +or +.I file2 +line, where +.I n +is a decimal number from 1 to 2147483647. +An item may be repeated. +A field the line does not have is written as the +.B \-e +string, as is every field of the other file in an unpaired line. +On an unpaired line of +.IR file2 , +.B 0 +is the join field of +.IR file2 . +A list with no items is not rejected, and the output is then +meaningless. +See +.B NOTES +for defects. +.TP +.BI "\-t " sep +Separate fields with the character +.I sep +in the input and the output, instead of runs of blanks. +.I sep +must be exactly one byte, so the empty string is an error, and so is a +non-ASCII character where arguments are UTF-8, as on Windows 10 version +1903 and later. +It is taken literally, with no backslash escapes. +Pass a tab as a tab character. +.TP +.BI "\-1 " field +Use field number +.I field +of +.I file1 +as the join field. +It is a decimal number from 1 to 2147483647. +The default is 1. +.TP +.BI "\-2 " field +Use field number +.I field +of +.I file2 +as the join field. +The range and default are those of +.BR \-1 . +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments, including option arguments, are expanded +against file names at startup, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, whether or not any line was written. +.TP +.B 1 +Invalid command line, such as an unknown option, an invalid option +argument, both +.B \-a +and +.BR \-v , +or other than two operands; a file could not be opened, or is a +directory; writing the output still buffered at exit failed; or out of +memory. +A message or the usage is written to standard error. +.TP +.B 141 +A write to standard output failed because it is a pipe whose reader has +exited. +When this happens only at exit, while writing the output still buffered, +the status is 1 instead. +.SH EXAMPLES +Join two files on their first field, writing only the keys found in +both: +.PP +.RS 4 +.EX +$ cat names.txt +1 alice +2 bob +3 carol +$ cat ages.txt +1 34 +3 27 +4 51 +$ join names.txt ages.txt +1 alice 34 +3 carol 27 +.EE +.RE +.PP +Also write the lines of the first file that have no match, with a +placeholder for the missing age: +.PP +.RS 4 +.EX +$ join \-a 1 \-e unknown \-o 0,1.2,2.2 names.txt ages.txt +1 alice 34 +2 bob unknown +3 carol 27 +.EE +.RE +.PP +Write only the lines of the first file that have no match: +.PP +.RS 4 +.EX +$ join \-v 1 names.txt ages.txt +2 bob +.EE +.RE +.PP +Join comma-separated files on the second field of the first and the +first field of the second, sorting the first file on its way in: +.PP +.RS 4 +.EX +$ cat orders.csv +o1,2,pen +o2,1,ink +o3,2,pad +$ cat customers.csv +1,alice +2,bob +$ sort \-t, \-k2,2 orders.csv | join \-t, \-1 2 \-2 1 \- customers.csv +1,o2,ink,alice +2,o1,pen,bob +2,o3,pad,bob +.EE +.RE +.SH NOTES +Differences from GNU join: +.IP \(bu 2 +The only long option is +.BR \-\-help : +there is no +.BR \-\-check\-order , +.BR \-\-nocheck\-order , +or +.BR \-\-header , +and no +.BR \-i , +.BR \-j , +or +.BR \-z . +.B \-o +has no +.B auto +form. +.IP \(bu 2 +The order of the input is never checked. +.IP \(bu 2 +Join fields are compared as bytes, not in the collation order of the +locale. +.IP \(bu 2 +.B \-a +and +.B \-v +cannot be combined. +.IP \(bu 2 +.B \-t +takes exactly one byte. +An empty argument, which makes each line one field in GNU join, is an +error. +.PP +Defects in this version: +.IP \(bu 2 +With +.BR \-o , +only the first line written for a pairing of two groups, or for a group +of unpaired lines, follows +.IR list . +The other lines of it are empty. +This happens whenever a join field repeats within a file, so use +.B \-o +only on input whose join fields are unique. +.IP \(bu 2 +With a list whose every item is +.BR 0 , +such as +.BR "\-o 0" , +.B join +reads past the end of its copy of the list, and some runs write extra +fields, such as a second copy of the join field. +.IP \(bu 2 +A group of more than eight lines in one file overruns the buffer that +holds it, even if the group is never written, and +.B join +usually crashes. +Nine consecutive blank lines form such a group. +.PP +Only memory limits the length of a line and the number of fields. +.PP +Files are read as binary. +A CR directly before an LF is removed from each input line, so files with +CR LF and LF line endings behave alike, and output lines end with LF. +Any other CR, such as one ending an unterminated last line, is an +ordinary character. +A NUL byte ends a line, as LF does, and is not written. +The last line of a file need not end in a newline. +A read error ends a file silently. +.PP +.I file1 +and +.I file2 +may be Windows paths, with a drive letter and either kind of slash, or a +busybox-w32 device name such as +.IR /dev/null . +On Windows 10 version 1903 or later, file names and arguments are UTF-8 +and may contain any Unicode characters, and on older systems only those +of the system code page. +.B join +handles text as bytes. +.PP +When standard output is a console, text is converted for display from +the ANSI code page, which is UTF-8 on Windows 10 version 1903 and later. +.SH SEE ALSO +.BR busybox (1), +.BR comm (1), +.BR paste (1), +.BR sort (1) diff --git a/man/man1/kill.1 b/man/man1/kill.1 new file mode 100644 index 0000000..310f6a3 --- /dev/null +++ b/man/man1/kill.1 @@ -0,0 +1,371 @@ +.TH KILL 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +kill \- send a signal to processes +.SH SYNOPSIS +.B kill +.RB [ \-s +.I signal +.RB "| " \-\c +.IR signal ] +.IR pid ... +.br +.B kill \-l +.RI [ signal ...] +.SH DESCRIPTION +.B kill +sends a signal, by default +.BR TERM , +to each process whose ID it is given. +With +.BR \-l , +it lists signals instead and sends nothing. +Windows has no signals, so they are emulated; see +.BR NOTES . +.PP +Each +.I pid +is a decimal Windows process ID, as listed by +.BR ps (1). +A positive +.I pid +signals that process only. +Zero, or a negative number +.B \-\c +.IR n , +signals every descendant of a process and then the process itself: +the process running +.B kill +for 0, and process +.I n +otherwise. +The descendants are the children, grandchildren, and so on, found +through the parent process IDs of the processes running when +.B kill +looks. +If any of them cannot be signaled, the operand fails and is reported +with its own +.IR pid , +but the others are still signaled. +.PP +An operand may hold several PIDs separated by single spaces. +An empty operand is ignored. +.PP +.B kill +writes nothing on success. +It reports each failure on standard error and goes on to the next +operand: +.PP +.RS 4 +.EX +kill: can\(aqt kill pid 1234: Invalid argument +kill: invalid number \(aqabc\(aq +.EE +.RE +.SS Signals +A signal is a name or a number. +A name is case-insensitive and may begin with +.BR SIG , +as in +.BR sigterm . +A number is decimal. +The signals are: +.PP +.RS 4 +.EX + 0 EXIT 4 ILL 11 SEGV 22 ABRT + 1 HUP 8 FPE 13 PIPE + 2 INT 9 KILL 15 TERM + 3 QUIT +.EE +.RE +.PP +Any other number from 0 to 22 is accepted, but sending it fails with +.BR "Invalid argument" . +So does an empty name, or +.B SIG +alone, which is taken as 5. +Other names, such as +.BR USR1 , +.BR ALRM , +.BR STOP , +and +.BR CONT , +and numbers above 22 are errors, and nothing is sent. +Every signal except 0 ends the target process. +They differ only in the exit code the process gets, and in how +.B KILL +is delivered; see +.BR NOTES . +Signal 0 sends nothing, but fails if the process cannot be signaled, so +it tests for a process. +.SH OPTIONS +Options are recognized only at the start of the arguments, and cannot be +grouped. +Everything after them is an operand, even if it begins with +.BR \- , +so a negative +.I pid +may follow a signal option. +.TP +.B \-l +List signals and send nothing. +It must be the first argument. +With no operands, write one line per signal, without +.BR EXIT : +its number right-aligned to width 2, then +.BR ) , +a space, and its name. +.IP +For each operand, write the name if it is a number, or the number if it +is a name. +A number is first reduced modulo 128, so that an exit status of +.RI "128 + " n +gives the name of signal +.IR n , +and a result with no name is written as a number. +An operand that is not a signal is reported, and ends the list with +status 1. +.TP +.BI "\-s " signal +Send +.I signal +instead of +.BR TERM . +The same as +.BI \- signal\fR. +.TP +.BI \- signal +Send +.I signal +instead of +.BR TERM . +.I signal +is a name or a number, as described in +.BR Signals . +.TP +.B \-\- +As the first argument, end the options and send +.BR TERM , +so that the first +.I pid +may be negative. +After a signal option it is an operand, which is not a valid PID. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and not by the built-in +.B kill +of the kit's shell. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every signal was sent, or the list was written. +.TP +.B 1 +A usage error, such as an unknown signal or no operands, or exactly one +failure. +.TP +.B >1 +The number of failures: each operand that is not a valid PID, and each +PID that could not be signaled. +The status is this count modulo 256, so 256 failures give 0. +.SH EXAMPLES +Ask a process to end: +.PP +.RS 4 +.EX +$ kill 1234 +.EE +.RE +.PP +End a process without letting it clean up: +.PP +.RS 4 +.EX +$ kill \-KILL 1234 +.EE +.RE +.PP +Test whether a process exists and can be signaled: +.PP +.RS 4 +.EX +$ kill \-0 1234 && echo running +.EE +.RE +.PP +End a process and all its descendants, using the negative form of its +ID. +The +.B \-\- +is needed only when no signal option precedes the ID: +.PP +.RS 4 +.EX +$ kill \-\- \-1234 +$ kill \-KILL \-1234 +.EE +.RE +.PP +End a background job of the shell: +.PP +.RS 4 +.EX +$ kill %1 +.EE +.RE +.PP +Name the signal that ended a command, given its exit status: +.PP +.RS 4 +.EX +$ kill \-l 143 +TERM +.EE +.RE +.PP +List the signals: +.PP +.RS 4 +.EX +$ kill \-l + 1) HUP + 2) INT + 3) QUIT + 4) ILL + 8) FPE + 9) KILL +11) SEGV +13) PIPE +15) TERM +22) ABRT +.EE +.RE +.SH NOTES +.B KILL +calls +.BR TerminateProcess , +which gives the process no chance to clean up. +Any other signal except 0 makes the process call +.B ExitProcess +from a thread that +.B kill +injects into it. +No signal handler runs in either case, and +.B INT +does not send Ctrl+C: it ends the process like +.BR TERM . +.PP +The exit code of a signaled process is the signal number shifted left +24 bits, such as +.B 0x0F000000 +for +.BR TERM , +which the kit's shell reports as 128 plus the signal number, so +.B $?\& +is 143 for a process ended by +.BR TERM . +.PP +A signal is delivered asynchronously. +The command returns once it has created the thread, and does not report +a failure to create it, so the process may exit a moment later, or not +at all. +Injecting a thread works only when +.B kill +and the target are both 32-bit or both 64-bit. +Otherwise every signal except +.BR KILL , +including 0, fails. +.PP +The reason after +.B can\(aqt kill pid +is +.B Invalid argument +for a process that does not exist or has already exited, or for a +number with no name, and +.B Permission denied +for a process that cannot be opened with the access needed, such as a +system process, or that has the other bitness. +.PP +Windows reuses process IDs, so a process whose parent has exited is +taken for a child of any later process that gets the parent's ID. +If reused IDs make a process its own ancestor, a negative +.I pid +or 0 whose descendants include it makes +.B kill +run without end. +.PP +Differences from the usual Unix command: +.IP \(bu 2 +There are no process groups, so a negative +.I pid +selects descendants, and there is no PID +.B \-1 +for all processes. +.IP \(bu 2 +Only the signals listed above exist, with no job control signals such +as +.B STOP +and +.BR CONT . +.IP \(bu 2 +Numbers follow the Windows C runtime: +.B ABRT +is 22, not 6, and 6 cannot be sent. +.IP \(bu 2 +There are no +.B \-n +or +.B \-L +options. +.IP \(bu 2 +The exit status counts failures. +.PP +In the kit's shell +.B kill +is a built-in that runs this same code inside the shell's process, so +.B kill 0 +ends the shell itself and everything it started. +Its messages begin with the name of the shell instead of +.BR kill: . +It also accepts job specifications such as +.B %1 +in place of PIDs, and signals each running process of the job and all +of their descendants. +An unknown job is a shell error with status 2. +.PP +For a command run in the background, +.B $!\& +is the ID of a shell process, which runs the program as its child +unless the program is a busybox applet that runs inside it. +Then +.B kill $!\& +ends only that shell and leaves the program running, but +.B kill %1 +and +.B kill \-\- \-$!\& +end both. +.SH SEE ALSO +.BR busybox (1), +.BR killall (1), +.BR pgrep (1), +.BR pidof (1), +.BR pkill (1), +.BR ps (1), +.BR sh (1) diff --git a/man/man1/killall.1 b/man/man1/killall.1 new file mode 100644 index 0000000..18089c0 --- /dev/null +++ b/man/man1/killall.1 @@ -0,0 +1,435 @@ +.TH KILLALL 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +killall \- send a signal to all processes with a given name +.SH SYNOPSIS +.B killall +.RB [ \-q ] +.RB [ \-\c +.IR signal ] +.IR name ... +.br +.B killall +.RB [ \-q ] +.B \-s +.I signal +.IR name ... +.br +.B killall +.RB [ \-q ] +.B \-\- +.IR name ... +.br +.B killall \-l +.RI [ signal ...] +.SH DESCRIPTION +.B killall +sends a signal, by default +.BR TERM , +to every running process whose name is one of the +.I name +operands. +It takes the operands in order, and reports each one that matches no +process. +It never signals its own process, but a +.I name +matched only by that process, such as +.BR killall , +still counts as matched. +It reads no input. +With +.BR \-l , +it instead converts signal names to numbers and back, writing the +results on standard output. +.PP +Messages go to standard error. +A +.I name +that matches no process is reported as +.PP +.RS 4 +.EX +killall: \fIname\fR: no process killed +.EE +.RE +.PP +and a process that could not be signaled as +.PP +.RS 4 +.EX +killall: can\(aqt kill pid \fIpid\fR: \fIreason\fR +.EE +.RE +.PP +where +.I reason +is usually +.B Permission denied +or +.BR "Invalid argument" . +.PP +This +.B killall +is a busybox applet; see +.BR busybox (1). +A +.I name +is an exact process name, not a pattern. +To select processes by pattern, use +.BR pkill (1). +For what the signals do on Windows, see +.BR NOTES . +.SS Process names +Only the name of a process is matched, never its path or command line. +The name is the file name of its executable as Windows reports it, +including the extension, such as +.BR explorer.exe . +The comparison is case-sensitive, although Windows file names are not, +and the extension is part of the name, so +.B server +does not match +.BR server.exe . +.PP +A process running the same build of busybox is named after its applet +instead, such as +.B sh +or +.BR sleep , +unless +.B killall +cannot read its memory, as for an elevated process, which leaves it +.BR busybox.exe . +A script whose +.B #!\& +line names an applet is named after the script file, except that a shell +script run from the kit's shell is named after the shell, such as +.BR sh . +The kit's command launchers, such as +.B sleep.exe +and +.BR killall.exe , +appear under their own names, each alongside the busybox process it +started, so +.B killall sleep +signals the busybox process and leaves the launcher to exit with it. +.PP +Only the first 15 characters of a long name are compared. +A process name of 15 or more characters matches any operand that agrees +with it in its first 15 characters, however the two differ after that, +so the extension may be left off a name with 15 or more characters +before it. +A shorter process name must match the whole operand. +.PP +The idle process, with process ID 0 and the name +.BR "[System\ Process]" , +is never selected. +.SH OPTIONS +Options are recognized only at the start of the command line. +First comes +.BR \-q , +if given, and then one of +.BR \-s , +.BI \- signal\fR, +or +.BR \-\- . +.B \-l +and +.B \-\-help +are recognized only as the first argument. +Every later argument is a +.IR name , +even one that begins with a dash, and options cannot be grouped. +.TP +.B \-l +List or convert signals, then exit without signaling anything. +With no further arguments, write one signal per line as a number, a +parenthesis, a space, and a name, such as +.B "\ 9)\ KILL" +and +.BR "15)\ TERM" . +The list is +.BR HUP , +.BR INT , +.BR QUIT , +.BR ILL , +.BR FPE , +.BR KILL , +.BR SEGV , +.BR PIPE , +.BR TERM , +and +.BR ABRT , +numbered 1, 2, 3, 4, 8, 9, 11, 13, 15, and 22. +.IP +With arguments, write a line for each, converting them in order. +A name, in any case and with or without a +.B SIG +prefix, is converted to its number. +A decimal number is reduced to its low 7 bits, so that a shell exit +status of 128 plus a signal number gives that signal's name, and is +written as that name, or as the reduced number when it has none. +An argument that is neither stops the conversion with +.B unknown signal +and exit status 1, after the lines for earlier arguments. +.TP +.B \-q +Do not report names that match no process, or processes that could not +be signaled. +Each still counts toward the exit status. +.TP +.BI "\-s " signal +Send +.I signal +instead of +.BR TERM . +It must be a separate argument: +.B \-sTERM +is rejected as a bad signal name. +It is otherwise the same as +.BI \- signal +below, and the usage message does not list it. +.TP +.BI \- signal +Send +.I signal +instead of +.BR TERM . +It is a name, in any case and with or without a +.B SIG +prefix, or a decimal number from 0 to 22. +The names are those listed by +.BR \-l , +plus +.B EXIT +for 0. +Any other name or number is rejected with +.B bad signal name +and exit status 1, before any process is looked at. +.IP +Signal 0 sends nothing, but still fails for a process that could not be +signaled, so it tests whether each match exists and can be signaled. +A number from 0 to 22 with no name, such as 21, is accepted but fails +with +.B Invalid argument +for each process it is sent to. +So does an empty name, or +.B SIG +alone, which is taken as 5. +.TP +.B \-\- +Ends the options, so that the first +.I name +may begin with a dash. +It is recognized only in place of a signal. +After +.BI \- signal +or +.BI "\-s " signal , +it is a name. +.TP +.B \-\-help +Print the usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded as file names before +.B killall +sees them, even inside quotes, as needed when run from +.BR cmd.exe . +A name is never a pattern, so the effect is only that an operand such as +.B app* +is replaced by the names of matching files in the current directory, +which are then taken as process names. +A pattern that matches nothing is left as it is. +A busybox process started with the variable unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.PP +The startup code shared by all applets also reads +.B BB_CRITICAL_ERROR_DIALOGS +and +.BR BB_UMASK , +neither of which changes what +.B killall +does, and variables such as +.B BB_TERMINAL_MODE +for console output; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every +.I name +matched a process and each match was signaled, or +.B \-l +converted every argument, or +.B \-\-help +was given. +.TP +.B 1 +An invalid command line: a bad signal name, no +.IR name , +a lone +.BR \-q , +which also prints the usage message on standard error, or an unknown +signal given to +.BR \-l . +.TP +.I n +The number of failures, with or without +.BR \-q : +one for each +.I name +that matches no process, and one for each process that could not be +signaled. +A single failure also gives 1. +Every operand is tried, whatever fails. +The status is this count modulo 256, so 256 failures give 0. +.SH EXAMPLES +Terminate every instance of a program: +.PP +.RS 4 +.EX +$ killall server.exe +.EE +.RE +.PP +Show the report and the exit status when nothing matches: +.PP +.RS 4 +.EX +$ killall server.exe; echo $? +killall: server.exe: no process killed +1 +.EE +.RE +.PP +Stay silent when the program is not running: +.PP +.RS 4 +.EX +$ killall \-q server.exe +.EE +.RE +.PP +End a program at once, without letting it clean up: +.PP +.RS 4 +.EX +$ killall \-KILL server.exe +.EE +.RE +.PP +Test, without signaling it, whether a program is running and could be +signaled: +.PP +.RS 4 +.EX +$ killall \-q \-0 server.exe && echo running +.EE +.RE +.PP +Convert between signal numbers and names, such as the status 143 that +the shell reports for a process ended by +.BR TERM : +.PP +.RS 4 +.EX +$ killall \-l 143 +TERM +$ killall \-l kill +9 +.EE +.RE +.SH NOTES +Differences from the psmisc +.BR killall , +and from busybox on Linux: +.IP \(bu 2 +Only a process's name is matched. +Busybox on Linux also matches the name a program was started with, and +the name or full path of its executable. +.IP \(bu 2 +There are no options to select processes by pattern, owner, or age, or +to wait for them to exit. +.IP \(bu 2 +Only the ten signals listed by +.B \-l +exist. +There is no +.BR USR1 , +.BR ALRM , +.BR STOP , +or +.BR CONT . +.IP \(bu 2 +Names include the extension and are case-sensitive. +.IP \(bu 2 +Failures to signal a process are reported and counted. +.BR pkill (1) +ignores them. +.PP +An operand is a name, never a path, so one such as +.I ./server.exe +or +.I C:/bin/server.exe +matches no process. +The list of processes is read again for each operand, and covers every +process on the system, including those of other users. +.PP +Windows cannot send signals between processes, so +.B killall +emulates them. +.B KILL +calls +.BR TerminateProcess , +which gives the process no chance to clean up. +Any other signal except 0 makes the process call +.B ExitProcess +from a thread injected into it, so that its DLLs are notified, but no +signal handler runs and the signal cannot be caught or ignored. +Either way the process ends at once, with an exit code of the signal +number shifted left 24 bits, such as +.B 0x0F000000 +for +.BR TERM . +The busybox shell reports that as death by the signal, with status 128 +plus the signal number. +Only the matched process is signaled, not its children. +A thread that cannot be created is not reported, so a successful exit +status does not prove that the process exited. +.PP +Injecting a thread works only into a process of the same bitness as +busybox, 64-bit or 32-bit, so for any other process every signal except +.BR KILL , +including 0, fails with +.BR "Permission denied" . +A process that Windows does not let busybox open, such as a system +process or one of another user, fails the same way. +.PP +Only the process running +.B killall +is excluded. +In the kit's shell that is the shell itself, because the shell runs +.B killall +without starting a process, so +.B killall sh +spares the shell that runs it but signals every other busybox shell. +A subshell or a pipeline element is a separate process, so there the +shell it was started from is signaled too. +Started from +.B cmd.exe +through the launcher +.BR killall.exe , +the launcher is a separate process and is not excluded. +.SH SEE ALSO +.BR busybox (1), +.BR kill (1), +.BR pgrep (1), +.BR pidof (1), +.BR pkill (1), +.BR ps (1), +.BR sh (1) diff --git a/man/man1/lash.1 b/man/man1/lash.1 new file mode 100644 index 0000000..ddc511e --- /dev/null +++ b/man/man1/lash.1 @@ -0,0 +1 @@ +.so man1/sh.1 diff --git a/man/man1/less.1 b/man/man1/less.1 new file mode 100644 index 0000000..2a40018 --- /dev/null +++ b/man/man1/less.1 @@ -0,0 +1,680 @@ +.TH LESS 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +less \- view text one screenful at a time +.SH SYNOPSIS +.B less +.RB [ \-EFIMmNRSsX~ ] +.RI [ file ...] +.SH DESCRIPTION +.B less +shows text on the console one screenful at a time, and lets the user +scroll through it and search it. +It shows each +.IR file , +or standard input when there are no +.I file +operands. +This +.B less +is an applet of +.BR busybox , +with far fewer options and commands than GNU +.BR less ; +see +.BR NOTES . +.PP +The keyboard is read from the console, not from standard input, so +standard input may be a pipe or a file. +A +.I file +is opened when it is first shown, so a bad name later in the list is +found only when it is reached. +.PP +.B less +pages only when standard output is a console and the console window is +at least 20 columns wide and 3 rows high. +Otherwise it acts as +.BR cat : +it copies each +.IR file , +or standard input, to standard output unchanged, ignores all options, +and treats a +.I file +named +.B \- +as standard input. +A file that cannot be opened or copied is reported on standard error, +and the remaining files are still copied. +.PP +When standard output is a console and there are no +.I file +operands, standard input must not be a console. +Otherwise there is nothing to show, and +.B less +prints a usage message on standard error and exits with status 1. +.SS Display +The window is the console window when +.B less +starts; see +.BR COLUMNS " and " LINES . +The last row is the prompt, and the rows above it show text. +A line wider than the window wraps onto further rows, unless +.B \-S +is given. +Input that ends with a newline shows an empty row after its last line. +Rows after the end of the input show a +.BR ~ , +unless +.B \-~ +is given. +Scrolling forward stops once one such row shows. +.PP +The prompt is in reverse video, except for a lone colon. +While the first line of the input is at the top, it is the name of the +file, or +.BR "standard input" . +Otherwise it is a +.B : +while more text follows, and +.B (END) +once the end of the input is displayed. +With several files, the name and +.B (END) +are followed by +.BI "(file " i " of " n ) . +The prompt also shows messages, such as +.BR "No matches found" . +.PP +With +.B \-M +or +.B \-m +the prompt is longer, as in +.BR "main.c lines 1-23/100 23%" . +After the file name come +.BI "(file " i " of " n ) +when there are several files, the numbers of the first and last lines +shown, and a slash and the total number of lines when that is known. +The total is known for a +.I file +operand that is a regular file, and for other input once all of it has +been read. +The prompt ends with +.B (END) +when the end of the input is displayed, followed by +.B \- next: +and the next file's name when another file follows. +Otherwise it ends with the last line shown as a percentage of the total, +when the total is known. +.B = +and +.B :f +show this prompt whatever the options. +.PP +The input is read as it is needed, enough to fill the window, and more +as commands scroll or search further. +Only the first 9999999 rows are kept, and input beyond them is ignored. +Bytes are shown as follows: +.IP \(bu 2 +A tab advances to the next multiple of 8 columns. +.IP \(bu 2 +A CR is discarded, so CRLF line endings show as plain line ends, but it +still takes a column when a line is wrapped. +.IP \(bu 2 +A backspace removes the character before it, so text overstruck for +bold or underline, as in some formatted pages, shows as its last +character. +After a tab, at the start of a row, or with +.B \-R +after an SGR sequence, it is shown like other control characters. +.IP \(bu 2 +Any other control character is shown in reverse video as the character +0x40 above it: NUL as +.BR @ , +ESC as +.BR [ , +and so on. +DEL is shown as +.B ?\& +in the same way. +.IP \(bu 2 +With +.BR \-R , +an SGR sequence is passed to the console, and takes no columns. +Any other escape sequence is cut down: its ESC is removed, and for a +CSI sequence, so are the +.B [ +and any digits and semicolons after it. +What remains, such as the final letter, is shown as text. +.IP \(bu 2 +All other bytes are shown as they are. +Text is UTF-8, and each character takes one column, if the ANSI code +page is UTF-8 and the first of +.BR LC_ALL , +.BR LC_CTYPE , +and +.B LANG +that is set is not +.BR C . +Otherwise each byte takes one column. +.SS Commands +A command is one key, with no Enter. +Besides the ASCII keys, only Up, Down, PgUp, PgDn, Home, and End have +commands. +Any other key does nothing. +Control characters other than Enter and Backspace are skipped wherever +a key is read. +.PP +A command that prompts for text shows the prompt on the last row. +The text is edited only with Backspace, and cannot be longer than fits +on the row. +Enter ends it, and Enter on an empty line cancels the command. +.TP +.BR j ", " e ", " Enter ", " Down +Scroll forward one line. +.TP +.BR k ", " y ", " Up +Scroll back one line. +.TP +.BR f ", " z ", " Space ", " PgDn +Scroll forward one window, which is all the rows above the prompt. +.TP +.BR b ", " w ", " PgUp +Scroll back one window. +.TP +.B d +Scroll forward half a window. +.TP +.B u +Scroll back half a window. +.TP +.BR g ", " < ", " p ", " % ", " Home +Go to the first line. +.TP +.BR G ", " > ", " End +Go to the end of the input. +This reads all the remaining input first. +.TP +.BI / regex +Search forward for the first line after the first line shown that +matches +.IR regex , +and scroll to put it at the top, as far as the end of the input allows. +If the input read so far has no such line, more is read until one is +found or the input ends. +If no line after it matches, go to the last line that does. +The prompt gives +.B No matches found +when no line matches. +An empty +.I regex +cancels the command and also clears the previous search. +See +.BR Searching . +.TP +.BI ? regex +Like +.BR / , +but find the last match at or before the first line shown. +If there is none, go to the first match after it. +.TP +.B n +Go to the match after the current one. +.TP +.B N +Go to the match before the current one. +.TP +.BI m letter +Mark the first line shown. +.I letter +is a letter, A to Z or a to z. +Fourteen marks can be set. +After that, new marks replace the oldest, and some older marks are lost. +Marking a letter again, while its first mark is kept, has no effect. +A mark is a position in the displayed rows, and is not tied to a file. +.TP +.BI \(aq letter +Show the line marked with +.I letter +as the first line. +An unset +.I letter +does nothing. +.TP +.BR { ", " ( ", " [ +The first line shown must contain the bracket. +Scroll so that the nearest line at or after it that contains the +matching close bracket is the last line shown. +Only the input read so far is searched, and nesting is not tracked. +.TP +.BR } ", " ) ", " ] +The last line shown must contain the bracket. +Scroll so that the nearest line at or before it that contains the +matching open bracket is the first line shown. +Nesting is not tracked. +.TP +.B :n +Show the next file. +.TP +.B :p +Show the previous file. +.TP +.B :x +Show the first file. +.TP +.B :d +Show the previous file, or the next if the current file is the first, +and remove a file from the list: the current file if it is the first +or second, and otherwise the second file. +It has no effect when there is only one file. +.TP +.BR E ", " :e +Prompt for a file name, and show that file instead. +The list of files from the command line is forgotten, so +.B :n +and +.B :p +find no other file. +A file that cannot be read is refused with +.BR "Cannot read this file" . +.TP +.BR = ", " :f +Show the longer prompt of +.BR \-m . +.TP +.B s +Prompt for a file name, and write the input read so far to it, +replacing the file if it exists. +Each row is written as a line, so a wrapped line is broken where it +wrapped. +With +.BR \-R , +SGR sequences are kept. +.TP +.BI \- flag +Toggle an option. +.I flag +is one of +.BR M , +.BR m , +.BR E , +.BR S , +.BR N , +and +.BR ~ . +Toggling +.B \-N +wraps the text again and clears the search. +Toggling +.B \-~ +changes nothing visible, as the rows past the end are chosen at startup. +.TP +.BR r ", " R +Redraw the screen. +.TP +.BR q ", " Q ", " :q +Quit. +.PP +Digits typed before a command form a count, which the prompt shows +after a colon. +A count is from 1 to 9999999, and is used by these commands only. +With any other key, or a count out of range, both the count and the +key are discarded. +.IP \(bu 2 +.BR e ", " z ", " d ", " Space ", " Enter ", " Down : +scroll forward that many lines. +.IP \(bu 2 +.BR y ", " b ", " w ", " u ", " Up : +scroll back that many lines. +.IP \(bu 2 +.BR g ", " < ", " G ", " > : +go to that line, counting lines of input, not wrapped rows. +.IP \(bu 2 +.BR p ", " % : +go to that percentage of the file. +.IP \(bu 2 +.B n +goes that many matches on from the current match. +.IP \(bu 2 +.BR / " and " ?\& +ignore the count. +.SS Searching +A search pattern is a POSIX basic regular expression, with the GNU +operators +.BR \e+ , +.BR \e? , +and +.BR \e| . +It is matched against each row of text on its own, so a match cannot +span a wrapped line, and +.B ^ +and +.B $ +match at the ends of a row. +Case matters unless +.B \-I +is given. +With +.BR \-R , +SGR sequences are not part of the text matched. +An error in the pattern is shown in the prompt, and the previous search +is already cleared. +.PP +The matches of a search are shown in reverse video until the next +search, or until +.B \-N +is toggled. +.B n +and +.B N +move through the matches of the last search in file order, whatever +the direction of that search. +They move from the last match found, not from the screen, and stop at +the first and last matches. +.SH OPTIONS +Options may be grouped, as in +.BR \-EF , +and may follow the +.I file +operands unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +An unknown option prints a usage message on standard error and exits +with status 1. +That includes +.BR \-h , +which the usage message itself lists. +As the first argument, +.B \-\-help +prints the usage message on standard output and exits with status 0; +see +.BR busybox (1). +.TP +.B \-E +Quit when the end of the input is displayed. +The whole of +.B less +quits, not only the current file. +The flag can be toggled with the +.B \- +command. +.TP +.B \-F +Quit if all of a file's input fits on one screen, when that file is +shown. +With +.BR \-F , +.B \-E +has no effect. +.TP +.B \-I +Ignore case in all searches. +.TP +.BR \-M ", " \-m +Show the longer prompt described under +.BR Display . +The two options are the same, and can be toggled separately. +.TP +.B \-N +Put each line number before its line, in 7 columns followed by a space. +A wrapped line repeats its number on each row, and rows past the end of +the input get blank space. +The text is wrapped 8 columns narrower. +The flag can be toggled. +.TP +.B \-S +Truncate long lines: show only the first window width of each line, and +leave the rest out of reach, as there is no scrolling sideways. +The flag can be toggled. +.TP +.B \-R +Pass SGR sequences, which set colors and text styles, to the console. +They are the sequences of the form ESC, then +.BR [ , +then digits and semicolons, then +.BR m . +Each takes no columns. +A wrapped line carries its style onto its further rows, and every row +that used a style ends with a reset. +Without +.BR \-R , +ESC is shown as described under +.BR Display , +so the sequences appear as text. +By default, +.BR man (1) +runs +.B less \-R +to show its emphasis. +.TP +.B \-~ +Leave the rows after the end of the input blank, instead of showing +a +.BR ~ . +.TP +.BR \-s ", " \-X +Accepted and ignored. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B BB_SKIP_ANSI_EMULATION +The older form of +.BR BB_TERMINAL_MODE ; +see +.BR busybox (1). +.TP +.B BB_TERMINAL_MODE +How the console handles escape sequences and keys; see +.BR busybox (1). +It decides whether +.B less +reads keys with virtual terminal input; see +.BR NOTES . +.TP +.B COLUMNS +The window width in columns, instead of the console's. +A value from 2 to 29999 is used. +Any other value means 80. +.TP +.B CONEMUPID +When set, the default +.B BB_TERMINAL_MODE +is 0; see +.BR busybox (1). +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +The first of these that is set decides whether text is UTF-8; see +.BR Display . +It also decides how the console is written; see +.BR busybox (1). +.TP +.B LESS +Options for every run, read after the command line and scanned one +character at a time. +.BR F , +.BR M , +.BR R , +and +.B S +turn on +.BR \-F , +.BR \-M , +.BR \-R , +and +.BR \-S . +Every other character, including a dash, is ignored, so +.B FRSXMK +is the same as +.BR \-FRSM . +.IP +.BR man (1) +sets it to +.B R +for its pager when it is unset and the output of +.B man +is a console. +.TP +.B LINES +The window height in rows, instead of the console's. +A value from 2 to 29999 is used. +Any other value means 24. +.TP +.B POSIXLY_CORRECT +If set, options must come before operands. +.SH EXIT STATUS +.TP +.B 0 +Success: +.B less +quit, the input was copied, or +.B \-\-help +printed the usage message. +.TP +.B 1 +An unknown option, no +.I file +and a console for standard input, a +.I file +that cannot be opened, or a console that cannot be opened. +A file that cannot be opened ends +.B less +at once, even when it is reached late. +When +.B less +acts as +.BR cat , +a file that cannot be opened or copied also gives 1, after the others +are copied. +.SH EXAMPLES +Number the lines of a file as it is shown: +.PP +.RS 4 +.EX +$ less \-N main.c +.EE +.RE +.PP +Page compiler output, keeping its colors: +.PP +.RS 4 +.EX +$ gcc \-fdiagnostics\-color=always \-c main.c 2>&1 | less \-R +.EE +.RE +.PP +View two files with the longer prompt, and type +.B :n +to move to the second: +.PP +.RS 4 +.EX +$ less \-M one.txt two.txt +.EE +.RE +.PP +Make every +.BR less , +including the one that +.BR man (1) +runs, show colors and truncate long lines: +.PP +.RS 4 +.EX +$ export LESS=RS +.EE +.RE +.SH NOTES +.B less +uses the console's alternate screen buffer. +It switches to it when it starts paging, and back when it quits, so the +screen then shows what it showed before +.B less +ran, and nothing that +.B less +displayed remains. +That includes the text shown by +.B \-E +or +.BR \-F , +which quit as soon as the end of the input is displayed. +A +.I file +that cannot be opened after paging has begun ends +.B less +without switching back, so its error message, and whatever runs next, +appear on the alternate screen. +.PP +The window size is read once, when +.B less +starts, and a resize is not noticed. +.PP +Keys are read through the console API, unless standard input is the +console and it already has virtual terminal input enabled, or +.B BB_TERMINAL_MODE +forces virtual terminal input. +While +.B less +waits for a key, Ctrl+C is read as a key and ignored. +.PP +Standard input is read with blocking reads. +.B less +shows nothing until it has a screenful of input, or the end of the +input, and a command that needs more input waits for it. +.PP +.B less +does not decompress files. +A file named +.B \- +is an ordinary file name when paging. +.PP +Unlike GNU +.BR less : +.IP \(bu 2 +The options are those above, and +.B LESS +sets only four of them. +.IP \(bu 2 +There is no help command, no +.B +cmd +option, and no command to run a shell command, edit the file, use tags, +or scroll sideways. +.IP \(bu 2 +Searches have no modifiers, the regular expressions are basic ones, and +.B n +and +.B N +ignore the direction of the search. +.IP \(bu 2 +The +.B \- +command toggles only six options, and has no long names. +.IP \(bu 2 +There is no +.BR LESSOPEN , +no +.BR LESSKEY , +and no way to change the prompt. +.PP +w64devkit patches +.B less +so that +.B \-R +passes SGR sequences through, where busybox removes them, and so that a +UTF-8 character takes one column and byte 0x9B is not shown as a +control character. +.SH SEE ALSO +.BR busybox (1), +.BR cat (1), +.BR grep (1), +.BR man (1) diff --git a/man/man1/ln.1 b/man/man1/ln.1 new file mode 100644 index 0000000..80e2f77 --- /dev/null +++ b/man/man1/ln.1 @@ -0,0 +1,444 @@ +.TH LN 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +ln \- make hard links or symbolic links +.SH SYNOPSIS +.B ln +.RI [ options ] +.I target link +.br +.B ln +.RI [ options ] +.IR target ...\& +.I directory +.br +.B ln +.RI [ options ] +.I target +.SH DESCRIPTION +.B ln +makes a link named +.I link +to +.IR target . +By default the link is a hard link, another name for the same file. +With +.BR \-s , +it is a symbolic link, a small file that holds a path to +.IR target . +This +.B ln +is the +.BR busybox (1) +applet, which has fewer options than GNU +.BR ln ; +see +.BR NOTES . +.SS Operands +With one operand, +.B ln +makes the link in the current directory, named after the last component +of +.IR target , +so that +.B ln ../lib/util.h +makes +.IR util.h . +That name is then treated as the +.I link +operand below, so if a directory of that name exists, the link is made +inside it. +.PP +With more operands, the last is +.IR link . +If it is an existing directory, or a symbolic link or junction to one, +each +.I target +is linked into it, under the last component of the +.IR target . +Otherwise +.I link +is the new name, and only one +.I target +is expected. +.B ln +does not check this: it links each +.I target +to the same name in turn. +The first makes the link, and each other fails with +.BR "File exists" . +With +.BR \-f , +each replaces the one before, so the last wins. +.PP +The last component of a +.I target +is found after removing trailing slashes and backslashes. +A name that is already taken is an error, unless +.B \-f +or +.B \-b +is given. +Each +.I target +is processed on its own: an error is reported, and the remaining +targets are still linked. +.SS Hard links +.I target +must exist, though a symbolic link whose own target is missing counts as +existing. +It cannot be a directory. +The file system must support hard links, and +.I link +must be on the same volume. +All names of a file share its contents and attributes, such as read-only. +.SS Symbolic links +With +.BR \-s , +.I target +need not exist. +It is stored as written, except that slashes become backslashes. +Windows resolves a relative +.I target +from the directory that holds +.IR link , +not from the current directory, so +.B ln \-s src/a.c build +makes +.I build/a.c +point to +.IR build/src/a.c . +.PP +Windows has file links and directory links. +.B ln +makes a directory link when +.I target +is an existing directory at that moment, looked up where Windows will +resolve it, and a file link otherwise, even if +.I target +does not exist yet. +Windows does not follow a file link as a directory, so make the link +again after creating the directory. +.SS Output +.B ln +writes nothing, except with +.BR \-v . +It reports each failure to make a link on standard error as +.PP +.RS 4 +.EX +ln: \fIname\fR: \fIreason\fR +.EE +.RE +.PP +where +.I name +is the link that could not be made, or a hard link +.I target +that does not exist. +.SH OPTIONS +Options may be grouped, as in +.BR \-sf , +and may follow operands, unless +.B POSIXLY_CORRECT +is set. +The argument of +.B \-S +may be attached, as in +.BR \-S.bak , +or be the next argument. +.B \-\- +ends the options. +There are no long options. +.TP +.B \-s +Make symbolic links instead of hard links. +Windows allows this only in Developer Mode or with the privilege to +create symbolic links; see +.BR NOTES . +.TP +.B \-f +Delete an existing +.I link +first. +A read-only file is deleted too, after its read-only attribute is +cleared, which every hard link to the file shares. +A failure to delete is not reported, and the new link then fails if the +name is still taken. +.IP +The deletion comes before the new link is made, so the old +.I link +is lost if that fails, as it does when symbolic links are not permitted. +.B ln +does not check that +.I link +and +.I target +are the same file, so +.B ln \-f x x +deletes +.IR x . +For a hard link, a +.I target +that does not exist is found first, and nothing is deleted. +.TP +.B \-n +When +.I link +is a symbolic link or junction to a directory, treat it as an ordinary +name instead of linking into the directory. +With +.BR \-f , +the symbolic link or junction itself is deleted and replaced, and the +directory is left alone. +This has no effect when +.I link +is itself a directory. +.B \-T +implies it. +.TP +.B \-b +Before making the link, rename an existing +.I link +to its name followed by a suffix, which is +.B ~ +unless +.B \-S +gives another. +An existing file with the backup name is replaced. +If +.I link +does not exist, nothing is renamed and that is not an error. +Any other failure to rename is reported, and the +.I target +is skipped. +Overrides +.BR \-f . +.TP +.BI "\-S " suffix +Use +.I suffix +instead of +.B ~ +for the name of a backup. +This does not make backups by itself. +.TP +.B \-T +Treat +.I link +as the name of the link, never as a directory to link into. +A symbolic link or junction to a directory is not followed, as with +.BR \-n , +so it counts as an existing name. +A real directory is an error, and so are more than two operands. +.TP +.B \-v +Write +.BI \(aq link "\(aq \-> \(aq" target \(aq +on standard output for each link before it is made, so links that then +fail are written too. +.TP +.B \-\-help +As the first argument only, write a usage message on standard output +and exit with status 0. +The message lists a +.B \-t +option, which +.B ln +does not accept. +.SH ENVIRONMENT +.TP +.B BB_CRITICAL_ERROR_DIALOGS +When it is +.BR 1 , +Windows shows its critical-error dialogs, such as for a drive with no +disk in it, instead of the operation failing with an error. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when busybox starts, for a caller +such as +.B cmd.exe +that does not expand them. +When it is unset, busybox sets it to +.B 0 +for the programs it starts, so commands run from the kit's shell get the +shell's expansion only. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Messages written to a console also depend on +.BR BB_SKIP_ANSI_EMULATION , +.BR BB_TERMINAL_MODE , +.BR CONEMUPID , +.BR LANG , +.BR LC_ALL , +and +.BR LC_CTYPE , +as for every busybox applet; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every link was made. +.TP +.B 1 +An invalid command line, with a usage message on standard error, an +error with +.BR \-T , +or any link that could not be made. +.SH EXAMPLES +Keep a second name for a file: +.PP +.RS 4 +.EX +$ ln data.txt backup.txt +.EE +.RE +.PP +Link two programs into a directory, listing each link: +.PP +.RS 4 +.EX +$ ln \-v a.exe b.exe bin +\(aqbin/a.exe\(aq \-> \(aqa.exe\(aq +\(aqbin/b.exe\(aq \-> \(aqb.exe\(aq +.EE +.RE +.PP +Link a header into the current directory: +.PP +.RS 4 +.EX +$ ln ../common/util.h +.EE +.RE +.PP +Make a symbolic link. +The target is relative to the directory that holds the link: +.PP +.RS 4 +.EX +$ ln \-s ../lib/libfoo.dll bin/libfoo.dll +.EE +.RE +.PP +Point a symbolic link to a different directory, replacing the link +instead of linking into its old target: +.PP +.RS 4 +.EX +$ ln \-sfn gcc\-15 current +.EE +.RE +.PP +Replace a file with a link to another, keeping the old file as +.IR app.cfg.bak : +.PP +.RS 4 +.EX +$ ln \-b \-S .bak app.new app.cfg +.EE +.RE +.SH NOTES +Differences from GNU +.BR ln : +.IP \(bu 2 +Long options, such as +.BR \-\-backup , +and the options +.BR \-d , +.BR \-F , +.BR \-i , +.BR \-L , +.BR \-P , +.BR \-r , +and +.B \-t +are invalid. +.IP \(bu 2 +The same file is not detected. +.B ln \-f x x +deletes +.IR x , +and so does +.B ln \-f x +with one operand. +.B ln \-b x x +renames +.I x +to +.IR x~ , +and then fails. +Windows file names are not case sensitive by default, so +.B ln \-f x X +also deletes +.IR x . +.IP \(bu 2 +Several targets are not checked to have a directory as +.IR link ; +see +.BR Operands . +.IP \(bu 2 +.B \-v +writes each line before the link is made. +.PP +Hard links need no privilege, but a directory cannot be hard linked: +that fails with +.BR "Permission denied" . +Creating a symbolic link needs Developer Mode or the privilege to create +symbolic links, which an elevated administrator has, and otherwise fails +with +.BR "Permission denied" . +Windows XP has no symbolic links, so there +.B \-s +always fails. +With +.B \-f +or +.BR \-b , +the old link is then already deleted or renamed. +.PP +A junction, as made by +.BR jn (1), +is followed like a symbolic link to decide whether +.I link +is a directory, and +.B \-n +and +.B \-T +treat it as an ordinary name. +.B ln +cannot make junctions. +.PP +Paths may have drive letters and backslashes. +Names in a directory are joined with a slash, so +.B ln \-v x \(aqdir\e\(aq +writes +.BR \(aqdir\e/x\(aq . +A name made from a +.I target +is what follows its last slash, backslash, or drive prefix. +A bare drive such as +.I c: +names the current directory of that drive, so +.B ln x c: +makes +.IR c:x . +Names may contain any Unicode character on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +A full path of 260 or more characters, counting the current directory +for a relative path, fails. +.PP +From +.BR cmd.exe , +.B ln +expands wildcards in its arguments itself; see +.BR BB_GLOBBING . +.SH SEE ALSO +.BR busybox (1), +.BR cp (1), +.BR jn (1), +.BR ls (1), +.BR readlink (1) diff --git a/man/man1/logname.1 b/man/man1/logname.1 new file mode 100644 index 0000000..e6d2750 --- /dev/null +++ b/man/man1/logname.1 @@ -0,0 +1,170 @@ +.TH LOGNAME 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +logname \- print the login name of the current user +.SH SYNOPSIS +.B logname +.SH DESCRIPTION +.B logname +prints the name of the current user, followed by a newline, on standard +output. +It takes no operands. +.PP +The name is the account name that Windows reports for the process, as +the Windows API function +.B GetUserName +returns it. +It has no domain, keeps the case that Windows gives it, and has each +space replaced by an underscore. +.BR id (1) +and +.BR whoami (1) +use the same name for the current user, but in a process that is +elevated and has the Administrators group enabled they print +.B root +instead, as +.BR id (1) +describes. +.B logname +always prints the account name. +.PP +The name does not come from the environment, so setting +.BR LOGNAME , +.BR USER , +or +.B USERNAME +does not change it. +.SH OPTIONS +.B logname +takes no options. +Any argument other than +.B \-\-help +as the first argument, including +.BR \-\- , +a lone +.BR \- , +and +.BR \-\-version , +is rejected with a usage message on standard error and exit status 1. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +.SH ENVIRONMENT +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An argument other than a first +.BR \-\-help , +or a failure to get the name. +.TP +.B 255 +The output could not be written. +No message is printed. +.PP +A rejected argument is reported with a usage message on standard error. +A failure to get the name is reported on standard error as +.PP +.RS 4 +.EX +logname: getlogin: \fIreason\fR +.EE +.RE +.PP +where +.I reason +is +.B "Result too large" +for a name that is too long, as described in +.BR NOTES . +When Windows does not supply the name at all, busybox records no +reason, so the message shows an unrelated reason or ends at +.BR getlogin . +.SH EXAMPLES +Print the name of the current user: +.PP +.RS 4 +.EX +$ logname +jdoe +.EE +.RE +.PP +The environment does not change the result: +.PP +.RS 4 +.EX +$ USER=nobody LOGNAME=nobody logname +jdoe +.EE +.RE +.PP +For an account named +.BR "Jane Doe" , +each space becomes an underscore: +.PP +.RS 4 +.EX +$ logname +Jane_Doe +.EE +.RE +.PP +Name a directory after the current user: +.PP +.RS 4 +.EX +$ mkdir "build-$(logname)" +.EE +.RE +.SH NOTES +Differences from POSIX and GNU +.BR logname : +.IP \(bu 2 +There is no login record to read. +The result is the name of the account that Windows reports for the +process, and no terminal is needed. +.IP \(bu 2 +There is no +.BR \-\-version , +and +.B \-\-help +is recognized only as the first argument. +.PP +For an account name with spaces the result differs from the +.B USERNAME +variable, which keeps the spaces. +.PP +The user name is read in the ANSI code page, which is UTF-8 on Windows 10 +version 1903 and later, so on those versions it may contain any Unicode +characters. +On older versions it is limited to the system code page. +A name of 64 bytes or more is not printed and fails with +.BR "Result too large" , +and one of 100 bytes or more cannot be read at all; see +.BR "EXIT STATUS" . +.PP +The output line ends with LF, not CRLF. +When standard output is a console, a name with non-ASCII characters is +converted for display from the ANSI code page, unless the variables in +.B ENVIRONMENT +say otherwise. +.SH SEE ALSO +.BR busybox (1), +.BR id (1), +.BR whoami (1) diff --git a/man/man1/ls.1 b/man/man1/ls.1 new file mode 100644 index 0000000..089ccf3 --- /dev/null +++ b/man/man1/ls.1 @@ -0,0 +1,805 @@ +.TH LS 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +ls \- list directory contents +.SH SYNOPSIS +.B ls +.RI [ options ] +.RI [ file ...] +.SH DESCRIPTION +.B ls +lists the files named by its +.I file +operands, and the entries of the directories among them. +With no +.IR file , +it lists the current directory. +This +.B ls +is the busybox applet; see +.BR busybox (1). +.PP +Operands that are not directories are listed first, as one group. +Each directory follows, with its entries. +Both are sorted; see +.BR Sorting . +When there is more than one operand, or with +.BR \-R , +each directory's entries are preceded by a line holding its name and a +colon. +A blank line separates the groups. +An operand that cannot be examined is reported on standard error and +skipped, and the rest are still listed. +.PP +An operand that is a symbolic link is followed, so that the directory it +names is listed, unless +.BR \-l , +.BR \-i , +.BR \-s , +or +.B \-F +is given, in which case the link itself is listed. +.B \-H +and +.B \-L +follow links whatever else is given. +.PP +Entries whose names begin with a dot are not listed, and neither are +entries with the hidden attribute. +.B \-a +and +.B \-A +list them. +An operand is always listed. +.SS Formats +.B \-1 +writes one name per line, +.B \-C +writes columns filled from the top down, +.B \-x +writes columns filled from the left across, and +.B \-l +writes the long format, one file per line. +Of +.BR \-1 , +.BR \-C , +.BR \-x , +and +.BR \-l , +the last one given applies, except that +.B \-l +prevails over +.BR \-1 . +With none of them, the format is +.B \-C +when standard output is a console, and +.B \-1 +otherwise. +.PP +In the column formats, each column is as wide as the longest name plus +two spaces, and as many columns are written as fit in the line width, +which +.B \-w +sets. +The indicators of +.B \-F +and +.B \-p +are not counted in a name's length. +.PP +In every format, a name is preceded by its inode number with +.BR \-i , +and then by its allocated size, in units of 1024 bytes, with +.BR \-s . +.SS Long format +Each line has these fields, separated by spaces, followed by the name: +.IP \(bu 2 +The mode: a type character, then three triples of +.BR r , +.BR w , +and +.B x +for owner, group, and other, with +.B \- +for a permission that is absent. +The type is +.B \- +for a file, +.B d +for a directory, +.B l +for a symbolic link, and +.B c +for a device. +.IP \(bu 2 +The number of links. +.IP \(bu 2 +The owner and the group, as names, or as numbers with +.BR \-n . +With +.BR \-g , +only the group. +.IP \(bu 2 +The size in bytes, or as +.B \-h +writes it. +A device has its major and minor numbers, separated by a comma, instead. +.IP \(bu 2 +The time: the modification time, or with +.B \-c +or +.B \-u +another. +It is local time. +A time within the last six months is written as an abbreviated month, +the day, and the hour and minute. +Any other time, including one more than 15 minutes in the future, is +written as the month, the day, and the year. +.B \-\-full\-time +writes +.I yyyy\-mm\-dd hh:mm:ss zone +instead, with the zone as a signed offset from UTC such as +.BR \-0500 , +and no fraction of a second. +.PP +A symbolic link's name is followed by +.B \-> +and its target. +.PP +The listing of a directory with +.B \-l +or +.B \-s +starts with a line +.B total +.IR n , +the allocated sizes of its entries added up and rounded up to a unit of +1024 bytes. +A directory that cannot be opened still gets the line, as +.BR "total 0" . +No such line comes before files named as operands. +.SS Sorting +Entries are sorted by name, comparing bytes, so that +.B Z +comes before +.BR a . +.BR \-S , +.BR \-t , +.BR \-v , +and +.B \-X +sort by another key, and entries that compare equal on it are sorted by +name. +If more than one of them is given, the first in the order +.BR \-S " or " \-t , +.BR \-v , +.B \-X +applies, and +.B \-S +and +.B \-t +cancel each other, so the last of those two given applies. +.B \-r +reverses the result. +.B \-\-group\-directories\-first +takes effect before any key. +.SH OPTIONS +Options may be grouped, as in +.BR \-lah , +and may follow the operands unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +The argument of +.B \-w +or +.B \-T +may be attached, as in +.BR \-w80 , +or be the next argument. +A long option may be abbreviated to a unique prefix. +.TP +.B \-1 +Write one name per line. +This is the default when standard output is not a console. +.TP +.B \-a +List all entries: those whose names begin with a dot, including +.B .\& +and +.BR .. , +and those with the hidden attribute. +.TP +.B \-A +Like +.BR \-a , +but leave out the +.B .\& +and +.B ..\& +entries. +.TP +.BR \-aa ", " \-AA +Like +.B \-a +and +.BR \-A , +but omit files that have both the hidden and the system attribute. +The option must be given twice: neither +.B \-aA +nor +.B "\-a \-A" +counts. +.TP +.B \-C +Write columns, filled from the top down. +This is the default when standard output is a console. +.TP +.B \-x +Write columns, filled from the left across. +.TP +.B \-d +List a directory itself, not its contents. +Every operand is listed as a file. +Cancels +.BR \-R . +.TP +.B \-L +Follow all symbolic links: show the file a link points to in place of +the link. +A link whose target cannot be examined is an error, and is not listed. +.TP +.B \-H +Follow symbolic links named as operands, even with +.BR \-l , +.BR \-i , +.BR \-s , +or +.BR \-F . +Of +.B \-H +and +.BR \-L , +the last one given applies. +.TP +.B \-R +List subdirectories, recursively, after the entries of their parent. +A symbolic link is not entered, unless +.B \-L +is given. +.TP +.B \-p +Append +.B / +to the names of directories. +.TP +.B \-F +Append an indicator to names: +.B / +for a directory, +.B * +for an executable file, and +.B @ +for a symbolic link. +The usage message also lists +.B | +and +.BR = , +for pipes and sockets, which do not occur. +In the long format, a link's name gets no indicator, and its target gets +the one for the target's own type. +.TP +.B \-l +Write the long format; see +.BR Formats . +.TP +.B \-g +Write the long format with one name column, the group, in place of the +owner and group columns. +Implies +.BR \-l . +.TP +.B \-i +Write the inode number before each name. +.TP +.B \-n +Write numeric owner and group, in place of names. +Implies +.BR \-l . +.TP +.B \-s +Write the allocated size of each file, in units of 1024 bytes, before +its name. +.TP +.B \-c +Use the creation time, in place of the modification time, in the long +format and as the key of +.BR \-t . +Without +.BR \-l , +it also implies +.BR \-t . +Of +.B \-c +and +.BR \-u , +the last one given applies. +.TP +.B \-u +Use the last access time, as +.B \-c +uses the creation time. +.TP +.B \-\-full\-time +Write the full date and time in the long format. +Implies +.BR \-l . +.TP +.B \-h +Write sizes in the long format, and the allocated sizes of +.BR \-s , +as a number with one decimal digit and a suffix: +.BR K , +.BR M , +.BR G , +.BR T , +.BR P , +.BR E , +.BR Z , +or +.B Y +for the largest power of 1024 that fits, as in +.BR 1.4M . +A size below 1024 is a plain number. +The number on a +.B total +line has no decimal digit. +.TP +.B \-\-group\-directories\-first +List directories before other entries. +With +.BR \-r , +they come last. +.TP +.B \-S +Sort by size, largest first. +.TP +.B \-X +Sort by extension, which is the text of the name from its first dot +onward. +Names with no dot come first. +.TP +.B \-v +Sort by version: runs of digits in names compare as numbers, so that +.B f9 +comes before +.BR f10 . +.TP +.B \-t +Sort by time, newest first. +The time is the modification time, or the one +.B \-c +or +.B \-u +selects. +.TP +.B \-r +Reverse the sort order. +.TP +.BI "\-w " width +Fit the column formats to +.I width +characters. +The default is one less than +.B COLUMNS +when that is set, or else than the width of the console window of +standard output, or failing that of standard error. +Without either, it is 79. +A +.I width +of 0 means no limit. +.TP +.B \-Q +Enclose names in double quotes. +In a name, a double quote or backslash is preceded by a backslash, +characters 7 to 13 are written as +.BR \ea , +.BR \eb , +.BR \et , +.BR \en , +.BR \ev , +.BR \ef , +and +.BR \er , +and any other byte below 32 or above 126 is written as a backslash and +three octal digits. +Overrides +.BR \-q . +.TP +.B \-q +Write +.B ?\& +in place of each character in a name that is not printable. +This is the default when standard output is a console. +.TP +.B \-k +Accepted for compatibility and ignored. +.TP +.BI "\-T " cols +Accepted for compatibility, and its argument is ignored. +.TP +\fB\-\-color\fR[\fB=\fIwhen\fR] +Write names in color; see +.BR NOTES . +.I when +is one of: +.RS +.TP +.BR always ", " yes ", " force +Use color. +.TP +.BR auto ", " tty ", " if\-tty +Use color when standard output is a console and +.B TERM +is not +.BR dumb . +.TP +.BR never ", " no ", " none +Use no color. +.RE +.IP +Any word that begins with +.B n +means no color, and a unique prefix of any other value is accepted. +Another value leaves the default. +Without +.IR when , +the value is +.BR always . +It must be attached, as in +.BR \-\-color=never . +.IP +Color is on by default when standard output is a console, unless +.B TERM +is +.BR dumb , +.B LS_COLORS +is empty or +.BR none , +or +.B NO_COLOR +is set and not empty. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_FIX_BACKSLASH +When it is +.BR 1 , +backslashes in the operands are changed to forward slashes, so that the +names written have forward slashes. +.TP +.B BB_UMASK +The file mode creation mask, in octal. +Its bits +.B 020 +and +.B 002 +remove the write permission of group and of other from the modes +.B ls +writes; see +.BR NOTES . +.TP +.B COLUMNS +The width of the output, in place of the width of the console window; see +.BR \-w . +A value outside the range 2 to 29999 is taken as 80. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +When names are UTF-8 (see +.BR NOTES ) +and the first of these that is set has the value +.BR C , +a byte of a name above 127 counts as not printable for +.BR \-q . +.TP +.B LS_COLORS +When it is empty or +.BR none , +color is not on by default. +Its value is otherwise ignored: the colors are fixed. +.TP +.B NO_COLOR +When it is set and not empty, color is not on by default. +It does not affect +.BR \-\-color . +.TP +.B POSIXLY_CORRECT +When set, the first operand ends the options. +.TP +.B TERM +When it is +.BR dumb , +color is not on by default, and +.B \-\-color=auto +gives none. +.TP +.B TZ +The time zone for the times written in the long format. +.PP +Variables that affect every busybox applet, such as +.B BB_GLOBBING +and +.BR BB_TERMINAL_MODE , +are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An operand or an entry of a directory could not be examined, a +directory could not be opened, or an option or the argument of +.B \-w +was invalid. +.TP +.B 141 +Standard output is a pipe that was closed before all output was written. +.PP +After a failure to examine or open something, +.B ls +reports it on standard error and carries on. +A file that cannot be examined is reported as +.PP +.RS 4 +.EX +ls: \fIname\fR: \fIreason\fR +.EE +.RE +.PP +A directory that cannot be opened is reported as +.PP +.RS 4 +.EX +ls: can\(aqt open \(aq\fIname\fR\(aq: \fIreason\fR +.EE +.RE +.PP +An invalid option prints a message and the usage on standard error. +.SH EXAMPLES +List a directory in the long format: +.PP +.RS 4 +.EX +$ ls \-l +total 44 +\-rw\-rw\-r\-\- 1 user user 5 Oct 17 09:05 Makefile +drwxrwxr\-x 2 user user 0 Oct 19 08:20 build +\-rw\-rw\-r\-\- 1 user user 26 Oct 19 08:12 main.c +\-rwxrwxr\-x 1 user user 30720 Oct 19 08:20 main.exe +drwxrwxr\-x 2 user user 0 Oct 19 08:20 src +\-rw\-rw\-r\-\- 1 user user 412 Oct 18 17:40 util.c +.EE +.RE +.PP +Mark directories and executables, in a console: +.PP +.RS 4 +.EX +$ ls \-F +Makefile build/ main.c main.exe* src/ util.c +.EE +.RE +.PP +List the largest files first, with sizes people can read: +.PP +.RS 4 +.EX +$ ls \-lSh +.EE +.RE +.PP +List a directory itself, not its contents: +.PP +.RS 4 +.EX +$ ls \-ld build +.EE +.RE +.PP +List everything, including hidden files, newest first: +.PP +.RS 4 +.EX +$ ls \-lat +.EE +.RE +.PP +Page a colored listing, keeping the colors: +.PP +.RS 4 +.EX +$ ls \-\-color=always \-lR | less \-R +.EE +.RE +.PP +List the root of a drive: +.PP +.RS 4 +.EX +$ ls C:/ +.EE +.RE +.SH NOTES +Modes are made up from file attributes, not from the access control +list. +Every file is readable, and writable unless it has the read-only +attribute. +A file is executable if its name ends in +.BR .com , +.BR .exe , +.BR .sh , +.BR .bat , +or +.BR .cmd , +in any case. +Otherwise, unless its name ends in +.B .dll +or its data is held remotely, as for a cloud file not yet downloaded, +.B ls +reads its first bytes, and the file is executable if it begins with +.B #!\& +or is a PE program that is not a DLL. +This makes the listing of many files slower, though +.B ls +tries to leave the access time unchanged. +A directory is readable, writable, and searchable. +For a file or directory, the three triples of a mode are the same, +except that the write permission of group and of other is removed when +the file mode creation mask has its bit. +The default mask is +.BR 002 , +so other cannot write; see +.B BB_UMASK +in +.BR busybox (1). +For a file owned by another account, the permissions of other are raised +to those of the owner when the file's access control list gives the +current user read, write, and execute access, except in an elevated +process. +.PP +The devices that busybox emulates, such as +.IR /dev/null , +may be named as operands, though +.I /dev +itself cannot be listed. +Each is a character device owned by the current user, with the mode +.BR crw\-rw\-rw\- , +the numbers 0, 0, and the time of the Unix epoch. +Symbolic links, junctions, volume mount points, and app execution +aliases are all shown as symbolic links. +A link has every permission, and its size is the length of its target's +name. +.PP +There are no groups: the group of a file is its owner. +A file owned by the current user shows that user's name, with spaces +replaced by underscores, or 4095 with +.BR \-n . +The owner of another local or domain account is shown as the number +that ends its security identifier, when that is from 500 to 4094. +Any other owner, such as Administrators, SYSTEM, or TrustedInstaller, is +shown as +.B root +or 0. +A file whose security descriptor cannot be opened is owned by root, and +has no permissions for other. +.PP +The number of links of a file is its number of hard links. +That of a directory is 2 plus its number of subdirectories, not counting +symbolic links and junctions, and a link to a directory shows the count +of its target. +The inode number is the file index that Windows reports, which is 0 for +a device. +.PP +The modification time is the last write time. +Windows has no time of last change to a file's status, so +.B \-c +uses the creation time. +.PP +Allocated sizes estimate the space on disk. +Windows gives no cluster size, so +.B ls +assumes 4096 bytes and rounds every nonempty file up to a multiple of +that. +A compressed or sparse NTFS file counts the space it occupies, which can +be much less than its length. +A symbolic link counts as 4096 bytes. +A directory counts the size Windows reports for it, rounded up in the +same way, which is 0 for a small NTFS directory. +.PP +Names are UTF-8 on Windows 10 version 1903 or later; see +.BR busybox (1). +They sort by byte value, so that uppercase letters come before lowercase +ones, and accented letters after +.BR z . +.PP +Each colored name is written between a sequence that selects its color +and the sequence +.B ESC[m +that resets it. +The sequences are +.B ESC[1;32m +for an executable file, +.B ESC[1;34m +for a directory, +.B ESC[1;36m +for a symbolic link, +.B ESC[1;35m +for a device, and +.B ESC[0;0m +for any other file. +In the long format, the target of a link is colored for its own type, +or with +.B ESC[1;31m +when it does not exist. +.PP +Operands may use +.B / +or +.BR \e , +and are written as given. +A directory name of 258 bytes or more cannot be listed. +A bare drive such as +.B C: +lists the current directory of that drive, and +.B C:/ +lists its root. +.PP +A console is a Windows console window; a pipe or a file is not one. +.PP +When started from +.BR cmd.exe , +.B ls +expands wildcards in its operands; see +.BR busybox (1). +.PP +Differences from GNU +.BR ls : +.IP \(bu 2 +Options +.BR \-b , +.BR \-f , +.BR \-G , +.BR \-I , +.BR \-m , +.BR \-N , +.BR \-o , +.BR \-U , +and +.BR \-Z , +and every long option but +.BR \-\-color , +.BR \-\-full\-time , +and +.BR \-\-group\-directories\-first , +do not exist. +.IP \(bu 2 +The colors are fixed. +.IP \(bu 2 +Names are sorted bytewise, whatever the locale. +.IP \(bu 2 +Lines end with LF, not CRLF. +.IP \(bu 2 +Columns are separated with spaces, never tabs. +.SH SEE ALSO +.BR busybox (1), +.BR chmod (1), +.BR du (1), +.BR find (1), +.BR less (1), +.BR ln (1), +.BR lsattr (1), +.BR stat (1) diff --git a/man/man1/lsattr.1 b/man/man1/lsattr.1 new file mode 100644 index 0000000..126bf62 --- /dev/null +++ b/man/man1/lsattr.1 @@ -0,0 +1,343 @@ +.TH LSATTR 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +lsattr \- list Windows file attributes +.SH SYNOPSIS +.B lsattr +.RB [ \-Radl ] +.RI [ file ...] +.SH DESCRIPTION +.B lsattr +lists the Windows file attributes of each +.IR file , +such as read-only, hidden, and compressed. +With no +.IR file , +it lists the current directory. +.BR chattr (1) +changes some of the attributes. +.PP +A +.I file +that is a directory is not listed itself. +Its entries are listed instead, without descending into subdirectories; +see +.B \-d +and +.BR \-R . +A symbolic link or junction is listed itself, never its target or the +entries of its target, even when it is named on the command line, +unless that name ends in a slash or backslash. +A junction, or a symbolic link to a directory, named that way, as in +.IR jn/ , +is treated as a plain directory: its entries are listed, and with +.B \-d +its first attribute position shows +.B R +and +.B \-l +shows +.BR Reparse_Point . +.PP +Each line of output is an attribute field, a space, and a name. +The name of a +.I file +is printed as given. +The name of an entry in a directory is the name of the directory, a +slash, and the name of the entry, with the slash omitted if the +directory's name already ends in one or is a bare drive, as in +.IR C:main.c . +A trailing backslash does not count: the entries of +.I proj\e +are named like +.IR proj\e/main.c . +Names are never converted, so backslashes and drive letters stay as +typed. +Entries are listed in the order the file system returns them; +.B lsattr +does not sort. +Entries whose names begin with a dot are skipped unless +.B \-a +is given. +The hidden and system attributes do not hide an entry. +.PP +Files are processed in order. +A file that cannot be found, or an entry that cannot be examined, is +reported on standard error as +.PP +.RS 4 +.EX +lsattr: can\(aqt stat \(aq\fIfile\fR\(aq: \fIreason\fR +.EE +.RE +.PP +and the remaining files are still processed. +A device, such as +.IR /dev/null , +has no attributes and is reported as +.PP +.RS 4 +.EX +lsattr: reading \fIfile\fR +.EE +.RE +.PP +This message may end with a reason left over from an earlier failure, +which does not apply. +A directory that cannot be opened is skipped without a message. +.SS Attribute field +The field has one position for each attribute shown, in the order below. +A position holds the attribute's letter if the file has the attribute and +a hyphen if it does not, so a file with none of them shows 11 hyphens. +.TP +.BR j ", " l ", " A ", " R +The first position. +It is +.B j +for a junction, +.B l +for a symbolic link, +.B A +for an app execution link, such as those in +.IR $LOCALAPPDATA/Microsoft/WindowsApps , +and +.B R +for any other reparse point, such as a cloud storage placeholder. +.TP +.B o +Offline. +.TP +.B e +Encrypted. +.TP +.B c +Compressed. +.TP +.B S +Sparse. +.TP +.B r +Read-only. +.TP +.B h +Hidden. +.TP +.B s +System. +.TP +.B a +Archive. +.TP +.B t +Temporary. +.TP +.B n +Not content indexed. +.PP +No other attribute is shown. +A directory has no letter of its own. +.SH OPTIONS +Options may be grouped, as in +.BR \-aR , +and may follow the operands unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options, for a +.I file +whose name begins with a dash. +.TP +.B \-R +Recurse: list the entries of each subdirectory found in a directory +that is listed. +After the line for the subdirectory, +.B lsattr +prints a blank line, the subdirectory's name followed by a colon, the +subdirectory's entries, and another blank line, and then goes on with +the rest of the parent's entries. +The directory named on the command line gets no such heading. +The +.B .\& +and +.B ..\& +entries, symbolic links, and junctions are not entered, and a +subdirectory whose name begins with a dot is entered only with +.BR \-a . +The heading of a subdirectory that cannot be opened is still printed, +followed by no entries. +With +.BR \-d , +nothing is entered. +.TP +.B \-a +List entries whose names begin with a dot, including the +.B .\& +and +.B ..\& +entries. +Both are listed in every directory, even the root directory of a drive, +where the file system does not return them. +.TP +.B \-d +List a directory named on the command line itself, instead of its +entries. +.TP +.B \-l +Print the names of the attributes instead of the attribute field. +Each line is the file's name padded with spaces to 28 bytes, a space, +and the names of the attributes the file has, separated by a comma and a +space, in the order of the attribute field. +A name of 28 bytes or more is followed by just the one space. +The names, in that order, are +.BR Reparse_Point , +.BR Offline , +.BR Encrypted , +.BR Compressed , +.BR Sparse , +.BR Read_Only , +.BR Hidden , +.BR System , +.BR Archive , +.BR Temporary , +and +.BR Not_Indexed . +A symbolic link, junction, or app execution link shows +.BR Symbolic_Link , +.BR Junction , +or +.B App_Exec_Link +instead of +.BR Reparse_Point . +A file with none of the attributes shows +.BR \-\-\- . +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Variables that busybox-w32 reads in every applet, such as those that +control console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +Files that could not be found or listed do not affect the status. +.TP +.B 1 +An invalid option, with a usage message on standard error. +.SH EXAMPLES +Show the attributes of a directory itself, and of a file in it: +.PP +.RS 4 +.EX +$ lsattr \-d proj proj/main.c +\-\-\-\-\-\-\-\-\-\-\- proj +\-\-\-\-\-\-\-\-a\-\- proj/main.c +.EE +.RE +.PP +List a directory tree. +The listing of a subdirectory comes right after its own line: +.PP +.RS 4 +.EX +$ lsattr \-R proj +\-\-\-\-\-\-\-\-\-\-\- proj/include +\& +proj/include: +\-\-\-\-\-r\-\-a\-\- proj/include/util.h +\& +\-\-\-\-\-\-\-\-a\-\- proj/main.c +.EE +.RE +.PP +Show attribute names instead of letters: +.PP +.RS 4 +.EX +$ lsattr \-l proj/include/util.h +proj/include/util.h Read_Only, Archive +.EE +.RE +.PP +List the files with the hidden attribute in a tree, dot files included: +.PP +.RS 4 +.EX +$ lsattr \-aR | grep \(aq^......h.... \(aq +.EE +.RE +.PP +Find the symbolic links and junctions in a tree: +.PP +.RS 4 +.EX +$ lsattr \-R src | grep \(aq^[jl]\(aq +.EE +.RE +.SH NOTES +Differences from the e2fsprogs +.B lsattr +on Linux: +.IP \(bu 2 +The attributes are Windows file attributes, not ext2 inode flags, and +the letters mean different things: +.B a +is archive, not append-only, and +.B s +is system, not secure deletion. +.IP \(bu 2 +There is no +.B \-p +or +.BR \-v ; +both are invalid options. +.IP \(bu 2 +Errors on individual files do not change the exit status. +.PP +Of the attributes that +.B lsattr +shows, +.BR chattr (1) +can change only +.BR r , +.BR h , +.BR s , +.BR a , +.BR t , +and +.BR n . +.PP +File names may use drive letters and backslashes. +A bare drive such as +.I C: +names the current directory of that drive. +On Windows 10 version 1903 or later, file names may contain any Unicode +characters, and on older systems only those of the system code page. +A path of 260 or more characters, counting the current directory when the +path is relative, cannot be examined and is reported as +.B can\(aqt stat +like a missing file. +.PP +The padding for +.B \-l +counts bytes, not characters, so a name with non-ASCII characters is +followed by fewer spaces. +.SH SEE ALSO +.BR busybox (1), +.BR chattr (1), +.BR ls (1) diff --git a/man/man1/lzcat.1 b/man/man1/lzcat.1 new file mode 100644 index 0000000..fa38a8c --- /dev/null +++ b/man/man1/lzcat.1 @@ -0,0 +1 @@ +.so man1/lzma.1 diff --git a/man/man1/lzma.1 b/man/man1/lzma.1 new file mode 100644 index 0000000..757d7a0 --- /dev/null +++ b/man/man1/lzma.1 @@ -0,0 +1,322 @@ +.TH LZMA 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +lzma, unlzma, lzcat \- decompress .lzma files +.SH SYNOPSIS +.B unlzma +.RB [ \-cdfkqtv ] +.RI [ file ...] +.br +.B lzma +.RB { \-d | \-t } +.RB [ \-cfkqv ] +.RI [ file ...] +.br +.B lzcat +.RB [ \-cdfkqtv ] +.RI [ file ...] +.SH DESCRIPTION +.B unlzma +decompresses each +.I file +in the legacy +.B .lzma +format of LZMA Utils and the LZMA SDK, and replaces it with a file of the +same name without the +.B .lzma +suffix. +.B lzma +is the same, but requires +.B \-d +or +.BR \-t : +it cannot compress, and without either option it prints a usage message +and fails. +.B lzcat +is +.BR "unlzma \-c" : +it writes the decompressed data of each +.IR file , +in order, to standard output. +.PP +With no +.I file +operands, or for a +.I file +named +.BR \- , +the program reads standard input and writes standard output. +When standard input is a console, it exits with an error unless +.B \-f +is given. +.PP +When decompressing to files, a +.I file +whose name does not end in +.B .lzma +is reported and skipped. +With +.B \-c +or +.BR \-t , +any name is accepted. +The output file is created next to +.IR file , +read-only if +.I file +is, and must not already exist unless +.B \-f +is given. +Its modification time is the current time. +Once the output is complete, +.I file +is deleted, unless +.BR \-c , +.BR \-k , +or +.B \-t +is given. +If the data is invalid or the output cannot be written, the partial +output file is deleted, +.I file +is kept, and the next +.I file +is processed. +With +.BR \-c , +data decoded before the failure may already have been written. +A +.I file +that ends early after its header, or whose dictionary does not fit in +memory, instead ends the program at once, leaving its partial output +file in place. +.PP +A +.B .lzma +file is a 13-byte header, holding the coding properties, the dictionary +size, and the decompressed size, followed by one LZMA stream. +When the header gives no size, the stream ends with an end marker. +Decoding stops at the size or the marker, and any data after it is +ignored, so only the first of several concatenated files is +decompressed. +The format has no checksum, so damage is detected only where it makes +the stream invalid. +An +.B .xz +file is rejected; decompress it with +.BR xz (1). +.SH OPTIONS +Options may be grouped, as in +.BR \-dk , +and may follow +.I file +operands unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +All three names accept every option. +.TP +.B \-c +Write the decompressed data to standard output instead of to files, and +keep the input files. +Implied by +.BR lzcat . +.TP +.B \-d +Decompress. +Required by +.B lzma +unless +.B \-t +is given, and otherwise ignored. +.TP +.B \-f +Force: delete an existing output file, even a read-only one, before +writing it, and allow reading compressed data from a console. +.TP +.B \-k +Keep the input files. +.TP +.B \-q +Accepted and ignored. +Errors are still reported. +.TP +.B \-t +Test: decompress each +.I file +and discard the output, keeping the input files. +Overrides +.BR \-c . +.TP +.B \-v +For each +.I file +decompressed to an output file, report on standard error the space +saved, as a percentage of the decompressed size rounded up: +.RS +.PP +.EX +notes.txt.lzma: 53% \- replaced with notes.txt +.EE +.RE +.IP +The line is the same with +.BR \-k , +although nothing is replaced. +When the compressed file is the larger, the percentage is a meaningless +large number. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +The other +.B BB_ +variables described in +.BR busybox (1) +apply to this command as to every applet. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the command line are expanded at startup, for callers such +as +.B cmd.exe +that do not expand them. +A busybox program started without this variable, such as the kit's +shell, sets it to +.BR 0 , +so the commands it runs do not expand their arguments again. +.TP +.B BB_UMASK +An octal file mode creation mask applied at startup. +Only the owner write bit, +.BR 200 , +has an effect here: a mask with it, such as +.BR 222 , +creates output files read-only. +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options, and later arguments that begin with +.B \- +are file names. +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid option, +.B lzma +without +.B \-d +or +.BR \-t , +or a failure with any input: it could not be read or is a console, its +name lacks the +.B .lzma +suffix, its output file exists, its data is invalid or truncated, memory +ran out, or its output could not be written. +.SH EXAMPLES +Decompress a file, replacing it with +.IR notes.txt : +.PP +.RS 4 +.EX +$ unlzma notes.txt.lzma +.EE +.RE +.PP +Decompress a file and keep the original: +.PP +.RS 4 +.EX +$ unlzma \-k notes.txt.lzma +.EE +.RE +.PP +Read a compressed file without decompressing it to disk: +.PP +.RS 4 +.EX +$ lzcat notes.txt.lzma | less +.EE +.RE +.PP +Check every +.B .lzma +file in the current directory: +.PP +.RS 4 +.EX +$ lzma \-t *.lzma +.EE +.RE +.PP +Extract a compressed tar archive, which +.BR tar (1) +recognizes by its suffix: +.PP +.RS 4 +.EX +$ tar \-xf src.tar.lzma +.EE +.RE +.SH NOTES +Differences from the +.BR lzma , +.BR unlzma , +and +.B lzcat +of XZ Utils: +.IP \(bu 2 +There is no compression, so +.B lzma +requires +.B \-d +or +.BR \-t . +.IP \(bu 2 +The only recognized suffix is +.BR .lzma ; +.B .tlz +is not. +.IP \(bu 2 +The output file gets the current time, not the input's modification +time. +.IP \(bu 2 +There are no long options except +.BR \-\-help , +and +.B \-q +has no effect. +.PP +The suffix is matched case-sensitively, so +.I NOTES.LZMA +is rejected although Windows file names ignore case. +A read-only input file is deleted after decompression like any other, +and +.B \-f +replaces a read-only output file. +.PP +A +.B \- +operand after a +.I file +operand does not read standard input, and fails. +.PP +Decompression holds the dictionary in memory, up to the decompressed +size, and a dictionary may be as large as 4 GiB. +A file with a huge dictionary can fail with +.BR "out of memory" , +particularly in the 32-bit kit, where busybox has 2 GiB of address +space. +.SH SEE ALSO +.BR busybox (1), +.BR bzip2 (1), +.BR gzip (1), +.BR tar (1), +.BR xz (1), +.BR zstd (1) diff --git a/man/man1/lzop.1 b/man/man1/lzop.1 new file mode 100644 index 0000000..261c2cc --- /dev/null +++ b/man/man1/lzop.1 @@ -0,0 +1,305 @@ +.TH LZOP 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +lzop, unlzop, lzopcat \- compress or expand files in lzop format +.SH SYNOPSIS +.B lzop +.RB [ \-cdfkqtUv123456CF ] +.RI [ file ...] +.br +.B unlzop +.RB [ \-cfkqtUvF ] +.RI [ file ...] +.br +.B lzopcat +.RB [ \-ftF ] +.RI [ file ...] +.SH DESCRIPTION +.B lzop +compresses each +.I file +with the LZO1X algorithm, or with +.B \-d +decompresses it. +.B unlzop +is +.BR "lzop \-d" , +and +.B lzopcat +is +.BR "lzop \-dc" . +All three accept the same options. +.PP +When compressing, the output file is +.I file +with +.B .lzo +appended, even when it already ends in +.BR .lzo . +When decompressing, a final +.B .lzo +is removed, and any other name gets +.B .out +appended. +The input file is kept unless +.B \-U +is given. +An existing output file is an error unless +.B \-f +is given. +The output file gets the permissions of the input file, and the current +time as its modification time. +.PP +With no +.I file +operands, or for a +.I file +named +.BR \- , +.B lzop +reads standard input and writes standard output. +It refuses to read from a console, even when compressing, unless +.B \-f +is given. +.PP +Data is compressed in blocks of 256 KiB, and a block that does not +shrink is stored uncompressed. +Each block carries an Adler-32 checksum of its uncompressed data, which +is verified when decompressing. +The header records no file name, permissions, or time, and these fields +are ignored in files from other lzop programs. +Decompression accepts files compressed at any level, and also verifies +CRC-32 checksums. +.PP +Only the first compressed stream in a file is read, and anything after +it is silently ignored. +A concatenation of +.B .lzo +files, such as the output of +.B "lzop \-c" +with several files, expands to the first file only. +With +.BR \-U , +the input file is still deleted, and the rest of its data is lost. +.SS Diagnostics +Invalid input is reported with one of these messages: +.TP +.B bad magic number +The input is not in lzop format. +.TP +.BI "header_error " n +The header is invalid or unsupported. +2 means a header checksum mismatch; +3, a format older than lzop 0.94, or a bad extra field; +\-1, 14, and 15, an unknown method or level; +16, a file that requires lzop later than 1.01 or uses a filter; +and \-13, reserved flags set. +.TP +.BR "corrupted data" ", " "checksum error" +A block is damaged. +.TP +.B short read +The input ends early, or reading it fails. +.TP +.B this file is a split lzop file +Split files are not supported. +.SH OPTIONS +Options may be grouped, as in +.BR \-dc , +and may follow the +.I file +operands. +.B \-\- +ends the options. +There are no long options. +Level options have no effect when decompressing. +.TP +.B \-1 +Compress with the LZO1X-1(15) method. +.TP +.BR \-2 " to " \-6 +Compress with the LZO1X-1 method, the default. +These levels are identical. +.TP +.BR \-7 ", " \-8 ", " \-9 +Fail with the message +.BR "high compression not compiled in" . +The output file, if any, has already been created, and is left empty. +With +.BR \-f , +an existing output file has already been deleted. +.TP +.B \-d +Decompress. +.TP +.B \-c +Write to standard output. +The output for several files is concatenated. +Input files are never deleted. +.TP +.B \-f +Replace existing output files, including read-only ones, and allow +reading from a console. +.TP +.B \-U +Delete each input file, including a read-only one, after processing it +successfully. +Ignored with +.B \-c +or +.BR \-t . +.TP +.B \-k +Keep input files. +This is the default, and it overrides +.B \-U +wherever it appears. +.TP +.B \-t +Test: process each input and discard the output, creating and deleting +no files. +With +.BR \-d , +this checks that the files decompress and that their checksums match. +Without +.BR \-d , +.B "lzop \-t" +compresses and discards the result. +.TP +.B \-v +After writing each output file, print +\fIfile\fB: \fIN\fB% \- replaced with \fIoutput\fR +on standard error. +The percentage is meaningless, and the message appears even when the +input is kept. +Nothing is printed with +.B \-c +or +.BR \-t , +or for standard input. +.TP +.B \-q +Accepted and ignored. +.TP +.B \-F +When compressing, store no block checksums, so +.B \-C +has no effect. +When decompressing, do not verify block checksums. +The header checksum is always stored and verified. +.TP +.B \-C +Also store an Adler-32 checksum of each compressed block, which is +verified when decompressing unless +.B \-F +is given. +.TP +.B \-\-help +Print a usage message on standard output and exit. +Recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the command line are expanded at startup, for callers such +as +.B cmd.exe +that do not expand them. +A busybox program started without this variable sets it to +.BR 0 , +so the commands it runs do not expand their arguments again. +.TP +.B BB_UMASK +An octal file mode creation mask applied at startup. +If it includes the owner write bit, +.BR 0200 , +output files are created read-only. +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid option, or an error with any file. +.PP +A file that cannot be opened, or whose output file cannot be created, +is reported and skipped, and the remaining files are still processed. +Any other error, such as invalid input, a level from 7 to 9, or a write +error, stops +.B lzop +at once. +The incomplete output file is left in place, and the input file is not +deleted. +When compressing, a read error is taken as the end of the input, and is +not reported: the output is cut short, the status is 0, and with +.B \-U +the input file is deleted. +.SH EXAMPLES +Compress a file, keeping the original: +.PP +.RS 4 +.EX +$ lzop data.bin +.EE +.RE +.PP +Expand it, overwriting the existing +.IR data.bin : +.PP +.RS 4 +.EX +$ unlzop \-f data.bin.lzo +.EE +.RE +.PP +Check a set of compressed files: +.PP +.RS 4 +.EX +$ lzop \-dt *.lzo +.EE +.RE +.PP +Archive a directory, and extract it again: +.PP +.RS 4 +.EX +$ tar cf \- src | lzop >src.tar.lzo +$ lzopcat src.tar.lzo | tar xf \- +.EE +.RE +.SH NOTES +This +.B lzop +is derived from the original lzop and reads and writes the same format, +but it has fewer options, no levels above 6, and stores no file names, +permissions, or times. +.PP +Data is read and written in binary mode, with no newline translation. +Compressed data is written to a console without complaint. +.PP +The +.B .lzo +suffix is case-sensitive, so +.I DATA.LZO +expands to +.IR DATA.LZO.out . +The output of a read-only file is read-only. +.PP +When decompressing, blocks larger than 64 MiB are rejected as corrupted +data. +.SH SEE ALSO +.BR busybox (1), +.BR bzip2 (1), +.BR gzip (1), +.BR tar (1), +.BR xz (1), +.BR zstd (1) diff --git a/man/man1/lzopcat.1 b/man/man1/lzopcat.1 new file mode 100644 index 0000000..e17dd70 --- /dev/null +++ b/man/man1/lzopcat.1 @@ -0,0 +1 @@ +.so man1/lzop.1 diff --git a/man/man1/man.1 b/man/man1/man.1 new file mode 100644 index 0000000..2566edf --- /dev/null +++ b/man/man1/man.1 @@ -0,0 +1,520 @@ +.TH MAN 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +man \- display manual pages +.SH SYNOPSIS +.B man +.RB [ \-aw ] +.RI [ section ] +\fIpage\fR[\fB.\fIsection\fR]... +.br +.B man +.RB [ \-aw ] +.IR file ... +.SH DESCRIPTION +.B man +shows manual pages. +For each operand it finds a page, formats it with +.BR nroff (1), +and displays the result through a pager. +It is an applet of +.BR busybox (1). +.PP +An operand that contains a slash or a backslash is a +.IR file , +which +.B man +formats as a page without searching. +Any other operand is the name of a +.IR page , +which +.B man +looks for in the manual directories. +A page is written in man(7) or mdoc(7) macros, and may be compressed. +.SS Finding pages +A manual directory holds page sources in subdirectories named +.BR man1 , +.BR man2 , +and so on, and may hold preformatted text pages in +.BR cat1 , +.BR cat2 , +and so on. +The page +.B xxd +in section 1 is the file +.I man1/xxd.1 +in a manual directory, or +.IR cat1/xxd.1 : +the section is part of both the directory name and the file name. +.PP +.B man +searches these manual directories, in order: +.IP 1. 4 +The elements of the +.B MANPATH +environment variable, separated by semicolons. +.IP 2. 4 +The directories named by the +.B MANPATH +and +.B MANDATORY_MANPATH +lines of the configuration file. +.IP 3. 4 +The kit's own pages, in +.I ../share/man +relative to the directory that holds +.IR busybox.exe . +.PP +Empty elements, and elements spelled the same as an earlier one, are +ignored. +A relative element is relative to the root of the system drive, not to +the current directory. +.PP +In each directory, +.B man +tries the sections in turn, and in each section a +.B cat +page before a +.B man +page. +The sections are +.BR 0p:1:1p:2:3:3p:4:5:6:7:8:9 , +or the list in the +.B MANSECT +line of the configuration file. +.B man +displays the first page it finds, and then goes on to the next operand. +A cat page hides the man page of its section. +.PP +If the first operand is a section and another operand follows, only +that section is searched, for every operand. +A section here is any text whose first occurrence in the list of +sections ends at a colon or at the end of the list. +That includes a run such as +.BR 2:3 , +which searches both, and the tail of a section: +.B man p foo +searches only section +.BR p , +for +.IR manp/foo.p . +.B 0 +is not a section, because it first occurs in +.BR 0p . +A +.I page +that ends in a dot and a section, as in +.BR printf.3 , +is searched for in that section only, which takes precedence. +.PP +When no page is found, and the name contains +.BR \-w64\-mingw32\- , +.B man +looks again for the part of the name after it, so that +.B x86_64\-w64\-mingw32\-gcc +finds +.BR gcc (1). +.SS Links +A man page file, not a cat page, of at most 300 bytes whose first line is +.BR .so , +a space, and a name is a link. +Later lines are ignored. +.B man +shows the page it names instead. +A name without a slash is relative to the directory that holds the link. +A name with a slash, such as +.IR man1/grep.1 , +is relative to the directory above that one. +Trailing white space, including a carriage return, is ignored. +After 10 links in a chain, +.B man +formats the next link file as a page, and +.B nroff +follows its +.B .so +request. +When the target cannot be found, nothing is displayed, and the operand +counts as found. +.PP +A +.B .so +request inside a longer page is handled by +.BR nroff . +It resolves relative to the manual directory the page was found in, or +to the current directory for a +.IR file . +.SS Formatting and display +To show a page, +.B man +runs the +.B nroff +that is next to +.IR busybox.exe , +in the manual directory where it found the page, or in the current +directory for a +.IR file . +The page is its standard input, and its options are +.BR \-mandoc , +.BI \-T charset\fR, +.BI \-rLL= w n\fR, +and +.BI \-rLT= w n\fR. +Its output and error messages go to the pager. +.PP +The +.I charset +is +.B utf8 +when the ANSI code page of the process is UTF-8, and +.B ascii +otherwise. +The line length +.I w +is the width of the display less 2, or the width itself when that is +10 or less. +The width is that of the console window of standard output, or else of +standard error. +When +.B COLUMNS +is set, its value is the width instead, or 80 if its numeric value is +not from 2 to 29999. +Without a console and without +.BR COLUMNS , +the width is 80. +.PP +A cat page is not formatted: it goes to the pager as it is. +.PP +The pager is +.BR "less \-R" , +unless the configuration file, or +.B MANPAGER +or +.BR PAGER , +names another one. +It is run by +.BR sh , +so it may be a command line with arguments. +When standard output is a console and +.B LESS +is not set, +.B man +sets it to +.B R +for the pager, so that a plain +.B less +shows bold and underlined text too. +.PP +When standard output is not a console, there is no pager. +.B man +sets +.B GROFF_NO_SGR +to +.BR 1 , +so that +.B nroff +writes plain text with no escape sequences, and writes the pages one +after another to standard output. +.SS Configuration file +.B man +reads the first of +.IR /etc/man.config , +.IR /etc/man.conf , +and +.I /etc/man_db.conf +that exists, in the root of the system drive. +The kit installs none. +A line holds a keyword and the rest of the line as its value. +A +.B # +starts a comment, a backslash at the end of a line continues it, and +other lines are ignored. +The keywords are: +.TP +.BI "MANPATH " directories +Add manual directories, separated by semicolons. +.B MANDATORY_MANPATH +is a synonym. +.TP +.BI "MANSECT " sections +Replace the sections to search, as a colon-separated list. +.TP +.BI "DEFINE nroff " command +Replace the formatter, which is otherwise the kit's +.B nroff +with +.BR \-mandoc . +.B man +appends the +.B \-T +and +.B \-r +options to +.IR command . +.TP +.BI "DEFINE pager " command +Replace the pager. +.B MANPAGER +and +.B PAGER +still override it. +.SH OPTIONS +Options may be grouped, as in +.BR \-aw , +and must come before the operands. +.B \-\- +ends them. +.TP +.B \-a +Display every page found, in the order found, instead of only the first. +.TP +.B \-w +Print the path of each page file found, one per line, and do not +display it. +The path of a compressed page ends in its compression suffix, and that +of a link is the link file's own. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit with status 0. +.SH ENVIRONMENT +Variables that apply to every applet, such as +.BR BB_OVERRIDE_APPLETS , +are described in +.BR busybox (1). +.TP +.B BB_SYSTEMROOT +A drive, such as +.BR D: , +to use instead of the system drive. +.B man +makes the root of that drive its working directory before it searches, +which is why relative +.B MANPATH +elements, and +.I /etc +for the configuration file, are found there. +.TP +.B COLUMNS +The display width; see +.BR "Formatting and display" . +.TP +.B GROFF_NO_SGR +Set to +.B 1 +for +.B nroff +when standard output is not a console. +.TP +.B LESS +Set to +.B R +when it is not set and standard output is a console. +.TP +.B MANPAGER +The pager, run by +.BR sh . +It overrides the configuration file, and takes precedence over +.BR PAGER . +A set but empty +.B MANPAGER +or +.B PAGER +still counts, and then nothing is displayed. +.TP +.B MANPATH +Manual directories to search first, separated by semicolons. +.TP +.B PAGER +The pager, when +.B MANPAGER +is not set. +.TP +.B PATH +Where +.B sh +finds a pager that is not an applet, and where +.B man +finds the decompressors +.B gunzip +and +.BR unzstd . +.SH EXIT STATUS +.TP +.B 0 +Every operand was found. +.TP +.B 1 +Some operand was not found, a relative +.I file +does not exist, +.B gunzip +or +.B unzstd +is needed but not found, or the command line is invalid. +.PP +A page that is not found is reported on standard error as +.PP +.RS 4 +.EX +man: no manual entry for \(aq\fIname\fR\(aq +.EE +.RE +.PP +and the remaining operands are still processed. +Errors in +.BR nroff , +the pager, or a decompressor do not change the status. +.SH EXAMPLES +Read a page, and a page from section 5: +.PP +.RS 4 +.EX +$ man gcc +$ man 5 gdbinit +.EE +.RE +.PP +Find out where a page is kept: +.PP +.RS 4 +.EX +$ man \-w gcc +C:/w64devkit/share/man/man1/gcc.1 +.EE +.RE +.PP +Read the page for a tool by its prefixed name: +.PP +.RS 4 +.EX +$ man x86_64\-w64\-mingw32\-ld +.EE +.RE +.PP +Read a page that is not installed: +.PP +.RS 4 +.EX +$ man ./mytool.1 +.EE +.RE +.PP +Look in two more directories of pages first: +.PP +.RS 4 +.EX +$ MANPATH=\(aqD:/docs/man;D:/more/man\(aq man mytool +.EE +.RE +.PP +Save a page as plain text, formatted for a 100-column display: +.PP +.RS 4 +.EX +$ COLUMNS=100 man gcc >gcc.txt +.EE +.RE +.SH NOTES +Differences from the +.B man +of Unix systems: +.IP \(bu 2 +The only options are +.B \-a +and +.BR \-w . +There is no search by keyword. +.IP \(bu 2 +Manual directories are separated by semicolons, since colons occur in +drive letters. +.IP \(bu 2 +Formatting is done by the kit's +.BR nroff (1) +alone, not by a pipeline of groff, tbl, and col. +.IP \(bu 2 +Page names are matched by the file system, which usually does not +distinguish case on Windows, so +.B man GCC +shows the page for +.BR gcc . +.PP +A file operand may use slashes or backslashes. +A drive letter with no slash after it, as in +.IR c:doc/page.1 , +starts from the current directory of that drive. +A file operand that does not begin with a drive letter and a slash, or +with a UNC prefix, is made absolute first, which fails if it does not +exist. +.B man +then stops at once, before it processes any operand, with status 1 and +the message +.PP +.RS 4 +.EX +man: can\(aqt open \(aq\fIfile\fR\(aq: \fIreason\fR +.EE +.RE +.PP +A missing file that begins with a drive letter and a slash, or with a +UNC prefix, is reported as a page that is not found. +.PP +Pages may be compressed. +For each page file, +.B man +tries the name with +.BR .lzma , +.BR .xz , +.BR .bz2 , +and +.B .gz +appended, in that order, before the name itself. +A file is decompressed whatever its name when its first bytes identify +gzip, compress, bzip2, xz, or zstd data, and a name ending in +.B .lzma +is enough for lzma. +The decompressors are programs run by name: +.BR bunzip2 , +.BR unxz , +.BR unlzma , +and +.B uncompress +are applets, and +.B gunzip +and +.B unzstd +come from +.BR PATH ; +see +.BR gzip (1) +and +.BR zstd (1). +When a page needs one of them and it is not on +.BR PATH , +.B man +stops at once with status 1. +.PP +.B man +reads a man page file of 300 bytes or fewer within its own process to +look for a link, and for gzip and zstd data that fails: the decompressor +reports an error, and +.B man +exits at once with status 0, without showing the page or processing +later operands. +.PP +The width comes from the console window, not the screen buffer. +Escape sequences for bold and underlined text pass through +.BR "less \-R" ; +see +.BR less (1). +The busybox manifest asks Windows for a UTF-8 code page, which takes +effect on Windows 10 version 1903 and later. +On older systems, such as Windows XP, +.B man +passes +.BR \-Tascii . +.SH SEE ALSO +.BR busybox (1), +.BR gzip (1), +.BR less (1), +.BR nroff (1), +.BR sh (1), +.BR zstd (1) diff --git a/man/man1/md5sum.1 b/man/man1/md5sum.1 new file mode 100644 index 0000000..24f646e --- /dev/null +++ b/man/man1/md5sum.1 @@ -0,0 +1,419 @@ +.TH MD5SUM 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +md5sum, sha1sum, sha256sum, sha3sum, sha512sum \- print or check digests +.SH SYNOPSIS +.B md5sum +.RB [ \-b " | " \-t ] +.RI [ file ...] +.br +.B md5sum \-c +.RB [ \-sw ] +.RI [ file ...] +.br +.B sha3sum +.RB [ \-b " | " \-t ] +.RB [ \-a +.IR bits ] +.RI [ file ...] +.br +.B sha3sum \-c +.RB [ \-sw ] +.RB [ \-a +.IR bits ] +.RI [ file ...] +.SH DESCRIPTION +These commands print the message digest of each +.IR file , +or with +.B \-c +check files against digests listed in other files. +They are one program, and differ only in the algorithm: +.TP +.B md5sum +MD5, a 128-bit digest. +.TP +.B sha1sum +SHA-1, 160 bits. +.TP +.B sha256sum +SHA-256, 256 bits. +.TP +.B sha512sum +SHA-512, 512 bits. +.TP +.B sha3sum +SHA-3, 224 bits unless +.B \-a +chooses another size. +.PP +.BR sha1sum , +.BR sha256sum , +and +.B sha512sum +take the same options and operands as +.BR md5sum . +Only +.B sha3sum +takes +.BR \-a . +.PP +With no +.IR file , +or for a +.I file +named +.BR \- , +they read standard input. +Every file is read as binary. +.SS Printing digests +For each +.IR file , +the command writes a line of the digest in lowercase hex digits, two +spaces, and the name exactly as given. +Standard input is named +.BR \- . +With +.BR \-b , +the second space is an asterisk. +A file that cannot be opened or read is reported on standard error and +gets no line, and the remaining files are still processed. +.SS Checking digests +With +.BR \-c , +each +.I file +is a list of digests, such as the output of the same command, and the +command hashes every file that a list names and compares the digests. +A list named +.BR \- , +or no list, is read from standard input. +Names in a list are relative to the current directory, not to the list. +.PP +A list line is a digest, a space, optionally one more space or an +asterisk, and a name, which is the rest of the line, including any +spaces. +A CR before the LF is dropped. +The digest is everything before the first space. +It is compared with the computed digest without regard to case. +Its length and digits are not checked, so a line with a digest of +another algorithm is not invalid: its file is hashed, and the line +fails. +A name of +.B \- +hashes standard input. +A line with no space, such as a blank line, is invalid and counts as +failed. +Nothing is skipped: a comment line is read as a digest and a name, and +fails. +.PP +For each valid line, the command writes +.IB name ": OK" +or +.IB name ": FAILED" +on standard output. +A file that cannot be opened or read is reported on standard error, and +also counts as +.BR FAILED . +After each list in which any line failed, it writes to standard error +a line such as +.PP +.RS 4 +.EX +md5sum: WARNING: 1 of 2 computed checksums did NOT match +.EE +.RE +.PP +which begins with the name of the command. +The first count is the lines of that list that failed, and the second +is all its lines, invalid lines included. +A list with no lines is reported as +.IB list ": no checksum lines found" +on standard error, and counts as a failure. +.SH OPTIONS +Options may be grouped, as in +.BR \-cs , +and may follow the operands. +.B \-\- +ends the options. +The argument of +.B \-a +may be attached, as in +.BR \-a256 , +or be the next argument. +.TP +.B \-c +Check the digests listed in the +.I file +operands, as described under +.BR "Checking digests" . +.TP +.B \-s +Do not write the +.BR OK , +.BR FAILED , +and +.B WARNING +lines, so that only the exit status tells whether every digest matched. +Other errors are still written to standard error: files that cannot be +opened, lists with no lines, and with +.BR \-w , +invalid lines. +Requires +.BR \-c : +without it, the command writes its usage message to standard error and +exits with status 1. +.TP +.B \-w +Warn about each invalid line by writing +.B invalid format +to standard error. +The message does not name the line. +Requires +.BR \-c , +like +.BR \-s . +.TP +.BI "\-a " bits +Set the size of the digest in bits, which is written as +.IR bits /4 +hex digits. +The other commands reject +.B \-a +as an unknown option. +The default is 224. +Sizes 224, 256, 384, and 512 give SHA3-224, SHA3-256, SHA3-384, and +SHA3-512 as standardized by FIPS 202. +Any other multiple of 32 from 32 to 768 is accepted, and gives a +nonstandard digest. +Any other number ends the command with status 1 and an error such as +.B sha3sum: bad \-a100 +when the first file is opened, after any earlier files that could not +be opened are reported. +A value that is not a plain decimal number, such as +.B \-5 +or +.BR 0x100 , +is an error at once. +A list does not record its size, so give the same +.B \-a +when checking. +.TP +.B \-b +Binary mode: write an asterisk instead of the second space before each +name. +It affects only the output, since every file is read as binary. +Ignored with +.BR \-c . +A later +.B \-t +cancels it. +.TP +.B \-t +Text mode, the default: write two spaces before each name. +A later +.B \-b +cancels it, and +.B \-bt +is the same as +.BR \-t . +Ignored with +.BR \-c . +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options, so that later arguments such as +.B \-b +are file names. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when the program starts, even in +quoted operands, as needed when run from +.BR cmd.exe . +A pattern that matches nothing is left as it is. +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success: every file was hashed, or with +.B \-c +every listed file matched. +.TP +.B 1 +An invalid option, a file that could not be opened or read, a bad +.BR \-a , +and with +.BR \-c , +a digest that did not match, an invalid line, a list with no lines, or a +list that could not be opened. +.PP +A list that cannot be opened, and a bad +.BR \-a , +end the command at once, and later operands and list lines are not +processed. +.SH EXAMPLES +Print the MD5 digest of a file: +.PP +.RS 4 +.EX +$ printf abc >abc.txt +$ md5sum abc.txt +900150983cd24fb0d6963f7d28e17f72 abc.txt +.EE +.RE +.PP +Standard input is named +.BR \- : +.PP +.RS 4 +.EX +$ md5sum SHA256SUMS +$ sha256sum \-c SHA256SUMS +.EE +.RE +.PP +Check a file against a published digest: +.PP +.RS 4 +.EX +$ echo "$digest release.zip" | sha256sum \-c +release.zip: OK +.EE +.RE +.PP +Check without the OK and FAILED lines, and report failure: +.PP +.RS 4 +.EX +$ sha256sum \-cs SHA256SUMS || echo corrupt +.EE +.RE +.PP +Record SHA3-256 digests of a tree, then check them: +.PP +.RS 4 +.EX +$ find src \-type f \-exec sha3sum \-a 256 {} + >tree.sha3 +$ sha3sum \-a 256 \-c tree.sha3 +.EE +.RE +.SH NOTES +Differences from GNU coreutils: +.IP \(bu 2 +.B \-s +is GNU's +.BR \-\-status . +There are no long options besides +.BR \-\-help , +and no equivalents of GNU +.BR \-\-quiet , +.BR \-\-ignore\-missing , +.BR \-\-strict , +.BR \-\-tag , +or +.BR \-z . +.IP \(bu 2 +An invalid line in a list makes the exit status 1, where GNU skips it +unless given +.BR \-\-strict . +.IP \(bu 2 +Names are neither escaped when written nor unescaped when read. +GNU starts the line with a backslash and escapes names that contain a +backslash or a newline. +.PP +Standard input from a file or pipe is read as binary, like files, so a +digest covers the exact bytes. +A text file with CR LF line endings has a different digest from a copy +with LF line endings, and +.B \-t +does not change that. +Lists may have either line ending. +Output lines end with LF. +.PP +Lines typed at a console arrive with CR LF line endings, which are part +of the digest. +To end the input, type Ctrl-Z at the start of a line and press Enter. +.PP +Standard input is not closed after it is read. +A second +.B \- +operand hashes what remains, which at end of file is nothing. +.PP +A +.I file +may be a Windows path, with a drive letter and either kind of slash, or +a busybox-w32 device name such as +.IR /dev/null . +It is printed exactly as given, so a list made with backslashes can be +checked as it is. +On Windows 10 version 1903 or later, file names may contain any Unicode +characters, and on older systems only those of the system code page. +A directory fails with +.BR "Permission denied" , +or with +.B Is a directory +when it is a list for +.BR \-c . +.PP +When standard output is a console, names are converted for display from +the ANSI code page to the console's output code page. +.PP +MD5 and SHA-1 detect accidental damage only, not deliberate tampering. +.PP +busybox also has +.BR sha384sum , +which takes the same options as +.BR md5sum . +The kit installs no +.I sha384sum.exe +for it. +The kit's shell, and busybox commands such as +.BR find , +run it by name, but elsewhere, such as from +.BR cmd.exe , +run it as +.BR "busybox sha384sum" . +.SH SEE ALSO +.BR busybox (1), +.BR cksum (1), +.BR cut (1), +.BR find (1) diff --git a/man/man1/mkdir.1 b/man/man1/mkdir.1 new file mode 100644 index 0000000..7bccaf1 --- /dev/null +++ b/man/man1/mkdir.1 @@ -0,0 +1,368 @@ +.TH MKDIR 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +mkdir \- make directories +.SH SYNOPSIS +.B mkdir +.RB [ \-pv ] +.RB [ \-m +.IR mode ] +.IR directory ... +.SH DESCRIPTION +.B mkdir +creates each +.I directory +operand, in order. +It is the +.BR busybox (1) +applet, which has fewer options than GNU +.BR mkdir ; +see +.BR NOTES . +.PP +A +.I directory +that cannot be created is reported on standard error, and the remaining +operands are still processed. +The exit status is then 1. +With no operand, or with an invalid option, it prints a usage message on +standard error and exits with status 1. +.PP +Without +.BR \-p , +the parent of each +.I directory +must exist, and an existing directory or file of that name is an +error. +The operands +.B .\& +and +.B / +are the exception: they name directories that exist, and +.B mkdir +succeeds on them without doing anything, with or without +.BR \-p . +Other spellings, such as +.B ./ +and +.BR .. , +are errors without +.BR \-p . +.SS Parent directories +With +.BR \-p , +.B mkdir +creates the missing parents of each +.IR directory , +starting from the leftmost. +A parent or +.I directory +that exists as a directory is left unchanged and is not an error. +An existing file with the name of a parent or +.I directory +is an error. +Parents created before an error remain. +.SS Output +Nothing is written to standard output unless +.B \-v +is given. +An error is written to standard error as +.PP +.RS 4 +.EX +mkdir: can\(aqt create directory \(aq\fIpath\fR\(aq: \fIreason\fR +.EE +.RE +.PP +where +.I reason +is the system's message, such as +.B File exists +or +.BR "No such file or directory" . +The +.I path +is the operand with any backslashes changed to slashes. +With +.BR \-p , +it is cut after the slashes that follow the component that failed, so it +can end in a slash. +.SH OPTIONS +Options may be grouped, as in +.BR \-pv , +and may follow operands, unless +.B POSIXLY_CORRECT +is set. +The argument of +.B \-m +may be attached, as in +.BR \-m755 , +or be the next argument. +A long option may be abbreviated to any unambiguous prefix, and takes +its argument after +.B = +or as the next argument. +.B \-\- +ends the options. +.TP +\fB\-m\fR \fImode\fR, \fB\-\-mode=\fImode\fR +Set the mode of each +.I directory +operand that +.B mkdir +creates to +.IR mode , +after creating it. +Parents made by +.BR \-p , +and directories that already exist, are not changed. +.IP +The +.I mode +is an octal number from 0 to 7777, written with octal digits only, or a +symbolic mode as in +.BR chmod (1) +that modifies 0777. +A +.I mode +that begins with a digit from 0 to 7 is read as octal. +One that cannot be parsed is reported as +.B mkdir: invalid mode +.BI \(aq mode \(aq +before any directory is created, and the exit status is 1. +A symbolic clause with no +.BR u , +.BR g , +.BR o , +or +.B a +before its operator is limited by the umask; see +.BR BB_UMASK . +.IP +If the mode cannot be set, +.B mkdir +reports +.B can\(aqt set permissions of directory +and the directory remains. +On Windows a valid +.I mode +has no visible effect; see +.BR NOTES . +.TP +.BR \-p ", " \-\-parents +Create missing parent directories, and do not treat an existing +directory as an error. +.TP +.BR \-v ", " \-\-verbose +Write +.BI "created directory: \(aq" path \(aq +on standard output for each directory created, including each parent +made by +.BR \-p . +The +.I path +of a parent ends with the slashes that follow it in the operand, as in +.BR \(aqout/\(aq . +The usage message omits this option. +.TP +.B \-\-help +As the first argument only, write a usage message on standard output +and exit with status 0. +The message omits the long options and +.BR \-v . +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when busybox starts, for a caller +such as +.B cmd.exe +that does not expand them. +When it is unset, busybox sets it to +.B 0 +for the programs it starts, so commands run from the kit's shell get the +shell's expansion only. +.TP +.B BB_UMASK +The file mode creation mask, in octal, applied before +.B mkdir +runs. +It limits a symbolic +.B \-m +mode that has no +.BR u , +.BR g , +.BR o , +or +.B a +before its operator, but since the mode has no visible effect, neither +does the mask. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Messages written to a console also depend on +.BR BB_SKIP_ANSI_EMULATION , +.BR BB_TERMINAL_MODE , +.BR LANG , +.BR LC_ALL , +and +.BR LC_CTYPE , +and Windows error dialogs on +.BR BB_CRITICAL_ERROR_DIALOGS , +as for every busybox applet; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, including +.B \-\-help +as the first argument. +.TP +.B 1 +An invalid option or mode, no operand, or any directory that could not +be created or given its mode. +.SH EXAMPLES +Make a directory: +.PP +.RS 4 +.EX +$ mkdir build +.EE +.RE +.PP +Make several directories: +.PP +.RS 4 +.EX +$ mkdir src doc test +.EE +.RE +.PP +Make a directory and its parents, without an error if it exists: +.PP +.RS 4 +.EX +$ mkdir \-p out/bin/debug +.EE +.RE +.PP +List the directories that are made: +.PP +.RS 4 +.EX +$ mkdir \-pv out/lib +created directory: \(aqout/\(aq +created directory: \(aqout/lib\(aq +.EE +.RE +.PP +Make a directory and its parents on another drive: +.PP +.RS 4 +.EX +$ mkdir \-p d:/work/tmp +.EE +.RE +.PP +Take a lock, or print +.B busy +if another script holds it: +.PP +.RS 4 +.EX +$ mkdir lock.d 2>/dev/null || echo busy +.EE +.RE +.SH NOTES +Differences from GNU +.BR mkdir : +.IP \(bu 2 +.B \-m +only checks its mode; see below. +.IP \(bu 2 +.B mkdir .\& +and +.B mkdir / +succeed even without +.BR \-p . +.IP \(bu 2 +.B \-v +is accepted although the usage message omits it. +.IP \(bu 2 +Options not listed above, such as +.BR \-Z , +.BR \-\-context , +and +.BR \-\-version , +are invalid. +.PP +Windows has no Unix mode. +A new directory gets the permissions it inherits from its parent +directory. +.B \-m +can only set the read-only attribute, and never does for a directory, +whatever the +.IR mode , +so it only checks that the +.I mode +is valid; see +.BR chmod (1). +.PP +Paths may have drive letters and backslashes. +Backslashes in an operand are changed to slashes, so messages and +.B \-v +output show slashes. +A path may be absolute, as in +.IR c:/dir , +relative, or relative to a drive, as in +.IR c:dir . +With +.BR \-p , +the drive or UNC share that begins a path, as in +.I q:/dir +or +.IR //host/share/dir , +is one component that must exist. +If it does not, the error names it, as in +.BR \(aqq:/\(aq . +.PP +Names are not case sensitive on most volumes, so +.B mkdir Foo +fails with +.B File exists +when +.I foo +exists. +Names may contain any Unicode character on Windows 10 version 1903 and +later; see +.BR busybox (1). +A name that Windows does not allow, such as one containing +.BR ? , +fails with +.BR "Invalid argument" . +Avoid Windows device names: +.B mkdir con +fails with +.BR "Invalid argument" , +but +.B mkdir nul +reports success and can make a directory that ordinary paths cannot +reach. +The full path of a directory, counting the current directory when the +operand is relative, must be shorter than 248 characters. +A longer path fails with +.BR "No such file or directory" . +.PP +From +.BR cmd.exe , +.B mkdir +expands wildcards in its arguments itself; see +.BR BB_GLOBBING . +A pattern that matches nothing is used as it is, and fails with +.BR "Invalid argument" . +.SH SEE ALSO +.BR busybox (1), +.BR chmod (1), +.BR install (1), +.BR rmdir (1) diff --git a/man/man1/mktemp.1 b/man/man1/mktemp.1 new file mode 100644 index 0000000..0397661 --- /dev/null +++ b/man/man1/mktemp.1 @@ -0,0 +1,358 @@ +.TH MKTEMP 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +mktemp \- create a temporary file or directory +.SH SYNOPSIS +.B mktemp +.RB [ \-dqtu ] +.RB [ \-p +.IR dir ] +.RB [ \-\-tmpdir [ =\c +.IR dir ]] +.RI [ template ] +.SH DESCRIPTION +.B mktemp +creates a temporary file, or with +.B \-d +a directory, and prints its name on standard output followed by a +newline. +A new file is empty. +.PP +The name is +.I template +with its trailing +.B X +characters replaced to make a name that is not in use. +The template must end in at least six +.B X +characters, and nothing may follow them. +In a file name, and in any name printed by +.BR \-u , +only the last six are replaced; in a directory name, all of them are. +The rest of the path is left as it is, and its directory part must +already exist, except with +.BR \-u . +With no +.IR template , +.B mktemp +acts as if it were given +.BR "\-t tmp.XXXXXX" . +.PP +With +.BR \-t , +.BR \-p , +or +.BR \-\-tmpdir , +the template is joined to a base directory by a slash, which is left out +when the base directory already ends in one. +Slashes at the start of the template are dropped first. +The base directory is the last argument given to +.B \-p +or +.BR \-\-tmpdir , +else the value of +.BR TMPDIR , +else +.IR /tmp . +Without these options the template is used as given, so a template with +no directory part makes the name in the current directory. +.PP +The name printed is the path as built above, so a relative template +gives a relative name. +.SH OPTIONS +Options may be grouped, as in +.BR \-dq , +and the argument of +.B \-p +may be attached, as in +.B \-p\c +.IR dir . +Options may follow the template, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +A long option may be shortened to any unambiguous prefix, such as +.B \-\-dry +for +.BR \-\-dry\-run . +At most one template is allowed. +.TP +.BR \-d ", " \-\-directory +Create a directory instead of a file. +It has no effect with +.BR \-u , +which creates nothing. +.TP +.BR \-q ", " \-\-quiet +Print no message when no name can be made, or the file or directory +cannot be created. +The exit status is still 1. +Command line errors are still reported. +.TP +.B \-t +Put the base directory in front of the template. +.TP +.BI "\-p " dir +Use +.I dir +as the base directory. +Implies +.BR \-t . +An empty +.I dir +makes the template relative to the current directory. +.TP +.BR \-u ", " \-\-dry\-run +Create nothing. +Print a name that did not exist when it was chosen. +With +.BR \-d , +the name is made as for a file; see +.BR NOTES . +.TP +\fB\-\-tmpdir\fR[\fB=\fIdir\fR] +Like +.BR \-t . +With +.BI = dir\fR, +use +.I dir +as the base directory, as +.B \-p +does. +The argument must be attached with +.BR = : +a separate word is the template. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when +.B mktemp +starts, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.B BB_UMASK +When it has the owner write bit, +.BR 200 , +the file that +.B mktemp +creates is read-only. +A directory is not affected. +.TP +.B POSIXLY_CORRECT +When set, the C library ends option parsing at the first argument that +is not an option. +.TP +.B TMPDIR +The default base directory. +When it is unset, the value of +.B TMP +is used, then that of +.BR TEMP , +and Windows normally sets both. +The first one that is set is used even when it is empty, and an empty +value gives +.IR /tmp . +It is used when +.BR \-t , +.BR \-\-tmpdir , +or a missing template calls for a base directory, and +.B \-p +or +.BI \-\-tmpdir= dir +gives none. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +Error. +For an invalid command line, meaning an unknown or ambiguous option, a +missing argument to +.BR \-p , +or more than one template, a usage message is written on standard error. +When no name can be made, or the file or directory cannot be created, a +message of the form +.RB \(dq "mktemp: : " \c +.IR reason \(dq +is written on standard error, unless +.B \-q +is given. +For example, the reason is +.B No such file or directory +when the directory part of the template does not exist, +.B Invalid argument +when the template does not end in six +.B X +characters, and +.B File exists +when the C library runs out of file names; see +.BR NOTES . +.SH EXAMPLES +Create a temporary file, and keep its name in a variable: +.PP +.RS 4 +.EX +$ f=$(mktemp) +$ gcc \-E main.c >"$f" +.EE +.RE +.PP +Make a scratch directory that is removed when the shell exits: +.PP +.RS 4 +.EX +$ dir=$(mktemp \-d) +$ trap \(aqrm \-rf "$dir"\(aq EXIT +.EE +.RE +.PP +Make a file in another directory: +.PP +.RS 4 +.EX +$ mktemp \-p build cc.XXXXXX +build/cc.a14280 +.EE +.RE +.PP +Take another action when the directory cannot be made, here because +.I work +does not exist: +.PP +.RS 4 +.EX +$ mktemp \-q \-d work/XXXXXX || echo no work directory +no work directory +.EE +.RE +.SH NOTES +Differences from GNU +.BR mktemp : +.IP \(bu 2 +The template must end in +.BR XXXXXX , +and nothing may follow it: there is no +.BR \-\-suffix . +.IP \(bu 2 +With +.B \-\-tmpdir +or +.BR \-p , +a template that starts with a slash is not an error: the slashes are +dropped. +.IP \(bu 2 +With +.BR \-t , +the argument of +.B \-p +takes precedence over +.BR TMPDIR , +and the template may contain slashes. +.IP \(bu 2 +An empty argument to +.B \-p +or +.B \-\-tmpdir= +means the current directory, not the default base directory. +.PP +The C library, not +.BR mktemp , +chooses the name. +For a file, and for any name printed by +.BR \-u , +including with +.BR \-d , +it replaces the six +.B X +characters with a lowercase letter and five digits derived from the ID +of the calling thread, so the names are predictable, not random. +When that name exists, the letter advances through +.BR z , +and then the attempt fails with +.BR "File exists" . +For a directory, each trailing +.B X +becomes a random letter or digit. +.PP +A file is created after its name is chosen, with no exclusive-create +check, so another process can create the same name in between, and +.B mktemp +then shares the file instead of failing. +Do not rely on +.B mktemp +in a directory that untrusted users can write. +Neither files nor directories are private: access follows the +permissions of the containing directory. +.PP +A slash is the only separator that +.B mktemp +recognizes when it joins the base directory and the template. +A backslash at the end of the base directory gets a slash after it, and +a backslash at the start of the template is kept. +Windows accepts both, so the name can mix separators, as with the usual +.B TMP +setting when +.B mktemp +runs from +.BR cmd.exe : +.PP +.RS 4 +.EX +C:\eUsers\eme\eAppData\eLocal\eTemp/tmp.a01276 +.EE +.RE +.PP +The kit's shell changes backslashes to slashes in the environment it +imports, so under it +.B TMP +and +.B TEMP +give names with slashes only; see +.BR sh (1). +Elsewhere, set +.B TMPDIR +to a path with forward slashes to avoid mixed separators. +A template that starts with a drive letter, such as +.BR C:/x/XXXXXX , +cannot follow a base directory. +A base directory that is a bare drive, such as +.IR c: , +names the current directory of that drive and gets no slash, as in +.IR c:tmp.a01276 . +A template that starts with a slash still gets one after a bare drive, +so the name is in the root of the drive, as in +.IR c:/tmp.a01276 . +.PP +The default base directory +.I /tmp +is not translated. +It names the directory +.I \etmp +on the current drive, and +.B mktemp +does not create it. +.PP +The name is followed by LF, not CRLF. +.SH SEE ALSO +.BR busybox (1), +.BR mkdir (1), +.BR rm (1), +.BR sh (1) diff --git a/man/man1/mv.1 b/man/man1/mv.1 new file mode 100644 index 0000000..c561d20 --- /dev/null +++ b/man/man1/mv.1 @@ -0,0 +1,407 @@ +.TH MV 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +mv \- move or rename files and directories +.SH SYNOPSIS +.B mv +.RB [ \-finTv ] +.I source dest +.br +.B mv +.RB [ \-finv ] +.IR source ...\& +.I directory +.br +.B mv +.RB [ \-finv ] +.BI "\-t " directory +.IR source ...\& +.SH DESCRIPTION +.B mv +renames a file or directory, or moves files and directories into a +directory. +It is the +.BR busybox (1) +applet, which has fewer options than GNU +.BR mv ; +see +.BR NOTES . +.SS Operands +With +.BR \-t , +every operand is a +.I source +and is moved into +.IR directory . +Otherwise, with two operands, +.I source +is renamed to +.I dest +itself, except that when +.I dest +is an existing directory, or a symbolic link or junction to one, +.I source +is moved into it. +.B \-T +always renames to +.IR dest . +With more than two operands, the last is +.IR directory . +With no operand, or with one operand and no +.BR \-t , +.B mv +writes a usage message on standard error and exits with status 1. +.PP +A move into +.I directory +is named after the last component of +.IR source , +with trailing slashes and backslashes removed, so +.B mv src/ out +makes +.I out/src +when +.I out +exists. +.B mv +does not check beforehand that +.I directory +exists or is a directory: the move of each +.I source +then fails on its own, with a reason such as +.B No such file or directory +or +.BR "Invalid argument" . +.SS What is moved +A move is a rename, not a copy: the file or directory keeps its +contents, times, and attributes. +A directory is moved with everything in it, and cannot be moved into +itself, which fails with +.BR "Invalid argument" . +A symbolic link or junction is moved as a link, and its target is not +touched. +For moves to another volume, see +.BR NOTES . +.SS Existing destinations +.B \-n +skips a source whose destination exists. +Otherwise, unless +.B \-f +is given, +.B mv +asks before replacing an existing destination if +.B \-i +is given, or if the destination is read-only and standard input is a +console. +It writes +.BI "mv: overwrite \(aq" dest "\(aq?\&" +on standard error and reads a line from standard input. +The destination is replaced only if the first character of the line +that is not a space or tab is +.B y +or +.BR Y , +and otherwise the source is skipped, which is not an error. +End of input counts as no. +.PP +An existing destination file is replaced by the moved file, even if it +is read-only. +The moved file keeps its own attributes, so the replacement is writable +if the moved file is. +An existing destination directory is never replaced: moving a file or +directory onto one fails with +.BR "Is a directory" , +even when it is empty. +A directory moved onto an existing file does replace it. +.SS Output +.B mv +reports each error on standard error as +.BI "mv: " message +and goes on with the remaining operands. +A source that cannot be moved is reported as +.BI "mv: can\(aqt rename \(aq" source "\(aq: " reason \c +.RI . +Prompts go to standard error. +Only +.B \-v +and +.B \-\-help +write to standard output. +.SH OPTIONS +Options may be grouped, as in +.BR \-fv , +and may follow operands, unless +.B POSIXLY_CORRECT +is set. +The argument of +.B \-t +may be attached, as in +.BR \-tbin . +A long option may be abbreviated to any unambiguous prefix, and takes +its argument after +.B = +or as the next argument. +.B \-\- +ends the options. +.TP +.BR \-f ", " \-\-force +Do not ask before replacing an existing destination, even a read-only +one. +Of +.BR \-f , +.BR \-i , +and +.BR \-n , +only the last given takes effect. +.TP +.BR \-i ", " \-\-interactive +Ask before replacing any existing destination, as described above. +Only the last of +.BR \-f , +.BR \-i , +and +.B \-n +takes effect. +.TP +.BR \-n ", " \-\-no\-clobber +Skip, without a message, each source whose destination exists. +A destination that differs from the source only in case exists, so +.B mv \-n a A +does nothing. +Only the last of +.BR \-f , +.BR \-i , +and +.B \-n +takes effect. +.TP +.BR \-T ", " \-\-no\-target\-directory +Rename to +.I dest +itself, never into it. +Requires exactly two operands, and is incompatible with +.BR \-t . +If +.I dest +is an existing directory, the move fails: a +.I source +that is not a directory is refused with +.BI "mv: \(aq" dest "\(aq is a directory" +and exit status 1, and a directory cannot replace a directory. +.TP +\fB\-t\fR \fIdirectory\fR, \fB\-\-target\-directory\fR=\fIdirectory\fR +Move every operand into +.IR directory . +Incompatible with +.BR \-T . +.TP +.BR \-v ", " \-\-verbose +Write +.BI \(aq source "\(aq \-> \(aq" dest \(aq +on standard output for each source, after trying to move it. +The line is written whether the move succeeded, failed, or was skipped +by +.B \-n +or by an answer to +.BR \-i , +but not when +.B \-T +refuses it. +.I dest +is the name of the destination itself, or, for a move into a +directory, the directory and the new name joined with a slash. +.TP +.B \-\-help +As the first argument only, write a usage message on standard output +and exit with status 0. +The message omits the long options and +.BR \-v . +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when busybox starts, for a caller +such as +.B cmd.exe +that does not expand them. +When it is unset, busybox sets it to +.B 0 +for the programs it starts, so commands run from the kit's shell get the +shell's expansion only. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Messages written to a console also depend on +.BR BB_SKIP_ANSI_EMULATION , +.BR BB_TERMINAL_MODE , +.BR LANG , +.BR LC_ALL , +and +.BR LC_CTYPE , +and Windows error dialogs on +.BR BB_CRITICAL_ERROR_DIALOGS , +as for every busybox applet; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, including sources skipped by +.B \-n +or an answer to +.BR \-i , +and a name moved onto itself. +.TP +.B 1 +An invalid command line, with a usage message on standard error, or any +operand that could not be moved. +.SH EXAMPLES +Rename a file: +.PP +.RS 4 +.EX +$ mv old.c new.c +.EE +.RE +.PP +Move the C sources into a directory, listing each move: +.PP +.RS 4 +.EX +$ mv \-v *.c src +\(aqhello.c\(aq \-> \(aqsrc/hello.c\(aq +\(aqmain.c\(aq \-> \(aqsrc/main.c\(aq +.EE +.RE +.PP +Move only the files that are not already in the destination: +.PP +.RS 4 +.EX +$ mv \-n *.txt backup +.EE +.RE +.PP +Change only the case of a name: +.PP +.RS 4 +.EX +$ mv readme.txt README.TXT +.EE +.RE +.PP +Move the files that another command lists into a directory: +.PP +.RS 4 +.EX +$ find build \-name \(aq*.o\(aq | xargs mv \-t obj +.EE +.RE +.PP +Move a file to a directory on another drive: +.PP +.RS 4 +.EX +$ mv report.txt d:/archive +.EE +.RE +.SH NOTES +Differences from GNU +.BR mv : +.IP \(bu 2 +.B mv +does not detect that source and destination are the same file. +A name moved onto itself is left alone, and a name moved onto another +hard link to the same file is removed, leaving the other name. +.IP \(bu 2 +An existing directory is never replaced, not even an empty one. +.IP \(bu 2 +A directory replaces an existing file. +.IP \(bu 2 +.B \-v +writes a line for every source, including those that failed or were +skipped. +.IP \(bu 2 +A destination directory that is missing, or is not a directory, is not +detected before moving starts. +.IP \(bu 2 +A trailing slash on a +.I dest +that does not exist is ignored, so +.B mv f new/ +renames the file +.I f +to +.IR new . +.IP \(bu 2 +Options not listed above, such as +.BR \-b , +.BR \-S , +.BR \-u , +.BR \-Z , +.BR \-\-backup , +.BR \-\-suffix , +.BR \-\-update , +and +.BR \-\-strip\-trailing\-slashes , +are invalid. +.PP +On a case-insensitive file system, a destination that differs from its +source only in case exists, so +.B \-n +skips such a move and +.B \-i +asks first. +Otherwise the move changes the case of the name. +.PP +A file moved to another volume is copied and deleted by Windows, and +keeps its times and read-only attribute. +A directory or junction cannot be moved to another volume: the move +fails with +.B Permission denied +and the source is left alone. +Copy a directory with +.B cp \-a +and remove the original with +.B rm \-r +instead. +Replacing a read-only file on another volume also fails with +.BR "Permission denied" . +.B mv +has its own fallback that copies a tree and removes the original, but +it runs only when the rename fails with a cross-device error (EXDEV), +which none of these moves produce. +.PP +Windows also refuses to move a directory that another process uses as +its current directory, with +.BR "Permission denied" . +.PP +Paths may have drive letters and backslashes. +Names in a directory are joined with +.BR / , +so +.B mv \-v x \(aqc:\etools\(aq +writes names such as +.IR c:\etools/x . +A bare drive such as +.I d: +names the current directory of that drive, so +.B mv x d: +writes +.IR d:x . +Names may contain any Unicode character on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +A full path of 260 or more characters, counting the current directory +for a relative path, fails with +.BR "No such file or directory" . +.PP +From +.BR cmd.exe , +.B mv +expands wildcards in its arguments itself; see +.BR BB_GLOBBING . +.SH SEE ALSO +.BR busybox (1), +.BR cp (1), +.BR ln (1), +.BR rm (1) diff --git a/man/man1/nc.1 b/man/man1/nc.1 new file mode 100644 index 0000000..a5405c6 --- /dev/null +++ b/man/man1/nc.1 @@ -0,0 +1,318 @@ +.TH NC 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +nc \- copy data to and from a TCP connection +.SH SYNOPSIS +.B nc +.I host +.RI [ port ] +.br +.B nc \-l +.RB [ \-p +.IR port ] +.RI [ addr ] +.SH DESCRIPTION +.B nc +connects its standard input and standard output to a TCP connection. +Without +.BR \-l , +it connects to +.I host +at +.IR port . +With +.BR \-l , +it waits for one connection to arrive. +Either way, it sends what it reads from standard input to the connection, +and writes what it reads from the connection to standard output. +.PP +It speaks TCP over IPv4 and IPv6, and nothing else. +There is no UDP, and no way to run a program on the connection. +.SS Connecting +.I host +is a name, a dotted IPv4 address, or an IPv6 address. +Windows resolves a name. +When it has several addresses, +.B nc +tries only one: the first IPv4 address, or else the first address. +.PP +.I port +is a number from 0 to 65535, or a service name; see +.BR NOTES . +A port may instead follow the host after a colon, as in +.BR example.com:80 , +and then it overrides the +.I port +operand. +This port must be a number. +An IPv6 address with more than one colon is never split this way, so give +it a port in brackets, as in +.BR [::1]:80 . +With no port at all, +.B nc +tries port 0, and the connection fails. +.SS Listening +With +.BR \-l , +.B nc +binds a socket, accepts the first connection from any peer, and closes +the listening socket. +It prints nothing when the connection arrives. +.PP +.I addr +is the local address to bind. +It must be numeric: a name is an error. +Without it, +.B nc +listens on all addresses, IPv4 and IPv6 alike. +With an IPv4 address it accepts IPv4 connections only, and with an IPv6 +address, IPv6 only. +To accept only connections from the local machine, give +.B 127.0.0.1 +or +.BR ::1 . +As with a host, a port may follow the address, as in +.B 127.0.0.1:8000 +or +.BR [::1]:8000 , +and overrides +.BR \-p . +.SS Relaying +Once connected, +.B nc +waits until standard input or the connection has data, reads up to 1024 +bytes, and writes them to the other side before it reads again. +Data to and from files and pipes is not translated; for consoles, see +.BR NOTES . +.PP +When standard input reaches the end of the file, +.B nc +shuts down the sending direction of the connection, so the peer sees end +of file, and keeps copying what the peer sends. +A failed read from standard input is treated the same way, without a +message. +.PP +When a read from the connection returns end of file or fails, +.B nc +exits with status 0. +This happens as soon as the peer closes the connection or shuts down its +sending direction, even if standard input has more data. +That data is lost. +Whatever the peer sent before is written first. +.SH OPTIONS +Options may be grouped, as in +.BR \-lp , +and the argument of +.B \-p +may be attached or be the next argument. +.B \-\- +ends the options, and so does the first operand: an option after it is +taken as an operand. +.TP +.B \-l +Listen for one connection instead of connecting. +The number of times +.B \-l +is given is the backlog of the listening socket. +With +.BR \-l , +at most one operand is allowed, and without it, one or two. +.TP +.BI "\-p " port +With +.BR \-l , +listen on local port +.IR port , +a number from 0 to 65535 or a service name. +The default is 0, which has Windows choose a free port. +.B nc +does not report which. +Without +.BR \-l , +.B \-p +is accepted and ignored: the local port of an outgoing connection is +always chosen by Windows. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.PP +Any other option, a missing option argument, or the wrong number of +operands prints the usage on standard error and exits with status 1. +.SH ENVIRONMENT +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +The connection ended or a read from it failed, or the usage was +requested with +.BR \-\-help . +.TP +.B 1 +An invalid command line, a host or port that could not be understood, a +socket that could not be created, bound, or listened on, a connection +that could not be made or accepted, or an error writing to the +connection or to standard output. +The message is on standard error, prefixed with +.BR nc: . +.TP +.B 141 +Standard output is a pipe that was closed before all output was written. +.SH EXAMPLES +Chat across the loopback interface. +In one window, listen: +.PP +.RS 4 +.EX +$ nc \-l \-p 8000 127.0.0.1 +.EE +.RE +.PP +In another, connect. +Each line typed in either window appears in the other: +.PP +.RS 4 +.EX +$ nc 127.0.0.1 8000 +.EE +.RE +.PP +Copy a file to another machine. +On the receiver, at a console, listen and write to a file: +.PP +.RS 4 +.EX +$ nc \-l \-p 9000 >data.bin +.EE +.RE +.PP +On the sender, send the file. +Both commands exit when it has been sent: +.PP +.RS 4 +.EX +$ nc 192.168.1.5 9000 +and +.BR < , +with a period for each byte that is not printable ASCII. +.PP +Several specifiers may follow one another in a +.B \-t +argument, as in +.BR dCdS , +but a numeric size must end the argument. +A letter after it, such as the +.B z +in +.B x1z +or the second +.B d +in +.BR d2d2 , +gives a misleading error about a 4294967295-byte type. +Give the size as a letter, as in +.BR xCz , +or give +.B \-t +again. +.SS Traditional syntax +Without +.BR \-\-traditional , +every operand is a file. +With it, at most one file may be given, and the operands can also be an +offset, which is the number of bytes to skip and replaces any +.BR \-j , +and after an offset a label. +.PP +An offset is octal, or decimal when it contains a period, or +hexadecimal when it starts with +.B 0x +or +.BR 0X . +The period ends the number, and anything after it is ignored. +A leading +.B + +is ignored. +A +.B b +or +.B B +at the end of an octal or decimal number multiplies it by 512 or 1024, +as in +.B 1b +or +.BR 2b. ; +in a hexadecimal number they are digits. +.PP +One operand is an offset or a file. +Two operands are an offset and a label, or a file and an offset. +Three are a file, an offset, and a label. +Anything else is an error. +Where an offset may appear, an operand that starts with a digit, after +any +.BR + , +is taken as one, so +.B od \-\-traditional 1.txt +skips 1 byte of standard input, and a malformed offset such as +.B 1file +is an error. +.PP +The label, written like an offset, is the address to show for the first +byte written. +Each address is then followed by the label address in parentheses. +With +.BR "\-A n" , +only an address in parentheses is written, and it is the plain address, +not the label address. +.SH OPTIONS +Options may be grouped, as in +.BR \-bx , +and may follow the +.I file +operands. +An option's argument may be attached, as in +.BR \-N16 , +or be the next argument. +The argument of a long option may follow an +.B = +or be the next argument. +The exceptions are +.BR \-w , +.BR \-\-width , +and +.BR \-\-strings , +whose argument is optional and must be attached, as in +.B \-w8 +or +.BR \-\-strings=8 . +Long options may be abbreviated to a unique prefix. +.B \-\- +ends the options. +.PP +The arguments of +.BR \-j , +.BR \-N , +and +.B \-S +are numbers in decimal, hexadecimal with a +.B 0x +prefix, or octal with a leading +.BR 0 . +A lowercase +.BR b , +.BR k , +or +.B m +after the number multiplies it by 512, 1024, or 1048576. +A sign is not allowed. +.TP +.B \-a +Same as +.BR "\-t a" . +.TP +.B \-b +Same as +.BR "\-t oC" : +octal bytes. +.TP +.B \-c +Same as +.BR "\-t c" . +.TP +.B \-d +Same as +.BR "\-t u2" : +unsigned decimal 2-byte words. +.TP +.B \-D +Same as +.BR "\-t u4" . +.TP +.B \-f +Same as +.BR "\-t fF" : +4-byte floating point. +.TP +.BR \-h ", " \-x +Same as +.BR "\-t x2" : +hexadecimal 2-byte words. +.TP +.BR \-H ", " \-X +Same as +.BR "\-t x4" . +.TP +.BR \-i ", " \-I ", " \-l ", " \-L +Same as +.BR "\-t d4" : +signed decimal 4-byte integers. +All four are the same here; see +.BR NOTES . +.TP +.BR \-o ", " \-B +Same as +.BR "\-t o2" : +octal 2-byte words. +This is the default when no format is given. +.TP +.B \-O +Same as +.BR "\-t o4" . +.TP +.BR \-v ", " \-\-output\-duplicates +Write every block, including those identical to the one before. +.TP +.B \-s +Same as +.BR "\-t d2" : +signed decimal 2-byte words. +.TP +\fB\-t\fR \fItype\fR, \fB\-\-format=\fR\fItype\fR +Add the format or formats that +.I type +describes; see +.BR "Type specifiers" . +May be repeated. +An invalid +.I type +is an error. +.TP +\fB\-A\fR \fIradix\fR, \fB\-\-address\-radix=\fR\fIradix\fR +Write addresses in the radix named by the first character of +.IR radix : +.B d +for decimal, with at least 7 digits; +.B o +for octal, with at least 7 digits, the default; +.B x +for hexadecimal, with at least 6 lowercase digits; +or +.B n +for none, which also omits the final address. +Any other character is an error, but an empty +.I radix +is accepted and garbles the addresses. +.TP +\fB\-N\fR \fIbytes\fR, \fB\-\-read\-bytes=\fR\fIbytes\fR +Read at most +.I bytes +bytes of input, counted after the +.B \-j +skip. +Less is read if the input ends first. +If the skip and +.I bytes +together overflow 63 bits, it is an error. +.TP +\fB\-j\fR \fIbytes\fR, \fB\-\-skip\-bytes=\fR\fIbytes\fR +Skip +.I bytes +bytes of input before writing. +Within regular files the skip seeks, and a regular file wholly within it +is not read; other input is read and discarded. +A skip past the end of the combined input is an error, and nothing is +written. +A skip of 2 GiB or more into a regular file goes wrong; see +.BR NOTES . +.TP +\fB\-S\fR \fIlength\fR, \fB\-\-strings\fR[\fB=\fR\fIlength\fR] +Write strings instead of values. +A string is a run of at least +.I length +printable ASCII characters, 0x20 to 0x7e, ended by a NUL byte. +The default +.I length +is 3. +Each string is written on a line of its own, after its address and a +space, and no final address is written. +Any other byte, such as a tab, ends a run without a string, and so does +the end of the input. +Formats are checked but not otherwise used. +The argument of +.B \-S +is required. +.TP +\fB\-w\fR[\fIbytes\fR], \fB\-\-width\fR[\fB=\fR\fIbytes\fR] +Write +.I bytes +bytes of input per line, in decimal. +Without a number, the width is 32. +Without +.BR \-w , +it is 16, or the least common multiple of the value sizes when that +does not divide 16, as with a 12-byte +.B long double +on x86. +The width must be a positive multiple of the size of every value. +If it is not, +.B od +warns +.B invalid width +on standard error and uses the least common multiple of the sizes +instead. +.TP +.B \-\-traditional +Accept the operands described under +.BR "Traditional syntax" . +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options, so that later arguments such as +.B \-c +are file names. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid option, number, address radix, type, or operand; a skip past +the end of the input; a failed seek; a read or write error; or a file +that could not be opened. +.TP +.B 141 +Standard output is a pipe that was closed before all output was written. +.PP +A file that cannot be opened or read is reported, and +.B od +goes on with the next file. +A failed seek, described in +.BR NOTES , +is not reported, and +.B od +goes on from the start of the file. +Either way the exit status is 1. +The other errors stop +.B od +at once. +.SH EXAMPLES +Dump a file in the default format. +Each word is read little-endian, so the bytes 0x48 0x65 of +.B He +appear as 062510: +.PP +.RS 4 +.EX +$ od hello.txt +0000000 062510 066154 026157 073440 071157 062154 005041 +0000016 +.EE +.RE +.PP +Write the bytes in hexadecimal, with no addresses: +.PP +.RS 4 +.EX +$ od \-An \-tx1 hello.txt + 48 65 6c 6c 6f 2c 20 77 6f 72 6c 64 21 0a +.EE +.RE +.PP +Write hexadecimal addresses, hexadecimal bytes, and the bytes as text, +8 bytes per line: +.PP +.RS 4 +.EX +$ od \-Ax \-t xCz \-w8 hello.txt +000000 48 65 6c 6c 6f 2c 20 77 >Hello, w< +000008 6f 72 6c 64 21 0a >orld!.< +00000e +.EE +.RE +.PP +Print the 4-byte value at offset 0x3c of an EXE, the offset of its PE +header: +.PP +.RS 4 +.EX +$ od \-An \-tu4 \-j 0x3c \-N 4 xxd.exe + 128 +.EE +.RE +.PP +List the strings of at least 8 characters in a program, with their +addresses in hexadecimal: +.PP +.RS 4 +.EX +$ od \-Ax \-S 8 program.exe +.EE +.RE +.PP +Read 4-byte floating-point numbers: +.PP +.RS 4 +.EX +$ printf \(aq\e0\e0\e200\e077\(aq | od \-An \-tfF + 1.0000000e+000 +.EE +.RE +.PP +Skip the first 7 bytes with the obsolete operand syntax, in which the +offset is octal: +.PP +.RS 4 +.EX +$ od \-\-traditional \-tx1 hello.txt 7 +0000007 77 6f 72 6c 64 21 0a +0000016 +.EE +.RE +.SH NOTES +Unlike +.B od +on 64-bit Unix systems, +.BR \-I , +.BR \-l , +.BR \-L , +and the size +.B L +are 4 bytes, the size of a Windows +.BR long , +so they match +.B \-i +and +.BR "\-t d4" . +Use the size 8 for 8-byte integers, as in +.BR "\-t d8" . +.PP +The obsolete operands that POSIX describes are accepted only with +.BR \-\-traditional . +.PP +Floating-point numbers are formatted by the Microsoft C runtime, so +exponents have three digits, as in +.BR 1.0000000e+000 , +and infinities and NaNs are written in forms such as +.B 1.#INF000e+000 +and +.BR 1.#QNAN00e+000 . +That runtime cannot format a +.BR "long double" , +so the types +.B fL +and +.B f16 +(or +.B f12 +on x86) write wrong values. +Use +.B fD +for doubles. +.PP +With +.B \-A n +and more than one format, the lines after the first for each block are +indented by an arbitrary number of columns, because the width of the +missing address is read from past the end of a table. +.PP +With +.BR \-S , +a string cut off by the limit of +.B \-N +is written, but with an address one less than its own. +.PP +With +.B \-N +and no +.BR \-S , +input is read without buffering, so a program that shares standard input +with +.B od +continues where +.B od +stopped. +.PP +Addresses, and the numbers given to +.B \-j +and +.BR \-N , +are 64-bit, but a skip that reaches 2 GiB or more into a regular file +seeks with only the low 32 bits of the offset, as a signed number. +When those bits are negative the seek fails, and +.B od +dumps from the start of the file and exits with status 1, without a +message; otherwise it dumps from the wrong place. +Either way the addresses show the requested skip. +A pipe is skipped by reading, so +.B cat +.I file +.B | od \-j +.I bytes +works. +.PP +Input from files and pipes is read as bytes: a CR LF is not translated, +and Ctrl-Z does not end the input. +Output lines end with LF. +.PP +File names may use drive letters and either kind of slash. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +The names +.IR /dev/null , +.IR /dev/zero , +.IR /dev/urandom , +.IR /dev/stdin , +.IR /dev/tty , +and +.I /dev/fd/N +work as input files, but after reading +.IR /dev/fd/0 , +.B od +fails with +.B "standard input: Bad file descriptor" +and exits with status 1. +A directory fails with +.BR "Is a directory" . +.SH SEE ALSO +.BR busybox (1), +.BR hexdump (1), +.BR xxd (1) diff --git a/man/man1/paste.1 b/man/man1/paste.1 new file mode 100644 index 0000000..d80888e --- /dev/null +++ b/man/man1/paste.1 @@ -0,0 +1,335 @@ +.TH PASTE 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +paste \- merge lines of files +.SH SYNOPSIS +.B paste +.RB [ \-d +.IR list ] +.RB [ \-s ] +.RI [ file ...] +.SH DESCRIPTION +.B paste +reads its +.I file +operands and writes their lines side by side on standard output. +Each output line is made of lines of the files joined by delimiters, TAB +by default. +With no +.I file +operands, or for a +.I file +named +.BR \- , +it reads standard input. +.PP +A line ends at an LF. +A CR directly before the LF is removed, so files with CRLF and LF line +endings give the same result. +A NUL byte also ends a line, and is not written. +The last line of a file need not end with an LF. +Lines may be of any length. +Every output line ends with an LF. +.SS Parallel merge +Without +.BR \-s , +output line +.I n +is line +.I n +of every file, in operand order, with delimiters between them. +A file with fewer lines than the others supplies empty lines after its +last, so the delimiters are still written and the later columns stay +aligned. +Output stops after the last line of the longest file. +If every file is empty, nothing is written. +.PP +A file name given twice is opened twice, and the two are read +independently. +Operands that are +.B \- +share standard input, so they take turns reading it, one line each, in +operand order. +Thus +.B "paste \- \- \-" +writes three lines of input on each output line. +.SS Serial merge +With +.BR \-s , +each file produces one output line: all of its lines, joined by +delimiters. +The output lines are in operand order. +A file with no lines produces no output line. +Operands that are +.B \- +read the rest of standard input in turn, so when it is a file or pipe, +only the first of them produces a line. +.SS Delimiter lists +Between two consecutive lines on an output line, +.B paste +writes a delimiter taken from the list given by +.BR \-d , +which is a single TAB by default. +The delimiters are used in turn, and after the last one the list starts +again from the first. +The list starts over for each output line, or with +.BR \-s , +for each file. +No delimiter follows the last line. +.PP +The list is read as bytes, so a multibyte UTF-8 character is several +delimiters, one for each of its bytes. +Backslash sequences in the list are replaced before it is used: +.TP +.B \e\e +A backslash. +.TP +.BR \ea ", " \eb ", " \ee ", " \ef ", " \en ", " \er ", " \et ", " \ev +BEL, backspace, ESC, form feed, LF, CR, TAB, and vertical tab. +.TP +.BI \e ooo +The byte with octal value +.IR ooo , +using up to three digits and stopping before a digit that would make +the value exceed 255. +.TP +.BI \ex hh +The byte with hexadecimal value +.IR hh , +using one or two digits of either case. +.PP +A NUL delimiter, as from +.BR \e0 , +is written as nothing, but still takes its place in the list. +Any other backslash sequence is kept as written: the delimiters of +.B \ez +are a backslash and +.BR z . +So are a backslash at the end of the list and a +.B \ex +with no hexadecimal digit after it. +.SH OPTIONS +Options may follow the operands, and may be grouped, as in +.BR \-sd . +The argument of +.B \-d +may be the next argument or be attached to it, as in +.BR \-d: . +.B \-\- +ends the options. +.TP +.BI "\-d " list +Use the delimiters in +.IR list , +described under +.BR "Delimiter lists" , +instead of TAB. +When given more than once, the last +.B \-d +is used. +An empty +.I list +is an error, reported as +.BR "\-d \(aq\(aq is not supported" ; +use +.B \e0 +for no delimiter. +.TP +.B \-s +Merge serially: write one output line for each file, as described under +.BR "Serial merge" . +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments, including option arguments, are expanded +against file names at startup, as needed when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, and the console interprets the +bytes in its own code page; see +.BR NOTES . +.TP +.B POSIXLY_CORRECT +When set, the first +.I file +operand ends the options, so that later arguments such as +.B \-s +are file names. +.PP +Variables that busybox-w32 reads in every applet, such as those that +control console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An invalid option or a missing option argument, with a usage message on +standard error; an empty +.B \-d +list; a +.I file +that could not be opened; a failure writing standard output; or memory +exhausted. +Each is reported on standard error. +.TP +.B 141 +Standard output is a pipe whose reader exited while +.B paste +was writing. +Output still buffered when +.B paste +finishes is written as it exits, and a broken pipe found then is instead +reported as a write error, with status 1. +.SH EXAMPLES +Put two files side by side: +.PP +.RS 4 +.EX +$ paste names.txt ages.txt +ann 31 +bob 27 +.EE +.RE +.PP +Join the lines of two files with a comma: +.PP +.RS 4 +.EX +$ paste \-d, names.txt ages.txt +ann,31 +bob,27 +.EE +.RE +.PP +Arrange the lines of a list in three columns: +.PP +.RS 4 +.EX +$ seq 6 | paste \- \- \- +1 2 3 +4 5 6 +.EE +.RE +.PP +Join all the lines of a list into one line: +.PP +.RS 4 +.EX +$ seq 5 | paste \-sd, \- +1,2,3,4,5 +.EE +.RE +.PP +Combine pairs of lines into single lines, cycling through two +delimiters: +.PP +.RS 4 +.EX +$ seq 5 | paste \-s \-d \(aq \en\(aq +1 2 +3 4 +5 +.EE +.RE +.PP +Join the lines of two files with no delimiter: +.PP +.RS 4 +.EX +$ paste \-d \(aq\e0\(aq prefix.txt suffix.txt +.EE +.RE +.SH NOTES +Differences from GNU paste: +.IP \(bu 2 +There is no +.BR \-z , +and no long options but +.BR \-\-help . +.IP \(bu 2 +A CR before an LF is removed, and a NUL byte ends a line. +.IP \(bu 2 +An empty +.B \-d +list is an error, where GNU paste uses no delimiter. +.IP \(bu 2 +The list also takes +.BR \ea , +.BR \ee , +octal, and hexadecimal escapes, and an unknown sequence keeps its +backslash. +.IP \(bu 2 +With +.BR \-s , +an empty file produces no line, not an empty one. +.PP +All operands are opened before any input is read. +If one cannot be opened, +.B paste +reports the first such file, writes nothing, and exits with status 1. +A read error is not reported; it ends that file as end of file would. +.PP +From +.BR cmd.exe , +wildcard characters in an argument, even a quoted one or the list of +.BR \-d , +are expanded against file names unless +.B BB_GLOBBING +is +.BR 0 , +so a list of +.B * +can be replaced by file names. +A pattern that matches no file is left as it is. +Commands run from the kit's shell normally get no such expansion; see +.B BB_GLOBBING +under +.BR ENVIRONMENT . +.PP +Files and the standard streams are binary, so the C runtime translates +no line endings. +Output lines end in LF even where the input lines end in CRLF. +.PP +File names may use drive letters and backslashes. +They may contain any Unicode characters on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +The device names +.IR /dev/null , +.IR /dev/stdin , +and +.I /dev/tty +(the console) work as on Unix. +A directory operand fails with +.BR "Is a directory" . +.PP +When standard output is a console, bytes above 0x7F are converted for +display from the ANSI code page, which is UTF-8 on Windows 10 version +1903 and later, to the console's code page, unless +.B LC_ALL +or a related variable is +.BR C . +Escape sequences in the input lines, such as those for color, take +effect, and busybox emulates them on consoles without virtual terminal +support. +.PP +On Windows 10 version 1903 and later, non-ASCII characters typed at a +console arrive in the console's input code page, not in UTF-8. +.SH SEE ALSO +.BR busybox (1), +.BR cat (1), +.BR cut (1), +.BR join (1) diff --git a/man/man1/patch.1 b/man/man1/patch.1 new file mode 100644 index 0000000..68844f4 --- /dev/null +++ b/man/man1/patch.1 @@ -0,0 +1,513 @@ +.TH PATCH 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +patch \- apply a unified diff to files +.SH SYNOPSIS +.B patch +.RB [ \-ENR ] +.RB [ \-p +.IR N ] +.RB [ \-i +.IR patchfile ] +.RB [ \-\-dry\-run ] +.RI [ file +.RI [ patchfile ]] +.SH DESCRIPTION +.B patch +applies the changes in a unified diff, the format that +.BR diff (1) +writes, to the files that the diff names. +It is the +.BR busybox (1) +applet, which is much simpler than GNU +.BR patch ; +see +.BR NOTES . +.PP +The diff is read from standard input, from the file named by +.BR \-i , +or from the second operand, +.IR patchfile , +which is used only when there is a first operand. +A +.I patchfile +of +.B \- +is standard input. +Only unified diffs are understood. +Outside a hunk, a line that starts with +.B \-\-\- +or +.B +++ +and a space is a file header, and a line that starts with +.B "@@ \-" +after a +.B +++ +line is a hunk header. +Every other line outside a hunk is ignored, so text before a diff and +the extra header lines of a git diff do nothing. +A git diff that only renames a file or changes its mode has no effect, +and neither has a binary patch. +.PP +A hunk ends when it has as many lines as its header counts. +An empty line in a hunk is a context line for an empty line. +If a line that does not start with a space, +.BR + , +.BR \- , +or +.B \e +comes first, the hunk fails, and if the diff ends first, the hunk is +ignored. +.SS "File names" +The file to change is named on the +.B +++ +line of its header. +The exception is a file that the diff empties, described below, which is +named on the +.B \-\-\- +line. +A name ends at the first tab, so a time stamp after a tab is not part of +it, and a name may contain spaces. +A time stamp that starts with a year from 1901 to 1970 makes the name +.IR /dev/null , +which stands for a file that does not exist. +.PP +Leading directories are removed from the name as +.B \-p +says. +If +.I file +is given, it is the file for every section of the diff, and the names in +the diff are not used, not even to recognize +.IR /dev/null . +.SS "Applying hunks" +.B patch +ignores the line numbers in hunk headers. +It copies the file to a temporary file in the same directory. +For each hunk, in order, it searches forward from the end of the +previous hunk for a place where the hunk's context lines and removed +lines occur together, and writes the hunk's context lines and added +lines there. +Lines must be equal exactly, except that a CR before an LF is ignored. +There are no offsets, no fuzz, and no leniency about white space. +Hunks therefore must be in the same order in the diff as in the file. +A hunk with no trailing context lines, or with fewer trailing than +leading context lines, matches only at the end of the file. +Every hunk that +.B "diff \-U0" +writes is such a hunk. +.PP +When all the hunks of a file have applied, the temporary file replaces +the file. +When a hunk cannot be applied, +.B patch +reports it, leaves the file unchanged, even if earlier hunks applied, +skips the rest of the diff's hunks for that file, and goes on to the +next file. +The exit status is then 1. +.SS "Creating and removing files" +A file is created when the +.B \-\-\- +line names +.IR /dev/null , +or when the old range of its first hunk is exactly +.BR \-0,0 , +as in +.BR "@@ \-0,0 +1,3 @@" . +.B patch +creates any missing directories above it, and the file must not already +exist, even as an empty file. +.B "diff \-U0" +also writes +.B \-0,0 +for lines added at the top of a file, and +.B patch +then stops with an error because the file exists. +.PP +The diff empties a file when the +.B +++ +line names +.IR /dev/null , +or when the new range of its first hunk is exactly +.BR +0,0 . +.B patch +truncates the file to zero length, or with +.B \-E +removes it. +It does not compare the file with the hunks, so any file with that name +is emptied or removed, and it ignores the rest of the file's hunks. +.B "diff \-U0" +also writes +.B +0,0 +for lines removed from the top of a file, so such a diff empties the +whole file. +.SS Messages +.B patch +prints one line on standard output for each file it processes, with the +name as left by +.BR \-p : +.TP +.BI "patching file " name +The file is patched, or emptied. +.TP +.BI "creating " name +The file is created. +.TP +.BI "removing " name +The file is removed because of +.BR \-E . +.PP +The other messages go to standard error: +.TP +.BI "Possibly reversed hunk " n " at " line +Hunk +.I n +of the file, counting from 1, cannot be applied, and a line that it adds +was found in the file where it would add it. +.I line +is one more than the number of lines in the file. +.TP +.BI "Hunk " n " FAILED " old / new .\& +Hunk +.I n +of the file could not be applied. +.I old +and +.I new +are the start lines in its header. +The lines of the hunk follow, as they are in the diff. +Only the first failed hunk of a file is reported. +.TP +.BI "patch: " message +An error. +.B patch +ends at once. +Files that are already finished stay changed, and a file in progress is +left unchanged, with its temporary file beside it. +.SH OPTIONS +Options may be grouped, as in +.BR \-Np0 . +An option's argument may be attached, as in +.BR \-p1 , +or be the next argument. +Long options may be abbreviated to a unique prefix, and the argument of +a long option may follow +.B = +or be the next argument. +Options may follow the operands, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +Options not listed here are errors. +.TP +\fB\-p\fR \fIN\fR, \fB\-\-strip=\fIN\fR +Remove the first +.I N +components from the file names in the diff. +A component is a name and the slashes after it, and a leading slash is a +component by itself, so +.B \-p1 +turns +.I /a/b/c +into +.IR a/b/c , +and +.I a/b/c +into +.IR b/c . +The last component is never removed, so a name with +.I N +or fewer components keeps its last one. +Without +.BR \-p , +every directory is removed, leaving the last component: the file is +looked for in the current directory. +.B \-p0 +keeps the names as they are. +.I N +is a decimal number, and a negative +.I N +makes +.B patch +hang. +.TP +\fB\-i\fR \fIpatchfile\fR, \fB\-\-input=\fIpatchfile\fR +Read the diff from +.I patchfile +instead of standard input. +A +.I patchfile +of +.B \- +is standard input. +This takes the place of a +.I patchfile +operand, which is then ignored. +.TP +.BR \-R ", " \-\-reverse +Reverse the diff: remove the lines it adds, and restore the lines it +removes. +The file is still the one on the +.B +++ +line. +See +.B NOTES +for diffs that create or remove files. +.TP +.BR \-N ", " \-\-forward +Skip a hunk that is already applied, rather than fail. +When the file matches a hunk up to its first added line (a +.B + +line, or with +.B \-R +a +.B \- +line), and the next line of the file equals that line, +.B patch +takes the hunk as applied: it skips the hunk if the rest of the file +matches the patched text, and fails it otherwise. +.BR diff (1) +writes the removed lines of a change first, so a hunk whose first change +replaces lines is recognized only with +.BR \-R . +A hunk that adds a line equal to the one after it, such as a second +.BR } , +fails, although it applies without +.BR \-N . +.TP +.BR \-E ", " \-\-remove\-empty\-files +Remove a file that the diff empties, instead of leaving it empty, and +print +.BR removing . +.TP +.B \-\-dry\-run +Change nothing: create, truncate, remove, and replace no files, and +leave no temporary files. +The messages are as usual, a failed hunk still sets exit status 1, and +a file to be patched must exist. +.TP +.BR \-u ", " \-\-unified +Accepted and ignored. +Only unified diffs are understood anyway. +.TP +.BR \-f ", " \-\-force +Accepted and ignored. +.B patch +never asks a question. +.TP +.B \-g +Accepted and ignored. +It takes no argument, so the +.B \-g0 +form that other implementations accept is an error. +.TP +.BI "\-\-get " n +Accepted and ignored, with its argument. +.TP +.B \-\-backup\-if\-mismatch +Accepted and ignored. +.B patch +makes no backup files. +.TP +.B \-\-no\-backup\-if\-mismatch +Accepted and ignored. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit with status 0. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded when +.B patch +starts, as needed when it is run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B BB_UMASK +The file mode creation mask, in octal. +When it includes the owner write bit, +.BR 200 , +the files that +.B patch +patches or creates are read-only. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every hunk applied or was skipped by +.BR \-N , +or the diff had none. +A hunk that the end of the diff cuts short is ignored. +.TP +.B 1 +A hunk failed, or an error ended the program: an invalid command line, +with a usage message on standard error, an argument of +.B \-p +that is not a number, a hunk header whose old and new ranges are both +empty, a file that cannot be opened, or one that cannot be created +because it exists. +.SH EXAMPLES +Apply a diff made from a source tree, from the top of the tree: +.PP +.RS 4 +.EX +$ patch \-p1 hello.diff +$ patch hello.c.new hello.diff +.EE +.RE +.PP +Patch a file that has CR LF line endings, and restore them: +.PP +.RS 4 +.EX +$ patch dos.txt dos.diff +$ unix2dos dos.txt +.EE +.RE +.SH NOTES +Differences from GNU +.BR patch : +.IP \(bu 2 +Only unified diffs are understood. +.IP \(bu 2 +Hunks are found by content alone, with no fuzz and no offsets. +.IP \(bu 2 +A failed hunk gives up on its whole file, where GNU +.B patch +applies the other hunks. +.IP \(bu 2 +Neither backup nor reject files are made, and a failed hunk is only +printed. +.IP \(bu 2 +It asks no questions, and warns about a reversed hunk only when the +hunk fails. +.IP \(bu 2 +The exit status is never 2. +.IP \(bu 2 +Options such as +.BR \-b , +.BR \-d , +.BR \-F , +.BR \-l , +.BR \-o , +.BR \-r , +and +.B \-s +are errors. +.PP +With +.BR \-R , +no file is ever created, and the file named on the +.B \-\-\- +line is emptied, or removed with +.BR \-E , +when the +.B +++ +line names +.I /dev/null +or the old range of the first hunk is +.BR \-0,0 . +So +.B \-R +cannot undo a diff that creates or removes a file. +Reversing a creation empties or removes a file named like +.I /dev/null +after +.B \-p +is applied, such as +.I null +without +.BR \-p , +and fails when there is no such file. +Reversing a removal empties or removes the file that it should restore, +and fails when there is none. +.PP +Files are read and written in binary mode. +A CR before an LF is ignored in the diff and in the file when lines are +compared, so a diff with CR LF line endings applies to a file with LF +endings, and the reverse. +Every line that +.B patch +writes itself ends with LF, though. +The part of a file after the last hunk is copied unchanged, so a file +with CR LF line endings comes out with LF endings up to the end of the +last hunk and CR LF endings after it. +.BR unix2dos (1) +makes them the same again. +.PP +A line in a hunk that is followed by the marker +.B \e No newline at end of file +is written without a newline. +A last line that lacks a newline gets one when +.B patch +writes it and its line in the hunk has no such marker. +.PP +A name in the diff may be a Windows path. +Only a forward slash separates the components that +.B \-p +removes, so a backslash is part of a component, and a drive letter such +as +.B C: +is a component of its own. +Missing directories are created only above a name that has a forward +slash. +.I /dev/null +is recognized by that spelling only, and not as +.IR nul . +File names, including those in the diff, are UTF-8 and may contain any +Unicode characters on Windows 10 version 1903 and later, and are limited +to the system code page on earlier versions. +.PP +The temporary file is named after the file with six more characters. +It replaces the file by a rename, so the result is a new file: it is +not read-only, even if the old one was, and other hard links to the old +file keep the old content. +If the rename fails, as when another program has the file open, the file +stays unchanged and the result stays in the temporary file, with no +message and exit status 0. +.PP +The file is read one octet at a time up to the end of the last hunk, +which is slow for a large file: a hunk near the end of a file of 7 MB +takes several seconds, and a failed hunk always reads the rest of the +file. +.SH SEE ALSO +.BR busybox (1), +.BR diff (1), +.BR unix2dos (1) diff --git a/man/man1/pgrep.1 b/man/man1/pgrep.1 new file mode 100644 index 0000000..aec9ec3 --- /dev/null +++ b/man/man1/pgrep.1 @@ -0,0 +1,376 @@ +.TH PGREP 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +pgrep, pkill \- find or signal processes by name +.SH SYNOPSIS +.B pgrep +.RB [ \-lvx ] +.I pattern +.br +.B pgrep +.RB [ \-lvx ] +.B \-P +.I ppid +.RI [ pattern ] +.br +.B pkill +.RB [ \-\c +.IR signal ] +.RB [ \-evx ] +.I pattern +.br +.B pkill +.RB [ \-\c +.IR signal ] +.RB [ \-evx ] +.B \-P +.I ppid +.RI [ pattern ] +.br +.B pkill \-l +.SH DESCRIPTION +.B pgrep +writes the process ID of each running process whose name matches +.IR pattern , +one per line, on standard output. +.B pkill +instead sends each such process a signal, +.B TERM +by default. +Neither selects its own process. +.PP +.I pattern +is an extended regular expression, as in +.BR "grep \-E" , +and matches case-sensitively anywhere in the name unless +.B \-x +is given. +With +.BR \-P , +a process must also be a child of +.IR ppid , +.I pattern +is optional, and operands after the first are ignored. +Without +.BR \-P , +exactly one +.I pattern +is required. +.PP +Processes are visited in the order Windows lists them, not sorted by +process ID. +.SS Process names +Only the name of a process is matched, never its command line. +The name is the file name of its executable as Windows reports it, +including the extension, such as +.BR explorer.exe , +truncated to 31 bytes. +A process running the same build of busybox is named after its applet +instead, such as +.B sh +or +.BR sleep , +and a script whose +.B #!\& +line names an applet may be named after the script file. +The kit's command launchers, such as +.B sh.exe +and +.BR pgrep.exe , +appear under their own names, each alongside the busybox process it +started. +.SH OPTIONS +Options may be grouped, as in +.BR \-lx , +and the argument of +.B \-P +may be attached, as in +.BR \-P1234 . +Options may follow +.IR pattern , +unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options, so that a +.I pattern +may begin with +.BR \- . +.TP +.BI \- signal +Send +.I signal +instead of +.BR TERM . +Only +.B pkill +accepts it, and only as the first argument. +.I signal +is a name, in any case and with or without a +.B SIG +prefix, or a number from 0 to 22. +The names are those listed by +.BR "pkill \-l" : +.BR HUP , +.BR INT , +.BR QUIT , +.BR ILL , +.BR FPE , +.BR KILL , +.BR SEGV , +.BR PIPE , +.BR TERM , +and +.BR ABRT , +plus +.B EXIT +for 0. +Signal 0, and a number without a name, select processes but send +nothing. +See +.B NOTES +for what the signals do on Windows. +.TP +.B \-l +For +.BR pgrep , +write each process's name after its ID, separated by a space. +For +.BR pkill , +write the signal numbers and names on standard output and exit without +signaling anything. +.TP +.B \-v +Negate the match: select the processes that would otherwise not be +selected. +With both +.B \-P +and +.IR pattern , +a process is selected if its parent is not +.I ppid +or its name does not match. +.TP +.B \-x +Require +.I pattern +to match the whole name. +Since names include the extension, +.B pgrep \-x explorer +does not match +.BR explorer.exe . +.TP +.BI "\-P " ppid +Select only children of the process +.IR ppid , +a non-negative decimal integer. +.TP +.B \-e +For +.BR pkill , +write a line +.IB name " killed (pid " pid ) +on standard output for each selected process, even when the signal was +not delivered. +.B pgrep +accepts +.B \-e +and ignores it. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and +exit. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the wildcards +.B * +and +.B ?\& +in arguments are expanded as file names before the command sees them, +even inside quotes, so a +.I pattern +such as +.B vim.*\& +may be replaced by file names, as when run from +.BR cmd.exe . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.B POSIXLY_CORRECT +If set, even to an empty value, the first operand ends the options. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +At least one process was selected, or +.B pkill \-l +or +.B \-\-help +was given. +.B pkill +exits 0 even when a signal could not be delivered. +.TP +.B 1 +No process was selected, or an error such as an invalid option, +.IR ppid , +or regular expression. +Selecting only process 0, +.BR "[System\ Process]" , +also exits 1. +.PP +A +.B pkill +that selects process 0 signals itself; see +.BR NOTES . +.SH EXAMPLES +List Vim processes with their names: +.PP +.RS 4 +.EX +$ pgrep \-l vim +.EE +.RE +.PP +Terminate every instance of a program, and show what was signaled: +.PP +.RS 4 +.EX +$ pkill \-e \-x \(aqserver\e.exe\(aq +server.exe killed (pid 12704) +server.exe killed (pid 16776) +.EE +.RE +.PP +Terminate a 32-bit program from a 64-bit busybox, which requires +.BR KILL : +.PP +.RS 4 +.EX +$ pkill \-KILL \-x \(aqserver32\e.exe\(aq +.EE +.RE +.PP +List the children of the current shell: +.PP +.RS 4 +.EX +$ sleep 60 & +[1] 22068 +$ pgrep \-l \-P $$ +22068 sleep +.EE +.RE +.PP +Check whether a program is running: +.PP +.RS 4 +.EX +$ pgrep \-x \(aqgdb\e.exe\(aq >/dev/null && echo running +.EE +.RE +.SH NOTES +Differences from the procps commands and from busybox on Linux: +.IP \(bu 2 +There is no +.BR \-a , +.BR \-f , +.BR \-n , +.BR \-o , +or +.BR \-s , +which busybox has on Linux, nor +.BR \-i , +.BR \-u , +or the other procps options. +.IP \(bu 2 +Names include the extension, and matching is case-sensitive although +Windows file names are not. +A bracket expression such as +.B [Nn]otepad +matches either case. +.IP \(bu 2 +Errors exit with status 1, the same as no match, not 2 or 3. +.PP +Every process on the system is listed, including those of other users +and system processes such as +.BR System . +A process whose parent has exited has parent ID 1, unless Windows has +since reused the parent's ID, in which case it appears to be a child of +the process now holding that ID. +.B pkill +silently fails to signal a process it cannot open. +.PP +Windows has no signals, so +.B pkill +emulates them as +.BR kill (1) +does. +.B KILL +calls +.BR TerminateProcess , +and any other signal that is sent makes the process call +.B ExitProcess +from a thread injected into it. +No signal handler runs either way, and +.B INT +does not send Ctrl+C. +The exit code of the process is the signal number shifted left 24 bits, +such as +.B 0x0F000000 +for +.BR TERM , +which the kit's shell reports as 128 plus the signal number. +.B pkill +does not wait for the process to exit. +Injecting a thread works only when the process and busybox are both +32-bit or both 64-bit, so otherwise only +.B KILL +takes effect. +Only the selected process is signaled, not its children. +.PP +Process 0, +.BR "[System\ Process]" , +is listed first, and a +.B pkill +that selects it signals itself and its descendants in its place, as +.BR kill (1) +does for PID 0. +Unless the signal is 0 or a number without a name, +.B pkill +then ends as if by that signal, and may not signal the processes after +it. +A pattern such as +.B ss +or +.B o +matches +.BR "[System\ Process]" , +and +.B \-v +with most other patterns selects it. +.PP +Each command excludes only its own process. +When started through the kit's +.B pgrep.exe +or +.B pkill.exe +launcher, as from +.BR cmd.exe , +the launcher is not excluded, so a +.B pkill +whose pattern matches +.B pkill.exe +signals its own launcher. +.SH SEE ALSO +.BR busybox (1), +.BR grep (1), +.BR kill (1), +.BR killall (1), +.BR pidof (1), +.BR ps (1) diff --git a/man/man1/pidof.1 b/man/man1/pidof.1 new file mode 100644 index 0000000..b66f10e --- /dev/null +++ b/man/man1/pidof.1 @@ -0,0 +1,323 @@ +.TH PIDOF 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +pidof \- list the process IDs of running programs by name +.SH SYNOPSIS +.B pidof +.RB [ \-s ] +.RB [ \-o +.IR pid ]...\& +.RI [ name ...] +.SH DESCRIPTION +.B pidof +writes the process ID of each running process whose name is one of the +.I name +operands. +It takes the operands in order, and for each one writes the IDs of the +processes with that name. +The IDs go on one line of standard output, separated by spaces. +When no ID is written, nothing is written, not even a newline, and the +exit status is 1. +It reads no input. +Its messages go to standard error. +.PP +This +.B pidof +is a busybox applet; see +.BR busybox (1). +A +.I name +is an exact process name, not a pattern. +To select processes by pattern, use +.BR pgrep (1). +.PP +The IDs for one name are in the reverse of the order in which Windows +lists the processes, which need not be sorted by ID. +A process that matches several operands is written once for each, so +.B pidof sh sh +writes every shell twice. +The list of processes is read again for each operand, and covers every +process on the system, including those of other users. +.PP +The process running +.B pidof +is named +.BR pidof , +so +.B pidof pidof +writes its own ID. +.SS Process names +Only the name of a process is matched, never its path or command line. +The name is the file name of its executable as Windows reports it, +including the extension, such as +.BR explorer.exe . +The comparison is case-sensitive, although Windows file names are not, +and the extension is part of the name, so +.B make +does not match +.BR make.exe . +An operand with a directory part, such as +.BR /bin/sh , +matches nothing. +.PP +A process running the same build of busybox is named after its applet +instead, such as +.B sh +or +.BR sleep . +A script whose +.B #!\& +line names an applet is named after the script file, except that a shell +script run from the kit's shell is named after the shell, such as +.BR sh . +The kit's command launchers, such as +.B sleep.exe +and +.BR pidof.exe , +appear under their own names, each alongside the busybox process it +started, so +.B pidof sleep +finds the busybox process and +.B pidof sleep.exe +finds the launcher. +A busybox process of a different build, or one that +.B pidof +cannot open, is named after its executable file instead, such as +.BR busybox.exe . +.PP +Only the first 15 bytes of a long name are compared. +A process name of 15 or more bytes matches any operand that agrees with +it in its first 15 bytes, however the two differ after that. +So +.B pidof x86_64\-w64\-mingw32\-gcc.exe +also finds +.BR x86_64\-w64\-mingw32\-g++.exe , +and the extension may be left off a name with 15 or more bytes before +it. +A shorter process name must match the whole operand. +.PP +The idle process, with process ID 0 and the name +.BR "[System\ Process]" , +is never written. +.SH OPTIONS +Options may be grouped, as in +.BR \-so , +and the argument of +.B \-o +may be attached, as in +.BR \-o4 . +Options may follow the names. +.B \-\- +ends the options, so that every later argument is a +.IR name , +even one that begins with a dash. +.TP +.B \-s +Write only one ID for each name: the first that would otherwise be +written, after any omitted by +.BR \-o . +The limit is per name operand, not for the whole command, so +.B pidof \-s sh sleep +writes up to two IDs. +.TP +.BI "\-o " pid +Omit the process ID +.I pid +from the output. +The option may be repeated, to omit several IDs. +.I pid +is a decimal integer from 0 to 4294967295, or +.BR %PPID , +which stands for the ID of the parent of +.BR pidof , +the process that started it; see +.BR NOTES . +A parent that has exited has ID 1, unless Windows has since reused its +ID. +.IP +A value that is neither, including a number with a sign or a +.B 0x +prefix, fails with +.B invalid number +and exit status 1. +This happens only when +.B pidof +compares the value to an ID it found, so a bad value goes unnoticed if +nothing is found, or if earlier +.B \-o +values omit every ID found. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the operands are expanded as file names before +.B pidof +sees them, even inside quotes, as needed when run from +.BR cmd.exe . +A name is never a pattern, so the effect is only that an operand such as +.B app* +is replaced by the names of matching files in the current directory, +which are then taken as process names. +A pattern that matches nothing is left as it is. +A busybox process started with the variable unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +operands as the shell expanded them. +.TP +.B POSIXLY_CORRECT +When it is set, even to an empty value, the C library's option parser +stops at the first operand, so that +.B \-s +and +.B \-o +are recognized only before the first +.IR name . +.PP +Variables read by the startup code shared by all applets, such as +.B BB_CRITICAL_ERROR_DIALOGS +and +.BR BB_UMASK , +do not change what +.B pidof +does; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +At least one process ID was written, or +.B \-\-help +was given. +.TP +.B 1 +No process ID was written: no process matched, every match was omitted +by +.BR \-o , +or there was no +.IR name . +Also an invalid option, a +.B \-o +with no argument, or an invalid +.B \-o +value. +.PP +An invalid option or a missing argument is reported on standard error, +followed by the usage message. +An invalid +.B \-o +value is reported on standard error as +.PP +.RS 4 +.EX +pidof: invalid number \(aq\fIvalue\fR\(aq +.EE +.RE +.SH EXAMPLES +Find a running program: +.PP +.RS 4 +.EX +$ sleep 60 & +[1] 22068 +$ pidof sleep +22068 +.EE +.RE +.PP +Test whether a program is running: +.PP +.RS 4 +.EX +$ pidof gdb.exe >/dev/null && echo running +.EE +.RE +.PP +Count the running instances of a program, as the IDs are all on one +line: +.PP +.RS 4 +.EX +$ pidof sleep | wc \-w +3 +.EE +.RE +.PP +Write the IDs one per line: +.PP +.RS 4 +.EX +$ pidof sleep | tr \(aq \(aq \(aq\en\(aq +.EE +.RE +.PP +List the other shells, leaving out the shell that runs the command: +.PP +.RS 4 +.EX +$ pidof \-o %PPID sh +.EE +.RE +.SH NOTES +Differences from the procps +.BR pidof , +and from busybox on Linux: +.IP \(bu 2 +Only a process's name is matched. +Busybox on Linux also matches the name a program was started with, and +the name of its executable file, or its full path when the operand +begins with a slash. +.IP \(bu 2 +Names include the extension and are case-sensitive. +.IP \(bu 2 +There are no options other than +.B \-s +and +.BR \-o . +.PP +The list of processes is a snapshot, so a process may have exited by the +time its ID is written. +The applet name of a busybox process is read from the memory of that +process, which fails for a process that Windows does not let busybox +open, such as an elevated one or one of another user. +Names are compared as bytes in the ANSI code page, which is UTF-8 on +Windows 10 version 1903 or later; see +.BR busybox (1). +.PP +Unlike +.BR kill (1) +and +.BR killall (1), +which the kit's shell runs without starting a process, +.B pidof +runs in a process of its own, whose parent is the shell. +As the last command of +.BR "sh \-c" , +or under +.BR exec , +it runs in the shell's own process instead, so its parent, and so +.BR %PPID , +is the parent of that shell, and that shell, now named +.BR pidof , +is not found as +.BR sh . +When started through the kit's +.B pidof.exe +launcher, as from +.BR cmd.exe , +the parent is the launcher instead, not the program that ran the +launcher. +Then +.B %PPID +is the ID of the launcher, and omits only a process named +.BR pidof.exe . +.SH SEE ALSO +.BR busybox (1), +.BR kill (1), +.BR killall (1), +.BR pgrep (1), +.BR pkill (1), +.BR ps (1), +.BR sh (1) diff --git a/man/man1/pipe_progress.1 b/man/man1/pipe_progress.1 new file mode 100644 index 0000000..c1e8b4f --- /dev/null +++ b/man/man1/pipe_progress.1 @@ -0,0 +1,123 @@ +.TH PIPE_PROGRESS 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +pipe_progress \- pass data through a pipe, showing activity with dots +.SH SYNOPSIS +.B pipe_progress +.SH DESCRIPTION +.B pipe_progress +copies standard input to standard output unchanged, and writes dots to +standard error, so that a long pipeline shows that data is still +flowing. +It takes no file operands: it reads standard input until end of input. +.PP +It reads in blocks of at most 4096 bytes. +After each read, it takes the time from the system clock, in whole +seconds. +If that differs from the time at start-up, or from the time of the +previous dot, it writes a dot to standard error and then writes the +block to standard output. +Each dot is written to standard error at once. +.PP +So a dot is written at most once per block, and a steady stream gives +about one dot per second. +The first dot can come less than a second after the start. +Dots mark arriving data, not elapsed time: nothing is written while a +read waits, and the first block after a stall of any length gets one +dot. +A pipeline whose data all arrives within the clock second in which it +started writes no dots. +There is no total or percentage; the program does not know how much +data to expect. +.PP +At end of input, +.B pipe_progress +writes a newline to standard error, even when it wrote no dots, so that +the next prompt starts on a fresh line. +.PP +An error reading standard input ends the copy as if at end of input. +An error writing standard output is ignored, and the rest of that block +is lost, unless standard output is a pipe whose reader has exited (see +.BR "EXIT STATUS" ). +Neither is reported. +.SH OPTIONS +No option is examined. +Any argument other than a first argument of +.B \-\-help +is ignored. +.TP +.B \-\-help +Print a usage message on standard output and exit. +It is recognized only as the first argument. +.SH ENVIRONMENT +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +This includes the case where standard input could not be read or +standard output could not be written, other than as below. +.TP +.B 141 +Standard output or standard error is a pipe whose reader has exited. +This is noticed only when a write to it fails: on standard output when +the next block arrives, and on standard error at the next dot or the +final newline, even after all the data was copied. +.SH EXAMPLES +Show activity while a directory tree is archived and compressed: +.PP +.RS 4 +.EX +$ tar cf - src | pipe_progress | bzip2 >src.tar.bz2 +.EE +.RE +.PP +Copy a large file to another drive, with dots on the console: +.PP +.RS 4 +.EX +$ pipe_progress d:/disk.img +.EE +.RE +.SH NOTES +The dots go to standard error, so they still show when standard output +is redirected to a file or another command. +Redirect standard error to hide them. +.PP +The time comes from the system clock, not from a monotonic timer. +If the clock is set back, the next block also gets a dot. +.PP +Standard input, output, and error are binary: CR LF pairs, NUL bytes, +and Ctrl-Z characters in the data pass through unchanged. +.PP +Lines typed at a console arrive with CR LF line endings. +To end the input, type Ctrl-Z at the start of a line and press Enter. +Elsewhere in a line, Ctrl-Z is copied as data, and Ctrl-D is an ordinary +character. +On Windows 10 version 1903 and later, non-ASCII characters typed at a +console arrive in the console's input code page, not in UTF-8. +.PP +When standard output is a console, text is converted for display from +the ANSI code page, which is UTF-8 on Windows 10 version 1903 and later. +Escape sequences, such as those for color, take effect, and busybox +emulates them on consoles without virtual terminal support. +Where busybox emulates them, an escape sequence split between two blocks +is not recognized, and is written as text. +A block that contains a NUL byte is written as is, with no conversion +or emulation. +This is decided for each block, so other blocks are still converted. +.SH SEE ALSO +.BR busybox (1), +.BR bzip2 (1), +.BR cat (1), +.BR tar (1) diff --git a/man/man1/pkill.1 b/man/man1/pkill.1 new file mode 100644 index 0000000..0e94b52 --- /dev/null +++ b/man/man1/pkill.1 @@ -0,0 +1 @@ +.so man1/pgrep.1 diff --git a/man/man1/printenv.1 b/man/man1/printenv.1 new file mode 100644 index 0000000..feedf38 --- /dev/null +++ b/man/man1/printenv.1 @@ -0,0 +1,240 @@ +.TH PRINTENV 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +printenv \- print environment variables +.SH SYNOPSIS +.B printenv +.RI [ name ...] +.SH DESCRIPTION +.B printenv +writes environment variables to standard output. +With no +.IR name , +it writes every variable, one per line, as +.IB name = value\fR. +The order is that of the process's environment: the order Windows +supplied the variables, followed by any that busybox added. +.PP +With one or more +.IR name s, +it writes the value of each variable in turn, followed by a LF, without +the name. +A name that is not set writes nothing and makes the exit status 1, and +the remaining names are still looked up. +A name may be repeated, and its value is written each time. +An empty name is never found. +A name that contains +.B = +is matched against a variable's name and value together: with +.B FOO +set to +.BR a=b , +.B printenv FOO=a +writes +.BR b . +.PP +Values are written as they are, without quoting, so a value that +contains newlines spans several lines. +A variable with an empty value writes an empty line and counts as +found, so the exit status tells an empty variable from one that is not +set. +.PP +Names are not case-sensitive: +.B printenv path +writes the value of +.BR PATH . +.SH OPTIONS +.B printenv +parses no options. +Apart from a first argument of +.BR \-\-help , +every argument, including +.B \-\- +and +.BR \-\-version , +is a name. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are ignored. +.SH ENVIRONMENT +The variables named as operands are read. +So are the following, which affect the lookup or the output. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the C runtime expands wildcards in the arguments when busybox starts, +quoted arguments too. +So when it is unset, as when +.B printenv +is run from +.B cmd.exe +or another program outside busybox, +.B printenv P* +looks up the names of the matching files and not the pattern. +A pattern that matches nothing is left as it is. +When the variable is unset, busybox then sets it to +.BR 0 , +so the listing includes +.BR BB_GLOBBING=0 . +.TP +.BR BB_TERMINAL_MODE ", " BB_SKIP_ANSI_EMULATION +When standard output is a console, decide whether the console or busybox +interprets the escape sequences in the values, such as for color. +See +.BR busybox (1). +.TP +.B CONEMUPID +When it is set and neither of the above is, busybox uses terminal mode +0: it turns virtual terminal output off and emulates escape sequences +itself. +.TP +.B HOME +When it is unset, +.B printenv HOME +writes the user's profile directory, with forward slashes, though the +listing does not include it. +The name must be in capitals: +.B printenv home +writes nothing. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.TP +.B TMPDIR +When it is unset, +.B printenv TMPDIR +writes the value of +.BR TMP , +or else of +.BR TEMP , +though the listing does not include it. +As with +.BR HOME , +the name must be in capitals. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every named variable was found, or no names were given. +.TP +.B 1 +A named variable is not set, with no message. +Also standard output could not be written, with a message such as +.B "printenv: standard output: Bad file descriptor" +on standard error. +.TP +.B 141 +Standard output is a pipe that was closed before the output was written, +and the output is too long for the C library's buffer. +No message is written. +Shorter output fails when +.B printenv +exits, with status 1. +.SH EXAMPLES +Write the value of one variable: +.PP +.RS 4 +.EX +$ printenv PATH +.EE +.RE +.PP +Test whether a variable is set, even if its value is empty: +.PP +.RS 4 +.EX +$ printenv EDITOR >/dev/null && echo set +.EE +.RE +.PP +Write several values, one per line, in the order asked. +The missing variable writes nothing and sets the status: +.PP +.RS 4 +.EX +$ FOO=1 BAR=2 printenv BAR FOO MISSING +2 +1 +$ echo $? +1 +.EE +.RE +.PP +List the busybox-w32 variables that are set: +.PP +.RS 4 +.EX +$ printenv | grep \(aq^BB_\(aq +BB_GLOBBING=0 +.EE +.RE +.PP +Write the environment with a NUL after each variable. +.B printenv +cannot do this, but +.B env +can: +.PP +.RS 4 +.EX +$ env \-0 +.EE +.RE +.SH NOTES +Differences from GNU +.BR printenv : +there are no options, so no +.B \-0 +or +.BR \-\-null , +and there is no +.BR \-\-version . +.B \-\-help +works only as the first argument. +.PP +Lines end with a bare LF, not CR LF. +.PP +Variables whose names begin with +.BR = , +such as the +.B =C: +and +.B =ExitCode +entries that +.B cmd.exe +keeps, are not visible to +.BR printenv , +neither in the listing nor by name. +.PP +Run from the kit's shell, +.B printenv +runs inside the shell process instead of starting a new one. +It sees the variables the shell has exported, and assignments on its own +command line, as in +.BR "FOO=1 printenv FOO" , +but not the shell's unexported variables. +The listing is in the shell's own order. +The shell changes some of what it imports from Windows, such as the +case of names and the separators in values; see +.BR sh (1). +.PP +busybox makes its ANSI code page UTF-8 on Windows 10 version 1903 and +later, so names and values may contain any Unicode character, and are +written to a file or pipe as UTF-8. +On older systems they are limited to the ANSI code page. +Output to a console is converted from the ANSI code page to the +console's code page. +Escape sequences in values, such as those for color, take effect, and +busybox emulates them on consoles without virtual terminal support. +.SH SEE ALSO +.BR busybox (1), +.BR env (1), +.BR sh (1) diff --git a/man/man1/printf.1 b/man/man1/printf.1 new file mode 100644 index 0000000..ced59d5 --- /dev/null +++ b/man/man1/printf.1 @@ -0,0 +1,690 @@ +.TH PRINTF 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +printf \- format and write data +.SH SYNOPSIS +.B printf +.RB [ \-\- ] +.I format +.RI [ argument ...] +.SH DESCRIPTION +.B printf +writes +.I format +to standard output, with each conversion specification in it replaced by +the next +.I argument +converted as the specification says. +It reads no input, and it adds no newline of its own. +.PP +Ordinary characters in the format are written as they are. +A backslash starts an escape sequence, which is replaced by the octet it +names; see +.BR "Escape sequences" . +A percent sign starts a conversion specification; see +.BR Conversions . +.PP +When the format has been written and arguments remain, the format is +used again from its start with the remaining arguments, until none +remain. +A pass that uses no argument, such as the only pass of a format with no +conversion specification, ends this repetition, and arguments left over +are ignored. +When the arguments run out partway through a pass, the rest of that pass +still runs and each remaining conversion uses an empty argument; see +.BR Arguments . +With no arguments at all, the format is written once in the same way. +.PP +The kit's shell has +.B printf +as a builtin that runs this same code, with the differences listed under +.BR NOTES ; +see +.BR sh (1). +Outside the shell, the +.I printf.exe +launcher runs the +.B busybox +applet; see +.BR busybox (1). +.SS Escape sequences +A backslash in the format, or in an argument converted by +.BR %b , +starts an escape sequence, which is replaced as follows. +.TP +.B \ea +Alert (BEL, 0x07). +.TP +.B \eb +Backspace (0x08). +.TP +.B \ec +Stop: write nothing more, not even the rest of the format. +Output from before it is kept, the remaining arguments are not used, and +the exit status is not affected. +.TP +.B \ee +Escape (0x1B). +.TP +.B \ef +Form feed (0x0C). +.TP +.B \en +Line feed (0x0A). +.TP +.B \er +Carriage return (0x0D). +.TP +.B \et +Tab (0x09). +.TP +.B \ev +Vertical tab (0x0B). +.TP +.B \e\e +Backslash. +.TP +.BI \e ooo +The octet whose octal value is +.IR ooo , +one to three digits. +A value above 255 ends the sequence before the digit that would exceed +it, so +.B \e400 +is a space (octal 40) followed by +.BR 0 . +.IP +In the format, a leading 0 counts as one of the three digits, so +.B \e0101 +is a backspace (octal 10) followed by +.BR 1 . +In an argument converted by +.BR %b , +a 0 right after the backslash is not counted when an octal digit +follows it, so +.B \e0101 +is +.BR A . +A +.B \e0 +with no octal digit after it is a NUL octet in both. +.TP +.BI \ex HH +The octet whose hexadecimal value is +.IR HH , +one or two digits in either case. +A +.B \ex +not followed by a hexadecimal digit is written as it is. +.PP +A backslash followed by any other character, or ending the format or an +argument, is written as it is, and the character after it is then read +normally. +So +.B \e\(dq +and +.B \eu0041 +are written unchanged. +.SS Conversions +A conversion specification is a percent sign followed by these parts, in +order, with only the conversion character required: +.PP +.RS 4 +\fB%\fR[\fIflags\fR][\fIwidth\fR][\fB.\fIprecision\fR][\fIlength\fR]\fIconv\fR +.RE +.PP +The flags are any number of the following, in any order. +.TP +.B \- +Left-justify the result within the width. +.TP +.B + +Write a sign, either +.B + +or +.BR \- , +with a signed number. +.TP +A space +Write a space before a non-negative signed number. +.TP +.B # +Use the alternate form: a leading +.B 0 +for +.BR o , +.B 0x +or +.B 0X +before a nonzero +.B x +or +.BR X , +and a decimal point in floating-point output even when no digit follows +it. +.TP +.B 0 +Pad with leading zeros instead of spaces. +This also applies to +.B c +and +.BR s . +.PP +The width is a minimum field width, as decimal digits or as +.BR * , +which takes it from the next argument, a decimal integer. +A negative width from +.B * +is the +.B \- +flag with the width made positive. +.PP +The precision is a period followed by decimal digits or by +.BR * , +or just a period, which means 0. +For integers it is the minimum number of digits, for +.BR e , +.BR E , +and +.B f +the digits after the decimal point, for +.B g +and +.B G +the significant digits, and for +.B s +the maximum number of bytes written. +The default for floating-point conversions is 6. +.PP +Any number of the length modifiers +.BR l , +.BR L , +.BR h , +and +.B z +are accepted and ignored: integer conversions always use 64 bits. +.PP +The conversion character is one of the following. +.TP +.BR d ", " i +Write a signed decimal integer. +.TP +.BR o ", " u ", " x ", " X +Write an unsigned integer in octal, decimal, lowercase hexadecimal, or +uppercase hexadecimal. +.TP +.BR e ", " E +Write a floating-point number with an exponent, such as +.BR 1.234568e+004 , +with +.B E +in place of +.B e +for +.BR E . +.TP +.B f +Write a floating-point number without an exponent, such as +.BR 1234.568000 . +.TP +.BR g ", " G +Write a floating-point number in the style of +.BR f , +or in that of +.B e +or +.B E +when the exponent is below \-4 or not below the precision, with trailing +zeros removed unless the +.B # +flag is given. +.TP +.B c +Write the first byte of the argument. +An empty or missing argument writes a NUL octet. +A +.B * +width or precision does not work here: the byte's value becomes the width +or precision, and an unpredictable byte is written in its place. +.TP +.B s +Write the argument. +.TP +.B b +Write the argument with its escape sequences interpreted. +The percent sign must be followed by the +.B b +at once: flags, width, and precision are not accepted. +.TP +.B % +Write a percent sign. +As with +.BR b , +nothing may come between the two percent signs. +.PP +Any other conversion character, such as +.BR a , +.BR A , +.BR F , +.BR n , +.BR p , +or +.BR j , +or a specification that ends before its conversion character, such as a +lone +.B % +at the end of the format, is an error: the message +.PP +.RS 4 +.EX +printf: \fIspec\fR: invalid format +.EE +.RE +.PP +is written to standard error, where +.I spec +is the rest of the format from the percent sign with any length +modifiers removed, and +.B printf +stops with status 1. +Output from before the bad specification is kept. +Positional arguments such as +.B %1$s +and the +.B \(aq +flag are not supported. +.SS Arguments +Whatever the conversion, an argument that was not given is empty. +.PP +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X , +an argument is an integer in decimal, in hexadecimal with a +.B 0x +prefix, or in octal with a leading +.BR 0 , +optionally signed and optionally preceded by white space. +Nothing may follow it. +For +.B d +and +.B i +the range is \-2^63 to 2^63\-1. +For the others it is 0 to 2^64\-1, and a negative number down to \-2^63 +is accepted as its two's complement, so +.B %u +of +.B \-1 +is +.BR 18446744073709551615 . +An empty or missing argument is an error here. +.PP +For +.BR e , +.BR E , +.BR f , +.BR g , +and +.BR G , +an argument is a number in the form that the C library's +.B strtod +function reads: decimal with an optional exponent, hexadecimal such as +.BR 0x1p3 , +.BR inf , +or +.BR nan , +optionally signed and optionally preceded by white space. +Nothing may follow it. +An empty or missing argument is 0, not an error. +.PP +For all of these, an argument may instead be a single or double quote +followed by a character, whose value is that of the first byte after the +quote, so +.B \(aqA +and +.B \(dqA +are both 65. +Anything after that byte is ignored, and a lone quote is 0. +A character above U+007F gives the first byte of its encoding, which is +UTF-8 on Windows 10 version 1903 and later; see +.BR NOTES . +.PP +An argument that is not a valid number, or that is out of range, is an +error: the message +.PP +.RS 4 +.EX +printf: invalid number \(aq\fIargument\fR\(aq +.EE +.RE +.PP +is written to standard error, output continues, and the exit status will +be 1. +The value used is 0, not the number that began the argument, except that +an out-of-range floating-point argument keeps the value that +.B strtod +gave it. +.PP +An argument taken by +.B * +as a width or precision is a decimal integer from \-2^31 to 2^31\-1, +optionally preceded by a minus sign. +White space, a plus sign, a +.B 0x +prefix, or a quote makes it invalid. +An invalid one is reported the same way and is 0, but does not change the +exit status. +A missing one is 0 without a message. +A negative precision counts as none. +.SH OPTIONS +.B printf +has no options. +A first argument that starts with a dash is the format, so +.B "printf \-n" +writes +.BR \-n . +Two arguments are recognized. +.TP +.B \-\- +As the first argument, ends the options and is skipped, so that a format +that starts with a dash can follow it. +Only one is skipped: in +.BR "printf \-\- \-\- x" , +the format is +.BR \-\- . +.TP +.B \-\-help +As the first argument of the applet, writes a usage message on standard +output and exits with status 0, whatever else is given. +The shell's builtin has no +.BR \-\-help : +there it is a format, so +.B "printf \-\-help" +writes +.BR \-\-help . +.SH ENVIRONMENT +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the applet expands wildcards in its arguments, as needed when run from +.BR cmd.exe ; +see +.BR NOTES . +A busybox process started with it unset sets it to +.B 0 +for its children, so commands run from the kit's shell receive their +arguments as the shell expanded them. +.TP +.BR BB_TERMINAL_MODE ", " BB_SKIP_ANSI_EMULATION +When standard output is a console, decide whether the console or busybox +interprets the escape sequences in the output, such as for color. +See +.BR busybox (1). +.TP +.B CONEMUPID +When it is set and neither of the above is, busybox uses terminal mode +0: it turns virtual terminal output off and emulates escape sequences +itself. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, including output stopped by +.BR \ec . +.TP +.B 1 +An argument was not a valid number, or a conversion specification was +not valid. +This is the status even if +.B \ec +stopped the output later. +It is also the status of a missing format in the applet. +.TP +.B 2 +A missing format in the shell's builtin. +.TP +.B 141 +Standard output is a pipe whose reader closed it before all the output +was written. +.PP +A missing format in the applet writes the usage message to standard +error. +In the builtin the message is +.BR "usage: printf FORMAT [ARGUMENT...]" , +preceded by the shell's name and a colon. +.SH EXAMPLES +Write each argument on a line of its own, using the format once for each: +.PP +.RS 4 +.EX +$ printf \(aq%s\en\(aq one two three +one +two +three +.EE +.RE +.PP +Align columns: +.PP +.RS 4 +.EX +$ printf \(aq%\-10s %5d\en\(aq apple 3 banana 12 +apple 3 +banana 12 +.EE +.RE +.PP +Convert a hexadecimal number to decimal, and a decimal number to +hexadecimal: +.PP +.RS 4 +.EX +$ printf \(aq%d %#x\en\(aq 0xff 255 +255 0xff +.EE +.RE +.PP +Show the code of a character: +.PP +.RS 4 +.EX +$ printf \(aq%d\en\(aq "\(aqA" +65 +.EE +.RE +.PP +Take the field width from an argument: +.PP +.RS 4 +.EX +$ printf \(aq%*d\en\(aq 6 42 + 42 +.EE +.RE +.PP +Write a number with two decimals and a percent sign: +.PP +.RS 4 +.EX +$ printf \(aq%.2f%%\en\(aq 12.345 +12.35% +.EE +.RE +.PP +Interpret the escapes in one argument but not in another: +.PP +.RS 4 +.EX +$ printf \(aq%s|%b|\en\(aq \(aqa\ex41\(aq \(aqa\ex41\(aq +a\ex41|aA| +.EE +.RE +.PP +Write a file with CR LF line endings: +.PP +.RS 4 +.EX +$ printf \(aqfirst\er\ensecond\er\en\(aq >dos.txt +.EE +.RE +.PP +Write a word in red on a console: +.PP +.RS 4 +.EX +$ printf \(aq\e033[31mred\e033[0m\en\(aq +.EE +.RE +.PP +Write text that +.BR echo (1) +would take as an option: +.PP +.RS 4 +.EX +$ printf \(aq%s\en\(aq "$text" +.EE +.RE +.PP +Pass file names, which may contain spaces, to a program that reads names +separated by NUL octets: +.PP +.RS 4 +.EX +$ printf \(aq%s\e0\(aq *.c | xargs \-0 wc \-c +.EE +.RE +.SH NOTES +Differences from GNU +.B printf +and bash: +.IP \(bu 2 +A missing argument for an integer conversion is an error, with exit +status 1, where they use 0. +.IP \(bu 2 +A numeric argument with trailing characters is an error, and its value +is 0, instead of the number that began it. +.IP \(bu 2 +.B \e\(dq +is a backslash and a double quote, and there are no +.B \eu +or +.B \eU +escapes. +.IP \(bu 2 +There are no +.BR %a , +.BR %A , +or +.B %F +conversions, and none of bash's +.BR %q , +.BR "%(...)T" , +or +.B \-v +.IR var . +.PP +The builtin differs from the applet in the exit status of a missing +format, in having no +.BR \-\-help , +and in the name that starts its error messages, which is the shell's, +such as +.BR sh , +instead of +.BR printf . +In the shell the builtin runs in preference to the applet and to any +program named +.B printf +in +.BR PATH . +.PP +Numbers are written by the C runtime, which differs from glibc. +Exponents have three digits, as in +.BR 1.000000e+000 . +Infinity and not-a-number are written as forms such as +.B 1.#INF00 +and +.BR 1.#QNAN0 . +An exact half rounds away from zero, so +.B %.0f +of 2.5 is 3. +The decimal point is always a period. +.PP +Standard output is binary, so +.B \en +is a bare LF. +Write +.B \er\en +for CR LF. +Output is written in blocks: one at the end of each pass through the +format, or sooner when a newline arrives with more than 40 bytes +pending. +A write error is not detected, except that a closed pipe ends +.B printf +with status 141. +Error messages are not buffered, so when standard output and standard +error go to the same place, a message can come before output that +preceded it. +.PP +In a batch file, +.B cmd.exe +treats the percent sign specially: write each +.B % +as +.BR %% . +Unless +.B BB_GLOBBING +is +.BR 0 , +as it is under the kit's shell, the C runtime of the applet expands +wildcards in the format and the arguments, even quoted ones. +So when +.B printf.exe +is started from +.BR cmd.exe , +a format or argument with +.B * +or +.B ?\& +that matches file names is replaced by them. +Set +.B BB_GLOBBING +to +.B 0 +to prevent that. +.PP +Arguments may contain any Unicode character on Windows 10 version 1903 +and later, and are limited to the system code page on earlier versions. +Widths and precisions count bytes, so a precision can cut a UTF-8 +character in two. +When standard output is a console, the output is converted for display +from the ANSI code page, which is UTF-8 on Windows 10 version 1903 and +later. +Escape sequences, such as those for color, take effect, and busybox +emulates them on consoles without virtual terminal support. +A block of output that contains a NUL octet, from +.BR \e0 , +.BR \ex00 , +or +.BR %c , +is written to a console unconverted and without escape sequence +emulation. +.SH SEE ALSO +.BR busybox (1), +.BR echo (1), +.BR sh (1), +.BR xargs (1) diff --git a/man/man1/ps.1 b/man/man1/ps.1 new file mode 100644 index 0000000..ad81322 --- /dev/null +++ b/man/man1/ps.1 @@ -0,0 +1,419 @@ +.TH PS 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +ps \- list the processes running on the system +.SH SYNOPSIS +.B ps +.RB [ \-AadeflZ ] +.RB [ \-o +.IR columns ] +.SH DESCRIPTION +.B ps +writes a table of the running processes on standard output: a header +line, then one line per process. +It takes a single snapshot and exits. +It lists every process on the system, including those of other users and +system processes such as +.BR System , +and has no way to select a subset. +Processes appear in the order Windows lists them, not sorted by process +ID. +.PP +The default columns are +.BR pid , +.BR ppid , +.BR user , +.BR time , +.BR etime , +and +.BR args . +.B \-o +chooses others from the eight described under +.BR Columns . +.SS Output +Each column is padded with spaces to its width and followed by a space, +except the last, which is not padded. +.B pid +and +.B ppid +are right-aligned within their width, and the other columns start at the +left edge of theirs. +A value wider than its column is cut to the width, except for +.B pid +and +.BR ppid , +which are written in full and push the rest of the line to the right. +An empty value is written as +.BR \- . +.PP +The header line uses the same widths, with every header at the left edge +of its column, including those of +.B pid +and +.BR ppid . +It is omitted when every column has an empty header, as with +.BR "\-o pid=,comm=" . +.PP +Each line is cut to a limit: one column less than the width of the +console when standard output is a console, up to 2048, and 2048 +otherwise. +Columns after the first one that, with its trailing space, reaches past +the limit are not printed, even when their values would fit. +As +.B args +is 2048 wide, a column after it is printed only when +.B args +has a header that narrows it. +Lines end in LF, and +.B ps +writes no escape sequences. +.SS Columns +.TP +.B pid +The process ID. +Header +.BR PID , +width 5. +.TP +.B ppid +The ID of the parent process. +Header +.BR PPID , +width 5. +It is 1 when the parent is not running, because Windows does not +reparent a process whose parent has exited, and 0 for process 0, which +has no parent. +Windows can reuse the ID of an exited parent, and the value is then the +ID of an unrelated process. +.TP +.B user +The user name. +Header +.BR USER , +width 8. +It is the name of the current user for a process that +.B ps +can open with full access, and +.B root +for any other process. +It is not the name of the process's owner; see +.BR NOTES . +.TP +.B group +The group name, which is the same as the user name. +Header +.BR GROUP , +width 8. +.TP +.B comm +The name of the process: the file name of its executable, including the +extension, such as +.BR explorer.exe , +cut to 31 bytes. +A process running the same build of busybox is named after its applet +instead, such as +.B sh +or +.BR sleep . +Header +.BR COMMAND , +width 32. +.TP +.B args +The command line. +For a process running the same build of busybox, including +.B ps +itself, it is the applet name and the arguments it was given, joined by +single spaces with no quoting. +At most 126 characters are kept, and an argument that does not fit is +left out together with all those after it. +For any other process +.B ps +does not read the command line, and the value is the same as +.BR comm . +Header +.BR COMMAND , +width 2048. +.TP +.B time +The CPU time the process has used, user and kernel together, truncated +to whole seconds. +Header +.BR TIME , +width 5. +The value is always five characters, padded on the left with spaces, in +the first of these forms that fits: +minutes and seconds, as in +.BR 3:07 ; +hours and minutes, as in +.BR 2h05 ; +days and hours, as in +.BR 12d03 ; +or, from 100 days, days alone, as in +.BR 100d . +.TP +.B etime +The time since the process started, in the same forms as +.BR time . +Header +.BR ELAPSED , +width 7. +.SH OPTIONS +Options may be grouped, as in +.BR \-Aef , +and the argument of +.B \-o +may be attached, as in +.BR \-opid,args . +Options may follow operands, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +Operands are ignored, so +.B ps aux +is the same as +.BR ps . +Any other option, such as +.BR \-T , +.BR \-w , +or +.BR \-h , +prints an error message and a usage message on standard error and exits +with status 1. +.TP +.BI "\-o " columns +Show the columns named in +.IR columns , +in that order, instead of the default ones. +.I columns +is a list of names from +.BR Columns , +separated by commas. +The names are lower case, and blanks are not separators. +The option may be repeated, and the lists are joined in order. +A name unknown to +.B ps +is an error: it prints the names it knows and exits with status 1. +.IP +A name may be followed by +.BI = header +to replace that column's header with +.IR header . +The header ends at the next comma, so it cannot contain one. +.IP +A header also sets the width of its column. +The column is exactly as wide as the header, even when that is narrower +than the default width, and values longer than that are cut off, except +for +.B pid +and +.BR ppid . +For example, +.B \-o comm=NAME +shows names of at most four characters. +Giving +.B pid +or +.B ppid +a header narrower than its values makes +.B ps +overrun its line buffer, which can corrupt the output. +An empty header, as in +.BR \-o\ pid= , +keeps the default width and shows no header text. +.TP +.BR \-A ", " \-a ", " \-d ", " \-e ", " \-f ", " \-l ", " \-Z +Accepted for compatibility and ignored. +.TP +.B \-\-help +As the first argument, print a usage message on standard output and exit +with status 0. +.SH ENVIRONMENT +.TP +.B COLUMNS +The width of the console, in place of its real width, when standard +output is a console. +A value that is not from 2 to 29999 is taken as 80. +It has no effect when standard output is not a console. +.TP +.B POSIXLY_CORRECT +When it is set, even to an empty value, the first operand ends the +options, so that in +.BR "ps aux \-o pid" , +.B \-o +is an operand and is ignored. +.PP +The variables that busybox reads for every applet, such as +.BR BB_GLOBBING , +are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success, or +.B \-\-help +was given. +.TP +.B 1 +An invalid option, a missing argument to +.BR \-o , +or an unknown column name. +.PP +Failure to list the processes is not detected: if Windows refuses to +supply the list, only the header is printed and the status is 0. +.SH EXAMPLES +List the processes with the default columns: +.PP +.RS 4 +.EX +$ ps +PID PPID USER TIME ELAPSED COMMAND + 0 0 root 0:00 1d05 [System Process] + 4 0 root 0:00 1d05 System +\&... +.EE +.RE +.PP +List the distinct program names that are running, with no header: +.PP +.RS 4 +.EX +$ ps \-o comm= | sort \-u +.EE +.RE +.PP +Find a background job and its parent, which is the shell: +.PP +.RS 4 +.EX +$ sleep 60 & +[1] 11732 +$ ps \-o pid,ppid,etime,comm | grep \-w sleep +11732 13472 0:01 sleep +.EE +.RE +.PP +Show how a header sets the column width, here cutting names to four +characters: +.PP +.RS 4 +.EX +$ ps \-o pid,comm=NAME | head \-3 +PID NAME + 0 [Sys + 4 Syst +.EE +.RE +.SH NOTES +Differences from the procps +.B ps +and from busybox +.B ps +on Linux: +.IP \(bu 2 +There is no way to select processes or change the format other than +.BR \-o . +The POSIX options +.BR \-A , +.BR \-a , +.BR \-d , +.BR \-e , +.BR \-f , +and +.BR \-l , +and the BSD form +.BR "ps aux" , +are accepted and ignored. +.IP \(bu 2 +There is no +.BR \-T , +.BR \-w , +or other option, and no column for the terminal, state, memory use, +process group, session, or niceness. +.IP \(bu 2 +The default columns include +.B ppid +and +.BR etime , +which busybox on Linux leaves out. +.IP \(bu 2 +Process names include the extension, such as +.BR cmd.exe . +.IP \(bu 2 +.B ps +does not look up the owner of a process, so +.B user +and +.B group +are not the owner's name; see below. +.PP +The list comes from +.BR CreateToolhelp32Snapshot , +so a process that exits while +.B ps +runs is still listed. +Whether a process is shown as the current user is decided by trying to +open it with +.BR PROCESS_ALL_ACCESS . +The current user's name comes from +.BR GetUserName , +with each space replaced by an underscore, and is cut to the width of +the column. +Processes that +.B ps +cannot open that way, such as those of other users and protected system +processes, are shown as +.BR root . +.PP +CPU and start times come from +.BR GetProcessTimes , +which needs only +.BR PROCESS_QUERY_LIMITED_INFORMATION , +so it can succeed for a process shown as +.BR root . +For a process whose times cannot be read, +.B time +is +.B 0:00 +and +.B etime +is the time the system has been up. +The times are kept as 32-bit counts of milliseconds, so +.B time +wraps after about 49 days of CPU time, and +.B etime +is wrong for a process that started more than about 49 days after the +system booted. +.PP +The name and command line of a process other than +.B ps +itself are read out of the memory of that process. +That works only for a process that runs the same build of busybox as +.B ps +and whose memory +.B ps +can open for reading. +Any other process is shown under its executable's file name for both +.B comm +and +.BR args . +.PP +The kit's command launchers, such as +.BR ps.exe , +appear under their own names, each alongside the busybox process it +started. +When +.B ps +is started through its launcher, as from +.BR cmd.exe , +the output has a row for +.B ps.exe +and another for +.BR ps . +.SH SEE ALSO +.BR busybox (1), +.BR kill (1), +.BR killall (1), +.BR pgrep (1), +.BR pidof (1), +.BR pkill (1) diff --git a/man/man1/pwd.1 b/man/man1/pwd.1 new file mode 100644 index 0000000..419b106 --- /dev/null +++ b/man/man1/pwd.1 @@ -0,0 +1,257 @@ +.TH PWD 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +pwd \- print the current directory +.SH SYNOPSIS +.B pwd +.RB [ \-LP ] +.SH DESCRIPTION +.B pwd +prints the name of the current directory, followed by a newline, on +standard output. +It reads no input and ignores operands. +.PP +The name is absolute, with a drive letter and forward slashes, as in +.IR C:/Users/me/src . +The root of a drive is +.IR C:/ . +A network share entered without a drive letter gives a UNC name, as in +.IR //host/share/dir . +.PP +It is the name that Windows holds for the process's current directory, +as set by the program that changed to it or started the process. +.B pwd +neither resolves links in it nor changes its case. +When the kit's shell changes directory, it uppercases the drive letter +or UNC host name, matches the capitalization stored on disk, and +resolves a symbolic link or junction that is the last component of the +new directory, so the name can differ from the shell's +.BR PWD . +.B cmd.exe +keeps the drive letter as typed, which may be lowercase, and keeps a +junction in the name. +.PP +The kit's +.BR sh (1) +has a +.B pwd +built-in of its own, which runs in place of this program; see +.BR NOTES . +.SH OPTIONS +Options may be grouped, as in +.BR \-LP , +repeated, and given after operands, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +Any other option is an error. +.TP +.B \-L +Print the value of +.B PWD +instead of the name from Windows, when +.B PWD +names the current directory. +.B PWD +must pass all of these tests: +.RS +.IP \(bu 2 +It begins with a forward slash. +A name with a drive letter never qualifies. +.IP \(bu 2 +It has no +.B .\& +or +.B ..\& +component, where components are separated by forward slashes. +.IP \(bu 2 +It names the current directory, which is judged by whether Windows +reports the same volume and file index for both. +.RE +.IP +When any of these fails, or +.B PWD +is unset, +.B \-L +has no effect, and there is no message. +Otherwise +.B PWD +is printed exactly as it is, with no cleanup. +.IP +The kit's shell sets +.B PWD +with a drive letter, except on a network share, so +.B \-L +usually prints the same name as without it. +It differs when +.B PWD +begins with a slash, as for a name relative to the root of the drive, +such as +.IR /Users/me , +or a UNC name, such as +.IR //host/share/dir . +.TP +.B \-P +Print the name from Windows. +This is the default. +Giving +.B \-P +does not cancel +.BR \-L : +with both, in either order, +.B \-L +applies. +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +.SH ENVIRONMENT +.TP +.B PWD +Read only with +.BR \-L , +as described there. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, as described in +.BR NOTES , +and the console interprets the bytes in its own code page. +.PP +Variables that affect every busybox applet, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +.TP +.B 1 +An unknown option, or a failure to get the name of the current +directory. +.TP +.B 255 +The output could not be written, as when standard output is closed or is +a pipe whose reader has exited. +No message is printed. +.PP +An unknown option is reported on standard error, followed by a usage +message. +A failure to get the name is reported on standard error as +.PP +.RS 4 +.EX +pwd: getcwd: \fIreason\fR +.EE +.RE +.SH EXAMPLES +Print the current directory: +.PP +.RS 4 +.EX +$ cd C:/Windows +$ pwd +C:/Windows +.EE +.RE +.PP +Print it with backslashes, for a program that wants them. +Naming +.B busybox +runs this program instead of the shell's built-in: +.PP +.RS 4 +.EX +$ busybox pwd | tr / \(aq\e\e\(aq +C:\eWindows +.EE +.RE +.PP +Set +.B PWD +to a name relative to the root of the drive. +With +.BR \-L , +it is printed when it names the current directory, and otherwise +ignored: +.PP +.RS 4 +.EX +$ cd C:/Windows +$ PWD=/Windows busybox pwd \-L +/Windows +$ PWD=/Users busybox pwd \-L +C:/Windows +.EE +.RE +.SH NOTES +The kit's +.BR sh (1) +runs its own +.B pwd +built-in, not this program, in scripts and at the prompt. +The built-in has its own options, including +.BR \-a , +which this program lacks; see +.BR sh (1). +This program is what the +.I pwd.exe +launcher in the kit's +.I bin +runs, as when +.BR cmd.exe , +.BR env , +or another program starts +.BR pwd , +and what +.B busybox pwd +runs; see +.BR busybox (1). +.PP +Differences from POSIX and GNU +.BR pwd : +.IP \(bu 2 +The default is +.BR \-P , +not +.BR \-L , +and +.B POSIXLY_CORRECT +does not change it. +.IP \(bu 2 +Unlike GNU +.BR "pwd \-P" , +.B \-P +does not resolve symbolic links; see +.BR DESCRIPTION . +.IP \(bu 2 +Operands are ignored without a warning. +.IP \(bu 2 +There are no long options other than +.BR \-\-help , +so +.B \-\-logical +and +.B \-\-version +are errors, and +.B \-\-help +is recognized only as the first argument. +.PP +On Windows 10 version 1903 and later, the name may contain any Unicode +characters. +On older versions it is limited to the system code page. +.PP +The output line ends with LF, not CRLF. +When standard output is a console, the result is converted for display +from the ANSI code page, which is UTF-8 on Windows 10 version 1903 and +later. +.SH SEE ALSO +.BR busybox (1), +.BR realpath (1), +.BR sh (1) diff --git a/man/man1/readlink.1 b/man/man1/readlink.1 new file mode 100644 index 0000000..a101551 --- /dev/null +++ b/man/man1/readlink.1 @@ -0,0 +1,344 @@ +.TH READLINK 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +readlink \- print the target of a symbolic link, or a canonical path +.SH SYNOPSIS +.B readlink +.RB [ \-fnqsv ] +.I file +.SH DESCRIPTION +.B readlink +prints the target of the symbolic link +.IR file , +followed by a newline. +With +.BR \-f , +it prints the canonical absolute path of +.I file +instead. +It takes exactly one operand, and any other number is a usage error. +This +.B readlink +is the +.BR busybox (1) +applet, which has fewer options than GNU +.BR readlink ; +see +.BR NOTES . +.SS Links +A link is a symbolic link, a directory junction such as +.BR jn (1) +makes, or an app execution alias, one of the program names that Windows +keeps in a user's +.I WindowsApps +directory. +The target of an alias is the path of the program it runs. +A hard link is an ordinary file. +.PP +Without +.BR \-f , +.B readlink +reads the link and prints its target as stored, without resolving it or +checking that it exists. +A relative target stays relative, and Windows resolves it from the +directory that holds the link. +Backslashes become slashes. +The NT prefix that Windows stores with an absolute target, such as +.BR \e??\e , +is removed, and a network target is printed in the form +.IR //server/share/dir . +.PP +Anything else is an error without +.BR \-f : +an ordinary file or directory, a missing file, or another kind of +reparse point. +A +.B .lnk +shortcut is an ordinary file. +.SS Canonical paths +With +.BR \-f , +.I file +need not be a link. +The result is an absolute path with forward slashes. +Dot and dot-dot components, repeated separators, and a trailing +separator are removed. +A dot-dot is removed by name, before any link is followed, so +.IB link /..\& +is the directory that holds +.IR link , +and the component that a dot-dot removes need not exist. +Every link left in the path is followed. +Each name has the case and the long form that it has on disk, so +.B c:/progra~1 +becomes +.BR "C:/Program Files" . +.PP +The file must exist, with one exception. +If only its last component is missing, the rest of the path is +canonicalized, and the component is appended as typed, along with the +separator typed before it, so a backslash there is kept. +The rest must exist, but need not be a directory. +A missing name with no directory part, such as +.BR new.o , +fails: write +.B ./new.o +instead. +A missing name directly in a root directory, such as +.B c:/new.o +or +.BR /new.o , +is printed exactly as typed, whether or not the drive exists. +.PP +If +.I file +is a link whose target is missing, the target is canonicalized by the +same rules. +A relative target is made absolute with the current directory, not the +directory that holds the link. +.SS Output +The path ends with a line feed, never a carriage return and line feed. +When +.I file +cannot be read, nothing is written to standard output. +With +.BR \-v , +a failure without +.B \-f +is reported on standard error as +.PP +.RS 4 +.EX +readlink: \fIfile\fR: cannot read link: \fIreason\fR +.EE +.RE +.PP +where +.I reason +is a system message. +It is +.B No such file or directory +for a missing file, and +.B Function not implemented +for a file or directory that is not a link. +.SH OPTIONS +Options may be grouped, as in +.BR \-fn , +and may follow the operand, unless +.B POSIXLY_CORRECT +is set. +.B \-\- +ends the options. +There are no long options. +.TP +.B \-n +Do not write the newline after the path. +.TP +.B \-f +Print the canonical absolute path of +.I file +instead of the target of a link; see +.BR "Canonical paths" . +.TP +.B \-v +Report a failure on standard error; see +.BR Output . +Failures are silent otherwise, and the exit status is the only sign. +Even with +.BR \-v , +a failure of +.B \-f +is silent. +.TP +.BR \-q ", " \-s +Accepted and ignored. +Failures are silent unless +.B \-v +is given, and these do not change that. +.TP +.B \-\-help +As the first argument only, write a usage message on standard output and +exit with status 0. +.SH ENVIRONMENT +.TP +.B BB_CRITICAL_ERROR_DIALOGS +When it is +.BR 1 , +Windows shows its critical-error dialogs, such as for a drive with no +disk in it, instead of the operation failing with an error. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +wildcards in the arguments are expanded when busybox starts, for a caller +such as +.B cmd.exe +that does not expand them. +When it is unset, busybox sets it to +.B 0 +for the programs it starts, so commands run from the kit's shell get the +shell's expansion only. +.TP +.B POSIXLY_CORRECT +If set, the first operand ends the options. +.PP +Output written to a console also depends on +.BR BB_SKIP_ANSI_EMULATION , +.BR BB_TERMINAL_MODE , +.BR CONEMUPID , +.BR LANG , +.BR LC_ALL , +and +.BR LC_CTYPE , +as for every busybox applet; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +The path was written. +.TP +.B 1 +An invalid command line, with a usage message on standard error, a +failure to read the link or to canonicalize the path, or an error +writing standard output. +.SH EXAMPLES +Show where a junction points: +.PP +.RS 4 +.EX +$ readlink vendor/zlib +C:/src/zlib\-1.3.1 +.EE +.RE +.PP +Test whether a path is a link, by exit status: +.PP +.RS 4 +.EX +$ readlink vendor/zlib >/dev/null && echo link +link +.EE +.RE +.PP +Say why a file is not a link: +.PP +.RS 4 +.EX +$ readlink \-v main.c +readlink: main.c: cannot read link: Function not implemented +.EE +.RE +.PP +Print the canonical path of a directory, and of a file that does not +exist yet in a directory that does: +.PP +.RS 4 +.EX +$ cd C:/src/app +$ readlink \-f ../lib/./include/.. +C:/src/lib +$ readlink \-f build/new.o +C:/src/app/build/new.o +.EE +.RE +.PP +A bare name that does not exist fails, and the same name with a +directory part does not: +.PP +.RS 4 +.EX +$ readlink \-f new.o; echo $? +1 +$ readlink \-f ./new.o +C:/src/app/new.o +.EE +.RE +.PP +Expand a short name to the real one: +.PP +.RS 4 +.EX +$ readlink \-f c:/progra~1 +C:/Program Files +.EE +.RE +.SH NOTES +Differences from GNU +.BR readlink : +.IP \(bu 2 +Only +.BR \-f , +.BR \-n , +and +.B \-v +do anything. +.BR \-q " and " \-s +are ignored, and +.BR \-e , +.BR \-m , +.BR \-z , +and the long options are invalid. +.IP \(bu 2 +Exactly one operand is allowed. +.IP \(bu 2 +A file that is not a link fails with +.B Function not implemented +rather than +.BR "Invalid argument" . +.IP \(bu 2 +.B \-f +fails on a missing name with no directory part, where GNU +.B readlink +prints the absolute path. +It reports no reason for a failure, even with +.BR \-v . +.IP \(bu 2 +.B \-f +removes a dot-dot before following the link that precedes it, where GNU +.B readlink +follows the link first. +.PP +.B readlink \-f +prints what +.BR realpath (1) +prints for the same operand. +.PP +Symbolic links need Developer Mode or an elevated administrator to +create; see +.BR ln (1). +A junction needs neither; see +.BR jn (1). +.B readlink +reads both. +.PP +Paths may have drive letters and either kind of slash. +Names may contain any Unicode character on Windows 10 version 1903 and +later, and are limited to the system code page on earlier versions. +.PP +Paths are limited to 259 characters. +Without +.BR \-f , +a longer path fails with +.BR "No such file or directory" . +.B \-f +treats a path of 260 or more characters, as typed or once made absolute, +as if its last component were missing: the component is appended as +typed without being checked, and if the rest is too long as well, +.B \-f +fails. +When the canonical path would have 256 to 259 characters, the path is +only made absolute: names keep the case and form typed, and a link +before the last component is not followed. +.PP +From +.BR cmd.exe , +.B readlink +expands wildcards in its operand itself; see +.BR BB_GLOBBING . +A pattern that matches several names gives several operands, which is a +usage error. +.SH SEE ALSO +.BR busybox (1), +.BR jn (1), +.BR ln (1), +.BR ls (1), +.BR realpath (1) diff --git a/man/man1/realpath.1 b/man/man1/realpath.1 new file mode 100644 index 0000000..7b9c535 --- /dev/null +++ b/man/man1/realpath.1 @@ -0,0 +1,330 @@ +.TH REALPATH 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +realpath \- print the canonical absolute name of each file +.SH SYNOPSIS +.B realpath +.IR file ... +.SH DESCRIPTION +.B realpath +prints the canonical absolute name of each +.IR file , +one per line, on standard output. +A canonical name has no +.B .\& +or +.B ..\& +components, no repeated separators, and no symbolic links or junctions. +It is written with slashes, as in +.BR C:/Users/me/src , +except where noted below. +.PP +There must be at least one +.IR file . +Standard input is not read. +The operands are processed in order. +One that cannot be resolved is reported on standard error, and the rest +are still processed. +.SS Existing files +Resolution has two steps. +The first works on the text of the operand, without touching the file +system. +It makes the name absolute, relative to the current directory, and +removes +.B .\& +components, repeated separators, and each +.B ..\& +with the component before it. +The empty operand is the current directory, a name that begins with a +single +.B / +or +.B \e +starts at the root of the current drive, and a drive without a +separator, as in +.BR C:dir , +is relative to the current directory on that drive. +As elsewhere in Windows, trailing dots and spaces in a component are +ignored. +.PP +Because this step removes +.B ..\& +by text, it does not follow links first: +.B link/..\& +is the directory that contains +.BR link , +not the parent of its target, and +.B missing/..\& +succeeds although +.B missing +does not exist. +.PP +The second step opens the resulting name, which fails unless the file +exists, and asks Windows for its final name. +This replaces every symbolic link and junction with its target, expands +8.3 short names, writes the drive letter in upper case, and gives every +component the case it has on disk. +An app execution alias, one of the program names that Windows keeps in a +user's +.I WindowsApps +directory, is replaced by the program it runs. +The result has no +.B \e\e?\e +prefix, and a name on a network share is written +.IR //server/share/dir . +Backslashes become slashes, and a trailing separator is removed unless +it ends a drive root such as +.BR C:/ . +An existing file followed by a separator is an error. +.SS Files that do not exist +A name that does not exist is still printed when only its last component +is missing, so that the name of a file to be created can be resolved. +The operand is split at its last separator, after trailing separators +are removed. +The part before it is resolved as above, and the last component is +appended as written, in its own case, after the separator that +was in the operand. +That separator may be a backslash, so in +.IR C:/work , +.B dir\enew +prints as +.BR C:/work/dir\enew . +.PP +It is an error if the part before the separator does not exist, or if +the operand has no separator. +So +.B new +fails, and +.B ./new +does not. +The part before the separator need not be a directory. +.PP +Two cases differ. +When the last separator is the one that ends the root of the operand, as +in +.BR C:/new , +.BR /new , +or +.BR //host/share/new , +there is nothing to resolve, and the operand is printed as written, +without being made absolute. +So +.B /new +prints +.BR /new , +as does +.BR ///new . +And when the part before the separator resolves to a drive root, the +result has two separators after the drive, as in +.BR C://new . +.PP +A symbolic link or junction whose target does not exist is replaced by +its target, and the rules above apply to that. +A relative target is taken relative to the current directory, not to the +directory that holds the link. +.SH OPTIONS +.B realpath +takes no options, so an operand that begins with a dash, such as +.BR \-s , +is a +.IR file , +and so is +.BR \-\- . +.TP +.B \-\-help +Print a usage message on standard output and exit with status 0. +It is recognized only as the first argument, and any further arguments +are then ignored. +.SH ENVIRONMENT +.TP +.B BB_CRITICAL_ERROR_DIALOGS +When it is +.BR 1 , +Windows shows its critical-error dialogs, such as for a drive with no +disk in it, instead of the operation failing with an error. +.TP +.B BB_GLOBBING +Unless it is +.BR 0 , +the C runtime expands the wildcards +.B * +and +.B ?\& +in the last component of each argument when busybox starts, even in +quoted arguments, as needed for commands typed in +.BR cmd.exe . +A pattern that matches nothing is left as it is, and then fails as +described under +.BR NOTES . +When the variable is unset, busybox sets it to +.BR 0 , +so that busybox programs it starts do not expand their arguments again. +.TP +.BR LC_ALL ", " LC_CTYPE ", " LANG +If the first of these that is set has the value +.BR C , +output to a console is not converted, and the console interprets the +bytes in its own code page. +.PP +Variables that affect every busybox program, such as +.B BB_TERMINAL_MODE +for console output, are described in +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Every operand was resolved and printed. +.TP +.B 1 +There was no operand, with a usage message on standard error, or at +least one operand could not be resolved, or standard output could not be +written. +.TP +.B 141 +Standard output is a pipe whose reader exited before +.B realpath +finished writing. +Nothing is printed. +When this is first detected as the output is flushed at exit, the +status is 1 instead. +.PP +A failure is reported on standard error as +.PP +.RS 4 +.EX +realpath: \fIfile\fR: \fIreason\fR +.EE +.RE +.PP +where +.I reason +is the system's message for the error, such as +.B No such file or directory +or +.BR "Invalid argument" . +A write error names +.B standard output +in place of the file. +.SH EXAMPLES +Print the canonical name of a file: +.PP +.RS 4 +.EX +$ cd C:/work/app +$ realpath ../lib/./util.c +C:/work/lib/util.c +.EE +.RE +.PP +Expand a short name: +.PP +.RS 4 +.EX +$ realpath c:/progra~1/common~1 +C:/Program Files/Common Files +.EE +.RE +.PP +Name a file that does not exist yet, in a directory that does: +.PP +.RS 4 +.EX +$ realpath build/app.exe +C:/work/app/build/app.exe +.EE +.RE +.PP +Test whether the directory of a new file exists: +.PP +.RS 4 +.EX +$ realpath nodir/log.txt || echo cannot resolve +realpath: nodir/log.txt: No such file or directory +cannot resolve +.EE +.RE +.SH NOTES +Differences from GNU +.BR realpath : +.IP \(bu 2 +There are no options, such as +.BR \-e , +.BR \-m , +.BR \-s , +.BR \-z , +or +.BR \-\-relative\-to . +.IP \(bu 2 +A missing last component is allowed, as with GNU +.BR realpath , +but only when the operand has a separator. +.IP \(bu 2 +The empty operand is the current directory, not an error. +.IP \(bu 2 +.B ..\& +is resolved before links, not after. +.IP \(bu 2 +Results are not made absolute in every case, and may mix separators; see +.BR "Files that do not exist" . +.PP +A name containing +.BR * , +.BR ? , +.BR < , +.BR > , +.BR | , +or +.BR \(dq , +as an unmatched wildcard does, fails with +.BR "Invalid argument" , +and so does a name that Windows takes for a device, such as +.B NUL +or a bare +.BR CON . +.PP +Names are limited to 259 characters. +An operand of 260 or more characters, as typed or once made absolute, is +treated as if its last component were missing, and if the part before +the last separator is too long as well, +.B realpath +fails with +.BR "No such file or directory" . +When the final name of an existing file would have 256 or more +characters, or 254 on a network share, the second step only follows a +link in the last component: +names keep the case and form typed, and other links are not followed. +.PP +On Windows XP, which lacks the API for finding a final name, the second +step only checks that the file exists and follows a link in the last +component, so names keep the case and form typed. +.PP +Started from +.BR cmd.exe , +.B realpath *.c +prints every match, as described under +.BR BB_GLOBBING . +In the kit's shell, the shell expands the pattern. +.PP +On Windows 10 version 1903 and later, a name may contain any Unicode +characters. +On older versions it is limited to the ANSI code page. +.PP +Lines end with LF, not CRLF. +When standard output is a console, the output is converted for display +from the ANSI code page, which is UTF-8 on Windows 10 version 1903 and +later. +.PP +The kit's +.B sh +runs +.B realpath +inside the shell process, without starting a new one, except where the +shell needs a separate process anyway, as for a command substitution or +a pipeline. +.SH SEE ALSO +.BR basename (1), +.BR busybox (1), +.BR dirname (1), +.BR jn (1), +.BR ln (1), +.BR readlink (1), +.BR sh (1) diff --git a/man/man1/reset.1 b/man/man1/reset.1 new file mode 100644 index 0000000..931cfbf --- /dev/null +++ b/man/man1/reset.1 @@ -0,0 +1,240 @@ +.TH RESET 1 2026-10-19 "w64devkit" "w64devkit Manual" +.SH NAME +reset \- reset the console's text attributes and clear its screen +.SH SYNOPSIS +.B reset +.RB [ \-\-help ] +.SH DESCRIPTION +.B reset +cleans up a console that a program has left in a bad state. +When standard output is a console, it does three things in order: +.IP 1. 4 +It writes +.RB ESC\ [m , +which resets the text attributes, such as color and bold. +.IP 2. 4 +It writes +.RB ESC\ [?1049l , +which leaves the alternate screen buffer. +.IP 3. 4 +It moves the cursor to the top left corner of the console's screen +buffer, then fills the whole buffer with spaces. +.PP +When standard output is not a console, such as a file, a pipe, or the +.B NUL +device, nothing is written and nothing is changed. +Whether standard input or standard error is a console does not matter. +.PP +When the console has virtual terminal processing enabled, it interprets +the two sequences; see +.BR BB_TERMINAL_MODE . +Otherwise busybox emulates them through the console API. +The third step always uses the console API. +.PP +The fill, and an emulated +.RB ESC\ [m , +use the text attributes that the console had when this busybox process +first used it. +The kit's +.B sh +runs +.B reset +within itself, so in an interactive shell these are the attributes from +before its first prompt, not any that a program has set since. +Run as a process of its own, as from +.BR cmd.exe , +.B reset +first uses the console when it writes the two sequences, so the fill +uses whatever colors a program left behind, and an emulated +.RB ESC\ [m +changes nothing. +.PP +An emulated +.RB ESC\ [?1049l +leaves only an alternate buffer that the same process entered with an +emulated +.RB ESC\ [?1049h , +such as one written by the shell's own +.B echo +or +.BR printf , +and not one that another program entered. +.SH OPTIONS +.B reset +takes no options. +It ignores its arguments, unless the first is +.BR \-\-help . +.TP +.B \-\-help +Print a usage message on standard output and exit. +The message describes the Unix build; see +.BR NOTES . +.SH ENVIRONMENT +Run as a process of its own, +.B reset +reads these variables only when standard output is a console. +When the shell runs +.B reset +itself, the shell's current mode applies, and an assignment before the +command, as in +.BR "BB_TERMINAL_MODE=0 reset" , +has no effect on it. +.TP +.B BB_TERMINAL_MODE +How busybox handles escape sequences written to a console. +With +.B 0 +or +.BR 2 , +it disables the console's virtual terminal processing and emulates the +sequences itself. +With +.B 1 +or +.BR 3 , +it enables virtual terminal processing and passes the sequences +through, even if the console cannot interpret them. +With +.BR 4 , +it passes them through if the console already has virtual terminal +processing enabled, and otherwise emulates them. +With +.BR 5 , +it enables virtual terminal processing if the console supports it, and +otherwise emulates the sequences. +A number outside 0 to 5 means +.BR 5 , +and text that is not a number means +.BR 0 . +.TP +.B BB_SKIP_ANSI_EMULATION +Used when +.B BB_TERMINAL_MODE +is unset: +.B 1 +means mode +.BR 1 , +.B 2 +means mode +.BR 5 , +and any other value means mode +.BR 0 . +.TP +.B CONEMUPID +When neither of the above is set, the mode is +.BR 5 , +or +.B 0 +if +.B CONEMUPID +is set, as under ConEmu, or when running under Wine. +.PP +The busybox startup code also reads +.BR BB_CRITICAL_ERROR_DIALOGS , +.BR BB_GLOBBING , +and +.BR BB_UMASK , +and console output reads +.BR LC_ALL , +.BR LC_CTYPE , +and +.BR LANG , +none of which changes what +.B reset +does; see +.BR busybox (1). +.SH EXIT STATUS +.TP +.B 0 +Success. +Errors from the console are ignored. +.TP +.B 141 +The +.B \-\-help +message was written to a pipe whose reader has exited. +.SH EXAMPLES +Clean up after a program that left the console in odd colors: +.PP +.RS 4 +.EX +$ reset +.EE +.RE +.PP +Standard output is not a console, so nothing is written: +.PP +.RS 4 +.EX +$ reset >out.txt +$ wc \-c