lib/w64devkit
1
0
Fork 0
mirror of https://github.com/skeeto/w64devkit.git synced 2026-10-23 06:08:56 +03:00
Code Activity

Add manual pages for the BusyBox applets

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Christopher Wellons
2026-10-20 06:33:28 -04:00
parent 1185617ee0
commit 880be39a58
149 changed files with 53282 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
man/man1/[.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/test.1

1
man/man1/[[.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/test.1

88
man/man1/arch.1 Normal file
View File

@@ -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)

1
man/man1/ash.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/sh.1

1418
man/man1/awk.1 Normal file
View File

File diff suppressed because it is too large Load Diff

186
man/man1/base32.1 Normal file
View File

@@ -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)

203
man/man1/base64.1 Normal file
View File

@@ -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)

299
man/man1/basename.1 Normal file
View File

@@ -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)

857
man/man1/bc.1 Normal file
View File

@@ -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)

1
man/man1/bunzip2.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/bzip2.1

930
man/man1/busybox.1 Normal file
View File

@@ -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)

1
man/man1/bzcat.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/bzip2.1

377
man/man1/bzip2.1 Normal file
View File

@@ -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)

205
man/man1/cal.1 Normal file
View File

@@ -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)

299
man/man1/cat.1 Normal file
View File

@@ -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 <<EOF
> #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)

251
man/man1/chattr.1 Normal file
View File

@@ -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)

367
man/man1/chmod.1 Normal file
View File

@@ -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)

185
man/man1/cksum.1 Normal file
View File

@@ -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)

177
man/man1/clear.1 Normal file
View File

@@ -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)

284
man/man1/cmp.1 Normal file
View File

@@ -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)

211
man/man1/comm.1 Normal file
View File

@@ -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)

574
man/man1/cp.1 Normal file
View File

@@ -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)

671
man/man1/cpio.1 Normal file
View File

@@ -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
drwxrwxr\-x 4095/4095 0 2026\-10\-19 20:43:04 src
\-rw\-rw\-r\-\- 4095/4095 29 2026\-10\-19 20:43:04 src/main.c
\-rw\-rw\-r\-\- 4095/4095 13 2026\-10\-19 20:43:04 src/Makefile
2 blocks
.EE
.RE
.PP
Extract only the C sources, creating their directories.
The quotes keep the shell from expanding the pattern:
.PP
.RS 4
.EX
$ cpio \-id \(aq*.c\(aq <src.cpio
.EE
.RE
.PP
Archive names that may contain newlines:
.PP
.RS 4
.EX
$ find src \-print0 | cpio \-o0 \-H newc >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)

171
man/man1/crc32.1 Normal file
View File

@@ -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)

571
man/man1/cut.1 Normal file
View File

@@ -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)

871
man/man1/date.1 Normal file
View File

@@ -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)

945
man/man1/dc.1 Normal file
View File

@@ -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\-d1<f*]sf 20 lfx p\(aq
2432902008176640000
.EE
.RE
.PP
Run a script file that counts from 1 to 5:
.PP
.RS 4
.EX
$ cat >count.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)

580
man/man1/dd.1 Normal file
View File

@@ -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)

409
man/man1/df.1 Normal file
View File

@@ -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)

566
man/man1/diff.1 Normal file
View File

@@ -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)

253
man/man1/dirname.1 Normal file
View File

@@ -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)

208
man/man1/dos2unix.1 Normal file
View File

@@ -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.txt >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)

411
man/man1/du.1 Normal file
View File

@@ -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)

340
man/man1/echo.1 Normal file
View File

@@ -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)

667
man/man1/ed.1 Normal file
View File

@@ -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 <stdio.h>\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)

1
man/man1/egrep.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/grep.1

383
man/man1/env.1 Normal file
View File

@@ -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)

216
man/man1/expand.1 Normal file
View File

@@ -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)

586
man/man1/expr.1 Normal file
View File

@@ -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)

175
man/man1/factor.1 Normal file
View File

@@ -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)

97
man/man1/false.1 Normal file
View File

@@ -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)

1
man/man1/fgrep.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/grep.1

939
man/man1/find.1 Normal file
View File

@@ -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)

291
man/man1/fold.1 Normal file
View File

@@ -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)

255
man/man1/free.1 Normal file
View File

@@ -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)

202
man/man1/fsync.1 Normal file
View File

@@ -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)

457
man/man1/getopt.1 Normal file
View File

@@ -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)

580
man/man1/grep.1 Normal file
View File

@@ -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 <stdio.h>\(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)

251
man/man1/groups.1 Normal file
View File

@@ -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)

1
man/man1/hd.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/hexdump.1

365
man/man1/head.1 Normal file
View File

@@ -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)

479
man/man1/hexdump.1 Normal file
View File

@@ -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)

966
man/man1/httpd.1 Normal file
View File

@@ -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 <<EOF
> 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<b>&</b>\(aq
&#60;b&#62;&#38;&#60;&#47;b&#62;
.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)

503
man/man1/iconv.1 Normal file
View File

@@ -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)

259
man/man1/id.1 Normal file
View File

@@ -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)

389
man/man1/inotifyd.1 Normal file
View File

@@ -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)

488
man/man1/install.1 Normal file
View File

@@ -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)

314
man/man1/ipcalc.1 Normal file
View File

@@ -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)

275
man/man1/jn.1 Normal file
View File

@@ -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 <JUNCTION> ,
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)

422
man/man1/join.1 Normal file
View File

@@ -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)

371
man/man1/kill.1 Normal file
View File

@@ -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)

435
man/man1/killall.1 Normal file
View File

@@ -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)

1
man/man1/lash.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/sh.1

680
man/man1/less.1 Normal file
View File

@@ -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)

444
man/man1/ln.1 Normal file
View File

@@ -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)

170
man/man1/logname.1 Normal file
View File

@@ -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)

805
man/man1/ls.1 Normal file
View File

@@ -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)

343
man/man1/lsattr.1 Normal file
View File

@@ -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)

1
man/man1/lzcat.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/lzma.1

322
man/man1/lzma.1 Normal file
View File

@@ -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)

305
man/man1/lzop.1 Normal file
View File

@@ -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)

1
man/man1/lzopcat.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/lzop.1

520
man/man1/man.1 Normal file
View File

@@ -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)

419
man/man1/md5sum.1 Normal file
View File

@@ -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 <abc.txt
900150983cd24fb0d6963f7d28e17f72 -
.EE
.RE
.PP
Print only the SHA-256 digest of a file:
.PP
.RS 4
.EX
$ sha256sum <release.zip | cut \-d" " \-f1
.EE
.RE
.PP
Record digests, then check them later:
.PP
.RS 4
.EX
$ sha256sum *.zip >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)

