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