overgrown/docs/scrut.1

.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
.\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH scrut 1
.SH NAME
scrut \(en scrutinize file properties
.SH SYNOPSIS

scrut
.RB ( -bcdefgkprsuwxLS )
.RB [ file... ]
.\"
.SH DESCRIPTION

Determine if files comply with requirements.
.\"
.SH OPTIONS

.IP -L
Requires the given files to exist and be symbolic links.
.IP -S
Requires the given files to exist and be sockets.
.IP -b
Requires the given files to exist and be block special files.
.IP -c
Requires the given files to exist and be character special files.
.IP -d
Requires the given files to exist and be directories.
.IP -e
Requires the given files to exist, and is redundant to any other option.
.IP -e
Requires the given files to exist and be regular files.
.IP -g
Requires the given files to exist and have their set group ID flags set.
.IP -k
Requires the given files to exist and have their sticky bit set.
.IP -p
Requires the given files to exist and be named pipes.
.IP -r
Requires the given files to exist and be readable.
.IP -u
Requires the given files to exist and have their set user ID flags set.
.IP -w
Requires the given files to exist and be writable.
.IP -x
Requires the given files to exist and be executable.
.\"
.SH DIAGNOSTICS

If the given files comply with the specified requirements, the program will exit
successfully. If not, it exits unsuccessfully.

When invoked incorrectly, a debug message will be printed and the program will
exit with the appropriate
.BR sysexits.h (3)
error code.
.\"
.SH RATIONALE 

The 
.BR test (1p)
utility contains functionality that was broken out into separate programs. Thus,
the scope of this program is narrower than it. Notably, the
.B -h
option is now invalid and therefore shows usage information instead of being an
alias to the modern
.B -L
option.
.\"
.SH AUTHOR

Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT

Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
.BR access (3p),
.BR lstat (3p),
.BR test (1p)