initial commit

1 files changed, 126 insertions, 0 deletions

diff --git a/slowbaud.1 b/slowbaud.1
new file mode 100644
index 0000000..7fcec1e
--- /dev/null
+++ b/slowbaud.1
@@ -0,0 +1,126 @@
+.\" Man page generated from reStructuredText.
+.
+.TH SLOWBAUD 1 "2021-07-21" "0.0.1" "Urchlay's Useless Stuff"
+.SH NAME
+slowbaud \- simulate a low bitrate serial connection
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.\" RST source for slowbaud(1) man page. Convert with:
+.
+.\" rst2man.py slowbaud.rst > slowbaud.1
+.
+.\" rst2man.py comes from the SBo development/docutils package.
+.
+.SH SYNOPSIS
+.sp
+\fBslowbaud\fP \fI<bits\-per\-sec>\fP [\fI<file>\fP ...]
+.sp
+\fBslowbaud\fP \fI<bits\-per\-sec>\fP \fB\-c\fP [\fI<command>\fP [\fI<arg>\fP ...]]
+.SH DESCRIPTION
+.sp
+slowbaud by default acts as a filter, or like the \fBcat(1)\fP command. It
+reads files or its standard input, and writes the contents unmodified
+to standard output... but slowly, at the given bits\-per\-second rate.
+Output is unbuffered.
+.sp
+With the \fB\-c\fP option, it creates a pseudo\-tty and runs the given command
+in it (or an interactive shell, if no command is given).
+.sp
+The \fI<bits\-per\-sec>\fP argument supports a range of 1 to 500000. Timing
+accuracy depends on your OS, kernel config (HZ and/or NO_HZ on Linux),
+and system load. No "fancy" techniques like realtime scheduling
+or hardware event timers are used. At bitrates up to 57600, on a
+typical unloaded Linux system, the timing should be around 99.7%
+accurate.
+.SH ENVIRONMENT
+.INDENT 0.0
+.TP
+.B \fBSLOWBAUD_DEBUG\fP
+Set this (to any value) in the environment to see verbose debug
+output on stderr, including timing accuracy stats.
+.TP
+.B \fBSHELL\fP
+Standard *nix environment variable, used to determine what
+shell to run when \fB\-c\fP is given with no \fI<command>\fP\&. If
+unset, \fB/bin/sh\fP is used.
+.UNINDENT
+.SH EXIT STATUS
+.sp
+Without \fB\-c\fP, 0 for success, non\-zero on any error such as
+nonexistent/unreadable files. slowbaud exits immediately on such
+errors (this is unlike \fBcat(1)\fP).
+.sp
+With \fB\-c\fP, exit status is that of the child process, or 127 if
+the child process couldn\(aqt be spawned (e.g. command not found).
+Of course, the child process could also exit with status 127...
+.SH NOTES
+.sp
+We can\(aqt really insert a delay between the bits of a byte, since
+I/O is done with byte granularity. For calculation purposes,
+\fI<bits\-per\-sec>\fP is divided by 10 to get bytes per second. This
+simulates "8\-N\-1": one start bit, 8 data bits, no parity, and 1 stop
+bit (total of 10 bits per byte).
+.sp
+The timing code works by calculating how long to sleep after each
+character (in microseconds), but actually sleeping slightly less
+than that, then busy\-waiting until the rest of the interval expires.
+At slower bitrates, this works well, and the CPU overhead is barely
+noticeable (at least on reasonably fast modern systems).
+.sp
+The timing error will almost always result in the bitrate
+being slightly too slow at lower bitrates and slightly too fast at
+higher ones.
+.sp
+Timing is more accurate on Linux than OSX. It\(aqs done with getitimer()
+and sigwait(). This works out to be slightly more accurate than
+using usleep() on both Linux and OSX. It would be possible to use
+the realtime timer_create() and clock_gettime() API on Linux, for
+possibly even better accuracy, but OSX doesn\(aqt have these (and I want to be
+portable).
+.sp
+If this were a truly useful application, it would be worth trying to
+decrease latency further, with realtime process scheduling. I didn\(aqt
+do this because slowbaud is just a toy, and because the RT stuff tends
+to be unportable and require elevated privileges (root, or something
+like setrtlimit or extended filesystem attributes to manage capabilities).
+.sp
+About the name... I\(aqm aware that "baud" is not synonymous with bps. I
+just think "slowbaud" sounds better than "slowbps", as a name. Anyway
+the stty command on Linux misuses the term ("speed 38400 baud"), so
+I\(aqm in good company.
+.SH BUGS
+.sp
+With \fB\-c\fP, signals aren\(aqt handled gracefully. Window size changes
+(SIGWINCH) don\(aqt get propagated to the child process, and pressing ^C
+doesn\(aqt interrupt the process. Yet.
+.SH COPYRIGHT
+.sp
+slowbaud is copyright 2021, B. Watson <\fI\%yalhcru@gmail.com\fP>. Released
+under the WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
+.\" Generated by docutils manpage writer.
+.