Update Debian changelog.
[packages/dc3dd.git] / Options_Reference.txt
1 ------
2 usage:
3 ------
4
5         ./dc3dd [OPTION 1] [OPTION 2] ... [OPTION N]
6
7                 *or*
8
9         ./dc3dd [HELP OPTION]
10
11         where each OPTION is selected from the basic or advanced
12         options listed below, or HELP OPTION is selected from the
13         help options listed below.
14
15 --------------
16 basic options:
17 --------------
18
19         if=DEVICE or FILE    Read input from a device or a file (see note #1
20                              below for how to read from standard input). This
21                              option can only be used once and cannot be
22                              combined with ifs=, pat=, or tpat=.
23         ifs=BASE.FMT         Read input from a set of files with base name
24                              BASE and sequential file name extensions
25                              conforming to the format specifier FMT (see note
26                              #4 below for how to specify FMT). This option
27                              can only be used once and cannot be combined with
28                              if=, pat=, or tpat=.
29         of=FILE or DEVICE    Write output to a file or device (see note #2
30                              below for how to write to standard output). This
31                              option can be used more than once (see note #3
32                              below for how to generate multiple outputs).
33         hof=FILE or DEVICE   Write output to a file or device, hash the
34                              output file or device, and verify by comparing
35                              the output hash(es) to the input hash(es). This
36                              option can be used more than once (see note #3
37                              below for how to generate multiple outputs).
38         ofs=BASE.FMT         Write output to a set of files with base name BASE
39                              and sequential file name extensions generated from
40                              the format specifier FMT (see note #4 below for
41                              how to specify FMT). This option can be used more
42                              than once (see note #3 below for how to generate
43                              multiple outputs). Specify the maximum size of
44                              each file in the set using ofsz=.
45         hofs=BASE.FMT        Write output to a set of files with base name BASE
46                              and sequential file name extensions generated from
47                              the format specifier FMT (see note #4 below for
48                              how to specify FMT). Hash the output files and
49                              verify by comparing the output hash(es) to the
50                              input hash(es). This option can be used more than
51                              once (see note #3 below for how to generate
52                              multiple outputs). Specify the maximum size of
53                              each file in the set using ofsz=.
54         ofsz=BYTES           Set the maximum size of each file in the sets of
55                              files specified using ofs= or hofs= to
56                              BYTES (see note #5 below). A default value for
57                              this option may be set at compile time using
58                              -DDEFAULT_OUTPUT_FILE_SIZE followed by the desired
59                              value in BYTES.
60         hash=ALGORITHM       Compute an ALGORITHM hash of the input and also
61                              of any outputs specified using hof=, hofs=, phod=,
62                              or fhod=, where ALGORITHM is one of md5, sha1,
63                              sha256, or sha512. This option may be used once
64                              for each supported ALGORITHM. Alternatively,
65                              hashing can be activated at compile time using one
66                              or more of -DDEFAULT_HASH_MD5,-DDEFAULT_HASH_SHA1,
67                              -DDEFAULT_HASH_SHA256, and -DDEFAULT_HASH_SHA512.
68         log=FILE             Log I/O statistcs, diagnostics, and total hashes
69                              of input and output to FILE. If hlog= is not
70                              specified, piecewise hashes of multiple file
71                              input and output are also logged to FILE. This
72                              option can be used more than once to generate
73                              multiple logs.
74         hlog=FILE            Log total hashes and piecewise hashes to FILE.
75                              This option can be used more than once to generate
76                              multiple logs.
77
78 -----------------
79 advanced options:
80 -----------------
81
82         phod=DEVICE          The same as hof=DEVICE, except only the bytes
83                              written to DEVICE by dc3dd are verified. This
84                              option can be used more than once (see note
85                              #3 below for how to generate multiple outputs).
86         fhod=DEVICE          The same as phod=DEVICE, with additional
87                              hashing of the entire output DEVICE. This option
88                              can be used more than once (see note #3 below
89                              for how to generate multiple outputs).
90         rec=off              By default, zeros are written to the output(s) in
91                              place of bad sectors when the input is a device.
92                              Use this option to cause the program to instead
93                              exit when a bad sector is encountered.
94         wipe=DEVICE          Wipe DEVICE by writing zeros (default) or a
95                              pattern specified by pat= or tpat=.
96         hwipe=DEVICE         Wipe DEVICE by writing zeros (default) or a
97                              pattern specified by pat= or tpat=. Verify
98                              DEVICE after writing it by hashing it and
99                              comparing the hash(es) to the input hash(es).
100         pat=HEX              Use pattern as input, writing HEX to every byte
101                              of the output. This option can only be used once
102                              and cannot be combined with if=, ifs=, or
103                              tpat=.
104         tpat=TEXT            Use text pattern as input, writing the string TEXT
105                              repeatedly to the output. This option can only be
106                              used once and cannot be combined with if=, ifs=,
107                              or pat=.
108         cnt=SECTORS          Read only SECTORS input sectors. Must be used
109                              with pat= or tpat= if not using the pattern with
110                              wipe= or hwipe= to wipe a device.
111         iskip=SECTORS        Skip SECTORS sectors at start of the input device
112                              or file.
113         oskip=SECTORS        Skip SECTORS sectors at start of the output
114                              file. Specifying oskip= automatically 
115                              sets app=on.
116         app=on               Do not overwrite an output file specified with
117                              of= if it already exists, appending output instead.
118         ssz=BYTES            Unconditionally use BYTES (see note #5 below) bytes
119                              for sector size. If ssz= is not specified,
120                              sector size is determined by probing the device;
121                              if the probe fails or the target is not a device,
122                              a sector size of 512 bytes is assumed.
123         bufsz=BYTES          Set the size of the internal byte buffers to BYTES
124                              (see note #5 below). This effectively sets the
125                              maximum number of bytes that may be read at a time
126                              from the input. BYTES must be a multiple of sector
127                              size. Use this option to fine-tune performance.
128         verb=on              Activate verbose reporting, where sectors in/out
129                              are reported for each file in sets of files
130                              specified using ifs=, ofs=, or hofs=.
131                              Alternatively, verbose reporting may be activated
132                              at compile time using -DDEFAULT_VERBOSE_REPORTING.
133         nwspc=on             Activate compact reporting, where the use
134                              of white space to divide log output into
135                              logical sections is suppressed. Alternatively,
136                              compact reporting may be activated at compile
137                              time using -DDEFAULT_COMPACT_REPORTING.
138         b10=on               Activate base 10 bytes reporting, where the
139                              progress display reports 1000 bytes instead
140                              of 1024 bytes as 1 KB. Alternatively, base 10
141                              bytes reporting may be activated at compile
142                              time using -DDEFAULT_BASE_TEN_BYTES_REPORTING.
143         corruptoutput=on     For verification testing and demonstration
144                              purposes, corrupt the output file(s) with extra
145                              bytes so a hash mismatch is guaranteed.
146
147 -------------
148 help options:
149 -------------
150
151       --help     display this help and exit
152       --version  output version information and exit
153       --flags    display compile-time flags and exit
154
155 ------
156 notes:
157 ------
158
159 1. To read from stdin, do not specify if=, ifs=, pat=, or tpat=.
160 2. To write to stdout, do not specify of=, hof=, ofs=, hofs=, phod=,
161    fhod=, wipe=, or hwipe=.
162 3. To write to multiple outputs specify more than one of of=, hof=, ofs=,
163    hofs=, phod=, or fhod=, in any combination.
164 4. FMT is a pattern for a sequence of file extensions that can be numerical
165    starting at zero, numerical starting at one, or alphabetical. Specify FMT
166    by using a series of zeros, ones, or a's, respectively. The number of
167    characters used indicates the desired length of the extensions.
168    For example, a FMT specifier of 1111 indicates four character
169    numerical extensions starting with 0000.
170 5. BYTES may be followed by the following multiplicative suffixes:
171    c (1), w (2), b (512), kB (1000), K (1024), MB (1000*1000),
172    M (1024*1024), GB (1000*1000*1000), G (1024*1024*1024), and
173    so on for T, P, E, Z, and Y.
174 6. Consider using cnt=, iskip= and oskip= to work around
175    unreadable sectors if error recovery fails.
176 7. Sending an interrupt (e.g., CTRL+C) to dc3dd will cause
177    the program to report the work completed at the time
178    the interrupt is received and then exit.
179
180 Report bugs to <dc3dd@dc3.mil>.