tar: Generate Mode
1
1 F.1 Generate Mode
1 =================
1
1 In this mode 'genfile' creates a data file for the test suite. The size
1 of the file is given with the '--length' ('-l') option. By default the
1 file contents is written to the standard output, this can be changed
1 using '--file' ('-f') command line option. Thus, the following two
1 commands are equivalent:
1
1 genfile --length 100 > outfile
1 genfile --length 100 --file outfile
1
1 If '--length' is not given, 'genfile' will generate an empty
1 (zero-length) file.
1
1 The command line option '--seek=N' istructs 'genfile' to skip the
1 given number of bytes (N) in the output file before writing to it. It
1 is similar to the 'seek=N' of the 'dd' utility.
1
1 You can instruct 'genfile' to create several files at one go, by
1 giving it '--files-from' ('-T') option followed by a name of file
1 containing a list of file names. Using dash ('-') instead of the file
1 name causes 'genfile' to read file list from the standard input. For
1 example:
1
1 # Read file names from file file.list
1 genfile --files-from file.list
1 # Read file names from standard input
1 genfile --files-from -
1
1 The list file is supposed to contain one file name per line. To use
1 file lists separated by ASCII NUL character, use '--null' ('-0') command
1 line option:
1
1 genfile --null --files-from file.list
1
1 The default data pattern for filling the generated file consists of
1 first 256 letters of ASCII code, repeated enough times to fill the
1 entire file. This behavior can be changed with '--pattern' option.
1 This option takes a mandatory argument, specifying pattern name to use.
1 Currently two patterns are implemented:
1
1 '--pattern=default'
1 The default pattern as described above.
1
1 '--pattern=zero'
1 Fills the file with zeroes.
1
1 If no file name was given, the program exits with the code '0'.
1 Otherwise, it exits with '0' only if it was able to create a file of the
1 specified length.
1
1 Special option '--sparse' ('-s') instructs 'genfile' to create a
1 sparse file. Sparse files consist of "data fragments", separated by
1 "holes" or blocks of zeros. On many operating systems, actual disk
1 storage is not allocated for holes, but they are counted in the length
1 of the file. To create a sparse file, 'genfile' should know where to
1 put data fragments, and what data to use to fill them. So, when
1 '--sparse' is given the rest of the command line specifies a so-called
1 "file map".
1
1 The file map consists of any number of "fragment descriptors". Each
1 descriptor is composed of two values: a number, specifying fragment
1 offset from the end of the previous fragment or, for the very first
1 fragment, from the beginning of the file, and "contents string", that
1 specifies the pattern to fill the fragment with. File offset can be
1 suffixed with the following quantifiers:
1
1 'k'
1 'K'
1 The number is expressed in kilobytes.
1 'm'
1 'M'
1 The number is expressed in megabytes.
1 'g'
1 'G'
1 The number is expressed in gigabytes.
1
1 Contents string can be either a fragment size or a pattern. Fragment
1 size is a decimal number, prefixed with an equals sign. It can be
1 suffixed with a quantifier, as discussed above. If fragment size is
1 given, the fragment of that size will be filled with the currently
1 selected pattern (⇒-pattern Generate Mode.) and written to the
1 file.
1
1 A pattern is a string of arbitrary ASCII characters. For each of
1 them, 'genfile' will generate a "block" of data, filled with that
1 character and will write it to the fragment. The size of block is given
1 by '--block-size' option. It defaults to 512. Thus, if pattern
1 consists of N characters, the resulting file fragment will contain
1 'N*BLOCK-SIZE' bytes of data.
1
1 The last fragment descriptor can have only file offset part. In this
1 case 'genfile' will create a hole at the end of the file up to the given
1 offset.
1
1 A dash appearing as a fragment descriptor instructs 'genfile' to read
1 file map from the standard input. Each line of input should consist of
1 fragment offset and contents string, separated by any amount of
1 whitespace.
1
1 For example, consider the following invocation:
1
1 genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K
1
1 It will create 3101184-bytes long file of the following structure:
1
1 Offset Length Contents
1 0 4*512=2048 Four 512-byte blocks, filled
1 with letters 'A', 'B', 'C' and
1 'D'.
1 2048 1046528 Zero bytes
1 1050624 5*512=2560 Five blocks, filled with
1 letters 'E', 'F', 'G', 'H',
1 'I'.
1 1053184 2048000 Zero bytes
1
1 The exit code of 'genfile --sparse' command is '0' only if created
1 file is actually sparse. If it is not, the appropriate error message is
1 displayed and the command exists with code '1'. The '--quite' ('-q')
1 option suppresses this behavior. If '--quite' is given, 'genfile
1 --sparse' exits with code '0' if it was able to create the file, whether
1 the resulting file is sparse or not.
1