xref: /freebsd/usr.bin/script/script.1 (revision eac7052fdebb90caf2f653e06187bdbca837b9c7)
1.\" Copyright (c) 1980, 1990, 1993
2.\"	The Regents of the University of California.  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. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"	@(#)script.1	8.1 (Berkeley) 6/6/93
29.\" $FreeBSD$
30.\"
31.Dd September 1, 2020
32.Dt SCRIPT 1
33.Os
34.Sh NAME
35.Nm script
36.Nd make typescript of terminal session
37.Sh SYNOPSIS
38.Nm
39.Op Fl adefkpqr
40.Op Fl F Ar pipe
41.Op Fl t Ar time
42.Op Ar file Op Ar command ...
43.Sh DESCRIPTION
44The
45.Nm
46utility makes a typescript of everything printed on your terminal.
47It is useful for students who need a hardcopy record of an interactive
48session as proof of an assignment, as the typescript file
49can be printed out later with
50.Xr lpr 1 .
51.Pp
52If the argument
53.Ar file
54is given,
55.Nm
56saves all dialogue in
57.Ar file .
58If no file name is given, the typescript is saved in the file
59.Pa typescript .
60.Pp
61If the argument
62.Ar command
63is given,
64.Nm
65will run the specified command with an optional argument vector
66instead of an interactive shell.
67.Pp
68The following options are available:
69.Bl -tag -width indent
70.It Fl a
71Append the output to
72.Ar file
73or
74.Pa typescript ,
75retaining the prior contents.
76.It Fl d
77When playing back a session with the
78.Fl p
79flag, do not sleep between records when playing back a timestamped session.
80.It Fl e
81Accepted for compatibility with
82.Em util-linux
83.Nm .
84The child command exit status is always the exit status of
85.Nm .
86.It Fl F Ar pipe
87Immediately flush output after each write.
88This will allow a user to create a named pipe using
89.Xr mkfifo 1
90and another user may watch the live session using a utility like
91.Xr cat 1 .
92.It Fl f
93Create
94.Ar file.filemon
95or
96.Pa typescript.filemon
97using
98.Xr filemon 4 .
99.It Fl k
100Log keys sent to the program as well as output.
101.It Fl p
102Play back a session recorded with the
103.Fl r
104flag in real time.
105.It Fl q
106Run in quiet mode, omit the start, stop and command status messages.
107.It Fl r
108Record a session with input, output, and timestamping.
109.It Fl t Ar time
110Specify the interval at which the script output file will be flushed
111to disk, in seconds.
112A value of 0
113causes
114.Nm
115to flush after every character I/O event.
116The default interval is
11730 seconds.
118.El
119.Pp
120The script ends when the forked shell (or command) exits (a
121.Em control-D
122to exit
123the Bourne shell
124.Pf ( Xr sh 1 ) ,
125and
126.Em exit ,
127.Em logout
128or
129.Em control-D
130(if
131.Em ignoreeof
132is not set) for the
133C-shell,
134.Xr csh 1 ) .
135.Pp
136Certain interactive commands, such as
137.Xr vi 1 ,
138create garbage in the typescript file.
139The
140.Nm
141utility works best with commands that do not manipulate the screen.
142The results are meant to emulate a hardcopy terminal, not an addressable one.
143.Sh ENVIRONMENT
144The following environment variables are utilized by
145.Nm :
146.Bl -tag -width SHELL
147.It Ev SCRIPT
148The
149.Ev SCRIPT
150environment variable is added to the sub-shell.
151If
152.Ev SCRIPT
153already existed in the users environment,
154its value is overwritten within the sub-shell.
155The value of
156.Ev SCRIPT
157is the name of the
158.Ar typescript
159file.
160.It Ev SHELL
161If the variable
162.Ev SHELL
163exists, the shell forked by
164.Nm
165will be that shell.
166If
167.Ev SHELL
168is not set, the Bourne shell
169is assumed.
170.Pq Most shells set this variable automatically .
171.El
172.Sh SEE ALSO
173.Xr csh 1
174.Po
175for the
176.Em history
177mechanism
178.Pc ,
179.Xr filemon 4
180.Sh HISTORY
181The
182.Nm
183command appeared in
184.Bx 3.0 .
185.Pp
186The
187.Fl d ,
188.Fl p
189and
190.Fl r
191options first appeared in
192.Nx 2.0
193and were ported to
194.Fx 9.2 .
195.Sh BUGS
196The
197.Nm
198utility places
199.Sy everything
200in the log file, including linefeeds and backspaces.
201This is not what the naive user expects.
202.Pp
203It is not possible to specify a command without also naming the script file
204because of argument parsing compatibility issues.
205.Pp
206When running in
207.Fl k
208mode, echo cancelling is far from ideal.
209The slave terminal mode is checked
210for ECHO mode to check when to avoid manual echo logging.
211This does not
212work when the terminal is in a raw mode where
213the program being run is doing manual echo.
214.Pp
215If
216.Nm
217reads zero bytes from the terminal, it switches to a mode when it
218only attempts to read
219once a second until there is data to read.
220This prevents
221.Nm
222from spinning on zero-byte reads, but might cause a 1-second delay in
223processing of user input.
224