diff options
Diffstat (limited to 'term-utils/script.1')
| -rw-r--r-- | term-utils/script.1 | 295 |
1 files changed, 295 insertions, 0 deletions
diff --git a/term-utils/script.1 b/term-utils/script.1 new file mode 100644 index 0000000..49ba582 --- /dev/null +++ b/term-utils/script.1 @@ -0,0 +1,295 @@ +.\" Copyright (c) 1980, 1990 Regents of the University of California. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)script.1 6.5 (Berkeley) 7/27/91 +.\" +.TH SCRIPT "1" "October 2019" "util-linux" "User Commands" +.SH NAME +script \- make typescript of terminal session +.SH SYNOPSIS +.B script +[options] +.RI [ file ] +.SH DESCRIPTION +.B script +makes a typescript of everything on your terminal session. The terminal +data are stored in raw form to the log file and information about timing +to another (optional) structured log file. The timing log file is necessary to replay +the session later by +.BR scriptreplay (1) +and to store additional information about the session. +.PP +Since version 2.35, +.B script +supports multiple streams and allows the logging of input and output to separate +files or all the one file. This version also supports new timing file +which records additional information. The command +.B scriptreplay \-\-summary +then provides all the information. + +.PP +If the argument +.I file +or option \fB\-\-log\-out\fR \fIfile\fR is given, +.B script +saves the dialogue in this +.IR file . +If no filename is given, the dialogue is saved in the file +.IR typescript . +.PP +Note that logging input using \fB\-\-log\-in\fR or \fB\-\-log\-io\fR +may record security-sensitive information +as the log file contains all terminal session input +(e.g., passwords) +independently of the terminal echo flag setting. +.SH OPTIONS +Below, the \fIsize\fR argument may be followed by the multiplicative +suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB +(the "iB" is optional, e.g., "K" has the same meaning as "KiB"), or the suffixes +KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB. +.TP +\fB\-a\fR, \fB\-\-append\fR +Append the output to +.I file +or to +.IR typescript , +retaining the prior contents. +.TP +\fB\-c\fR, \fB\-\-command\fR \fIcommand\fR +Run the +.I command +rather than an interactive shell. This makes it easy for a script to capture +the output of a program that behaves differently when its stdout is not a +tty. +.TP +\fB\-E\fR, \fB\-\-echo\fR \fIwhen\fR +This option controls the ECHO flag for the pseudoterminal within the session. +The supported modes are +.IR always , +.IR never , +or +.IR auto . +The default is +.I auto +-- in this case, ECHO is disabled if the current standard input is a +terminal iin order to avoid double-echo, +and enabled if standard input is not a terminal +(for example pipe: +.BR "echo date | script" ) +to avoid missing input in the session log. +.TP +\fB\-e\fR, \fB\-\-return\fR +Return the exit status of the child process. Uses the same format as bash +termination on signal termination +(i.e., exit status is 128 + the signal number). The exit status of +the child process is always stored in the type script file too. +.TP +\fB\-f\fR, \fB\-\-flush\fR +Flush output after each write. This is nice for telecooperation: one person +does `mkfifo foo; script \-f foo', +and another can supervise in real-time what is +being done using `cat foo'. Note that flush has an impact on performance; it's +possible to use SIGUSR1 to flush logs on demand. +.TP +\fB\-\-force\fR +Allow the default output file +.I typescript +to be a hard or symbolic link. The command will follow a symbolic link. +.TP +\fB\-B\fR, \fB\-\-log\-io\fR \fIfile\fR +Log input and output to the same +\fIfile\fR. Note, this option makes sense only if \fB\-\-log\-timing\fR is +also specified, otherwise it's impossible to separate output and input streams from +the log \fIfile\fR. +.TP +\fB\-I\fR, \fB\-\-log\-in\fR \fIfile\fR +Log input to the \fIfile\fR. The log output is disabled if only \fB\-\-log\-in\fR +specified. +.sp +Use this logging functionality carefully as it logs all input, including input +when terminal has disabled echo flag (for example, password inputs). +.TP +\fB\-O\fR, \fB\-\-log\-out\fR \fIfile\fR +Log output to the \fIfile\fR. The default is to log output to the file with +name +.I typescript +if the option \fB\-\-log\-out\fR or \fB\-\-log\-in\fR is not given. The log +output is disabled if only \fB\-\-log\-in\fR specified. +.TP +\fB\-T\fR, \fB\-\-log\-timing\fR \fIfile\fR +Log timing information to the \fIfile\fR. Two timing file formats are supported +now. The classic format is used when only one stream (input or output) logging +is enabled. The multi-stream format is used on \fB\-\-log\-io\fR or when +\fB\-\-log\-in\fR and \fB\-\-log\-out\fR are used together. +See also \fB\-\-logging\-format\fR. +.TP +\fB\-m\fR, \fB\-\-logging\-format\fR \fIformat\fR +Force use of +.I advanced +or +.I classic +format. The default is the classic format to log only output and the +advanced format when input as well as output logging is requested. +.sp +.RS +.B Classic format +.PP +The log contains two fields, separated by a space. The first +field indicates how much time elapsed since the previous output. The second +field indicates how many characters were output this time. +.sp +.B Advanced (multi-stream) format +.PP +The first field is an entry type identifier +('I'nput, 'O'utput, 'H'eader, 'S'ignal). +The socond field is how much time elapsed since the previous entry, +and the rest of the entry is type-specific data. +.RE +.TP +\fB\-o\fR, \fB\-\-output-limit\fR \fIsize\fR +Limit the size of the typescript and timing files to +.I size +and stop the child process after this size is exceeded. The calculated +file size does not include the start and done messages that the +.B script +command prepends and appends to the child process output. +Due to buffering, the resulting output file might be larger than the specified value. +.TP +\fB\-q\fR, \fB\-\-quiet\fR +Be quiet (do not write start and done messages to standard output). +.TP +\fB\-t\fR[\fIfile\fR], \fB\-\-timing\fR[=\fIfile\fR] +Output timing data to standard error, or to +.I file +when given. This option is deprecated in favour of \fB\-\-log\-timing\fR where +the \fIfile\fR argument is not optional. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information and exit. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help text and exit. +.SH SIGNALS +Upon receiving +.BR SIGUSR1 , +.B script +immediately flushes the output files. +.SH ENVIRONMENT +The following environment variable is utilized by +.BR script : +.TP +.B SHELL +If the variable +.B SHELL +exists, the shell forked by +.B script +will be that shell. If +.B SHELL +is not set, the Bourne shell is assumed. (Most shells set this variable +automatically). +.SH NOTES +The script ends when the forked shell exits (a +.I control-D +for the Bourne shell +.RB ( sh (1p)), +and +.IR exit , +.I logout +or +.I control-d +(if +.I ignoreeof +is not set) for the +C-shell, +.BR csh (1)). +.PP +Certain interactive commands, such as +.BR vi (1), +create garbage in the typescript file. +.B script +works best with commands that do not manipulate the screen, the results are +meant to emulate a hardcopy terminal. +.PP +It is not recommended to run +.B script +in non-interactive shells. The inner shell of +.B script +is always interactive, and this could lead to unexpected results. If you use +.B script +in the shell initialization file, you have to avoid entering an infinite +loop. You can use for example the \fB\%.profile\fR file, which is read +by login shells only: +.sp +.na +.RS +.nf +if test \-t 0 ; then + script + exit +fi +.fi +.RE +.ad +.PP +You should also avoid use of +.B script +in command pipes, as +.B script +can read more input than you would expect. +.SH HISTORY +The +.B script +command appeared in 3.0BSD. +.SH BUGS +.B script +places +.I everything +in the log file, including linefeeds and backspaces. This is not what the +naive user expects. +.PP +.B script +is primarily designed for interactive terminal sessions. When stdin +is not a terminal (for example: \fBecho foo | script\fR), then the session +can hang, because the interactive shell within the script session misses EOF and +.B script +has no clue when to close the session. See the \fBNOTES\fR section for more information. +.SH SEE ALSO +.BR csh (1) +(for the +.I history +mechanism), +.BR scriptreplay (1), +.BR scriptlive (1), +.SH AVAILABILITY +The script command is part of the util-linux package and is available from +.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ +Linux Kernel Archive +.UE . |