aboutsummaryrefslogtreecommitdiff
path: root/README.txt
diff options
context:
space:
mode:
Diffstat (limited to 'README.txt')
-rw-r--r--README.txt67
1 files changed, 41 insertions, 26 deletions
diff --git a/README.txt b/README.txt
index d9e2c32..870f356 100644
--- a/README.txt
+++ b/README.txt
@@ -10,6 +10,8 @@ SYNOPSIS
slowbaud [<bits-per-sec>] -e <string> [<string> ...]
+ slowbaud [<bits-per-sec>] -b [<bytes>]
+
DESCRIPTION
slowbaud by default acts as a filter, or like the cat(1) command. It reads
files or its standard input, and writes the contents unmodified to standard
@@ -17,7 +19,7 @@ DESCRIPTION
unbuffered.
slowbaud can also act like echo(1) (the -e option), or run an interactive com‐
- mand (the -c option).
+ mand in a pseudo-tty (the -c option).
The <bits-per-sec> argument is optional. If it's not given, the bit rate will
be set from SLOWBAUD_BPS in the environment, or a built-in default of 2400 if
@@ -25,46 +27,58 @@ DESCRIPTION
OPTIONS
bits-per-sec
- The bit ("baud") rate to simulate. This must be the first argument.
- slowbaud assumes that if the first argument is a number, it's the bit
- rate. If you're trying to pass a filename that consists only of dig‐
- its, give -- as the first argument, or use e.g. ./filename.
+ 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's the bit rate. If you're trying to pass a filename that
+ consists only of digits, give -- as the first argument, or use e.g.
+ ./filename.
-e Echo mode. Prints all further arguments as strings to stdout, separated
- by a single space, at the given bit rate. Does not support back‐
- slash-escapes, or any of the options of the regular echo command.
+ by a single space, at the given bit rate. Does not support back‐
+ slash-escapes, or any of the options of the regular echo command. At
+ least one argument is required after -e.
-c Command mode. Next argument (if present) is the command to run, any
remaining arguments become arguments to the command. With no arguments
after -c, a shell is spawned. This creates a pseudo-tty, so the com‐
mand can be interactive.
+ -b Benchmark mode. Prints <bytes> (or 4096, if no <bytes> given) bytes of
+ zeroes to /dev/null. Mostly useful for development and troubleshooting.
+
+ -h, -? Show built-in help message and exit.
+
ENVIRONMENT
SLOWBAUD_BPS
- Can be used to set the bit rate, when no <bits-per-sec> argument is
+ Can be used to set the bit rate, when no <bits-per-sec> argument is
used.
SLOWBAUD_DEBUG
- Set this (to any value) in the environment to see verbose debug output
+ Set this (to any value) in the environment to see verbose debug output
on stderr, including timing accuracy stats.
SHELL Standard *nix environment variable, used to determine what shell to run
when -c is given with no <command>. If unset, /bin/sh is used.
EXIT STATUS
- Without -c, 0 for success, non-zero on any error such as nonexistent/unread‐
- able files. slowbaud exits immediately on such errors (this is unlike cat(1)).
+ Without -c or -e, 0 for success, non-zero on any error such as nonexis‐
+ tent/unreadable files. slowbaud exits immediately on such errors (this is
+ unlike cat(1)).
+
+ With -e, exit status is 0, unless there were no arguments to echo.
With -c, exit status is that of the child process, or 127 if the child process
couldn't be spawned (e.g. command not found). Of course, the child process
could also exit with status 127...
+ With -b, exit status is 0, unless something catastrophic happened (e.g. unable
+ to open /dev/null for writing).
+
NOTES
- 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" tech‐
- niques 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.
We can't really insert a delay between the bits of a byte, since I/O is done
with byte granularity. For calculation purposes, <bits-per-sec> is divided by
@@ -77,8 +91,8 @@ NOTES
works well, and the CPU overhead is barely noticeable (at least on reasonably
fast modern systems).
- 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.
Timing is more accurate on Linux than OSX. It's done with getitimer() and sig‐
wait(). This works out to be slightly more accurate than using usleep() on
@@ -86,23 +100,24 @@ NOTES
and clock_gettime() API on Linux, for possibly even better accuracy, but OSX
doesn't have these (and I want to be portable).
- If this were a truly useful application, it would be worth trying to decrease
- latency further, with realtime process scheduling. I didn't do this because
+ If this were a truly useful application, it would be worth trying to increase
+ accuracy further, with realtime process scheduling. I didn't 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).
About the name... I'm aware that "baud" is not synonymous with bps. I just
think "slowbaud" sounds better than "slowbps", as a name. Anyway the stty com‐
- mand on Linux misuses the term ("speed 38400 baud"), so I'm in good company.
+ mand on both Linux and OSX misuses the term ("speed 38400 baud"), as well as
+ the man page for termios(3), so I'm in good company.
BUGS
- With -c, signals aren't handled gracefully. Window size changes (SIGWINCH)
- don't get propagated to the child process, and pressing ^C doesn't interrupt
- the process. Yet.
+ With -c, signals aren't handled gracefully. Window size changes (SIGWINCH)
+ don't get propagated to the child process, and pressing ^C doesn't interrupt
+ the process until all pending output is processed.
COPYRIGHT
- slowbaud is copyright 2021, B. Watson <yalhcru@gmail.com>. Released under the
+ slowbaud is copyright 2021, B. Watson <yalhcru@gmail.com>. Released under the
WTFPL. See http://www.wtfpl.net/txt/copying/ for details.
-0.0.1 2021-07-21 SLOWBAUD(1)
+0.0.1 2021-07-22 SLOWBAUD(1)