368
man/man1/mkdir.1 Normal file
View File

@@ -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)

358
man/man1/mktemp.1 Normal file
View File

@@ -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)

407
man/man1/mv.1 Normal file
View File

@@ -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)

318
man/man1/nc.1 Normal file
View File

@@ -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 <data.bin
.EE
.RE
.PP
Answer one HTTP request with a fixed page.
The request is written to the terminal:
.PP
.RS 4
.EX
$ printf \(aqHTTP/1.0 200 OK\er\en\er\enhi\en\(aq | nc \-l \-p 8000 127.0.0.1
.EE
.RE
.PP
Connect to an IPv6 address, giving the port with it:
.PP
.RS 4
.EX
$ nc \(aq[::1]:8000\(aq
.EE
.RE
.PP
There is no timeout option.
Stop after 10 seconds with
.BR timeout :
.PP
.RS 4
.EX
$ timeout 10 nc 192.168.1.5 9000 <data.bin
.EE
.RE
.SH NOTES
Differences from other versions of netcat:
.IP \(bu 2
The only options are
.BR \-l ,
.BR \-p ,
and
.BR \-\-help .
There are none for UDP, timeouts, scanning, verbose output, a source
address, or running a program.
.IP \(bu 2
Options must come before the operands.
.IP \(bu 2
In listen mode the operand is a local address, not a port.
.B nc \-l 8000
takes
.B 8000
as an address and fails with
.BR "nc: bind" .
Give the port with
.BR \-p .
.IP \(bu 2
Nothing is printed when a connection is made or accepted.
.PP
A service name is looked up in
.IR /etc/services ,
which busybox takes to be
.I \eetc\eservices
in the root of the current drive.
Windows does not normally have such a file, so use port numbers.
.PP
Socket failures are reported without the Windows reason, as in
.B nc: bind
and
.BR "nc: can't connect to remote host (127.0.0.1)" .
The address is shown only for IPv4.
A failed write to the connection, as when the peer has gone, prints
.BR "nc: write error: Invalid argument" ,
a misleading reason.
.PP
The listening socket sets
.BR SO_REUSEADDR ,
which on Windows lets sockets share a port.
A second
.B nc
can listen on a port that another
.B nc
is listening on without an error, and Windows decides which of them
receives a connection.
.PP
The sending direction of the connection is shut down as soon as standard
input ends.
When standard input is already at end of file, as with
.BR </dev/null ,
this happens at once, and the
.B nc
at the other end then exits, which can cut off data still being sent to
it.
Run a receiving
.B nc
at a console, or give it input that does not end.
.PP
Standard input and output are binary, so bytes such as CR LF, Ctrl-Z, and
NUL pass through files and pipes unchanged.
A console delivers a line to
.B nc
when you press Enter, with a CR LF line ending.
.B nc
reads the console a line at a time, so data from the peer is not shown
while you are typing a line.
To end the input, type Ctrl-Z at the start of a line and press Enter.
.PP
When standard output is a console, received 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.
A block of data that contains a NUL byte is written unconverted.
.PP
There is no connection timeout other than the one Windows applies.
.SH SEE ALSO
.BR busybox (1),
.BR sh (1),
.BR timeout (1),
.BR wget (1)

328
man/man1/nl.1 Normal file
View File

@@ -0,0 +1,328 @@
.TH NL 1 2026-10-19 "w64devkit" "w64devkit Manual"
.SH NAME
nl \- number the lines of files
.SH SYNOPSIS
.B nl
.RB [ \-p ]
.RB [ \-b
.IR style ]
.RB [ \-i
.IR incr ]
.RB [ \-s
.IR sep ]
.RB [ \-v
.IR start ]
.RB [ \-w
.IR width ]
.RI [ file ...]
.SH DESCRIPTION
.B nl
writes each
.I file
to standard output, adding a line number to the start of each line that
it numbers.
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.
.PP
A numbered line is its number in decimal, right-aligned in a field of at
least
.I width
columns, then the separator, then the line.
A line that is not numbered gets spaces in place of the number and
separator, as many as the field width plus the length of the separator
in bytes.
A line that is not numbered does not advance the count.
.PP
By default only nonempty lines are numbered.
The first number is 1, and each numbered line adds 1 to the next number.
The count continues from one file to the next.
.B \-b
chooses the lines to number, and
.B \-v
and
.B \-i
change the first number and the step.
.SS Lines
A line ends at an LF.
A CR just before the LF is removed, so CR LF line endings are accepted.
A NUL byte also ends a line and is removed, and an LF right after it
then makes an empty line of its own.
Every line is written with a final LF, including a last line that has
none.
.PP
A line is empty when nothing is left of it after this.
A line that holds only CR LF is empty, and one that holds only spaces or
tabs is not.
A CR anywhere else, such as at the end of a file with no final LF, is
kept.
Each line is held in memory whole.
.SS Numbers
Numbers are unsigned 32-bit decimal values that wrap around to 0 after
4294967295.
The
.I width
is a minimum, and a longer number is written in full.
.SH OPTIONS
Options may be grouped, as in
.BR \-pba ,
and may follow
.I file
operands, unless
.B POSIXLY_CORRECT
is set.
An option's argument may be attached, as in
.BR \-w3 ,
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.
If an option is given more than once, the last one applies.
.PP
The arguments of
.BR \-i ,
.BR \-v ,
and
.B \-w
are decimal numbers from 0 to 2147483647, with no sign, space, or
prefix.
Leading zeros are allowed, and the number is still decimal.
A value from 2147483648 to 4294967295 is reported as
.BR "not in 0..2147483647 range" ,
and any other bad argument, including a larger number, as
.BR "invalid number" .
Both errors exit with status 1.
.TP
\fB\-b\fR \fIstyle\fR, \fB\-\-body\-numbering\fR=\fIstyle\fR
Choose the lines to number by the first character of
.IR style :
.B a
for all lines,
.B t
for nonempty lines, and
.B n
for none.
Any other first character, or an empty
.IR style ,
numbers no lines, like
.BR n .
The rest of
.I style
is ignored, so the GNU form
.BI p regexp
is not supported and numbers no lines.
The default is
.BR t .
.TP
\fB\-i\fR \fIincr\fR, \fB\-\-line\-increment\fR=\fIincr\fR
Add
.I incr
to the number after each numbered line.
The default is 1.
With 0, every numbered line has the same number.
.TP
.BR \-p ", " \-\-no\-renumber
Accepted for compatibility and ignored.
.TP
\fB\-s\fR \fIsep\fR, \fB\-\-number\-separator\fR=\fIsep\fR
Write
.I sep
after the number, instead of a tab.
It may be empty or several characters long.
Its length in bytes, not in display columns, sets the spaces written for
a line that is not numbered.
.TP
\fB\-v\fR \fIstart\fR, \fB\-\-starting\-line\-number\fR=\fIstart\fR
Give the first numbered line the number
.IR start ,
instead of 1.
.TP
\fB\-w\fR \fIwidth\fR, \fB\-\-number\-width\fR=\fIwidth\fR
Right-align numbers in a field of at least
.I width
columns, instead of 6.
With 0, numbers have no padding.
.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
.B BB_GLOBBING
Unless it is
.BR 0 ,
wildcards in the arguments, including option arguments, are expanded
against file names when
.B nl
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.
.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 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
Success.
.TP
.B 1
An invalid option or number, a
.I file
could not be opened (a directory is reported as
.BR "Is a directory" ),
or standard output could not be written.
.TP
.B 141
Standard output is a pipe whose reader closed it while
.B nl
was still writing.
If the closed pipe is found only by the final flush at exit, as with
output shorter than the output buffer, the status is 1 instead.
.SH EXAMPLES
Number the nonempty lines of a file:
.PP
.RS 4
.EX
$ nl notes.txt
.EE
.RE
.PP
Number every line, including empty ones, in a field of 3 columns, with a
colon as the separator:
.PP
.RS 4
.EX
$ printf \(aqone\en\entwo\en\(aq | nl \-ba \-w3 \-s:
1:one
2:
3:two
.EE
.RE
.PP
Number from 100 in steps of 10, separated by a space:
.PP
.RS 4
.EX
$ printf \(aqone\entwo\en\(aq | nl \-ba \-v 100 \-i 10 \-s \(aq \(aq
100 one
110 two
.EE
.RE
.PP
Find where a word occurs, with line numbers:
.PP
.RS 4
.EX
$ nl \-ba main.c | grep TODO
.EE
.RE
.PP
Number each file separately, since the count restarts at each run:
.PP
.RS 4
.EX
$ for f in *.txt; do nl \-ba "$f"; done
.EE
.RE
.SH NOTES
Differences from GNU nl:
.IP \(bu 2
Only
.BR \-b ,
.BR \-i ,
.BR \-p ,
.BR \-s ,
.BR \-v ,
and
.BR \-w ,
with their long forms, are accepted.
There are no
.BR \-d ,
.BR \-f ,
.BR \-h ,
.BR \-l ,
or
.BR \-n ,
so there are no logical pages, no header or footer numbering, no
joining of empty lines, and no other number format.
A delimiter line such as
.B \e:\e:\e:
is an ordinary line.
.IP \(bu 2
.B \-b
recognizes only
.BR a ,
.BR t ,
and
.BR n .
.IP \(bu 2
.B \-p
does nothing.
.IP \(bu 2
.B \-v
and
.B \-i
do not accept a negative number.
.IP \(bu 2
A CR before an LF is removed, and a NUL byte ends a line, as described
under
.BR Lines .
.PP
Standard input and output are binary, with no CR LF translation by the C
runtime.
It is
.B nl
itself that removes the CR of a CR LF line ending, so output lines end
with a bare LF.
Filter the output through
.BR unix2dos (1)
to make them CR LF.
.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 that busybox accepts, such as
.IR /dev/null ,
work as operands; see
.BR busybox (1).
.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 in the input, such as those for color, take effect.
.SH SEE ALSO
.BR busybox (1),
.BR cat (1),
.BR grep (1),
.BR unix2dos (1)

131
man/man1/nproc.1 Normal file
View File

@@ -0,0 +1,131 @@
.TH NPROC 1 2026-10-19 "w64devkit" "w64devkit Manual"
.SH NAME
nproc \- print the number of processors available
.SH SYNOPSIS
.B nproc
.RB [ \-\-all ]
.RB [ \-\-ignore=\c
.IR N ]
.SH DESCRIPTION
.B nproc
prints the number of logical processors available to it, as a decimal
number on a line of its own on standard output.
The number is never less than 1.
Operands are ignored.
.PP
The count is the number of bits set in the process affinity mask, which
is the set of processors the process may run on.
An unrestricted mask holds every processor in the system, within the
limits given in NOTES.
A process inherits its mask from its parent, so it can be restricted, for
example by
.B start /affinity
in
.BR cmd.exe .
Only the affinity mask is consulted.
.SH OPTIONS
There are no short options.
Long options may be abbreviated to any unique prefix, so
.B \-\-al
means
.BR \-\-all ,
and
.B \-\-ig=1
means
.BR \-\-ignore=1 .
Options may follow operands, unless
.B POSIXLY_CORRECT
is set.
.B \-\-
ends the options.
.TP
.B \-\-all
Count the processors in the system instead of those available to the
process.
This uses the system affinity mask in place of the process mask, so a
restricted process still counts every processor.
.B \-\-ignore
still applies.
.TP
.BI \-\-ignore= N
Subtract
.I N
from the count, but never go below 1.
.I N
is a nonnegative decimal integer no greater than 2147483647.
The argument may also be the next command line argument.
If the option is repeated, the last one applies.
.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 an unknown option.
.SH ENVIRONMENT
.TP
.B POSIXLY_CORRECT
Read by the C library's option parser.
When set, option parsing stops at the first operand, so options after it
are treated as operands and ignored.
.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 1
An unknown option, a missing or invalid argument to
.BR \-\-ignore ,
or an argument given to
.BR \-\-all .
A message is written to standard error, followed by a usage message
unless the cause is an invalid
.B \-\-ignore
number.
.SH EXAMPLES
Run
.B make
with one job per processor:
.PP
.RS 4
.EX
$ make \-j"$(nproc)"
.EE
.RE
.PP
Leave one processor free for other work:
.PP
.RS 4
.EX
$ make \-j"$(nproc \-\-ignore=1)"
.EE
.RE
.PP
Count the processors of a process restricted to the first two:
.PP
.RS 4
.EX
$ cmd /c start /affinity 3 /b /wait nproc
2
.EE
.RE
.SH NOTES
Differences from GNU
.BR nproc :
there is no
.BR \-\-version ,
the
.B OMP_NUM_THREADS
and
.B OMP_THREAD_LIMIT
variables are not read, and extra operands are ignored rather than
rejected.
.PP
The affinity mask is one machine word and covers one processor group, so
a 64-bit build counts at most 64 processors, and a 32-bit build at most
32.
On a system with more than 64 processors, Windows reports the mask of a
single processor group, or an empty mask when the process has threads in
several groups.
If the mask is empty or cannot be read, the count is 1.
.SH SEE ALSO
.BR busybox (1),
.BR make (1)

671
man/man1/od.1 Normal file
View File

@@ -0,0 +1,671 @@
.TH OD 1 2026-10-19 "w64devkit" "w64devkit Manual"
.SH NAME
od \- dump files in octal and other formats
.SH SYNOPSIS
.B od
.RI [ options ]
.RI [ file ...]
.br
.B od \-\-traditional
.RI [ options ]
.RI [ file ]
.RI [ offset
.RI [ label ]]
.SH DESCRIPTION
.B od
writes the bytes of its input to standard output as numbers or
characters, in one or more formats.
With no format options, it writes 2-byte words in octal.
With no
.I file
operands, or for a
.I file
named
.BR \- ,
it reads standard input.
The files form a single input: addresses run on from one file to the
next, and
.BR \-j ,
.BR \-N ,
and
.B \-S
apply to the whole.
A file that cannot be opened is reported on standard error and skipped,
and the others are still written.
.SS Output
The input is read in blocks, 16 bytes by default; see
.BR \-w .
Each block is written as a line: its address, then its values, each
preceded by a space.
The address is the number of input bytes before the block, counting the
bytes skipped by
.BR \-j .
It has at least 7 octal digits.
After the last block, the address just past the end of the input is
written on a line of its own.
.B \-A
changes the radix of the addresses, or omits them.
.PP
A value of more than one byte is read in the machine's byte order,
which is little-endian, so in hexadecimal the bytes of a word appear
reversed.
The last block may be short.
It is completed with zero bytes to a whole number of values.
.PP
Unless
.B \-v
is given, a block identical to the one before it is not written.
A run of identical blocks is written as its first block followed by a
line holding only
.BR * .
.PP
With several formats, each block is written once for each format, one
line per format.
Only the first line has the address, and the others begin with spaces in
its place.
The formats are written in a fixed order, not the order given:
.BR \-a ;
.BR \-b ;
.BR \-c ;
.BR \-d ;
.BR \-D ;
.BR \-f ;
.B \-h
or
.BR \-x ;
.B \-H
or
.BR \-X ;
.BR \-i ,
.BR \-I ,
.BR \-l ,
or
.BR \-L ;
.B \-o
or
.BR \-B ;
.BR \-O ;
the
.B \-t
types, in the order given; and
.BR \-s .
.SS Type specifiers
The argument of
.B \-t
is made of type specifiers.
A specifier is a type letter, an optional size, and an optional
.BR z .
Each value is written after a space, in a field as wide as the largest
value of its type and size: octal and hexadecimal values are padded with
zeros, and decimal values with spaces.
.TP
.BR d ", " o ", " u ", " x
An integer in signed decimal, octal, unsigned decimal, or hexadecimal.
The size is
.B C
for 1 byte,
.B S
for 2,
.B I
for 4,
.B L
for 4 as well, since a Windows
.B long
has 4 bytes, or the number 1, 2, 4, or 8.
The default is 4.
.TP
.B f
A floating-point number in exponent notation, with 7 digits after the
point for 4-byte values and 15 for 8-byte values.
The size is
.B F
for 4 bytes, a
.BR float ;
.B D
for 8, a
.BR double ;
.B L
for a
.BR "long double" ,
16 bytes on x64 and 12 on x86; or one of those numbers.
The default is 8.
See
.B NOTES
about
.BR "long double" .
.TP
.B a
A named character, 4 columns wide.
The byte is taken modulo 128.
Printable characters other than space are written as themselves.
Space is
.BR sp ,
0x7f is
.BR del ,
and each control character is its lowercase ASCII name, such as
.BR nul ,
.BR bel ,
or
.BR esc ,
except that LF is
.BR nl .
.TP
.B c
A character, 4 columns wide.
Printable ASCII, 0x20 to 0x7e, is written as itself.
NUL, BEL, BS, FF, LF, CR, tab, and VT are written as
.BR \e0 ,
.BR \ea ,
.BR \eb ,
.BR \ef ,
.BR \en ,
.BR \er ,
.BR \et ,
and
.BR \ev .
Any other byte is written as 3 octal digits.
.PP
The types
.B a
and
.B c
take no size.
A
.B z
after a specifier adds to the end of each of its lines the bytes of the
block as text between
.B >
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)

335
man/man1/paste.1 Normal file
View File

@@ -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)

513
man/man1/patch.1 Normal file
View File

@@ -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 <fix.patch
patching file src/main.c
patching file src/util.c
.EE
.RE
.PP
Check that a diff applies, then apply it:
.PP
.RS 4
.EX
$ patch \-\-dry\-run \-p1 \-i fix.patch && patch \-p1 \-i fix.patch
.EE
.RE
.PP
Undo a diff:
.PP
.RS 4
.EX
$ patch \-R \-p1 \-i fix.patch
.EE
.RE
.PP
Apply a diff to a file with a different name than the diff gives:
.PP
.RS 4
.EX
$ diff \-u hello.c.orig hello.c >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)

376
man/man1/pgrep.1 Normal file
View File

@@ -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)

323
man/man1/pidof.1 Normal file
View File

@@ -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)

123
man/man1/pipe_progress.1 Normal file
View File

@@ -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 <disk.img >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)

1
man/man1/pkill.1 Normal file
View File

@@ -0,0 +1 @@
.so man1/pgrep.1

240
man/man1/printenv.1 Normal file
View File

@@ -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)

690
man/man1/printf.1 Normal file
View File

@@ -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)

419
man/man1/ps.1 Normal file
View File

@@ -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)

257
man/man1/pwd.1 Normal file
View File

@@ -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)

344
man/man1/readlink.1 Normal file
View File

@@ -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)

330
man/man1/realpath.1 Normal file
View File

@@ -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)

240
man/man1/reset.1 Normal file
View File

@@ -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 <out.txt
0
.EE
.RE
.SH NOTES
Differences from the ncurses
.BR reset :
.IP \(bu 2
It takes no options or terminal type, ignores its arguments instead of
rejecting them, and does not use
.B TERM
or terminfo.
.IP \(bu 2
It does not reset the terminal modes as the Unix build does with
.BR "stty sane" ,
although its usage message says it does.
The console's input mode is not changed.
.IP \(bu 2
It does not make a hidden cursor visible.
.PP
Unlike
.BR clear ,
which writes its sequence even to a pipe or file,
.B reset
writes nothing unless standard output is a console.
.B clear
clears only the visible window, and
.B reset
clears the whole screen buffer.
.PP
In a classic console window the screen buffer holds the scrollback, so
.B reset
erases the history, and the window then shows the top of the buffer.
A terminal that keeps its own scrollback, such as Windows Terminal,
keeps it: there,
.B reset
clears only the visible screen.
.PP
Run as a process of its own,
.B reset
also adjusts the console as any busybox command does when it first
writes an escape sequence there: it turns virtual terminal processing on
or off as
.B BB_TERMINAL_MODE
says, clears
.BR DISABLE_NEWLINE_AUTO_RETURN ,
replaces an output mode of 0 with processed output and line wrapping,
and changes code page 850 to 858; see
.BR busybox (1).
An interactive
.B sh
sets the output mode the same way before each prompt.
.PP
The kit's
.B sh
runs
.B reset
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.
In a command substitution standard output is a pipe, so
.B reset
does nothing there.
When it runs inside the shell and its
.B \-\-help
message goes to a pipe whose reader has exited, it ends the shell
itself with status 141.
.SH SEE ALSO
.BR busybox (1),
.BR clear (1),
.BR sh (1)

208
man/man1/rev.1 Normal file
View File

@@ -0,0 +1,208 @@
.TH REV 1 2026-10-19 "w64devkit" "w64devkit Manual"
.SH NAME
rev \- reverse the characters of each line
.SH SYNOPSIS
.B rev
.RI [ file ...]
.SH DESCRIPTION
.B rev
copies each
.I file
to standard output, with the characters of every line in reverse 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 read.
.PP
A line ends at an LF, and a lone CR is an ordinary character.
The line ending is not reversed: the LF stays at the end of its line,
and so does one CR directly before it.
The last line of a file may have no LF.
It is written without one, so it runs into the first line of the next
file, and a CR that ends it stays in place too.
.SS Characters
In UTF-8 mode, described under
.BR ENVIRONMENT ,
a line is decoded as UTF-8, reversed one code point at a time, and
encoded again.
Combining characters are not treated specially, so a combining mark that
followed its base character comes before it in the output, where it
combines with the character that precedes it.
A line that contains a sequence the decoder rejects is written unchanged:
a byte from 0x80 to 0xBF that does not continue a character, a byte from
0xC0 to 0xFF without enough such bytes after it, or an overlong form of
an ASCII character.
Other invalid sequences, such as encoded surrogates and values above
U+10FFFF, are reversed as single characters, and an overlong form of
any other character is rewritten in its shortest form.
.PP
Outside UTF-8 mode, each byte is a character.
The bytes of a multibyte UTF-8 character are then reversed too, and the
output is not valid UTF-8.
.SH OPTIONS
.B rev
has no options other than
.BR \-\-help .
An argument that starts with a dash is an option wherever it appears,
even after the
.I file
operands, except
.BR \- ,
which is standard input.
.B \-\-
ends the options, so a file whose name starts with a dash follows it or
is given with a leading
.BR ./ .
.TP
.B \-\-help
Print a usage message on standard output and exit with status 0.
It is recognized only as the first argument.
.PP
Any other option prints an error and 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 a later argument such as
.B \-\-help
is a file name.
.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 exactly
.BR C ,
UTF-8 mode is off.
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 operands are expanded when
.B rev
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.
.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 file
could not be opened (a directory is reported as
.BR "Is a directory" ),
memory ran out, or standard output could not be written when
.B rev
flushed it at exit.
.TP
.B 141
Standard output is a pipe that was closed before
.B rev
finished writing to it.
Output to a pipe is buffered, so when the closed pipe is first noticed
by the final flush, as when all the output fits in the buffer,
.B rev
reports an error and exits with status 1 instead.
.SH EXAMPLES
Reverse a line:
.PP
.RS 4
.EX
$ echo hello | rev
olleh
.EE
.RE
.PP
Reverse each line of a file:
.PP
.RS 4
.EX
$ rev notes.txt >notes.rev
.EE
.RE
.PP
Print the last dot-separated field of a name, by reversing it, cutting
the first field, and reversing that:
.PP
.RS 4
.EX
$ echo archive.tar.gz | rev | cut \-d. \-f1 | rev
gz
.EE
.RE
.PP
Mirror a file, reversing both the order of its lines and the characters
in each:
.PP
.RS 4
.EX
$ tac notes.txt | rev
.EE
.RE
.SH NOTES
Files and standard streams are binary, with no CRLF translation, so a
file with CRLF line endings is read and written as it is.
Keeping the CR with the LF is specific to Windows: on Unix, busybox
reverses that CR with the rest of the line.
Output to a console is converted to the console's code page, as
described in
.BR busybox (1).
.PP
A NUL byte ends the text of its line: the NUL and the rest of the line,
including its line ending, are discarded.
The text before the NUL is reversed and written with no line ending, so
it runs into the next line.
This holds in and out of UTF-8 mode.
.PP
A read error ends a file as if it had reached its end, with no message.
.PP
A last line with no LF is lost, with no message, when its length in
bytes is 255, 351, 459, 580, 716, or a later length at which
.B rev
enlarges its line buffer, unless an earlier line, in this or a previous
file, was at least as long.
.PP
Each line is held in memory whole, and in UTF-8 mode also as a decoded
copy of four bytes per byte.
The length of a line is kept in an
.BR int ,
so a line of 2 GiB or more is not supported.
.PP
Options of other implementations, such as the
.B \-0
of util-linux, are errors.
.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 iconv (1),
.BR tac (1)

394
man/man1/rm.1 Normal file
View File

@@ -0,0 +1,394 @@
.TH RM 1 2026-10-20 "w64devkit" "w64devkit Manual"
.SH NAME
rm \- remove files and directories
.SH SYNOPSIS
.B rm
.RB [ \-fiRrv ]
.IR file ...\&
.SH DESCRIPTION
.B rm
removes each
.IR file ,
and with
.B \-r
each directory and everything in it.
It is the
.BR busybox (1)
applet, which has fewer options than GNU
.BR rm ;
see
.BR NOTES .
.PP
Removal is permanent.
Nothing goes to the Recycle Bin; for that, use
.BR recycle (1).
.SS Operands
Without
.BR \-r ,
a directory operand is an error.
With
.BR \-r ,
a directory is emptied recursively and then removed.
A symbolic link, junction, or app execution alias is removed itself,
with or without
.BR \-r ,
and never followed, even with a trailing slash.
Such a link found inside a directory is removed the same way.
.PP
Trailing slashes and backslashes are removed from each operand first,
down to a root such as
.BR c:/ .
An operand whose last component is
.B .\&
or
.BR .. ,
or that is only a drive, such as
.BR c: ,
is refused, even with
.BR \-f ,
and the other operands are still processed; see
.BR NOTES .
No other operand is protected:
.B rm \-r c:/
removes everything it can from the root of the drive.
.PP
With no operand,
.B rm
writes a usage message on standard error and exits with status 1.
With no operand and
.BR \-f ,
it does nothing and exits with status 0.
.SS Order and failures
.B rm
handles the operands in order.
It reports a failure, goes on with the remaining operands, and exits
with status 1 at the end.
The entries of a directory are removed in the order Windows lists them,
each before the directory itself.
If any entry could not be removed, the directory is left alone with no
further message, though
.B \-i
still asks about it and
.B \-v
still reports it removed.
A directory that cannot be opened for reading is left alone with status
1 and no message.
.SS Prompting
With
.BR \-i ,
.B rm
asks before removing each file, and for each directory it asks before
entering it and again before removing it.
Without
.BR \-f ,
it also asks before removing a read-only file, but only when standard
input is a console.
It does not ask about a link this way.
Windows reports every directory as writable, even one with the read-only
attribute, so a directory is asked about only with
.BR \-i .
.PP
The questions are written on standard error, with no newline after the
question mark:
.PP
.RS 4
.EX
rm: remove \(aqfile\(aq?
rm: descend into directory \(aqdir\(aq?
rm: remove directory \(aqdir\(aq?
.EE
.RE
.PP
.B rm
then reads a line from standard input.
The answer is yes if the first character of the line that is not a
space or tab is
.B y
or
.BR Y .
Anything else, including the end of input, is no, which skips the item
and is not an error.
A no to the question about descending leaves the directory and its
contents alone.
A no for a file in a directory followed by a yes for the directory
leaves the directory not empty, so its removal fails with
.BR "Directory not empty" ,
and the exit status is 1.
.SS Output
.B rm
writes each error on standard error, preceded by its name and a colon.
The messages are:
.TP
.BI "can\(aqt remove \(aq" path "\(aq: " reason
The path does not exist and
.B \-f
was not given, or Windows would not remove it.
.TP
.BI "can\(aqt stat \(aq" path "\(aq: " reason
The path could not be examined, for a reason other than that it does not
exist.
.TP
.BI \(aq dir "\(aq is a directory"
A directory operand without
.BR \-r .
.TP
.B "can\(aqt remove \(aq.\(aq or \(aq..\(aq"
An operand was refused.
.PP
Only
.B \-v
and
.B \-\-help
write to standard output.
.SH OPTIONS
Options may be grouped, as in
.BR \-rf ,
and may follow operands, unless
.B POSIXLY_CORRECT
is set.
.B \-\-
ends the options.
Apart from
.BR \-\-help ,
there are no long options.
.TP
.B \-i
Ask before every removal; see
.BR Prompting .
Of
.B \-f
and
.BR \-i ,
only the last given takes effect.
.TP
.B \-f
Never ask.
Ignore an operand that does not exist, with no message and no error.
Every other error is still reported, with status 1, such as a directory
without
.BR \-r ,
an operand of
.BR .\& ,
.BR .. ,
or only a drive, and a failed removal.
Of
.B \-f
and
.BR \-i ,
only the last given takes effect.
.TP
.BR \-R ", " \-r
Remove directories and their contents recursively.
.TP
.B \-v
Write
.BI removed\ \(aq file \(aq
on standard output after each file or link is removed, and
.BI removed\ directory:\ \(aq dir \(aq
after each directory, which comes after its contents.
Nothing is written for an item that is skipped or fails, but a
directory left in place because an entry in it could not be removed is
still reported as removed.
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
.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
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, including
.B \-\-help
as the first argument, operands skipped by an answer to a question,
operands that do not exist with
.BR \-f ,
and no operands with
.BR \-f .
.TP
.B 1
An invalid command line, with a usage message on standard error, or any
operand or directory entry that could not be removed.
.SH EXAMPLES
Remove the object files:
.PP
.RS 4
.EX
$ rm *.o
.EE
.RE
.PP
Remove a build directory and everything in it, without asking:
.PP
.RS 4
.EX
$ rm \-rf build
.EE
.RE
.PP
Ask before removing each backup file:
.PP
.RS 4
.EX
$ rm \-i *.bak
.EE
.RE
.PP
Remove a tree that holds a/b/f and g, and list each removal:
.PP
.RS 4
.EX
$ rm \-rv v
removed \(aqv/a/b/f\(aq
removed directory: \(aqv/a/b\(aq
removed directory: \(aqv/a\(aq
removed \(aqv/g\(aq
removed directory: \(aqv\(aq
.EE
.RE
.PP
Remove a file whose name begins with a dash:
.PP
.RS 4
.EX
$ rm \-\- \-x
.EE
.RE
.PP
Remove a junction or symbolic link to a directory, which needs no
.BR \-r ,
leaving the directory it points to alone:
.PP
.RS 4
.EX
$ rm link
.EE
.RE
.SH NOTES
Differences from GNU
.BR rm :
.IP \(bu 2
Only
.BR \-f ,
.BR \-i ,
.BR \-R ,
.BR \-r ,
and
.B \-v
exist.
Every other option is invalid, including
.BR \-d ,
.BR \-I ,
and every long option but
.BR \-\-help .
.IP \(bu 2
There is no
.BR \-\-preserve\-root .
Only an operand ending in
.B .\&
or
.BR .. ,
or one that is only a drive, is refused.
.PP
.B rm
clears the read-only attribute of a file before it removes it, and of a
directory once the directory is empty, so read-only items are removed.
If the removal then fails, the attribute stays cleared.
Hidden and system files are removed like any other.
.PP
Windows does not remove a file that another program has open without
allowing deletion, or a directory that is the current directory of a
running program, such as a shell.
The removal fails with
.BR "Permission denied" .
With
.BR \-r ,
the rest of the tree is still removed, apart from the directories that
hold the item.
.PP
A full path of 260 or more characters, counting the current directory
for a relative path, cannot be reached.
Without
.BR \-f ,
.B rm
reports
.B "No such file or directory"
for it.
With
.BR \-f ,
it skips it silently, and the directory that holds it then fails with
.BR "Directory not empty" .
A directory whose full path has 258 or more characters cannot be listed,
and is left alone with status 1 and no message.
Either way the directories above it are left too, and
.B rm
goes on.
.PP
An operand may have a drive letter and backslashes.
The names found in a directory are joined to the operand with
.BR / ,
so
.B rm \-rv \(aqc:\etmp\ex\(aq
writes names such as
.IR c:\etmp\ex/y .
Names may contain any Unicode character on Windows 10 version 1903 and
later; see
.BR busybox (1).
.PP
An operand that is only a drive, such as
.BR c: ,
names the current directory of that drive, as
.B c:.\&
does, and is refused in the same way.
.PP
From
.BR cmd.exe ,
or any caller that leaves
.B BB_GLOBBING
unset,
.B rm
expands wildcards in its operands itself, even quoted ones.
A pattern that matches nothing is left as it is, so
.B rm
reports
.B "No such file or directory"
for it, or with
.B \-f
quietly succeeds.
To delete the files that a search selects, see
.B find \-delete
in
.BR find (1).
.SH SEE ALSO
.BR busybox (1),
.BR find (1),
.BR recycle (1),
.BR rmdir (1)

326
man/man1/rmdir.1 Normal file
View File

@@ -0,0 +1,326 @@
.TH RMDIR 1 2026-10-20 "w64devkit" "w64devkit Manual"
.SH NAME
rmdir \- remove empty directories
.SH SYNOPSIS
.B rmdir
.RB [ \-pv ]
.RB [ \-\-ignore\-fail\-on\-non\-empty ]
.IR directory ...
.SH DESCRIPTION
.B rmdir
removes each
.I directory
operand, in order, if it is empty.
It is the
.BR busybox (1)
applet, which has fewer options than GNU
.BR rmdir ;
see
.BR NOTES .
It never removes a file, or a directory that has contents.
.B "rm \-r"
removes a tree; see
.BR rm (1).
.PP
A
.I directory
that cannot be removed is reported on standard error, and the remaining
operands are still processed.
The exit status is then 1.
An invalid option is reported on standard error.
With an invalid option or no operand,
.B rmdir
prints a usage message on standard error and exits with status 1.
.SS Parent directories
With
.BR \-p ,
after removing a directory
.B rmdir
goes on to its parent, then the parent's parent, and so on.
The parent is the path without its last component.
The walk for an operand ends after a directory that has no parent
component, such as
.I out
in
.IR out/obj ,
and at the first directory that cannot be removed.
That failure is an error like any other, so a parent that is not empty
makes the exit status 1 unless
.B \-\-ignore\-fail\-on\-non\-empty
is given.
.PP
A path with a root does not end by itself: after its topmost directory,
.B rmdir
tries the root, as in
.I c:/
or
.IR / ,
which cannot be removed.
A path that begins with
.IR .. ,
such as
.IR ../out ,
goes on to
.IR .. ,
the directory that holds the current directory, which cannot be removed.
.SS Output
Nothing is written to standard output unless
.B \-v
or
.B \-\-help
is given.
An error is written to standard error as
.PP
.RS 4
.EX
rmdir: \(aq\fIpath\fR\(aq: \fIreason\fR
.EE
.RE
.PP
where
.I path
is the operand as typed, or with
.B \-p
the parent as cut from it, and
.I reason
is the system's message.
These are the common reasons:
.TP
.B No such file or directory
The path does not exist, the operand is empty, or the full path is
260 or more characters.
.TP
.B Directory not empty
The directory has contents.
.TP
.B Not a directory
The operand is a symbolic link or junction named without a trailing
slash; see
.BR NOTES .
.TP
.B Invalid argument
The operand is a file, or contains a character that Windows does not
allow in a name, such as
.B ?\&
or
.BR * .
.TP
.B Permission denied
The directory is in use, such as the current directory of a process, or
access to it is denied.
.SH OPTIONS
Options may be grouped, as in
.BR \-pv ,
and may follow operands, unless
.B POSIXLY_CORRECT
is set.
A long option may be abbreviated to any unambiguous prefix.
.B \-\-
ends the options.
.TP
.BR \-p ", " \-\-parents
Remove the parents of each directory as well; see
.BR "Parent directories" .
.TP
.BR \-v ", " \-\-verbose
Write
.BI "rmdir: removing directory, \(aq" path \(aq
on standard output before each attempt to remove a directory, including
each parent tried by
.BR \-p ,
and a directory that then cannot be removed, whose error follows on
standard error.
The usage message omits this option.
.TP
.B \-\-ignore\-fail\-on\-non\-empty
Skip a directory that is not empty, without a message and without
changing the exit status.
With
.BR \-p ,
the walk up from it ends there.
Every other error is still reported.
.TP
.B \-\-help
As the first argument only, write a usage message on standard output
and exit with status 0.
The message omits
.BR \-v ,
.BR \-\-parents ,
and
.BR \-\-verbose ,
and lists
.B \-\-ignore\-fail\-on\-non\-empty
without a description.
.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
.B \-\-help
as the first argument, and directories skipped by
.BR \-\-ignore\-fail\-on\-non\-empty .
.TP
.B 1
An invalid option, no operand, or any directory that could not be
removed.
.SH EXAMPLES
Remove an empty directory:
.PP
.RS 4
.EX
$ rmdir build
.EE
.RE
.PP
A directory with contents is left alone:
.PP
.RS 4
.EX
$ rmdir src
rmdir: \(aqsrc\(aq: Directory not empty
.EE
.RE
.PP
Remove a directory and its empty parents, listing each:
.PP
.RS 4
.EX
$ rmdir \-pv out/obj/debug
rmdir: removing directory, \(aqout/obj/debug\(aq
rmdir: removing directory, \(aqout/obj\(aq
rmdir: removing directory, \(aqout\(aq
.EE
.RE
.PP
Remove a directory and as many of its parents as are empty, without an
error for the first one that is not:
.PP
.RS 4
.EX
$ rmdir \-p \-\-ignore\-fail\-on\-non\-empty out/obj/debug
.EE
.RE
.PP
Remove every empty directory under
.IR build ,
and
.I build
itself if nothing is left, discarding the errors for the others:
.PP
.RS 4
.EX
$ find build \-depth \-type d \-exec rmdir {} + 2>/dev/null
.EE
.RE
.PP
Remove a directory and everything in it:
.PP
.RS 4
.EX
$ rm \-r build
.EE
.RE
.SH NOTES
Unlike GNU
.BR rmdir ,
this
.B rmdir
has no
.B \-\-version
option, and
.B \-\-help
works only as the first argument.
.PP
A symbolic link or junction is refused with
.BR "Not a directory" ,
as on Linux, even when it points to a directory, and
.BR rm (1)
removes it; the target is untouched.
With a trailing slash, as in
.IR link/ ,
a junction is not detected: it is removed, even when its target has
contents, and the target is untouched.
A file is refused with
.BR "Invalid argument" .
A directory that a process uses as its current directory cannot be
removed, so
.B rmdir .\&
fails with
.BR "Permission denied" .
.PP
A read-only directory is removed.
.B rmdir
clears the read-only attribute of each path before it tries to remove
it, so a file or directory that then cannot be removed, such as a
directory that is not empty, is left without the attribute.
.PP
Paths may have drive letters and backslashes.
Both kinds of slash separate components, and messages show a path as
typed.
A path may be absolute, as in
.IR c:/dir ,
relative, or relative to the current directory of a drive, as in
.IR c:dir .
A bare drive, such as
.IR c: ,
names that directory, as does
.IR c:. ,
so on the current drive
.B rmdir c:
fails with
.BR "Permission denied" .
With
.BR \-p ,
the parent of
.I c:dir
is
.IR c:. ,
so
.B rmdir
goes on to try it instead of stopping.
.PP
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 rmdir
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 find (1),
.BR mkdir (1),
.BR rm (1)

1088
man/man1/sed.1 Normal file
View File

File diff suppressed because it is too large Load Diff

336
man/man1/seq.1 Normal file
View File

@@ -0,0 +1,336 @@
.TH SEQ 1 2026-10-19 "w64devkit" "w64devkit Manual"
.SH NAME
seq \- print a sequence of numbers
.SH SYNOPSIS
.B seq
.RB [ \-w ]
.RB [ \-s
.IR sep ]
.RI [ first
.RI [ incr ]]
.I last
.SH DESCRIPTION
.B seq
writes the numbers from
.I first
to
.I last
in steps of
.I incr
to standard output.
With one operand, it is
.IR last .
With two, they are
.I first
and
.IR last ,
and with three,
.IR first ,
.IR incr ,
and
.IR last .
.I first
and
.I incr
default to 1.
Any other number of operands is a usage error.
.PP
Each operand is read with the C library function
.BR strtod .
It may have leading white space and a sign, and be written with a
fraction, with an exponent as in
.BR 1e3 ,
or in hexadecimal as in
.BR 0x1F .
It may also be
.BR inf ,
.BR infinity ,
or
.BR nan ,
in any case.
The decimal separator is always a period.
An empty operand is 0.
Trailing characters after the number, a value too large for a double,
and a nonzero value smaller in magnitude than about 2.2e\-308 are usage
errors.
.PP
The number at position
.IR n ,
counting from 0, is
.IR first " + " n "*" incr ,
computed as a double, so rounding errors do not accumulate.
When
.I incr
is 0 or positive,
.B seq
writes numbers as long as they are at most
.IR last .
When it is negative, it writes them as long as they are at least
.IR last .
A sequence that starts beyond
.IR last ,
such as
.BR "seq 3 1" ,
is empty: nothing is written, not even a newline, and the status is 0.
An
.I incr
of 0 repeats
.I first
forever unless
.I first
is above
.IR last .
.PP
Numbers are written in decimal, never with an exponent.
Each has as many digits after the period as there are characters after
the period in
.I first
or
.IR incr ,
whichever has more, as typed.
Every character after the period counts, so
.B 1.5e1
gives three digits, and an operand with no period, such as
.BR 1e\-1 ,
gives none.
The characters of
.I last
do not count.
Numbers are rounded to that many digits, so
.B "seq 0 1e\-1 1"
writes whole numbers only.
.PP
.B seq
writes
.I sep
between numbers, and a newline after the last number.
.SH OPTIONS
Options may be grouped, and an option's argument may be attached or be
the next argument, so
.B \-ws:
is the same as
.BR "\-w \-s :" .
.B \-\-
ends the options.
Options must come before the operands: a later word is an operand.
.PP
A word that starts with a hyphen and a digit or a period, such as
.B \-5
or
.BR \-.5 ,
is a negative number wherever it appears, and the options end before it.
A
.I sep
that looks like that must be attached to the option, as in
.BR \-s\-1 .
.TP
.B \-w
Pad the numbers with leading zeros to a common width.
The width is the largest, over all the operands including
.IR last ,
of the number of characters typed before the period, or in the whole
operand when it has none, so white space, a sign, an exponent, and a
.B 0x
prefix count.
When the numbers have digits after the period, the period and those
digits are added.
The width is computed from the text, not the values:
.B "seq \-w 0x9 0x10"
pads to four characters and writes
.BR 0009 ,
.BR 0010 ,
and so on.
Zeros go after a sign, so
.B "seq \-w \-10 5"
writes
.B \-10
through
.BR \-01 ,
then
.B 000
through
.BR 005 .
.TP
.BI "\-s " sep
Write
.I sep
between numbers instead of a newline.
It is written as is, with no backslash escapes, and may be empty.
With several
.B \-s
options, the last wins.
.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, 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, 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 an empty sequence.
.TP
.B 1
Usage error: an unknown option, a missing option argument, a number of
operands other than one to three, or an operand that is not a number or
is out of range for a double.
The usage message is written to standard error, preceded for an option
error by a line such as
.BR "seq: unknown option \-\- x" .
.TP
.B 141
Standard output is a pipe whose reader has exited, found while writing
the numbers.
.TP
.B 255
Standard output could not be written when it was flushed at exit, such
as when it is closed, or when it is a pipe whose reader has exited and
the output was short enough to stay buffered until then.
No message is written.
.SH EXAMPLES
Write the numbers from 1 to 5 on one line:
.PP
.RS 4
.EX
$ seq \-s \(aq \(aq 5
1 2 3 4 5
.EE
.RE
.PP
Count down by fives, and count up from a negative number:
.PP
.RS 4
.EX
$ seq \-s \(aq \(aq 20 \-5 0
20 15 10 5 0
$ seq \-s, \-2 2
\-2,\-1,0,1,2
.EE
.RE
.PP
Write fractions; the step 0.25 sets two digits for every number:
.PP
.RS 4
.EX
$ seq 0 0.25 1
0.00
0.25
0.50
0.75
1.00
.EE
.RE
.PP
Number files with a common width:
.PP
.RS 4
.EX
$ for i in $(seq \-w 8 11); do echo img$i.png; done
img08.png
img09.png
img10.png
img11.png
.EE
.RE
.PP
Rounding makes the last number of a fractional sequence uncertain.
Here 0.3 is missing, because 3 times 0.1 is slightly more than 0.3:
.PP
.RS 4
.EX
$ seq 0 0.1 0.3
0.0
0.1
0.2
.EE
.RE
.PP
Keep 0.3 by stopping a little past it:
.PP
.RS 4
.EX
$ seq 0 0.1 0.35
.EE
.RE
.SH NOTES
Unlike GNU
.BR seq ,
this one has no format option
.RB ( \-f ),
and no long options other than
.BR \-\-help .
.PP
Numbers are doubles, so integers above 2 to the 53rd power are not all
representable.
Each number is rounded to the nearest double, so an
.I incr
that is small next to
.I first
makes numbers repeat or skip.
The count of numbers written is a 32-bit value, so a sequence of
4294967296 numbers or more starts over from
.I first
after that many, and never ends.
.PP
Standard output is binary, so the newline is a bare LF.
.PP
The C runtime expands wildcards in the arguments, even quoted ones, when
.B seq
is run from
.BR cmd.exe .
A
.I sep
such as
.B *
is then replaced by the names of the matching files, so the arguments
differ from those typed.
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.
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 in
.IR sep ,
such as those for color, take effect, and busybox emulates them on
consoles without virtual terminal support.
.SH SEE ALSO
.BR awk (1),
.BR busybox (1),
.BR printf (1),
.BR sh (1),
.BR shuf (1)

1698
man/man1/sh.1 Normal file
View File

File diff suppressed because it is too large Load Diff

Some files were not shown because too many files have changed in this diff Show More