script: support multi-stream logging

[thirdparty/util-linux.git] / term-utils / script.1

diff --git a/term-utils/script.1 b/term-utils/script.1
index 6c50bc621d1d61c2f85f68ac2ca3610b852e4812..75ad24f032b56aa7acfb06a9f622f7c0050c4a39 100644 (file)
--- a/term-utils/script.1
+++ b/term-utils/script.1
@@ -44,16 +44,24 @@ makes a typescript of everything displayed 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
 .BR lpr (1).
+Since version 2.35
+.B script
+supports multiple streams and allows to log input and output to separate
+files or all the one file.
 .PP
 If the argument
 .I file
-is given,
+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
 .BR typescript .
 .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
@@ -71,7 +79,8 @@ tty.
 .TP
 \fB\-e\fR, \fB\-\-return\fR
 Return the exit code of the child process.  Uses the same format as bash
-termination on signal termination exit code is 128+n.
+termination on signal termination exit code is 128+n.  The exit code of
+the child process is always stored in type script file too.
 .TP
 \fB\-f\fR, \fB\-\-flush\fR
 Flush output after each write.  This is nice for telecooperation: one person
@@ -82,16 +91,60 @@ being done using `cat foo'.
 Allow the default output destination, i.e. the typescript file, 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 it log passwords in the input).
+.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 '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 supporte
+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.
+.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 Multi-stream format
+.PP
+The first field is entry type itentifier ('I'nput, 'O'utput, 'H'eader, 'S'ignal).
+The socond field is how much time elapsed since the previous entry, and 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 data 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.  This information
-can be used to replay typescripts with realistic typing and output delays.
+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.
@@ -102,7 +155,7 @@ Display help text and exit.
 The script ends when the forked shell exits (a
 .I control-D
 for the Bourne shell
-.RB ( sh (1)),
+.RB ( sh (1p)),
 and
 .IR exit ,
 .I logout