term-utils/script.1

   1 .\" Copyright (c) 1980, 1990 Regents of the University of California.
   2 .\" 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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)script.1    6.5 (Berkeley) 7/27/91
  33 .\"
  34 .TH SCRIPT "1" "October 2019" "util-linux" "User Commands"
  35 .SH NAME
  36 script \- make typescript of terminal session
  37 .SH SYNOPSIS
  38 .B script
  39 [options]
  40 .RI [ file ]
  41 .SH DESCRIPTION
  42 .B script
  43 makes a typescript of everything on your terminal session.  The terminal
  44 data are stored in raw form to the log file and information about timing
  45 to another (optional) structured log file.  The timing log file is necessary to replay
  46 the session later by
  47 .B scriptreplay (1)
  48 and to store additional information about the session.
  49 .PP
  50 Since version 2.35
  51 .B script
  52 supports multiple streams and allows to log input and output to separate
  53 files or all the one file.  This version also supports new timing file
  54 which records additional information.  The command
  55 .B scriptreplay \-\-summary
  56 then provides all the information.
  57
  58 .PP
  59 If the argument
  60 .I file
  61 or option \fB\-\-log\-out\fR \fIfile\fR is given,
  62 .B script
  63 saves the dialogue in this
  64 .IR file .
  65 If no filename is given, the dialogue is saved in the file
  66 .BR typescript .
  67 .PP
  68 Note that log input by \fB\-\-log\-in\fR or \fB\-\-log\-io\fR may be security
  69 sensitive operation as the log file contains all terminal session input (it
  70 means also passwords) independently on the terminal echo flag setting.
  71 .SH OPTIONS
  72 Below, the \fIsize\fR argument may be followed by the multiplicative
  73 suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB
  74 (the "iB" is optional, e.g., "K" has the same meaning as "KiB"), or the suffixes
  75 KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
  76 .TP
  77 \fB\-a\fR, \fB\-\-append\fR
  78 Append the output to
  79 .I file
  80 or to
  81 .BR typescript ,
  82 retaining the prior contents.
  83 .TP
  84 \fB\-c\fR, \fB\-\-command\fR \fIcommand\fR
  85 Run the
  86 .I command
  87 rather than an interactive shell.  This makes it easy for a script to capture
  88 the output of a program that behaves differently when its stdout is not a
  89 tty.
  90 .TP
  91 \fB\-E\fR, \fB\-\-echo\fR \fIwhen\fR
  92 This option controls the ECHO flag for pseudoterminal within the session.  The
  93 supported modes are
  94 .IR always ,
  95 .IR never ,
  96 or
  97 .IR auto .
  98 The default is
  99 .I auto
 100 -- in this case, ECHO is disabled if the current standard input is a
 101 terminal to avoid double-echo, and enabled if standard input is not terminal
 102 (for example pipe:
 103 .BR "echo date | script" )
 104 to avoid missing input in the session log.
 105 .TP
 106 \fB\-e\fR, \fB\-\-return\fR
 107 Return the exit code of the child process.  Uses the same format as bash
 108 termination on signal termination exit code is 128+n.  The exit code of
 109 the child process is always stored in type script file too.
 110 .TP
 111 \fB\-f\fR, \fB\-\-flush\fR
 112 Flush output after each write.  This is nice for telecooperation: one person
 113 does `mkfifo foo; script \-f foo', and another can supervise real-time what is
 114 being done using `cat foo'.  Note that flush has an impact on performance, it's
 115 possible to use SIGUSR1 to flush logs on demand.
 116 .TP
 117 \fB\-\-force\fR
 118 Allow the default output file
 119 .B typescript
 120 to be a hard or symbolic link.  The command will follow a symbolic link.
 121 .TP
 122 \fB\-B\fR, \fB\-\-log\-io\fR \fIfile\fR
 123 Log input and output to the same
 124 \fIfile\fR.  Note, this option makes sense only if \fB\-\-log\-timing\fR is
 125 also specified, otherwise it's impossible to separate output and input streams from
 126 the log \fIfile\fR.
 127 .TP
 128 \fB\-I\fR, \fB\-\-log\-in\fR \fIfile\fR
 129 Log input to the \fIfile\fR.  The log output is disabled if only \fB\-\-log\-in\fR
 130 specified.
 131 .sp
 132 Use this logging functionality carefully as it logs all input, including input
 133 when terminal has disabled echo flag (for example password inputs).
 134 .TP
 135 \fB\-O\fR, \fB\-\-log\-out\fR \fIfile\fR
 136 Log output to the \fIfile\fR.  The default is to log output to the file with
 137 name
 138 .B typescript
 139 if the option \fB\-\-log\-out\fR or \fB\-\-log\-in\fR is not given.  The log
 140 output is disabled if only \fB\-\-log\-in\fR specified.
 141 .TP
 142 \fB\-T\fR, \fB\-\-log\-timing\fR \fIfile\fR
 143 Log timing information to the \fIfile\fR.  Two timing file formats are supported
 144 now.  The classic format is used when only one stream (input or output) logging
 145 is enabled.  The multi-stream format is used on \fB\-\-log\-io\fR or when
 146 \fB\-\-log\-in\fR and \fB\-\-log\-out\fR are used together.
 147 See also \fB\-\-logging\-format\fR.
 148 .TP
 149 \fB\-m\fR, \fB\-\-logging\-format\fR \fIformat\fR
 150 Force use
 151 .I advanced
 152 or
 153 .I classic
 154 format.  The default is the classic format to log only output and the
 155 advanced format when input as well as output logging is requested.
 156 .sp
 157 .RS
 158 .B Classic format
 159 .PP
 160 The log contains two fields, separated by a space.  The first
 161 field indicates how much time elapsed since the previous output.  The second
 162 field indicates how many characters were output this time.
 163 .sp
 164 .B Advanced (multi-stream) format
 165 .PP
 166 The first field is entry type itentifier ('I'nput, 'O'utput, 'H'eader, 'S'ignal).
 167 The socond field is how much time elapsed since the previous entry, and rest of the entry is type specific data.
 168 .RE
 169 .TP
 170 \fB\-o\fR, \fB\-\-output-limit\fR \fIsize\fR
 171 Limit the size of the typescript and timing files to
 172 .I size
 173 and stop the child process after this size is exceeded.  The calculated
 174 file size does not include the start and done messages that the
 175 .B script
 176 command prepends and appends to the child process output.
 177 Due to buffering, the resulting output file might be larger than the specified value.
 178 .TP
 179 \fB\-q\fR, \fB\-\-quiet\fR
 180 Be quiet (do not write start and done messages to standard output).
 181 .TP
 182 \fB\-t\fR[\fIfile\fR], \fB\-\-timing\fR[=\fIfile\fR]
 183 Output timing data to standard error, or to
 184 .I file
 185 when given.  This option is deprecated in favour of \fB\-\-log\-timing\fR where
 186 the \fIfile\fR argument is not optional.
 187 .TP
 188 \fB\-V\fR, \fB\-\-version\fR
 189 Display version information and exit.
 190 .TP
 191 \fB\-h\fR, \fB\-\-help\fR
 192 Display help text and exit.
 193 .SH NOTES
 194 The script ends when the forked shell exits (a
 195 .I control-D
 196 for the Bourne shell
 197 .RB ( sh (1p)),
 198 and
 199 .IR exit ,
 200 .I logout
 201 or
 202 .I control-d
 203 (if
 204 .I ignoreeof
 205 is not set) for the
 206 C-shell,
 207 .BR csh (1)).
 208 .PP
 209 Certain interactive commands, such as
 210 .BR vi (1),
 211 create garbage in the typescript file.
 212 .B script
 213 works best with commands that do not manipulate the screen, the results are
 214 meant to emulate a hardcopy terminal.
 215 .PP
 216 It is not recommended to run
 217 .B script
 218 in non-interactive shells.  The inner shell of
 219 .B script
 220 is always interactive, and this could lead to unexpected results.  If you use
 221 .B script
 222 in the shell initialization file, you have to avoid entering an infinite
 223 loop.  You can use for example the \fB\%.profile\fR file, which is read
 224 by login shells only:
 225 .RS
 226 .RE
 227 .sp
 228 .na
 229 .RS
 230 .nf
 231 if test \-t 0 ; then
 232     script
 233     exit
 234 fi
 235 .fi
 236 .RE
 237 .ad
 238 .PP
 239 You should also avoid use of script in command pipes, as
 240 .B script
 241 can read more input than you would expect.
 242 .PP
 243 .SH SIGNALS
 244 Upon receiving
 245 .BR SIGUSR1 ,
 246 .B script
 247 immediately flushes the output files.
 248 .PP
 249 .SH ENVIRONMENT
 250 The following environment variable is utilized by
 251 .BR script :
 252 .TP
 253 .B SHELL
 254 If the variable
 255 .B SHELL
 256 exists, the shell forked by
 257 .B script
 258 will be that shell.  If
 259 .B SHELL
 260 is not set, the Bourne shell is assumed.  (Most shells set this variable
 261 automatically).
 262 .SH SEE ALSO
 263 .BR csh (1)
 264 (for the
 265 .I history
 266 mechanism),
 267 .BR scriptreplay (1),
 268 .BR scriptlive (1),
 269 .SH HISTORY
 270 The
 271 .B script
 272 command appeared in 3.0BSD.
 273 .SH BUGS
 274 .B script
 275 places
 276 .I everything
 277 in the log file, including linefeeds and backspaces.  This is not what the
 278 naive user expects.
 279 .PP
 280 .B script
 281 is primarily designed for interactive terminal sessions.  When stdin
 282 is not a terminal (for example: \fBecho foo | script\fR), then the session
 283 can hang, because the interactive shell within the script session misses EOF and
 284 .B script
 285 has no clue when to close the session.  See the \fBNOTES\fR section for more information.
 286 .SH AVAILABILITY
 287 The script command is part of the util-linux package and is available from
 288 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 289 Linux Kernel Archive
 290 .UE .