ust.1

   1 .Dd ust\-VERSION
   2 .Dt UST 1
   3 .Os
   4 .Sh NAME
   5 .Nm ust
   6 .Nd uncomplicated serial terminal
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Op Fl bcehorRsSvX
  10 .Op Fl l Ar line
  11 .Op Fl s Ar # | Ar \-#
  12 .Op Fl i Ar #
  13 .Op Fl D Ar #
  14 .Op Fl d Ar #
  15 .Op Fl m Ar #
  16 .Op Fl t Ar option
  17 .Op Fl T Ar option
  18 .Sh DESCRIPTION
  19 .Nm
  20 is a simple, highly configurable serial terminal with stdin/stdout redirection support.
  21 Unlike other utilities of it's kind,
  22 .Nm
  23 always has all options set \- even the line (device name).
  24 So running ust without any arguments will make it try to open the line specified in
  25 .Ar config.h .
  26 This way the user might set the program up for a specific device without any additional shell scripts or aliases, or just set a different default for a few options according to their preferences.
  27
  28 .Nm
  29 relies on the parent terminal emulator for the actual terminal handling and does not open a secondary buffer, so it may overwrite data in the scrollback buffer.
  30 All messages sent by the program itself (verbose mode info, error messages, exit messages) are directed to stderr (fd 2), this way, one may easily filter the data recieved from the line and messages from the program.
  31 .Sh OPTIONS
  32 .Bl -tag -width ".Fl l , \-line Ar line"
  33 .It Fl l , \-line Ar line
  34 The device name can be input in two formats:
  35 .Ar /dev/cua00
  36 or
  37 .Ar cua00 .
  38 .It Fl s , \-speed Ar # | Ar \-#
  39 Baud rate set by this flag also applies to RX baud rate if that wasn't explicitly set.
  40 .It Fl i , \-rx\-speed Ar #
  41 Separate baud rate for RX line.
  42 .It Fl D , \-data\-bits Ar #
  43 Data bits, may be set to:
  44 .Ar 8 ,
  45 .Ar 7 ,
  46 .Ar 6
  47 or
  48 .Ar 5 .
  49 .It Fl S , \-stop\-bits
  50 .Ar 2
  51 stop bits are set if the flag is toggled on (in case of
  52 .Ar 5
  53 data bits, it's
  54 .Ar 1,5 ,
  55 which just means that the line is in marking state for the duration equal to 1,5 times the standard bit period)
  56 when toggle is off
  57 .Ar 1
  58 stop bit is set in every case.
  59 .It Fl e , \-even
  60 Toggle even parity.
  61 .It Fl o , \-odd
  62 Toggle odd parity (toggling both on disables parity entirely).
  63 .It Fl r , \-hardware\-rts\-cts
  64 Toggle RTS/CTS flow control.
  65 .It Fl R , \-hardware\-dtr\-dsr
  66 Toggle DTR/DSR flow control (setting both hardware flow control options will enable DCD flow control).
  67 .It Fl X , \-software
  68 Toggle XON/XOFF software flow control (can be enabled with hardware flow control simultaneously).
  69 .It Fl d , \-delay Ar #
  70 Delay between sending multiple characters (when redirecting stdin or writing a file) to the line in nanoseconds.
  71 .It Fl m , \-min\-chars Ar #
  72 The minimum of characters to input before they get sent to the line.
  73 .It Fl c , \-canonical
  74 Toggle canonical mode (the ability to edit the input locally before sending it to the line).
  75 .It Fl h , \-echo
  76 Toggle local echo (half\-duplex mode).
  77 .It Fl b , \-backspace
  78 Toggle the backspace key character between
  79 .Ar \&^H
  80 and
  81 .Ar \&^? .
  82 .It Fl v , \-verbose
  83 Toggle verbose output printed to stderr.
  84 .It Fl t , \-translation Ar option
  85 Toggle translation options (to the line) for CR and LF, toggling multiple should be done like so:
  86 .Fl t Ar no\-cr Fl t Ar no\-lf .
  87 .It Fl T , \-input\-translation Ar option
  88 Toggle translation options (from the line) for CR an LF, the options are:
  89 .Pp
  90 .Ar cr\-to\-lf
  91 .Ar cr\-in\-lf
  92 .Ar no\-cr
  93 .Ar lf\-to\-cr
  94 .Ar lf\-in\-cr
  95 .Ar no\-lf
  96 .Pp
  97 .Sh USAGE
  98 If the first character in the input buffer is the special character (tilde by default, can be changed in
  99 .Ar config.h )
 100 it will be escaped and the next character may run a command. The escape character and all subsequent characters
 101 do not get sent to the line.
 102 .Bl -tag -width ".Fl \&. No or Ar \&^D"
 103 .It Ar \&. No or Ar \&^D
 104 Drop the connection and exit.
 105 .It Ar s
 106 Set new baud rate (both TX and RX).
 107 .It Ar d
 108 Set new character transmission delay.
 109 .It Ar b
 110 Toggle the backspace key character.
 111 .It Ar t No | Ar T
 112 Toggle a translation option (output|input).
 113 .It Ar c
 114 Toggle canonical mode.
 115 .It Ar h
 116 Toggle local echo.
 117 .It Ar w
 118 Write a file to the line.
 119 .It Ar p
 120 Send a DCD pulse.
 121 .Sh EXIT STATUS
 122 .Pp
 123 .Nm
 124 exits 2 if some of the user\-set options were invalid (errors caused by trying to aply unsupported options to hardware, eg., setting unsupported baud rate, are considered as such) and exits 1 on general errors.
 125 .Sh EXAMPLES
 126 .Ed
 127 .Pp
 128 Pipe the utility and write output to a file:
 129 .Bd -literal -offset indent
 130 $ printf "00,78,FFFF\\r45\\r" | ust \-19200 \-d 9000000 > wozmon.out
 131 [EOF]
 132 $ cat wozmon.out
 133 00,78,FFFF
 134
 135 00: 54
 136 78: CE
 137 FFFF: 00
 138
 139 45
 140
 141 45: 9A
 142
 143 .Ed
 144 .Pp
 145 .Ed
 146 .Ed
 147 .Pp
 148 Write all output to a single file with keyboard input and no terminal output:
 149 .Bd -literal -offset indent
 150 $ ust > test.log 2>&1
 151 .Ed
 152 .Pp
 153 .Ed
 154 .Sh SEE ALSO
 155 .Xr stty 1 ,
 156 .Xr cu 1 ,
 157 .Xr tip 1
 158 .Sh BUGS
 159 The program is still in development, if you are reading this, know that a lot of functionality does not work or work as expected.