manual/util-linux/original/man1/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 .BR 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 the logging of 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 .IR typescript .
  67 .PP
  68 Note that logging input using \fB\-\-log\-in\fR or \fB\-\-log\-io\fR
  69 may record security-sensitive information
  70 as the log file contains all terminal session input
  71 (e.g., passwords)
  72 independently of the terminal echo flag setting.
  73 .SH OPTIONS
  74 Below, the \fIsize\fR argument may be followed by the multiplicative
  75 suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB
  76 (the "iB" is optional, e.g., "K" has the same meaning as "KiB"), or the suffixes
  77 KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
  78 .TP
  79 \fB\-a\fR, \fB\-\-append\fR
  80 Append the output to
  81 .I file
  82 or to
  83 .IR typescript ,
  84 retaining the prior contents.
  85 .TP
  86 \fB\-c\fR, \fB\-\-command\fR \fIcommand\fR
  87 Run the
  88 .I command
  89 rather than an interactive shell.  This makes it easy for a script to capture
  90 the output of a program that behaves differently when its stdout is not a
  91 tty.
  92 .TP
  93 \fB\-E\fR, \fB\-\-echo\fR \fIwhen\fR
  94 This option controls the ECHO flag for the pseudoterminal within the session.
  95 The supported modes are
  96 .IR always ,
  97 .IR never ,
  98 or
  99 .IR auto .
 100 The default is
 101 .I auto
 102 -- in this case, ECHO is disabled if the current standard input is a
 103 terminal iin order to avoid double-echo,
 104 and enabled if standard input is not a terminal
 105 (for example pipe:
 106 .BR "echo date | script" )
 107 to avoid missing input in the session log.
 108 .TP
 109 \fB\-e\fR, \fB\-\-return\fR
 110 Return the exit status of the child process.  Uses the same format as bash
 111 termination on signal termination
 112 (i.e., exit status is 128 + the signal number).  The exit status of
 113 the child process is always stored in the type script file too.
 114 .TP
 115 \fB\-f\fR, \fB\-\-flush\fR
 116 Flush output after each write.  This is nice for telecooperation: one person
 117 does `mkfifo foo; script \-f foo',
 118 and another can supervise in real-time what is
 119 being done using `cat foo'.  Note that flush has an impact on performance; it's
 120 possible to use SIGUSR1 to flush logs on demand.
 121 .TP
 122 \fB\-\-force\fR
 123 Allow the default output file
 124 .I typescript
 125 to be a hard or symbolic link.  The command will follow a symbolic link.
 126 .TP
 127 \fB\-B\fR, \fB\-\-log\-io\fR \fIfile\fR
 128 Log input and output to the same
 129 \fIfile\fR.  Note, this option makes sense only if \fB\-\-log\-timing\fR is
 130 also specified, otherwise it's impossible to separate output and input streams from
 131 the log \fIfile\fR.
 132 .TP
 133 \fB\-I\fR, \fB\-\-log\-in\fR \fIfile\fR
 134 Log input to the \fIfile\fR.  The log output is disabled if only \fB\-\-log\-in\fR
 135 specified.
 136 .sp
 137 Use this logging functionality carefully as it logs all input, including input
 138 when terminal has disabled echo flag (for example, password inputs).
 139 .TP
 140 \fB\-O\fR, \fB\-\-log\-out\fR \fIfile\fR
 141 Log output to the \fIfile\fR.  The default is to log output to the file with
 142 name
 143 .I typescript
 144 if the option \fB\-\-log\-out\fR or \fB\-\-log\-in\fR is not given.  The log
 145 output is disabled if only \fB\-\-log\-in\fR specified.
 146 .TP
 147 \fB\-T\fR, \fB\-\-log\-timing\fR \fIfile\fR
 148 Log timing information to the \fIfile\fR.  Two timing file formats are supported
 149 now.  The classic format is used when only one stream (input or output) logging
 150 is enabled.  The multi-stream format is used on \fB\-\-log\-io\fR or when
 151 \fB\-\-log\-in\fR and \fB\-\-log\-out\fR are used together.
 152 See also \fB\-\-logging\-format\fR.
 153 .TP
 154 \fB\-m\fR, \fB\-\-logging\-format\fR \fIformat\fR
 155 Force use of
 156 .I advanced
 157 or
 158 .I classic
 159 format.  The default is the classic format to log only output and the
 160 advanced format when input as well as output logging is requested.
 161 .sp
 162 .RS
 163 .B Classic format
 164 .PP
 165 The log contains two fields, separated by a space.  The first
 166 field indicates how much time elapsed since the previous output.  The second
 167 field indicates how many characters were output this time.
 168 .sp
 169 .B Advanced (multi-stream) format
 170 .PP
 171 The first field is an entry type identifier
 172 ('I'nput, 'O'utput, 'H'eader, 'S'ignal).
 173 The socond field is how much time elapsed since the previous entry,
 174 and the rest of the entry is type-specific data.
 175 .RE
 176 .TP
 177 \fB\-o\fR, \fB\-\-output-limit\fR \fIsize\fR
 178 Limit the size of the typescript and timing files to
 179 .I size
 180 and stop the child process after this size is exceeded.  The calculated
 181 file size does not include the start and done messages that the
 182 .B script
 183 command prepends and appends to the child process output.
 184 Due to buffering, the resulting output file might be larger than the specified value.
 185 .TP
 186 \fB\-q\fR, \fB\-\-quiet\fR
 187 Be quiet (do not write start and done messages to standard output).
 188 .TP
 189 \fB\-t\fR[\fIfile\fR], \fB\-\-timing\fR[=\fIfile\fR]
 190 Output timing data to standard error, or to
 191 .I file
 192 when given.  This option is deprecated in favour of \fB\-\-log\-timing\fR where
 193 the \fIfile\fR argument is not optional.
 194 .TP
 195 \fB\-V\fR, \fB\-\-version\fR
 196 Display version information and exit.
 197 .TP
 198 \fB\-h\fR, \fB\-\-help\fR
 199 Display help text and exit.
 200 .SH SIGNALS
 201 Upon receiving
 202 .BR SIGUSR1 ,
 203 .B script
 204 immediately flushes the output files.
 205 .SH ENVIRONMENT
 206 The following environment variable is utilized by
 207 .BR script :
 208 .TP
 209 .B SHELL
 210 If the variable
 211 .B SHELL
 212 exists, the shell forked by
 213 .B script
 214 will be that shell.  If
 215 .B SHELL
 216 is not set, the Bourne shell is assumed.  (Most shells set this variable
 217 automatically).
 218 .SH NOTES
 219 The script ends when the forked shell exits (a
 220 .I control-D
 221 for the Bourne shell
 222 .RB ( sh (1p)),
 223 and
 224 .IR exit ,
 225 .I logout
 226 or
 227 .I control-d
 228 (if
 229 .I ignoreeof
 230 is not set) for the
 231 C-shell,
 232 .BR csh (1)).
 233 .PP
 234 Certain interactive commands, such as
 235 .BR vi (1),
 236 create garbage in the typescript file.
 237 .B script
 238 works best with commands that do not manipulate the screen, the results are
 239 meant to emulate a hardcopy terminal.
 240 .PP
 241 It is not recommended to run
 242 .B script
 243 in non-interactive shells.  The inner shell of
 244 .B script
 245 is always interactive, and this could lead to unexpected results.  If you use
 246 .B script
 247 in the shell initialization file, you have to avoid entering an infinite
 248 loop.  You can use for example the \fB\%.profile\fR file, which is read
 249 by login shells only:
 250 .sp
 251 .na
 252 .RS
 253 .nf
 254 if test \-t 0 ; then
 255     script
 256     exit
 257 fi
 258 .fi
 259 .RE
 260 .ad
 261 .PP
 262 You should also avoid use of
 263 .B script
 264 in command pipes, as
 265 .B script
 266 can read more input than you would expect.
 267 .SH HISTORY
 268 The
 269 .B script
 270 command appeared in 3.0BSD.
 271 .SH BUGS
 272 .B script
 273 places
 274 .I everything
 275 in the log file, including linefeeds and backspaces.  This is not what the
 276 naive user expects.
 277 .PP
 278 .B script
 279 is primarily designed for interactive terminal sessions.  When stdin
 280 is not a terminal (for example: \fBecho foo | script\fR), then the session
 281 can hang, because the interactive shell within the script session misses EOF and
 282 .B script
 283 has no clue when to close the session.  See the \fBNOTES\fR section for more information.
 284 .SH SEE ALSO
 285 .BR csh (1)
 286 (for the
 287 .I history
 288 mechanism),
 289 .BR scriptreplay (1),
 290 .BR scriptlive (1),
 291 .SH AVAILABILITY
 292 The script command is part of the util-linux package and is available from
 293 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 294 Linux Kernel Archive
 295 .UE .