xref: /freebsd/usr.bin/script/script.1 (revision ba00ec3d539f213abbda3a45ef8c539306cac098)
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.\" 4. 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 Oct 27, 2012
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 adfkpqr
40.Op Fl t Ar time
41.Op Ar file Op Ar command ...
42.Sh DESCRIPTION
43The
44.Nm
45utility makes a typescript of everything printed on your terminal.
46It is useful for students who need a hardcopy record of an interactive
47session as proof of an assignment, as the typescript file
48can be printed out later with
49.Xr lpr 1 .
50.Pp
51If the argument
52.Ar file
53is given,
54.Nm
55saves all dialogue in
56.Ar file .
57If no file name is given, the typescript is saved in the file
58.Pa typescript .
59.Pp
60If the argument
61.Ar command
62is given,
63.Nm
64will run the specified command with an optional argument vector
65instead of an interactive shell.
66.Pp
67The following options are available:
68.Bl -tag -width indent
69.It Fl a
70Append the output to
71.Ar file
72or
73.Pa typescript ,
74retaining the prior contents.
75.It Fl d
76When playing back a session with the
77.Fl p
78flag, do not sleep between records when playing back a timestamped session.
79.It Fl f
80Create
81.Ar file.filemon
82or
83.Pa typescript.filemon
84using
85.Xr filemon 4 .
86.It Fl k
87Log keys sent to the program as well as output.
88.It Fl p
89Play back a session recorded with the
90.Fl r
91flag in real time.
92.It Fl q
93Run in quiet mode, omit the start, stop and command status messages.
94.It Fl r
95Record a session with input, output, and timestamping.
96.It Fl t Ar time
97Specify the interval at which the script output file will be flushed
98to disk, in seconds.
99A value of 0
100causes
101.Nm
102to flush after every character I/O event.
103The default interval is
10430 seconds.
105.El
106.Pp
107The script ends when the forked shell (or command) exits (a
108.Em control-D
109to exit
110the Bourne shell
111.Pf ( Xr sh 1 ) ,
112and
113.Em exit ,
114.Em logout
115or
116.Em control-D
117(if
118.Em ignoreeof
119is not set) for the
120C-shell,
121.Xr csh 1 ) .
122.Pp
123Certain interactive commands, such as
124.Xr vi 1 ,
125create garbage in the typescript file.
126The
127.Nm
128utility works best with commands that do not manipulate the screen.
129The results are meant to emulate a hardcopy terminal, not an addressable one.
130.Sh ENVIRONMENT
131The following environment variables are utilized by
132.Nm :
133.Bl -tag -width SHELL
134.It Ev SCRIPT
135The
136.Ev SCRIPT
137environment variable is added to the sub-shell.
138If
139.Ev SCRIPT
140already existed in the users environment,
141its value is overwritten within the sub-shell.
142The value of
143.Ev SCRIPT
144is the name of the
145.Ar typescript
146file.
147.It Ev SHELL
148If the variable
149.Ev SHELL
150exists, the shell forked by
151.Nm
152will be that shell.
153If
154.Ev SHELL
155is not set, the Bourne shell
156is assumed.
157.Pq Most shells set this variable automatically .
158.El
159.Sh SEE ALSO
160.Xr csh 1
161.Xr filemon 4
162.Po
163for the
164.Em history
165mechanism
166.Pc .
167.Sh HISTORY
168The
169.Nm
170command appeared in
171.Bx 3.0 .
172.Pp
173The
174.Fl d ,
175.Fl p
176and
177.Fl r
178options first appeared in
179.Nx 2.0
180and were ported to
181.Fx 10 .
182.Sh BUGS
183The
184.Nm
185utility places
186.Sy everything
187in the log file, including linefeeds and backspaces.
188This is not what the naive user expects.
189.Pp
190It is not possible to specify a command without also naming the script file
191because of argument parsing compatibility issues.
192.Pp
193When running in
194.Fl k
195mode, echo cancelling is far from ideal.
196The slave terminal mode is checked
197for ECHO mode to check when to avoid manual echo logging.
198This does not
199work when the terminal is in a raw mode where
200the program being run is doing manual echo.
201.Pp
202If
203.Nm
204reads zero bytes from the terminal, it switches to a mode when it
205only attempts to read
206once a second until there is data to read.
207This prevents
208.Nm
209from spinning on zero-byte reads, but might cause a 1-second delay in
210processing of user input.
211