1 @c This is part of the paxutils manual.
2 @c Copyright (C) 2005, 2006 Free Software Foundation, Inc.
3 @c Written by Sergey Poznyakoff
4 @c This file is distributed under GFDL 1.1 or any later version
5 @c published by the Free Software Foundation.
8 This appendix describes @command{genfile}, an auxiliary program
9 used in the GNU tar testsuite. If you are not interested in developing
10 GNU tar, skip this appendix.
12 Initially, @command{genfile} was used to generate data files for
13 the testsuite, hence its name. However, new operation modes were being
14 implemented as the testsuite grew more sophisticated, and now
15 @command{genfile} is a multi-purpose instrument.
17 There are three basic operation modes:
21 This is the default mode. In this mode, @command{genfile}
25 In this mode @command{genfile} displays status of specified files.
27 @item Synchronous Execution.
28 In this mode @command{genfile} executes the given program with
29 @option{--checkpoint} option and executes a set of actions when
30 specified checkpoints are reached.
34 * Generate Mode:: File Generation Mode.
35 * Status Mode:: File Status Mode.
36 * Exec Mode:: Synchronous Execution mode.
40 @appendixsec Generate Mode
42 @cindex Generate Mode, @command{genfile}
43 @cindex @command{genfile}, generate mode
44 @cindex @command{genfile}, create file
45 In this mode @command{genfile} creates a data file for the test
46 suite. The size of the file is given with the @option{--length}
47 (@option{-l}) option. By default the file contents is written to the
48 standard output, this can be changed using @option{--file}
49 (@option{-f}) command line option. Thus, the following two commands
54 genfile --length 100 > outfile
55 genfile --length 100 --file outfile
59 If @option{--length} is not given, @command{genfile} will
60 generate an empty (zero-length) file.
62 @cindex @command{genfile}, seeking to a given offset
63 The command line option @option{--seek=@var{N}} istructs @command{genfile}
64 to skip the given number of bytes (@var{N}) in the output file before
65 writing to it. It is similar to the @option{seek=@var{N}} of the
68 @cindex @command{genfile}, reading a list of file names
69 You can instruct @command{genfile} to create several files at one
70 go, by giving it @option{--files-from} (@option{-T}) option followed
71 by a name of file containing a list of file names. Using dash
72 (@samp{-}) instead of the file name causes @command{genfile} to read
73 file list from the standard input. For example:
77 # Read file names from file @file{file.list}
78 genfile --files-from file.list
79 # Read file names from standard input
80 genfile --files-from -
84 @cindex File lists separated by NUL characters
85 The list file is supposed to contain one file name per line. To
86 use file lists separated by ASCII NUL character, use @option{--null}
87 (@option{-0}) command line option:
90 genfile --null --files-from file.list
93 @cindex pattern, @command{genfile}
94 The default data pattern for filling the generated file consists
95 of first 256 letters of ASCII code, repeated enough times to fill the
96 entire file. This behavior can be changed with @option{--pattern}
97 option. This option takes a mandatory argument, specifying pattern
98 name to use. Currently two patterns are implemented:
101 @item --pattern=default
102 The default pattern as described above.
105 Fills the file with zeroes.
108 If no file name was given, the program exits with the code
109 @code{0}. Otherwise, it exits with @code{0} only if it was able to
110 create a file of the specified length.
112 @cindex Sparse files, creating using @command{genfile}
113 @cindex @command{genfile}, creating sparse files
114 Special option @option{--sparse} (@option{-s}) instructs
115 @command{genfile} to create a sparse file. Sparse files consist of
116 @dfn{data fragments}, separated by @dfn{holes} or blocks of zeros. On
117 many operating systems, actual disk storage is not allocated for
118 holes, but they are counted in the length of the file. To create a
119 sparse file, @command{genfile} should know where to put data fragments,
120 and what data to use to fill them. So, when @option{--sparse} is given
121 the rest of the command line specifies a so-called @dfn{file map}.
123 The file map consists of any number of @dfn{fragment
124 descriptors}. Each descriptor is composed of two values: a number,
125 specifying fragment offset from the end of the previous fragment or,
126 for the very first fragment, from the beginning of the file, and
127 @dfn{contents string}, i.e., a string of characters, specifying the
128 pattern to fill the fragment with. File offset can be suffixed with
129 the following quantifiers:
134 The number is expressed in kilobytes.
137 The number is expressed in megabytes.
140 The number is expressed in gigabytes.
143 For each letter in contents string @command{genfile} will generate
144 a @dfn{block} of data, filled with this letter and will write it to
145 the fragment. The size of block is given by @option{--block-size}
146 option. It defaults to 512. Thus, if the string consists of @var{n}
147 characters, the resulting file fragment will contain
148 @code{@var{n}*@var{block-size}} of data.
150 Last fragment descriptor can have only file offset part. In this
151 case @command{genfile} will create a hole at the end of the file up to
154 For example, consider the following invocation:
157 genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
161 It will create 3101184-bytes long file of the following structure:
163 @multitable @columnfractions .35 .20 .45
164 @item Offset @tab Length @tab Contents
165 @item 0 @tab 4*512=2048 @tab Four 512-byte blocks, filled with
166 letters @samp{A}, @samp{B}, @samp{C} and @samp{D}.
167 @item 2048 @tab 1046528 @tab Zero bytes
168 @item 1050624 @tab 5*512=2560 @tab Five blocks, filled with letters
169 @samp{E}, @samp{F}, @samp{G}, @samp{H}, @samp{I}.
170 @item 1053184 @tab 2048000 @tab Zero bytes
173 The exit code of @command{genfile --status} command is @code{0}
174 only if created file is actually sparse.
177 @appendixsec Status Mode
179 In status mode, @command{genfile} prints file system status for
180 each file specified in the command line. This mode is toggled by
181 @option{--stat} (@option{-S}) command line option. An optional argument to this
182 option specifies output @dfn{format}: a comma-separated list of
183 @code{struct stat} fields to be displayed. This list can contain
184 following identifiers @FIXME{should we also support @samp{%} notations
193 Device number in decimal.
199 @item mode[.@var{number}]
200 @itemx st_mode[.@var{number}]
201 File mode in octal. Optional @var{number} specifies octal mask to
202 be applied to the mode before outputting. For example, @code{--stat
203 mode.777} will preserve lower nine bits of it. Notice, that you can
204 use any punctuation character in place of @samp{.}.
208 Number of hard links.
220 File size in decimal.
224 The size in bytes of each file block.
228 Number of blocks allocated.
236 Time of last modification
240 Time of last status change
243 A boolean value indicating whether the file is @samp{sparse}.
246 Modification times are displayed in @acronym{UTC} as
247 @acronym{UNIX} timestamps, unless suffixed with @samp{H} (for
248 ``human-readable''), as in @samp{ctimeH}, in which case usual
249 @code{tar tv} output format is used.
251 The default output format is: @samp{name,dev,ino,mode,
252 nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime}.
254 For example, the following command will display file names and
255 corresponding times of last access for each file in the current working
259 genfile --stat=name,atime *
263 @appendixsec Exec Mode
265 @cindex Exec Mode, @command{genfile}
266 This mode is designed for testing the behavior of @code{paxutils}
267 commands when some of the files change during archiving. It is an
270 The @samp{Exec Mode} is toggled by @option{--run} command line
271 option (or its alias @option{-r}). The argument to this option gives
272 the command line to be executed. The actual command line is
273 constructed by inserting @option{--checkpoint} option between the
274 command name and its first argument (if any). Due to this, the
275 argument to @option{--run} may not use traditional @command{tar}
276 option syntax, i.e., the following is wrong:
280 genfile --run 'tar cf foo bar'
285 Use the following syntax instead:
288 genfile --run 'tar -cf foo bar'
291 The rest of command line after @option{--run} or its equivalent
292 specifies checkpoint values and actions to be executed upon reaching
293 them. Checkpoint values are introduced with @option{--checkpoint}
294 command line option. Argument to this option is the number of
295 checkpoint in decimal.
297 Any number of @dfn{actions} may be specified after a
298 checkpoint. Available actions are
301 @item --cut @var{file}
302 @itemx --truncate @var{file}
303 Truncate @var{file} to the size specified by previous
304 @option{--length} option (or 0, if it is not given).
306 @item --append @var{file}
307 Append data to @var{file}. The size of data and its pattern are
308 given by previous @option{--length} and @option{pattern} options.
310 @item --touch @var{file}
311 Update the access and modification times of @var{file}. These
312 timestamps are changed to the current time, unless @option{--date}
313 option was given, in which case they are changed to the specified
314 time. Argument to @option{--date} option is a date specification in
315 an almost arbitrary format (@pxref{Date input formats}).
317 @item --exec @var{command}
318 Execute given shell command.
322 Option @option{--verbose} instructs @command{genfile} to print on
323 standard output notifications about checkpoints being executed and to
324 verbosely describe exit status of the command.
326 While the command is being executed its standard output remains
327 connected to descriptor 1. All messages it prints to file descriptor
328 2, except checkpoint notifications, are forwarded to standard
331 @command{Genfile} exits with the exit status of the executed command.