Add man page

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 153 insertions, 0 deletions

diff --git a/asroot.8 b/asroot.8
new file mode 100644
index 0000000..4492fc1
--- /dev/null
+++ b/asroot.8
@@ -0,0 +1,153 @@
+.TH ASROOT 8 asroot
+
+.SH NAME
+asroot - run a process as the root user
+
+.SH SYNOPSIS
+.B asroot
+[-e]
+.I command
+.RI [ argument ]\ ...
+
+.SH DESCRIPTION
+The
+.B asroot
+utility as for the user's password and runs the
+specified
+.I command
+with sanitised and updated environment variables.
+.PP
+Only users in the
+.B wheel
+group are allowed to run the
+.B asroot
+utility, unless it is installed with non-standard permissions.
+
+.SH OPTIONS
+The
+.B asroot
+utility conforms to the Base Definitions volume of POSIX.1-2017,
+.IR "Section 12.2" ,
+.IR "Utility Syntax Guidelines" .
+.PP
+The following option is supported:
+.TP
+.B -e
+Keep the environment variables as is. Neither
+sanitise nor update them.
+
+.SH OPERANDS
+The following operands are supported:
+.TP
+.I command
+The command that shall be run with as the root user.
+This will be both the process image and the process's
+zeroth command line argument.
+.TP
+.IR argument \ ...
+Command line arguments for the command to run.
+
+.SH STDIN
+The
+.B asroot
+utility does not use the standard input, however the
+.I command
+it starts may.
+
+.SH INPUT FILES
+None.
+
+.SH ENVIRONMENT VARIABLES
+The following environment variables affects the execution of
+.BR asroot :
+.TP
+.SH PATH
+Default. See to the Base Definitions volume of POSIX.1-2017, Section 8.3, Other Environment Variables.
+
+.SH ASYNCHRONOUS EVENTS
+Default.
+
+.SH STDIN
+The
+.B asroot
+utility does not use the standard output, however the
+.I command
+it starts may.
+
+.SH STDERR
+The standard error is used for diagnostic messages and the
+password prompt. The
+.I command
+the
+.B asroot
+utility starts may also use the standard error.
+
+.SH OUTPUT FILES
+None.
+
+.SH EXTENDED DESCRIPTION
+None.
+
+.SH EXIT STATUS
+If the
+.B asroot
+utility fails it will exit withone of the following statuses:
+.TP
+125
+A error occurred.
+.TP
+126
+The process failed to change process image.
+.TP
+127
+The specified command was not found.
+.PP
+If the
+.B asroot
+utility is successful, the exit status is defined by the
+.I command
+it starts.
+
+.SH CONSEQUENCES OF ERRORS
+Default.
+
+.SH APPLICATION USAGE
+None.
+
+.SH EXAMPLES
+None.
+
+.SH CONFORMING TO
+The
+.B asroot
+utility is non-standard utility.
+
+.SH RATIONALE
+None.
+
+.SH NOTES
+The
+.I PATH
+environment variable will not be updated.
+Updates environment variables are:
+.IR HOME ,
+.IR LOGNAME ,
+.IR MAIL ,
+.IR SHEEL ,
+and
+.IR USER .
+
+.SH BUGS
+None.
+
+.SH FUTURE DIRECTIONS
+None.
+
+.SH SEE ALSO
+.BR sudo (8),
+.BR doas (1),
+.BR su (1)
+
+.SH AUTHORS
+Mattias Andrée
+.RI < maandree@kth.se >