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 displayed on your terminal.  It is useful for
  44 students who need a hardcopy record of an interactive session as proof of an
  45 assignment, as the typescript file can be printed out later with
  46 .BR lpr (1).
  47 Since version 2.35
  48 .B script
  49 supports multiple streams and allows to log input and output to separate
  50 files or all the one file.
  51 .PP
  52 If the argument
  53 .I file
  54 or option \fB\-\-log\-out\fR \fIfile\fR is given,
  55 .B script
  56 saves the dialogue in this
  57 .IR file .
  58 If no filename is given, the dialogue is saved in the file
  59 .BR typescript .
  60 .SH OPTIONS
  61 Below, the \fIsize\fR argument may be followed by the multiplicative
  62 suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB
  63 (the "iB" is optional, e.g. "K" has the same meaning as "KiB"), or the suffixes
  64 KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
  65 .TP
  66 \fB\-a\fR, \fB\-\-append\fR
  67 Append the output to
  68 .I file
  69 or to
  70 .BR typescript ,
  71 retaining the prior contents.
  72 .TP
  73 \fB\-c\fR, \fB\-\-command\fR \fIcommand\fR
  74 Run the
  75 .I command
  76 rather than an interactive shell.  This makes it easy for a script to capture
  77 the output of a program that behaves differently when its stdout is not a
  78 tty.
  79 .TP
  80 \fB\-e\fR, \fB\-\-return\fR
  81 Return the exit code of the child process.  Uses the same format as bash
  82 termination on signal termination exit code is 128+n.  The exit code of
  83 the child process is always stored in type script file too.
  84 .TP
  85 \fB\-f\fR, \fB\-\-flush\fR
  86 Flush output after each write.  This is nice for telecooperation: one person
  87 does `mkfifo foo; script -f foo', and another can supervise real-time what is
  88 being done using `cat foo'.
  89 .TP
  90 \fB\-\-force\fR
  91 Allow the default output destination, i.e. the typescript file, to be a hard
  92 or symbolic link.  The command will follow a symbolic link.
  93 .TP
  94 \fB\-B\fR, \fB\-\-log\-io\fR \fIfile\fR
  95 Log input and output to the same
  96 \fIfile\fR.  Note, this option makes sense only if \fB\-\-log\-timing\fR is
  97 also specified, otherwise it's impossible to separate output and input streams from
  98 the log \fIfile\fR.
  99 .TP
 100 \fB\-I\fR, \fB\-\-log\-in\fR \fIfile\fR
 101 Log input to the \fIfile\fR.  The log output is disabled if only \fB\-\-log\-in\fR
 102 specified.
 103 .sp
 104 Use this logging functionality carefully as it logs all input, including input
 105 when terminal has disabled echo flag (for example it log passwords in the input).
 106 .TP
 107 \fB\-O\fR, \fB\-\-log\-out\fR \fIfile\fR
 108 Log output to the \fIfile\fR. The default is to log output to the file with
 109 name 'typescript' if the option \fB\-\-log\-out\fR or \fB\-\-log\-in\fR is not
 110 given.  The log output is disabled if only \fB\-\-log\-in\fR specified.
 111 .TP
 112 \fB\-T\fR, \fB\-\-log\-timing\fR \fIfile\fR
 113 Log timing information to the \fIfile\fR. Two timing file formats are supporte
 114 now.  The classic format is used when only one stream (input or output) logging
 115 is enabled. The multi-stream format is used on \fB\-\-log\-io\fR or when
 116 \fB\-\-log\-in\fR and \fB\-\-log\-out\fR are used together.
 117 .sp
 118 .RS
 119 .B Classic format
 120 .PP
 121 The log contains two fields, separated by a space.  The first
 122 field indicates how much time elapsed since the previous output.  The second
 123 field indicates how many characters were output this time.
 124 .sp
 125 .B Multi-stream format
 126 .PP
 127 The first field is entry type itentifier ('I'nput, 'O'utput, 'H'eader, 'S'ignal).
 128 The socond field is how much time elapsed since the previous entry, and rest of the entry is type specific data.
 129 .RE
 130 .TP
 131 \fB\-o\fR, \fB\-\-output-limit\fR \fIsize\fR
 132 Limit the size of the typescript and timing files to
 133 .I size
 134 and stop the child process after this size is exceeded.  The calculated
 135 file size does not include the start and done messages that the
 136 .B script
 137 command prepends and appends to the child process output.
 138 Due to buffering, the resulting output file might be larger than the specified value.
 139 .TP
 140 \fB\-q\fR, \fB\-\-quiet\fR
 141 Be quiet (do not write start and done messages to standard output).
 142 .TP
 143 \fB\-t\fR[\fIfile\fR], \fB\-\-timing\fR[=\fIfile\fR]
 144 Output timing data to standard error, or to
 145 .I file
 146 when given.  This option is deprecated in favour of \fB\-\-log\-timing\fR where
 147 the \fIfile\fR argument is not optional.
 148 .TP
 149 \fB\-V\fR, \fB\-\-version\fR
 150 Display version information and exit.
 151 .TP
 152 \fB\-h\fR, \fB\-\-help\fR
 153 Display help text and exit.
 154 .SH NOTES
 155 The script ends when the forked shell exits (a
 156 .I control-D
 157 for the Bourne shell
 158 .RB ( sh (1p)),
 159 and
 160 .IR exit ,
 161 .I logout
 162 or
 163 .I control-d
 164 (if
 165 .I ignoreeof
 166 is not set) for the
 167 C-shell,
 168 .BR csh (1)).
 169 .PP
 170 Certain interactive commands, such as
 171 .BR vi (1),
 172 create garbage in the typescript file.
 173 .B script
 174 works best with commands that do not manipulate the screen, the results are
 175 meant to emulate a hardcopy terminal.
 176 .PP
 177 It is not recommended to run
 178 .B script
 179 in non-interactive shells.  The inner shell of
 180 .B script
 181 is always interactive, and this could lead to unexpected results.  If you use
 182 .B script
 183 in the shell initialization file, you have to avoid entering an infinite
 184 loop.  You can use for example the \fB\%.profile\fR file, which is read
 185 by login shells only:
 186 .RS
 187 .RE
 188 .sp
 189 .na
 190 .RS
 191 .nf
 192 if test -t 0 ; then
 193     script
 194     exit
 195 fi
 196 .fi
 197 .RE
 198 .ad
 199 .PP
 200 You should also avoid use of script in command pipes, as
 201 .B script
 202 can read more input than you would expect.
 203 .PP
 204 .SH ENVIRONMENT
 205 The following environment variable is utilized by
 206 .BR script :
 207 .TP
 208 .B SHELL
 209 If the variable
 210 .B SHELL
 211 exists, the shell forked by
 212 .B script
 213 will be that shell.  If
 214 .B SHELL
 215 is not set, the Bourne shell is assumed.  (Most shells set this variable
 216 automatically).
 217 .SH SEE ALSO
 218 .BR csh (1)
 219 (for the
 220 .I history
 221 mechanism),
 222 .BR scriptreplay (1)
 223 .SH HISTORY
 224 The
 225 .B script
 226 command appeared in 3.0BSD.
 227 .SH BUGS
 228 .B script
 229 places
 230 .I everything
 231 in the log file, including linefeeds and backspaces.  This is not what the
 232 naive user expects.
 233 .PP
 234 .B script
 235 is primarily designed for interactive terminal sessions.  When stdin
 236 is not a terminal (for example: \fBecho foo | script\fR), then the session
 237 can hang, because the interactive shell within the script session misses EOF and
 238 .B script
 239 has no clue when to close the session.  See the \fBNOTES\fR section for more information.
 240 .SH AVAILABILITY
 241 The script command is part of the util-linux package and is available from
 242 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 243 Linux Kernel Archive
 244 .UE .