Add new files

2 files changed, 285 insertions, 0 deletions

diff --git a/doc/DISTFILES b/doc/DISTFILES
new file mode 100644
index 0000000..954ea44
--- /dev/null
+++ b/doc/DISTFILES
@@ -0,0 +1 @@
+genfile.texi
diff --git a/doc/genfile.texi b/doc/genfile.texi
new file mode 100644
index 0000000..dd63031
--- /dev/null
+++ b/doc/genfile.texi
@@ -0,0 +1,284 @@
+@c This is part of the paxutils manual.
+@c Copyright (C) 2005 Free Software Foundation, Inc.
+@c Written by Sergey Poznyakoff
+@c This file is distributed under GFDL 1.1 or any later version
+@c published by the Free Software Foundation.
+
+@cindex genfile
+    This appendix describes @command{genfile}, an auxiliary program
+used in the GNU tar testsuite. If you are not interested in developing
+GNU tar, skip this appendix.
+
+    Initially, @command{genfile} was used to generate data files for
+the testsuite, hence its name. However, new operation modes were being
+implemented as the testsuite grew more sophisticated, and now
+@command{genfile} is a multi-purpose instrument.
+
+    There are three basic operation modes:
+
+@table @asis
+@item File Generation
+    This is the default mode. In this mode, @command{genfile}
+generates data files.
+
+@item File Status
+    In this mode @command{genfile} displays status of specified files.
+
+@item Synchronous Execution.
+    In this mode @command{genfile} executes the given program with
+@option{--checkpoint} option and executes a set of actions when
+specified checkpoints are reached.
+@end table
+
+@menu
+* Generate Mode::     File Generation Mode.
+* Status Mode::       File Status Mode.
+* Exec Mode::         Synchronous Execution mode.
+@end menu
+
+@node Generate Mode
+@appendixsec Generate Mode
+
+@cindex Generate Mode, @command{genfile}
+@cindex @command{genfile}, generate mode
+@cindex @command{genfile}, create file
+    In this mode @command{genfile} creates a data file for the test
+suite. The size of the file is given with the @option{--length}
+(@option{-l}) option. By default the file contents is written to the
+standard output, this can be changed using @option{--file}
+(@option{-f}) command line option. Thus, the following two commands
+are equivalent:
+
+@smallexample
+genfile --length 100 > outfile
+genfile --length 100 --file outfile
+@end smallexample
+
+    If @option{--length} is not given, @command{genfile} will
+generate an empty (zero-length) file.
+
+@cindex pattern, @command{genfile}
+    The default data pattern for filling the generated file consists
+of first 256 letters of ASCII code, repeated enough times to fill the
+entire file. This behavior can be changed with @option{--pattern}
+option. This option takes a mandatory argument, specifying pattern
+name to use. Currently two patterns are implemented:
+
+@table @option
+@item --pattern=default
+    The default pattern as described above.
+
+@item --pattern=zero
+    Fills the file with zeroes.
+@end table
+
+@cindex Sparse files, creating using @command{genfile}
+@cindex @command{genfile}, creating sparse files
+    Special option @option{--sparse} (@option{-s}) instructs
+@command{genfile} to create a sparse file. Sparse files consist of
+@dfn{data fragments}, separated by @dfn{holes} or blocks of zeros. On
+many operating systems, actual disk storage is not allocated for
+holes, but they are counted in the length of the file. To create a
+sparse file @command{genfile} should know where to put data fragments,
+and what data to use to fill them. So, when @option{--sparse} is given
+the rest of the command line specifies a so-called @dfn{file map}.
+
+    The file map consists of any number of @dfn{fragment
+descriptors}. Each descriptor is composed of two values: a number,
+specifying fragment offset in the file, and @dfn{contents string},
+i.e. a string of characters, specifying the pattern to fill the
+fragment with. File offset can be suffixed with the following
+quantifiers:
+
+@table @samp
+@item k
+@itemx K
+The number is expressed in kilobytes.
+@item m
+@itemx M
+The number is expressed in megabytes.
+@item g
+@itemx G
+The number is expressed in gigabytes.
+@end table
+
+    For each letter in contents string @command{genfile} will generate
+a @dfn{block} of data, filled with this letter and will write it to
+the fragment. The size of block is given by @option{--block-size}
+option. It defaults to 512. Thus, if the string consists of @var{n}
+characters, the resulting file fragment will contain
+@code{@var{n}*@var{block-size}} of data. 
+
+    Last fragment descriptor can have only file offset part. In this
+case @command{genfile} will create a hole at the end of the file up to
+the given offset.
+
+    For example, consider the following invocation:
+
+@smallexample
+genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K 
+@end smallexample
+
+@noindent
+It will create a 2048000-bytes long file of the following structure:
+
+@multitable @columnfractions .35 .20 .45
+@item Offset  @tab Length       @tab Contents
+@item 0       @tab 4*512=2048   @tab Four 512-byte blocks, filled with
+letters @samp{A}, @samp{B}, @samp{C} and @samp{D}.
+@item 2048    @tab 1046528      @tab Zero bytes 
+@item 1048576 @tab 5*512=2560   @tab Five blocks, filled with letters
+@samp{E}, @samp{F}, @samp{G}, @samp{H}, @samp{I}.
+@item 1051136 @tab 996864       @tab Zero bytes
+@end multitable
+
+@node Status Mode
+@appendixsec Status Mode
+
+    In status mode, @command{genfile} prints file system status for
+each file specified in the command line. This mode is toggled by
+@option{--stat} (@option{-S}) command line option. An optional argument to this
+option specifies output @dfn{format}: a comma-separated list of
+@code{struct stat} fields to be displayed. This list can contain
+following identifiers @FIXME{should we also support @samp{%} notations
+as in stat(1)??}:
+
+@table @asis
+@item name
+    The file name.
+    
+@item dev
+@itemx st_dev
+    Device number in decimal.
+    
+@item ino
+@itemx st_ino
+    Inode number.
+    
+@item mode
+@itemx st_mode
+    File mode in octal.
+    
+@item nlink
+@itemx st_nlink
+    Number of hard links.
+    
+@item uid
+@itemx st_uid
+    User ID of owner.
+    
+@item gid
+@itemx st_gid
+    Group ID of owner.
+    
+@item size
+@itemx st_size
+    File size in decimal.
+    
+@item blksize
+@itemx st_blksize
+    The size in bytes of each file block.
+    
+@item blocks
+@itemx st_blocks
+    Number of blocks allocated.
+     
+@item atime
+@itemx st_atime
+    Time of last access.
+    
+@item mtime
+@itemx st_mtime
+    Time of last modification
+
+@item ctime
+@itemx st_ctime
+    Time of last status change
+@end table
+
+    Modification times are displayed in @acronym{UTC} as
+@acronym{UNIX} timestamps, unless suffixed with @samp{H} (for
+``human-readable''), as in @samp{ctimeH}, in which case usual
+@code{tar tv} output format is used.
+
+    The default output format is: @samp{name,dev,ino,mode,
+nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime}. 
+
+    For example, the following command will display file names and
+corresponding times of last access for each file in the current working
+directory:
+
+@smallexample
+genfile --stat=name,atime *
+@end smallexample
+
+@node Exec Mode
+@appendixsec Exec Mode
+
+@cindex Exec Mode, @command{genfile}
+    This mode is designed for testing the behavior of @code{paxutils}
+commands when some of the files change during archiving. It is an
+experimental mode.
+
+    The @samp{Exec Mode} is toggled by @option{--run} command line
+option (or its alias @option{-r}). The argument to this option gives
+the command line to be executed. The actual command line is
+constructed by insertin @option{--checkpoint} option between the
+command name and its first argument (if any). Due to this, the
+argument to @option{--run} may not use traditional @command{tar}
+option syntax, i.e. the following is wrong: 
+
+@smallexample
+# Wrong!
+genfile --run 'tar cf foo bar'
+@end smallexample
+
+@noindent
+
+Use the following syntax instead:
+
+@smallexample
+genfile --run 'tar -cf foo bar'
+@end smallexample
+
+    The rest of command line after @option{--run} or its equivalent
+specifies checkpoint values and actions to be executed upon reaching
+them. Checkpoint values are introduced with @option{--checkpoint}
+command line option. Argument to this option is the number of
+checkpoint in decimal.
+
+    Any number of @dfn{actions} may be specified after a
+checkpoint. Available actions are
+
+@table @option
+@item --cut @var{file}
+@itemx --truncate @var{file}
+    Truncate @var{file} to the size specified by previous
+@option{--length} option (or 0, if it is not given).
+    
+@item --append @var{file}
+    Append data to @var{file}. The size of data and its pattern are
+given by previous @option{--length} and @option{pattern} options.
+
+@item --touch @var{file}
+    Update the access and modification times of @var{file}. These
+timestamps are changed to the current time, unless @option{--date}
+option was given, in which case they are changed to the specified
+time. Argument to @option{--date} option is a date specification in
+almost arbitrary format (@pxref{Date input formats}).
+
+@item --exec @var{command}
+    Execute given shell command.
+    
+@end table
+
+    Option @option{--verbose} instructs @command{genfile} to print on
+standard output notifications about checkpoints being executed and to
+verbosely describe exit status of the command.
+
+    While the command is being execute its standard output remains
+connected to descriptor 1. All messages it prints to file descriptor
+2, except checkpoint notifications, are forwarded to standard
+error.
+
+    @command{Genfile} exits with the exit status of the executed command.