diff options
Diffstat (limited to 'slowbaud.1')
| -rw-r--r-- | slowbaud.1 | 62 |
1 files changed, 42 insertions, 20 deletions
@@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH SLOWBAUD 1 "2021-07-21" "0.0.1" "Urchlay's Useless Stuff" +.TH SLOWBAUD 1 "2021-07-22" "0.0.1" "Urchlay's Useless Stuff" .SH NAME slowbaud \- simulate a low bitrate serial connection . @@ -36,6 +36,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] . .\" rst2man.py comes from the SBo development/docutils package. . +.\" Note: if you edit this, run "make" to recreate the man page and README, +. +.\" *then* do a "git commit -a". Even though they're generated files, the man +. +.\" page and README.txt are tracked by git. +. .SH SYNOPSIS .sp \fBslowbaud\fP [\fI<bits\-per\-sec>\fP] [\fI<file>\fP ...] @@ -43,6 +49,8 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] \fBslowbaud\fP [\fI<bits\-per\-sec>\fP] \fB\-c\fP [\fI<command>\fP [\fI<arg>\fP ...]] .sp \fBslowbaud\fP [\fI<bits\-per\-sec>\fP] \fB\-e\fP \fI<string>\fP [\fI<string>\fP ...] +.sp +\fBslowbaud\fP [\fI<bits\-per\-sec>\fP] \fB\-b\fP [\fI<bytes>\fP] .SH DESCRIPTION .sp slowbaud by default acts as a filter, or like the \fBcat(1)\fP command. It @@ -51,7 +59,7 @@ to standard output... but slowly, at the given bits\-per\-second rate. Input and output are unbuffered. .sp slowbaud can also act like \fBecho(1)\fP (the \fB\-e\fP option), or run an -interactive command (the \fB\-c\fP option). +interactive command in a pseudo\-tty (the \fB\-c\fP option). .sp The \fI<bits\-per\-sec>\fP argument is optional. If it\(aqs not given, the bit rate will be set from \fBSLOWBAUD_BPS\fP in the environment, or a @@ -60,20 +68,29 @@ built\-in default of 2400 if not set. .INDENT 0.0 .TP .B \fBbits\-per\-sec\fP -The bit ("baud") rate to simulate. This must be the first argument. -slowbaud assumes that if the first argument is a number, it\(aqs the bit rate. -If you\(aqre trying to pass a filename that consists only of digits, give -\fB\-\-\fP as the first argument, or use e.g. \fI\&./filename\fP\&. +The bit ("baud") rate to simulate. Range is 1 to 500000. This +must be the first argument. slowbaud assumes that if the first +argument is a number, it\(aqs the bit rate. If you\(aqre trying to pass +a filename that consists only of digits, give \fB\-\-\fP as the first +argument, or use e.g. \fI\&./filename\fP\&. .TP .B \fB\-e\fP Echo mode. Prints all further arguments as strings to stdout, separated by a single space, at the given bit rate. Does not support backslash\-escapes, or any of -the options of the regular \fBecho\fP command. +the options of the regular \fBecho\fP command. At least one argument is required +after \fB\-e\fP\&. .TP .B \fB\-c\fP Command mode. Next argument (if present) is the command to run, any remaining arguments become arguments to the command. With no arguments after \fB\-c\fP, a shell is spawned. This creates a pseudo\-tty, so the command can be interactive. +.TP +.B \fB\-b\fP +Benchmark mode. Prints \fI<bytes>\fP (or 4096, if no \fI<bytes>\fP given) bytes of +zeroes to /dev/null. Mostly useful for development and troubleshooting. +.TP +.B \fB\-h\fP, \fB\-?\fP +Show built\-in help message and exit. .UNINDENT .SH ENVIRONMENT .INDENT 0.0 @@ -92,20 +109,25 @@ 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 +Without \fB\-c\fP or \fB\-e\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\-e\fP, exit status is 0, unless there were no arguments to echo. +.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... +.sp +With \fB\-b\fP, exit status is 0, unless something catastrophic happened +(e.g. unable to open \fB/dev/null\fP for writing). .SH NOTES .sp -The bitrate has 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 at least 99.7% accurate. +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 at least +99.7% accurate. .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, @@ -119,9 +141,8 @@ 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. +The timing inaccuracy will almost always result in the bitrate +being slightly too slow. .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 @@ -131,20 +152,21 @@ 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 +increase accuracy 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. +the stty command on both Linux and OSX misuses the term ("speed +38400 baud"), as well as the man page for termios(3), 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. +doesn\(aqt interrupt the process until all pending output is processed. .SH COPYRIGHT .sp slowbaud is copyright 2021, B. Watson <\fI\%yalhcru@gmail.com\fP>. Released |