mirror of
https://git.hardenedbsd.org/hardenedbsd/HardenedBSD.git
synced 2024-11-26 10:53:39 +01:00
8ceac8e13d
Add a -w flag to forward terminal resize events on to the child, which can be useful in some circumstances to avoid terminal corruption. Reviewed by: des Co-authored-by: Xavier Beaudouin <xavier.beaudouin@klarasystems.com> Sponsored by: Modirum MDPay Sponsored by: Klara, Inc. Differential Revision: https://reviews.freebsd.org/D44167
305 lines
7.2 KiB
Groff
305 lines
7.2 KiB
Groff
.\" Copyright (c) 1980, 1990, 1993
|
|
.\" The 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. 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.
|
|
.\"
|
|
.Dd October 26, 2022
|
|
.Dt SCRIPT 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm script
|
|
.Nd make typescript of terminal session
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl aeFfkqrw
|
|
.Op Fl t Ar time
|
|
.Op Ar file Op Ar command ...
|
|
.Nm
|
|
.Fl p
|
|
.Op Fl deq
|
|
.Op Fl T Ar fmt
|
|
.Op Ar file
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility makes a typescript of everything printed on your terminal.
|
|
It is useful for students who need a hardcopy record of an interactive
|
|
session as proof of an assignment, as the typescript file
|
|
can be printed out later with
|
|
.Xr lpr 1 .
|
|
.Pp
|
|
If the argument
|
|
.Ar file
|
|
is given,
|
|
.Nm
|
|
saves all dialogue in
|
|
.Ar file .
|
|
If no file name is given, the typescript is saved in the file
|
|
.Pa typescript .
|
|
.Pp
|
|
If the argument
|
|
.Ar command
|
|
is given,
|
|
.Nm
|
|
will run the specified command with an optional argument vector
|
|
instead of an interactive shell.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width "-F pipe"
|
|
.It Fl a
|
|
Append the output to
|
|
.Ar file
|
|
or
|
|
.Pa typescript ,
|
|
retaining the prior contents.
|
|
.It Fl d
|
|
When playing back a session with the
|
|
.Fl p
|
|
flag, do not sleep between records when playing back a timestamped session.
|
|
.It Fl e
|
|
Accepted for compatibility with
|
|
.Em util-linux
|
|
.Nm .
|
|
The child command exit status is always the exit status of
|
|
.Nm .
|
|
.It Fl F
|
|
Immediately flush output after each write.
|
|
This will allow a user to create a named pipe using
|
|
.Xr mkfifo 1
|
|
and another user may watch the live session using a utility like
|
|
.Xr cat 1 .
|
|
.It Fl f
|
|
Create
|
|
.Ar file.filemon
|
|
or
|
|
.Pa typescript.filemon
|
|
using
|
|
.Xr filemon 4 .
|
|
.It Fl k
|
|
Log keys sent to the program as well as output.
|
|
.It Fl p
|
|
Play back a session recorded with the
|
|
.Fl r
|
|
flag in real time.
|
|
.It Fl q
|
|
Run in quiet mode, omit the start, stop and command status messages.
|
|
.It Fl r
|
|
Record a session with input, output, and timestamping.
|
|
.It Fl t Ar time
|
|
Specify the interval at which the script output file will be flushed
|
|
to disk, in seconds.
|
|
A value of 0
|
|
causes
|
|
.Nm
|
|
to flush after every character I/O event.
|
|
The default interval is
|
|
30 seconds.
|
|
.It Fl T Ar fmt
|
|
Implies
|
|
.Fl p ,
|
|
but just reports the time-stamp of each output.
|
|
This is very useful for assessing the timing of events.
|
|
.Pp
|
|
If
|
|
.Ar fmt
|
|
does not contain any
|
|
.Ql %
|
|
characters, it indicates the default format:
|
|
.Ql %n@ %s [%Y-%m-%d %T]%n ,
|
|
which is useful for both tools and humans to read, should be used.
|
|
Note that time-stamps will only be output when different from the
|
|
previous one.
|
|
.It Fl w
|
|
Forward terminal size changes on
|
|
.Dv SIGWINCH .
|
|
.El
|
|
.Pp
|
|
The script ends when the forked shell (or command) exits (a
|
|
.Em control-D
|
|
to exit
|
|
the Bourne shell
|
|
.Pf ( Xr sh 1 ) ,
|
|
and
|
|
.Em exit ,
|
|
.Em logout
|
|
or
|
|
.Em control-D
|
|
(if
|
|
.Em ignoreeof
|
|
is not set) for the
|
|
C-shell,
|
|
.Xr csh 1 ) .
|
|
.Pp
|
|
Certain interactive commands, such as
|
|
.Xr vi 1 ,
|
|
create garbage in the typescript file.
|
|
The
|
|
.Nm
|
|
utility works best with commands that do not manipulate the screen.
|
|
The results are meant to emulate a hardcopy terminal, not an addressable one.
|
|
.Sh ENVIRONMENT
|
|
The following environment variables are utilized by
|
|
.Nm :
|
|
.Bl -tag -width SCRIPT
|
|
.It Ev SCRIPT
|
|
The
|
|
.Ev SCRIPT
|
|
environment variable is added to the sub-shell.
|
|
If
|
|
.Ev SCRIPT
|
|
already existed in the users environment,
|
|
its value is overwritten within the sub-shell.
|
|
The value of
|
|
.Ev SCRIPT
|
|
is the name of the
|
|
.Ar typescript
|
|
file.
|
|
.It Ev SHELL
|
|
If the variable
|
|
.Ev SHELL
|
|
exists, the shell forked by
|
|
.Nm
|
|
will be that shell.
|
|
If
|
|
.Ev SHELL
|
|
is not set, the Bourne shell
|
|
is assumed.
|
|
.Pq Most shells set this variable automatically .
|
|
.El
|
|
.Sh EXAMPLES
|
|
Record a simple
|
|
.Xr csh 1
|
|
session with no additional details like input, output, and timestamping:
|
|
.Bd -literal -offset indent
|
|
$ SHELL=/bin/csh script
|
|
Script started, output file is typescript
|
|
% date
|
|
Tue Jan 5 15:08:10 UTC 2021
|
|
% exit
|
|
exit
|
|
|
|
Script done, output file is typescript
|
|
.Ed
|
|
.Pp
|
|
Now, replay the session recorded in the previous example:
|
|
.Bd -literal -offset indent
|
|
$ cat ./typescript
|
|
Script started on Tue Jan 5 15:08:08 2021
|
|
% date
|
|
Tue Jan 5 15:08:10 UTC 2021
|
|
% exit
|
|
exit
|
|
|
|
Script done on Tue Jan 5 15:08:13 2021
|
|
.Ed
|
|
.Pp
|
|
Record a
|
|
.Xr csh 1
|
|
session, but this time with additional details like timestamping:
|
|
.Bd -literal -offset indent
|
|
$ SHELL=/bin/csh script -r
|
|
Script started, output file is typescript
|
|
% date
|
|
Tue Jan 5 15:17:11 UTC 2021
|
|
% exit
|
|
exit
|
|
|
|
Script done, output file is typescript
|
|
.Ed
|
|
.Pp
|
|
In order to replay a sessions recorded with the
|
|
.Fl r
|
|
flag, it is necessary to specify
|
|
.Fl p
|
|
.Po
|
|
.Xr cat 1
|
|
will not work because of all the aditional information stored in the session file
|
|
.Pc .
|
|
Also, let us use
|
|
.Fl d
|
|
to print the whole session at once:
|
|
.Bd -literal -offset indent
|
|
$ script -dp ./typescript
|
|
Script started on Tue Jan 5 15:17:09 2021
|
|
% date
|
|
Tue Jan 5 15:17:11 UTC 2021
|
|
% exit
|
|
exit
|
|
|
|
Script done on Tue Jan 5 15:17:14 2021
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr csh 1
|
|
.Po
|
|
for the
|
|
.Em history
|
|
mechanism
|
|
.Pc ,
|
|
.Xr filemon 4
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command appeared in
|
|
.Bx 3.0 .
|
|
.Pp
|
|
The
|
|
.Fl d ,
|
|
.Fl p
|
|
and
|
|
.Fl r
|
|
options first appeared in
|
|
.Nx 2.0
|
|
and were ported to
|
|
.Fx 9.2 .
|
|
.Sh BUGS
|
|
The
|
|
.Nm
|
|
utility places
|
|
.Sy everything
|
|
in the log file, including linefeeds and backspaces.
|
|
This is not what the naive user expects.
|
|
.Pp
|
|
It is not possible to specify a command without also naming the script file
|
|
because of argument parsing compatibility issues.
|
|
.Pp
|
|
When running in
|
|
.Fl k
|
|
mode, echo cancelling is far from ideal.
|
|
The slave terminal mode is checked
|
|
for ECHO mode to check when to avoid manual echo logging.
|
|
This does not
|
|
work when the terminal is in a raw mode where
|
|
the program being run is doing manual echo.
|
|
.Pp
|
|
If
|
|
.Nm
|
|
reads zero bytes from the terminal, it switches to a mode when it
|
|
only attempts to read
|
|
once a second until there is data to read.
|
|
This prevents
|
|
.Nm
|
|
from spinning on zero-byte reads, but might cause a 1-second delay in
|
|
processing of user input.
|