overgrown/docs/strcmp.1

.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023–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 STRCMP 1 2024-06-17 "Bonsai Core Utilites 0.13.11"
.SH NAME
strcmp \(en compare strings
.\"
.SH SYNOPSIS

strcmp
.RM [ string ]
.RB [ strings... ]
.\"
.SH DESCRIPTION

Check whether string arguments are the same.
.\"
.SH DIAGNOSTICS

The program will exit successfully if the strings are identical. Otherwise, it
will exit with an error code of 1 if a string passed has a lesser byte value
than one of the prior strings:

.RS
strcmp b a
.RE

or with an error code of 255 if it has a greater byte value than one of the
prior strings:

.RS
strcmp a b
.RE

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

The program will exit unsuccessfully if the given strings are not identical;
therefore, Unicode strings may need to be normalized if the intent is to check
visual similarity and not byte similarity.
.\"
.SH RATIONALE

The traditional tool for string comparisons in POSIX and other Unix shells has
been
.BR test (1).
This tool also handles integer comparisons and file scrutiny. These parts of its
functionality have been broken out into multiple utilities.

This program\(cqs functionality may be performed on a POSIX-compliant system
with
.BR test (1p).
.\"
.SH AUTHOR

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

Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO
.BR strcmp (3),
.BR intcmp (1),
.BR scrut (1),
.BR test (1p)