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
.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. Without any inputs specified mm will use the
standard input. The standard input shall be used as an input if one or more of
the input files is \(lq-\(rq.
.IP \fB-o\fP
Opens a path as an output. Without any outputs specified mm will use the
standard output. The standard output shall be used as an output if one or more
of the output files is \(lq-\(rq.
.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 can no longer be written mm prints a diagnostic message, ceases
writing to that particular output, and if there are more outputs specified,
continues, eventually exiting unsuccessfully.

When an error is encountered, 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)