source: zzuf/trunk/doc/zzcat.1.in @ 4274

Last change on this file since 4274 was 4274, checked in by Sam Hocevar, 11 years ago

Improve zzcat's manual page. Fixes #75.

File size: 3.5 KB
Line 
1.TH zzcat 1 "2010-01-07" "zzcat @PACKAGE_VERSION@"
2.SH NAME
3zzcat \- concatenate files using different instruction sequences
4.SH SYNOPSIS
5\fBzzcat\fR [\fB\-AbeEntTv\fR] [\fB\-x\fR \fIsequence\fR] [\fIFILE\fR]...
6.br
7\fBzzcat \-l\fR | \fB\-\-list\fR
8.br
9\fBzzcat \-h\fR | \fB\-\-help\fR
10.br
11\fBzzcat \-V\fR | \fB\-\-version\fR
12.SH DESCRIPTION
13.PP
14The \fBzzcat\fR utility reads files sequentially, writing them to the
15standard output. The user can decide which sequence of library calls is
16used to seek and read data.
17
18\fBzzcat\fR is primarily used as a debugging tool for \fBzzuf\fR, because
19it can emulate different programs' ways to read files.
20.SH OPTIONS
21.TP
22\fB\-A\fR, \fB\-\-show\-all\fR
23Equivalent to \fB\-vET\fR.
24.TP
25\fB\-b\fR, \fB\-\-number\-nonblank\fR
26Number nonempty output lines.
27.TP
28\fB\-e\fR
29Equivalent to \fB\-vET\fR.
30.TP
31\fB\-E\fR, \fB\-\-show\-ends\fR
32Display $ at end of each line.
33.TP
34\fB\-n\fR, \fB\-\-number\fR
35Number all output lines.
36.TP
37\fB\-t\fR
38Equivalent to \fB\-vT\fR.
39.TP
40\fB\-T\fR, \fB\-\-show\-tabs\fR
41Display TAB characters as ^I.
42.TP
43\fB\-v\fR, \fB\-\-show\-nonprinting\fR
44Use ^ and M- notation, except for LFD and TAB.
45.TP
46\fB\-x\fR, \fB\-\-execute\fR=\fIsequence\fR
47Read a file or a stream using the instruction sequence specified in
48\fIsequence\fR.
49
50Instructions are executed sequentially until the end of the program.
51End-of-file is not an exit condition, except where the \fBfeof\fR keyword is
52used:
53
54\fB    fread(1,10); feof(1); fread(1,10)\fR
55
56Loops are permitted using the \fBrepeat\fR keyword. Again, \fBfeof\fR can be
57used to prematurely break out of a loop:
58
59\fB    repeat(10000, fgetc() feof(1))\fR
60
61Instructions can be separated by spaces, commas or semicolons.
62A list of all available instructions and control keywords can be obtained
63using this command:
64
65\fB    zzcat \-l\fR
66
67If no sequence is specified, the following default sequence is used:
68
69\fB    repeat(\-1, fread(1,32768), feof(1))\fR
70
71.TP
72\fB\-l\fR, \fB\-\-list\fR
73Display the list of supported keywords and functions and exit.
74.TP
75\fB\-h\fR, \fB\-\-help\fR
76Display a short help message and exit.
77.TP
78\fB\-V\fR, \fB\-\-version\fR
79Output version information and exit.
80.SH EXAMPLES
81.PP
82Read the first 1000 bytes of f, then exit:
83.PP
84\fB    zzcat \-x \(aqfread(1,1000)\(aq f\fR
85.PP
86Read the first four bytes of f, using four different instructions:
87.PP
88\fB    zzcat \-x \(aqgetc(),fgetc(),getc_unlocked(),_IO_getc()\(aq f\fR
89.PP
90Read f entirely, by calling \fBgetc()\fR repeatedly until end-of-file is
91reached:
92.PP
93\fB    zzcat \-x \(aqrepeat(\-1, getc(), feof(1))\(aq \fRf
94.PP
95Read f entirely, in chunks of 32768 bytes until end-of-file is reached:
96.PP
97\fB    zzcat \-x \(aqrepeat(\-1, fread(1,32768), feof(1))\(aq \fRf
98.\" .PP
99.\" Read only odd bytes, rewind file, then read all even bytes:
100.\" .PP
101.\" \fB    zzcat \-x \(aqrepeat(\-1, getc(), feof(1), fseek(1,SEEK_CUR)),
102.\" \fB              rewind(),
103.\" \fB              repeat(\-1, fseek(1,SEEK_CUR), getc(), feof(1))\(aq
104.SH SEE ALSO
105.PP
106\fBzzuf(3)\fR, \fBlibzzuf(3)\fR
107.SH AUTHOR
108.PP
109Copyright \(co 2002\-2010 Sam Hocevar <sam@hocevar.net>.
110.PP
111\fBzzcat\fR and this manual page are free software. They come without any
112warranty, to the extent permitted by applicable law. You can redistribute
113them and/or modify them under the terms of the Do What The Fuck You Want
114To Public License, Version 2, as published by Sam Hocevar. See
115\fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details.
116.PP
117\fBzzuf\fR's webpage can be found at \fBhttp://caca.zoy.org/wiki/zzuf\fR.
118An overview of the architecture and inner works is at
119\fBhttp://caca.zoy.org/wiki/zzuf/internals\fR.
Note: See TracBrowser for help on using the repository browser.