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 status of the child process.  Uses the same format as bash
 108 termination on signal termination exit status is 128+n.  The exit status 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 SIGNALS
 194 Upon receiving
 195 .BR SIGUSR1 ,
 196 .B script
 197 immediately flushes the output files.
 198 .PP
 199 .SH ENVIRONMENT
 200 The following environment variable is utilized by
 201 .BR script :
 202 .TP
 203 .B SHELL
 204 If the variable
 205 .B SHELL
 206 exists, the shell forked by
 207 .B script
 208 will be that shell.  If
 209 .B SHELL
 210 is not set, the Bourne shell is assumed.  (Most shells set this variable
 211 automatically).
 212 .SH NOTES
 213 The script ends when the forked shell exits (a
 214 .I control-D
 215 for the Bourne shell
 216 .RB ( sh (1p)),
 217 and
 218 .IR exit ,
 219 .I logout
 220 or
 221 .I control-d
 222 (if
 223 .I ignoreeof
 224 is not set) for the
 225 C-shell,
 226 .BR csh (1)).
 227 .PP
 228 Certain interactive commands, such as
 229 .BR vi (1),
 230 create garbage in the typescript file.
 231 .B script
 232 works best with commands that do not manipulate the screen, the results are
 233 meant to emulate a hardcopy terminal.
 234 .PP
 235 It is not recommended to run
 236 .B script
 237 in non-interactive shells.  The inner shell of
 238 .B script
 239 is always interactive, and this could lead to unexpected results.  If you use
 240 .B script
 241 in the shell initialization file, you have to avoid entering an infinite
 242 loop.  You can use for example the \fB\%.profile\fR file, which is read
 243 by login shells only:
 244 .RS
 245 .RE
 246 .sp
 247 .na
 248 .RS
 249 .nf
 250 if test \-t 0 ; then
 251     script
 252     exit
 253 fi
 254 .fi
 255 .RE
 256 .ad
 257 .PP
 258 You should also avoid use of script in command pipes, as
 259 .B script
 260 can read more input than you would expect.
 261 .PP
 262 .SH HISTORY
 263 The
 264 .B script
 265 command appeared in 3.0BSD.
 266 .SH BUGS
 267 .B script
 268 places
 269 .I everything
 270 in the log file, including linefeeds and backspaces.  This is not what the
 271 naive user expects.
 272 .PP
 273 .B script
 274 is primarily designed for interactive terminal sessions.  When stdin
 275 is not a terminal (for example: \fBecho foo | script\fR), then the session
 276 can hang, because the interactive shell within the script session misses EOF and
 277 .B script
 278 has no clue when to close the session.  See the \fBNOTES\fR section for more information.
 279 .SH SEE ALSO
 280 .BR csh (1)
 281 (for the
 282 .I history
 283 mechanism),
 284 .BR scriptreplay (1),
 285 .BR scriptlive (1),
 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 .