utilities/man

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)

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.

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.

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)

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 <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.

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.

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)

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.

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.

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)

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.

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.

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)