usr.bin/script/script.1

   1 .\" Copyright (c) 1980, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)script.1    8.1 (Berkeley) 6/6/93
  29 .\"
  30 .Dd October 26, 2022
  31 .Dt SCRIPT 1
  32 .Os
  33 .Sh NAME
  34 .Nm script
  35 .Nd make typescript of terminal session
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl aeFfkqr
  39 .Op Fl t Ar time
  40 .Op Ar file Op Ar command ...
  41 .Nm
  42 .Fl p
  43 .Op Fl deq
  44 .Op Fl T Ar fmt
  45 .Op Ar file
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 utility makes a typescript of everything printed on your terminal.
  50 It is useful for students who need a hardcopy record of an interactive
  51 session as proof of an assignment, as the typescript file
  52 can be printed out later with
  53 .Xr lpr 1 .
  54 .Pp
  55 If the argument
  56 .Ar file
  57 is given,
  58 .Nm
  59 saves all dialogue in
  60 .Ar file .
  61 If no file name is given, the typescript is saved in the file
  62 .Pa typescript .
  63 .Pp
  64 If the argument
  65 .Ar command
  66 is given,
  67 .Nm
  68 will run the specified command with an optional argument vector
  69 instead of an interactive shell.
  70 .Pp
  71 The following options are available:
  72 .Bl -tag -width "-F pipe"
  73 .It Fl a
  74 Append the output to
  75 .Ar file
  76 or
  77 .Pa typescript ,
  78 retaining the prior contents.
  79 .It Fl d
  80 When playing back a session with the
  81 .Fl p
  82 flag, do not sleep between records when playing back a timestamped session.
  83 .It Fl e
  84 Accepted for compatibility with
  85 .Em util-linux
  86 .Nm .
  87 The child command exit status is always the exit status of
  88 .Nm .
  89 .It Fl F
  90 Immediately flush output after each write.
  91 This will allow a user to create a named pipe using
  92 .Xr mkfifo 1
  93 and another user may watch the live session using a utility like
  94 .Xr cat 1 .
  95 .It Fl f
  96 Create
  97 .Ar file.filemon
  98 or
  99 .Pa typescript.filemon
 100 using
 101 .Xr filemon 4 .
 102 .It Fl k
 103 Log keys sent to the program as well as output.
 104 .It Fl p
 105 Play back a session recorded with the
 106 .Fl r
 107 flag in real time.
 108 .It Fl q
 109 Run in quiet mode, omit the start, stop and command status messages.
 110 .It Fl r
 111 Record a session with input, output, and timestamping.
 112 .It Fl t Ar time
 113 Specify the interval at which the script output file will be flushed
 114 to disk, in seconds.
 115 A value of 0
 116 causes
 117 .Nm
 118 to flush after every character I/O event.
 119 The default interval is
 120 30 seconds.
 121 .It Fl T Ar fmt
 122 Implies
 123 .Fl p ,
 124 but just reports the time-stamp of each output.
 125 This is very useful for assessing the timing of events.
 126 .Pp
 127 If
 128 .Ar fmt
 129 does not contain any
 130 .Ql %
 131 characters, it indicates the default format:
 132 .Ql %n@ %s [%Y-%m-%d %T]%n ,
 133 which is useful for both tools and humans to read, should be used.
 134 Note that time-stamps will only be output when different from the
 135 previous one.
 136 .El
 137 .Pp
 138 The script ends when the forked shell (or command) exits (a
 139 .Em control-D
 140 to exit
 141 the Bourne shell
 142 .Pf ( Xr sh 1 ) ,
 143 and
 144 .Em exit ,
 145 .Em logout
 146 or
 147 .Em control-D
 148 (if
 149 .Em ignoreeof
 150 is not set) for the
 151 C-shell,
 152 .Xr csh 1 ) .
 153 .Pp
 154 Certain interactive commands, such as
 155 .Xr vi 1 ,
 156 create garbage in the typescript file.
 157 The
 158 .Nm
 159 utility works best with commands that do not manipulate the screen.
 160 The results are meant to emulate a hardcopy terminal, not an addressable one.
 161 .Sh ENVIRONMENT
 162 The following environment variables are utilized by
 163 .Nm :
 164 .Bl -tag -width SCRIPT
 165 .It Ev SCRIPT
 166 The
 167 .Ev SCRIPT
 168 environment variable is added to the sub-shell.
 169 If
 170 .Ev SCRIPT
 171 already existed in the users environment,
 172 its value is overwritten within the sub-shell.
 173 The value of
 174 .Ev SCRIPT
 175 is the name of the
 176 .Ar typescript
 177 file.
 178 .It Ev SHELL
 179 If the variable
 180 .Ev SHELL
 181 exists, the shell forked by
 182 .Nm
 183 will be that shell.
 184 If
 185 .Ev SHELL
 186 is not set, the Bourne shell
 187 is assumed.
 188 .Pq Most shells set this variable automatically .
 189 .El
 190 .Sh EXAMPLES
 191 Record a simple
 192 .Xr csh 1
 193 session with no additional details like input, output, and timestamping:
 194 .Bd -literal -offset indent
 195 $ SHELL=/bin/csh script
 196 Script started, output file is typescript
 197 % date
 198 Tue Jan  5 15:08:10 UTC 2021
 199 % exit
 200 exit
 201
 202 Script done, output file is typescript
 203 .Ed
 204 .Pp
 205 Now, replay the session recorded in the previous example:
 206 .Bd -literal -offset indent
 207 $ cat ./typescript
 208 Script started on Tue Jan  5 15:08:08 2021
 209 % date
 210 Tue Jan  5 15:08:10 UTC 2021
 211 % exit
 212 exit
 213
 214 Script done on Tue Jan  5 15:08:13 2021
 215 .Ed
 216 .Pp
 217 Record a
 218 .Xr csh 1
 219 session, but this time with additional details like timestamping:
 220 .Bd -literal -offset indent
 221 $ SHELL=/bin/csh script -r
 222 Script started, output file is typescript
 223 % date
 224 Tue Jan  5 15:17:11 UTC 2021
 225 % exit
 226 exit
 227
 228 Script done, output file is typescript
 229 .Ed
 230 .Pp
 231 In order to replay a sessions recorded with the
 232 .Fl r
 233 flag, it is necessary to specify
 234 .Fl p
 235 .Po
 236 .Xr cat 1
 237 will not work because of all the aditional information stored in the session file
 238 .Pc .
 239 Also, let us use
 240 .Fl d
 241 to print the whole session at once:
 242 .Bd -literal -offset indent
 243 $ script -dp ./typescript
 244 Script started on Tue Jan  5 15:17:09 2021
 245 % date
 246 Tue Jan  5 15:17:11 UTC 2021
 247 % exit
 248 exit
 249
 250 Script done on Tue Jan  5 15:17:14 2021
 251 .Ed
 252 .Sh SEE ALSO
 253 .Xr csh 1
 254 .Po
 255 for the
 256 .Em history
 257 mechanism
 258 .Pc ,
 259 .Xr filemon 4
 260 .Sh HISTORY
 261 The
 262 .Nm
 263 command appeared in
 264 .Bx 3.0 .
 265 .Pp
 266 The
 267 .Fl d ,
 268 .Fl p
 269 and
 270 .Fl r
 271 options first appeared in
 272 .Nx 2.0
 273 and were ported to
 274 .Fx 9.2 .
 275 .Sh BUGS
 276 The
 277 .Nm
 278 utility places
 279 .Sy everything
 280 in the log file, including linefeeds and backspaces.
 281 This is not what the naive user expects.
 282 .Pp
 283 It is not possible to specify a command without also naming the script file
 284 because of argument parsing compatibility issues.
 285 .Pp
 286 When running in
 287 .Fl k
 288 mode, echo cancelling is far from ideal.
 289 The slave terminal mode is checked
 290 for ECHO mode to check when to avoid manual echo logging.
 291 This does not
 292 work when the terminal is in a raw mode where
 293 the program being run is doing manual echo.
 294 .Pp
 295 If
 296 .Nm
 297 reads zero bytes from the terminal, it switches to a mode when it
 298 only attempts to read
 299 once a second until there is data to read.
 300 This prevents
 301 .Nm
 302 from spinning on zero-byte reads, but might cause a 1-second delay in
 303 processing of user input.