.. RST source for slowbaud(1) man page. Convert with: .. rst2man.py slowbaud.rst > slowbaud.1 .. rst2man.py comes from the SBo development/docutils package. .. |version| replace:: 0.0.1 .. |date| date:: ======== slowbaud ======== ---------------------------------------- simulate a low bitrate serial connection ---------------------------------------- :Manual section: 1 :Manual group: Urchlay's Useless Stuff :Date: |date| :Version: |version| SYNOPSIS ======== **slowbaud** [**] [** ...] **slowbaud** [**] **-c** [** [** ...]] **slowbaud** [**] **-e** ** [** ...] 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 output... but slowly, at the given bits-per-second rate. Input and output are unbuffered. slowbaud can also act like **echo(1)** (the **-e** option), or run an interactive command (the **-c** option). The ** 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 not set. 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 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 backslash-escapes, or any of the options of the regular **echo** command. **-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 command can be interactive. ENVIRONMENT =========== **SLOWBAUD_BPS** Can be used to set the bit rate, when no ** argument is used. **SLOWBAUD_DEBUG** 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 **. If unset, **/bin/sh** is used. EXIT STATUS =========== Without **-c**, 0 for success, non-zero on any error such as nonexistent/unreadable files. slowbaud exits immediately on such errors (this is unlike **cat(1)**). 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... 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" 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, ** 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). 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). The timing error will almost always result in the bitrate being slightly too slow at lower bitrates and slightly too fast at higher ones. Timing is more accurate on Linux than OSX. It's 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'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 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 command on Linux misuses the term ("speed 38400 baud"), 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. COPYRIGHT ========= slowbaud is copyright 2021, B. Watson . Released under the WTFPL. See http://www.wtfpl.net/txt/copying/ for details.