overgrown/docs/mm.1

.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
.\"
.\" 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 MM 1 2024-06-17 "Harakit X.X.X"
.SH NAME
mm \(en middleman
.\"
.SH SYNOPSIS

mm
.RB ( -aenu )
.RB ( -i
.RB [ input ])
.RB ( -o
.RB [ output ])
.\"
.SH DESCRIPTION

Catenate input files and write them to the start of each output file or stream.
.\"
.SH OPTIONS

.IP \fB-a\fP
Opens subsequent outputs for appending rather than updating.
.IP \fB-e\fP
Use the standard error as an output.
.IP \fB-i\fP
Opens a path as an input. If one or more of the input files is \(lq-\(rq or if
no inputs are specified, the standard input shall be used.
.IP \fB-o\fP
Opens a path as an output. If one or more of the output files is \(lq-\(rq or if
no outputs are specified, the standard output shall be used.
.IP \fB-u\fP
Ensures neither input or output will be buffered.
.IP \fB-n\fP
Causes SIGINT signals to be ignored.
.\"
.SH DIAGNOSTICS

If an output cannot be written to, an error occurs; however, exiting will be 
deferred until writing to any other specified outputs completes.

When an error is encountered, a diagnostic message is printed and the program
exits with the appropriate
.BR sysexits.h (3)
status.
.\"
.SH CAVEATS

Existing files are not truncated on ouput and are instead overwritten.
.\"
.SH RATIONALE

The
.BR cat (1p)
and
.BR tee (1p)
programs specified in POSIX together provide similar functionality. The
separation of the two sets of functionality into separate APIs seemed
unncessary.
.\"
.SH COPYRIGHT

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