1
0

utilities/man

This commit is contained in:
dtb 2022-05-14 20:54:38 -04:00
parent 5fbbf96062
commit 7dcc2ecac8
13 changed files with 381 additions and 0 deletions

29
man/add.1 Normal file
View File

@ -0,0 +1,29 @@
.TH ADD 1
.SH NAME
add \(en add integers
.SH DESCRIPTION
Add sums an arbitrary quantity of integers and prints the output.
.SH NOTES
Add may be confused with sum(1), which prints checksums of files.
.SH DIAGNOSTICS
Add will print a message to standard error and exit unsuccessfully if a non-integer argument is given.
.SH BUGS
Add does not work with decimal values.
.SH COPYRIGHT
Public domain.
.SH SEE ALSO
fdivide(1), multiply(1), stris(1), subtract(1)

13
man/cat.1 Normal file
View File

@ -0,0 +1,13 @@
.TH CAT 1
.SH NAME
cat \(en concatenate files
.SH SYNOPSIS
cat [file...]
.SH DESCRIPTION
Cat prints the contents of file arguments, one after the other.

27
man/echo.1 Normal file
View File

@ -0,0 +1,27 @@
.TH ECHO 1
.SH NAME
echo \(en echo arguments
.SH SYNOPSIS
echo
.RB [ argument... ]
.SH DESCRIPTION
Echo echoes given arguments delimited by an ASCII blank, with a terminating newline.
.SH BUGS
Echo should not be used in scripts; printf(1) should be used in its place.
.SH STANDARDS
Echo does not recognize the escape sequences described in the X/Open System Interface Extension to POSIX.
This is intended.
.SH COPYRIGHT
Public domain.

22
man/false.1 Normal file
View File

@ -0,0 +1,22 @@
.TH FALSE 1
.SH NAME
false \(en do nothing, unsuccessfully
.SH DESCRIPTION
False does nothing regardless of operands or standard input.
False is always unsuccessful.
.SH STANDARDS
False functions as described in POSIX.1-2017.
.SH COPYRIGHT
Public domain.
.SH SEE ALSO
true(1)

52
man/getpaths.3 Normal file
View File

@ -0,0 +1,52 @@
.TH GETPATHS 3
.SH NAME
getpaths \- get an array of the current executable PATHs
.SH LIBRARY
libshell
.SH SYNOPSIS
.In stdlib.h
.In string.h
.In libshell.h
.Ft char **
.Fn getpaths void
.SH DESCRIPTION
.Fn getpaths
returns the system PATHs as an array of null-terminated strings ordered from highest to lowest priority.
The last address in the array is NULL.
The first address in the array, and the array address itself, should be passed to
.Xr free 3
to release the allocated storage when the returned array is no longer needed.
.SH EXAMPLES
To print the current PATHs, from highest to lowest priority:
.Bd -literal -offset indent
#include <stdlib.h>
#include <string.h>
#include <libshell.h>
int main(){
char **paths;
int i;
paths = getpaths();
if(paths == NULL)
exit(EXIT_FAILURE);
for(i = 0; paths[i] != NULL; ++i)
printf("%s\n", paths[i]);
free(*paths);
free(paths);
return EXIT_SUCCESS;
}
.Ed
.SH SEE ALSO
.Xr getenv 3
.SH STANDARDS
.Fn getpaths
is not part of any current standard.
.SH BUGS
Certainly existent but not yet known.

35
man/lowercase.1 Normal file
View File

@ -0,0 +1,35 @@
.TH LOWERCASE 1
.SH NAME
lowercase \(en make text lowercase
.SH SYNOPSIS
lowercase (-f)
.SH DESCRIPTION
Lowercase prints text from standard input to standard output as lowercase.
.SH DIAGNOSTICS
Lowercase will print an error message and exit with the appropriate status from sysexits(3) if it attempts
to process a glyph outside the supported encoding range; this is to not inadverdently mangle multi-byte
characters. The -f option exists to override this and process every character anyway.
.SH BUGS
Lowercase is not Unicode aware unless it's compiled with the USE_ICU flag, which requires libicu.
This isn't tested to any extent.
.PP
Lowercase is redundant to usages of tr(1) among other POSIX-specified utilities.
.SH HISTORY
Lorinda Cherry demonstrates using a lowercase utility in the AT&T film
.I UNIX: Making Computers Easier To Use.
.SH COPYRIGHT
Public domain.

25
man/multiply.1 Normal file
View File

@ -0,0 +1,25 @@
.TH MULTIPLY 1
.SH NAME
multiply \(en multiply integers
.SH DESCRIPTION
Multiply multiplies an arbitrary quantity of integers and prints the output.
.SH DIAGNOSTICS
Multiply will print a message to standard error and exit unsuccessfully if a non-integer argument is given.
.SH BUGS
Multiply does not work with decimal values.
.SH COPYRIGHT
Public domain.
.SH SEE ALSO
add(1), fdivide(1), stris(1), subtract(1)

18
man/nonzero.1 Normal file
View File

@ -0,0 +1,18 @@
.TH NONZERO 1
.SH NAME
nonzero \(en check for arguments
.SH DESCRIPTION
Nonzero exits successfully if any arguments are provided, and unsuccessfully otherwise.
.SH STANDARDS
Nonzero is not described in POSIX.1-2017.
Nonzero's function may be performed on a purely POSIX system with test(1).
.SH COPYRIGHT
Public domain.

49
man/simexec.1 Normal file
View File

@ -0,0 +1,49 @@
.TH SIMEXEC 1
.SH NAME
simexec \(en execute a program with the given argv
.SH SYNOPSIS
simexec
.RB [ pathname ]
.RB [ argv... ]
.SH DESCRIPTION
Simexec executes a given program with the given argv.
.SH PITFALLS
Non-binary programs cannot be executed. The PATH environment variable is not used and a valid pathname (relative or absolute) must be specified.
.PP
Simexec relies on the user to take proper precautions.
argv is not just the operands for the program but in fact directly the argv it will receive in runtime;
the first argv entry is the program's name, and forgoing this, though acceptable by simexec, can break customary assumptions.
for example, the true(1) implementation in the GNU coreutils suffers a segmentation fault if there is no argv[0].
.PP
While POSIX.1-2017 doesn't mandate there being an argv[0] per se a Strictly Conforming POSIX Application must pass an argv[0].
It has also been said that those who do not pass an argv[0] are mean and nasty and smell of elderberries.
.PP
Simexec directly uses the execv library function. It cannot execute shell scripts intelligently (via shebang).
It is inadviseable to use simexec as an alternative to simply calling a program, and in fact probably inadviseable to use simexec at all.
.SH DIAGNOSTICS
Simexec returns the value of execv(3), which will be -1 (or 0xFF; 255) if an error occurs.
This is not distinguishable from the executed program returning the same exit status.
.PP
Simexec will print a error message and return the proper sysexits(3) value if used in an invalid manner.
.SH COPYRIGHT
Public domain.
.SH SEE ALSO
exec(3)
.PP
The C89 standard's draft, section 2.1.2.2: "Hosted environment".
.PP
POSIX.1-2017 System Interfaces: execv. Particularly under the RATIONALE section header.

31
man/sleep.1 Normal file
View File

@ -0,0 +1,31 @@
.TH SLEEP 1
.SH NAME
sleep \(en wait a moment
.SH SYNOPSIS
sleep
.RB [ seconds ]
.SH DESCRIPTION
Sleep waits the given amount of seconds before exiting.
.SH EXIT STATUS
Sleep exits with a status indicating how much time is left for the program to sleep;
in practice, this is always 0.
.SH BUGS
User may still be tired after invoking sleep.
.SH COPYRIGHT
Public domain.
.SH SEE ALSO
sleep(3)

33
man/streq.1 Normal file
View File

@ -0,0 +1,33 @@
.TH STREQ 1
.SH NAME
streq \(en compare strings
.SH SYNOPSIS
streq
.RB [ strings... ]
.SH DESCRIPTION
Streq checks whether the given strings are the same.
Streq exits successfully if the strings are identical and unsuccessfully if not.
.SH DIAGNOSTICS
Streq will print an error message and exit unsuccessfully with a status described in sysexits(3) if used incorrectly (given less than two operands).
.SH UNICODE
Streq will exit unsuccessfully if the given strings are not identical;
Unicode strings may need to normalized if the intent is to check visual similarity and not byte similarity.
.SH STANDARDS
Streq is not described in POSIX.1-2017.
Streq's function may be performed on a purely POSIX system with test(1).
.SH COPYRIGHT
Public domain.

25
man/stris.1 Normal file
View File

@ -0,0 +1,25 @@
.TH STRIS 1
.SH NAME
stris \(en test if arguments are numbers
.SH SYNOPSIS
stris
.RB { float , int , uint }
[number...]
.SH DESCRIPTION
Stris tests an arbitrary amount of numbers against one of three properties: float, int, or uint; which correspond to whether the numbers are all representable as floating-point values, integers, or unsigned (absolute) integers.
.PP
Stris exits successfully if all given numbers match the specified property, and unsuccessfully if stris was used improperly or the numbers did not match the specified property.
.SH BUGS
Non-simple numbers that are technically representable as floating-point numbers may not be recognized. This includes infinity, negative infinity, and NaN.
.SH COPYRIGHT
Public domain.

22
man/true.1 Normal file
View File

@ -0,0 +1,22 @@
.TH TRUE 1
.SH NAME
true \(en do nothing, successfully
.SH DESCRIPTION
True does nothing regardless of operands or standard input.
True is always successful.
.SH STANDARDS
True functions as described in POSIX.1-2017.
.SH COPYRIGHT
Public domain.
.SH SEE ALSO
false(1)