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" "June 2014" "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\-\-return\fR
  92 Return the exit code of the child process.  Uses the same format as bash
  93 termination on signal termination exit code is 128+n.  The exit code of
  94 the child process is always stored in type script file too.
  95 .TP
  96 \fB\-f\fR, \fB\-\-flush\fR
  97 Flush output after each write.  This is nice for telecooperation: one person
  98 does `mkfifo foo; script -f foo', and another can supervise real-time what is
  99 being done using `cat foo'.
 100 .TP
 101 \fB\-\-force\fR
 102 Allow the default output destination, i.e. the typescript file, to be a hard
 103 or symbolic link.  The command will follow a symbolic link.
 104 .TP
 105 \fB\-B\fR, \fB\-\-log\-io\fR \fIfile\fR
 106 Log input and output to the same
 107 \fIfile\fR.  Note, this option makes sense only if \fB\-\-log\-timing\fR is
 108 also specified, otherwise it's impossible to separate output and input streams from
 109 the log \fIfile\fR.
 110 .TP
 111 \fB\-I\fR, \fB\-\-log\-in\fR \fIfile\fR
 112 Log input to the \fIfile\fR.  The log output is disabled if only \fB\-\-log\-in\fR
 113 specified.
 114 .sp
 115 Use this logging functionality carefully as it logs all input, including input
 116 when terminal has disabled echo flag (for example it log passwords in the input).
 117 .TP
 118 \fB\-O\fR, \fB\-\-log\-out\fR \fIfile\fR
 119 Log output to the \fIfile\fR. The default is to log output to the file with
 120 name 'typescript' if the option \fB\-\-log\-out\fR or \fB\-\-log\-in\fR is not
 121 given.  The log output is disabled if only \fB\-\-log\-in\fR specified.
 122 .TP
 123 \fB\-T\fR, \fB\-\-log\-timing\fR \fIfile\fR
 124 Log timing information to the \fIfile\fR. Two timing file formats are supporte
 125 now.  The classic format is used when only one stream (input or output) logging
 126 is enabled. The multi-stream format is used on \fB\-\-log\-io\fR or when
 127 \fB\-\-log\-in\fR and \fB\-\-log\-out\fR are used together.
 128 See also \fB\-\-logging\-format\fR.
 129 .TP
 130 \fB\-m\fR, \fB\-\-logging\-format\fR \fIformat\fR
 131 Force use 'advanced' or 'classic' format.  The default is the classic format to
 132 log only output and the advanced format when input as well as output logging is
 133 requested.
 134 .sp
 135 .RS
 136 .B Classic format
 137 .PP
 138 The log contains two fields, separated by a space.  The first
 139 field indicates how much time elapsed since the previous output.  The second
 140 field indicates how many characters were output this time.
 141 .sp
 142 .B Advanced (multi-stream) format
 143 .PP
 144 The first field is entry type itentifier ('I'nput, 'O'utput, 'H'eader, 'S'ignal).
 145 The socond field is how much time elapsed since the previous entry, and rest of the entry is type specific data.
 146 .RE
 147 .TP
 148 \fB\-o\fR, \fB\-\-output-limit\fR \fIsize\fR
 149 Limit the size of the typescript and timing files to
 150 .I size
 151 and stop the child process after this size is exceeded.  The calculated
 152 file size does not include the start and done messages that the
 153 .B script
 154 command prepends and appends to the child process output.
 155 Due to buffering, the resulting output file might be larger than the specified value.
 156 .TP
 157 \fB\-q\fR, \fB\-\-quiet\fR
 158 Be quiet (do not write start and done messages to standard output).
 159 .TP
 160 \fB\-t\fR[\fIfile\fR], \fB\-\-timing\fR[=\fIfile\fR]
 161 Output timing data to standard error, or to
 162 .I file
 163 when given.  This option is deprecated in favour of \fB\-\-log\-timing\fR where
 164 the \fIfile\fR argument is not optional.
 165 .TP
 166 \fB\-V\fR, \fB\-\-version\fR
 167 Display version information and exit.
 168 .TP
 169 \fB\-h\fR, \fB\-\-help\fR
 170 Display help text and exit.
 171 .SH NOTES
 172 The script ends when the forked shell exits (a
 173 .I control-D
 174 for the Bourne shell
 175 .RB ( sh (1p)),
 176 and
 177 .IR exit ,
 178 .I logout
 179 or
 180 .I control-d
 181 (if
 182 .I ignoreeof
 183 is not set) for the
 184 C-shell,
 185 .BR csh (1)).
 186 .PP
 187 Certain interactive commands, such as
 188 .BR vi (1),
 189 create garbage in the typescript file.
 190 .B script
 191 works best with commands that do not manipulate the screen, the results are
 192 meant to emulate a hardcopy terminal.
 193 .PP
 194 It is not recommended to run
 195 .B script
 196 in non-interactive shells.  The inner shell of
 197 .B script
 198 is always interactive, and this could lead to unexpected results.  If you use
 199 .B script
 200 in the shell initialization file, you have to avoid entering an infinite
 201 loop.  You can use for example the \fB\%.profile\fR file, which is read
 202 by login shells only:
 203 .RS
 204 .RE
 205 .sp
 206 .na
 207 .RS
 208 .nf
 209 if test -t 0 ; then
 210     script
 211     exit
 212 fi
 213 .fi
 214 .RE
 215 .ad
 216 .PP
 217 You should also avoid use of script in command pipes, as
 218 .B script
 219 can read more input than you would expect.
 220 .PP
 221 .SH ENVIRONMENT
 222 The following environment variable is utilized by
 223 .BR script :
 224 .TP
 225 .B SHELL
 226 If the variable
 227 .B SHELL
 228 exists, the shell forked by
 229 .B script
 230 will be that shell.  If
 231 .B SHELL
 232 is not set, the Bourne shell is assumed.  (Most shells set this variable
 233 automatically).
 234 .SH SEE ALSO
 235 .BR csh (1)
 236 (for the
 237 .I history
 238 mechanism),
 239 .BR scriptreplay (1)
 240 .SH HISTORY
 241 The
 242 .B script
 243 command appeared in 3.0BSD.
 244 .SH BUGS
 245 .B script
 246 places
 247 .I everything
 248 in the log file, including linefeeds and backspaces.  This is not what the
 249 naive user expects.
 250 .PP
 251 .B script
 252 is primarily designed for interactive terminal sessions.  When stdin
 253 is not a terminal (for example: \fBecho foo | script\fR), then the session
 254 can hang, because the interactive shell within the script session misses EOF and
 255 .B script
 256 has no clue when to close the session.  See the \fBNOTES\fR section for more information.
 257 .SH AVAILABILITY
 258 The script command is part of the util-linux package and is available from
 259 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 260 Linux Kernel Archive
 261 .UE .