aboutsummaryrefslogtreecommitdiff
path: root/README.txt
blob: d9e2c32549879f8e5f0e75381f1aa75e1c98724d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
SLOWBAUD(1)                    Urchlay's Useless Stuff                    SLOWBAUD(1)

NAME
       slowbaud - simulate a low bitrate serial connection

SYNOPSIS
       slowbaud [<bits-per-sec>] [<file> ...]

       slowbaud [<bits-per-sec>] -c [<command> [<arg> ...]]

       slowbaud [<bits-per-sec>] -e <string> [<string> ...]

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 com‐
       mand (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
       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 dig‐
              its, 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.

       -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.

ENVIRONMENT
       SLOWBAUD_BPS
              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
              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)).

       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"  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.

       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
       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 sig‐
       wait(). 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 com‐
       mand 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 <yalhcru@gmail.com>. Released under the
       WTFPL. See http://www.wtfpl.net/txt/copying/ for details.

0.0.1                                 2021-07-21                          SLOWBAUD(1)