From 7dcc2ecac8945eb5774aa44416dcbf027dd8002a Mon Sep 17 00:00:00 2001 From: Deven Blake Date: Sat, 14 May 2022 20:54:38 -0400 Subject: [PATCH] utilities/man --- man/add.1 | 29 +++++++++++++++++++++++++++ man/cat.1 | 13 +++++++++++++ man/echo.1 | 27 +++++++++++++++++++++++++ man/false.1 | 22 +++++++++++++++++++++ man/getpaths.3 | 52 +++++++++++++++++++++++++++++++++++++++++++++++++ man/lowercase.1 | 35 +++++++++++++++++++++++++++++++++ man/multiply.1 | 25 ++++++++++++++++++++++++ man/nonzero.1 | 18 +++++++++++++++++ man/simexec.1 | 49 ++++++++++++++++++++++++++++++++++++++++++++++ man/sleep.1 | 31 +++++++++++++++++++++++++++++ man/streq.1 | 33 +++++++++++++++++++++++++++++++ man/stris.1 | 25 ++++++++++++++++++++++++ man/true.1 | 22 +++++++++++++++++++++ 13 files changed, 381 insertions(+) create mode 100644 man/add.1 create mode 100644 man/cat.1 create mode 100644 man/echo.1 create mode 100644 man/false.1 create mode 100644 man/getpaths.3 create mode 100644 man/lowercase.1 create mode 100644 man/multiply.1 create mode 100644 man/nonzero.1 create mode 100644 man/simexec.1 create mode 100644 man/sleep.1 create mode 100644 man/streq.1 create mode 100644 man/stris.1 create mode 100644 man/true.1 diff --git a/man/add.1 b/man/add.1 new file mode 100644 index 0000000..e4bd608 --- /dev/null +++ b/man/add.1 @@ -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) diff --git a/man/cat.1 b/man/cat.1 new file mode 100644 index 0000000..e4b6964 --- /dev/null +++ b/man/cat.1 @@ -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. diff --git a/man/echo.1 b/man/echo.1 new file mode 100644 index 0000000..ac59eb4 --- /dev/null +++ b/man/echo.1 @@ -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. diff --git a/man/false.1 b/man/false.1 new file mode 100644 index 0000000..5caf763 --- /dev/null +++ b/man/false.1 @@ -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) diff --git a/man/getpaths.3 b/man/getpaths.3 new file mode 100644 index 0000000..f00f366 --- /dev/null +++ b/man/getpaths.3 @@ -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 +#include +#include +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. diff --git a/man/lowercase.1 b/man/lowercase.1 new file mode 100644 index 0000000..fcea152 --- /dev/null +++ b/man/lowercase.1 @@ -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. diff --git a/man/multiply.1 b/man/multiply.1 new file mode 100644 index 0000000..d3eff7d --- /dev/null +++ b/man/multiply.1 @@ -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) diff --git a/man/nonzero.1 b/man/nonzero.1 new file mode 100644 index 0000000..396392b --- /dev/null +++ b/man/nonzero.1 @@ -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. diff --git a/man/simexec.1 b/man/simexec.1 new file mode 100644 index 0000000..5d79338 --- /dev/null +++ b/man/simexec.1 @@ -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. diff --git a/man/sleep.1 b/man/sleep.1 new file mode 100644 index 0000000..5baca12 --- /dev/null +++ b/man/sleep.1 @@ -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) diff --git a/man/streq.1 b/man/streq.1 new file mode 100644 index 0000000..1a24d7d --- /dev/null +++ b/man/streq.1 @@ -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. diff --git a/man/stris.1 b/man/stris.1 new file mode 100644 index 0000000..ed9ee3f --- /dev/null +++ b/man/stris.1 @@ -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. diff --git a/man/true.1 b/man/true.1 new file mode 100644 index 0000000..32e1fde --- /dev/null +++ b/man/true.1 @@ -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)