Improved manpage and help page

Author: eribertomota

ChangeLog

@@ -10,19 +10,22 @@ Version 1.5
    - Moved some build lines from Makefile.am to src/Makefile.am.
    - Removed all autogenerated files.
  * Added a bash completion script (from Debian).
- * Added all new features from David Loveall to manpage.
  * Created CONTRIBUTING.md file.
  * Fixed some building warnings.
  * Fixed the message when using hashes (add a newline to generate a space
    between the summary message and hashes.
+ * Manpage and help page:
+     - Added all new features from David Loveall to manpage and help page.
+     - Full reviewed and improved the manpage and help page. Added examples
+       in manpage.
+     - Using txt2man to produce an updated manpage.
  * Moved all source code to src/.
  * Reorganized AUTHORS and ChangeLog files.
  * Rewritten README file, now called README.md.
  * Set -fgnu89-inline in CFLAGS to avoid warning (fix: 'warning: inline
-   function ‘quit’ declared but never defined').
+   function 'quit' declared but never defined').
  * Updated all headers and rights.
  * Updated GPL-2 text in all headers and in COPYING files.
- * Using txt2man to produce an updated manpage.
 
     [ Bernhard Übelacker ]
 

NEWS

@@ -1,5 +1,11 @@
 Version 1.5
 -----------
 
-New options: limit, using bytes in sizeprobe and MAC/WIN in split format.
+New options:
+  - limit
+  - using bytes in sizeprobe
+  - MAC/WIN in split format
+
+Added several examples in manpage.
+
 See the manpage.

man/create-man.sh

@@ -5,7 +5,7 @@
 #
 # This script can be used under BSD-3-Clause license.
 
-T2M_DATE="30 Oct 2019"
+T2M_DATE="01 Nov 2019"
 T2M_NAME=dcfldd
 T2M_VERSION=1.5
 T2M_LEVEL=1

man/dcfldd.1

@@ -1,5 +1,5 @@
 .\" Text automatically generated by txt2man
-.TH dcfldd 1 "30 Oct 2019" "dcfldd-1.5" "enhanced version of dd for forensics and security"
+.TH dcfldd 1 "01 Nov 2019" "dcfldd-1.5" "enhanced version of dd for forensics and security"
 .SH NAME
 \fBdcfldd \fP- enhanced version of dd for forensics and security
 \fB
@@ -39,6 +39,10 @@ natively.
 .IP \(bu 3
 When dd uses a default block size (bs, ibs, obs) of 512 bytes, \fBdcfldd\fP uses 32768 bytes (32 KiB)
 which is HUGELY more efficient.
+.IP \(bu 3
+The following options are present in \fBdcfldd\fP but not in dd: ALGORITHMlog:, errlog, hash, hashconv,
+hashformat, hashlog, hashlog:, hashwindow, limit, of:, pattern, sizeprobe, split, splitformat,
+statusinterval, textpattern, totalhashformat, verifylog, verifylog:, vf.
 .PP
 \fBdcfldd\fP supports the following letters to specify amount of data: k for kilo, M for Mega, G for Giga,
 T for Tera, P for Peta, E for Exa, Z for Zetta and Y for Yotta. E.g. 10M is equal to 10 MiB. See
@@ -47,8 +51,9 @@ the BLOCKS AND BYTES section to get other possibilities.
 .TP
 .B
 bs=BYTES
-Force ibs=BYTES and obs=BYTES. Default value is 32768 (32KiB). (see BLOCKS AND BYTES
-section)
+Force ibs=BYTES and obs=BYTES. Default value is 32768 (32KiB). See BLOCKS AND BYTES
+section. Warning: the block size will be created in RAM. Make sure you have sufficient
+amount of free memory.
 .TP
 .B
 cbs=BYTES
@@ -97,30 +102,32 @@ Skip BLOCKS ibs-sized blocks at start of input. (see BLOCKS AND BYTES section)
 .TP
 .B
 pattern=HEX
-Use the specified binary pattern as input.
+Use the specified binary pattern as input. You can use a byte only.
 .TP
 .B
 textpattern=TEXT
-Use repeating TEXT as input.
+Use repeating TEXT as input. You can use a character only.
 .TP
 .B
 errlog=FILE
 Send error messages to FILE as well as stderr.
 .TP
 .B
-hashwindow=BYTES
-Perform a hash on every BYTES amount of data.
-.TP
-.B
 hash=NAME
-Either md5, sha1, sha256, sha384 or sha512. Default algorithm is md5. To select multiple
-algorithms to run simultaneously enter the names in a comma separated list.
+Do hash calculation in parallel with the disk reading. Either md5, sha1, sha256, sha384
+or sha512 can be used. Default algorithm is md5. To select multiple algorithms to run
+simultaneously enter the names in a comma separated list.
 .TP
 .B
 hashlog=FILE
-Send MD5 hash output to FILE instead of stderr. If you are using multiple hash algorithms
-you can send each to a separate file using the convention ALGORITHMlog=FILE, for example
-md5log=FILE1, sha1log=FILE2, etc.
+Send hash output to FILE instead of stderr. If you are using multiple hash
+algorithms you can send each to a separate file using the convention ALGORITHMlog=FILE,
+for example md5log=FILE1, sha1log=FILE2, etc.
+.TP
+.B
+hashwindow=BYTES
+Perform a hash on every BYTES amount of data. The partial results will be shown in
+screen. The default hash is md5 but you can use hash= option to choose other.
 .TP
 .B
 hashlog:=COMMAND
@@ -154,35 +161,38 @@ Update the status message every N blocks. Default value is 256.
 .TP
 .B
 sizeprobe=[if|of|BYTES]
-Determine the size of the input or output file or an amount of BYTES for use with
-status messages. This option gives you a percentage indicator around the sizeprobe
-value. WARNING: do not use this option against a tape device. (see BLOCKS AND
-BYTES section)
+Determine the size of the input or output file or an amount of BYTES for use
+with status messages. This option gives you a percentage indicator around the
+sizeprobe value. WARNING: do not use this option against a tape device. (see
+BLOCKS AND BYTES section)
 .TP
 .B
 split=BYTES
 Write every BYTES amount of data to a new file. This operation applies to any
-of=FILE that follows. (see BLOCKS AND BYTES section)
+of=FILE that follows (split= must be put before of=). (see BLOCKS AND BYTES
+section)
 .TP
 .B
 splitformat=[TEXT|MAC|WIN]
-The file extension format for split operation. You may use "a" for letters and "n"
-for numbers. If you use annn, an extension started as a000 will be appended; the
-last possible extension for this format will be z999. splitformat=an will provide
-a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, b0, b1, b2\.\.\. If nothing is specified the
-default format is "nnn". NOTE: the split and splitformat options take effect only
-for output files (option of=) specified AFTER these options appear in the command
-line (e.g. split=50M splitformat=annn of=/tmp/test.iso). Likewise, you may specify
-these several times for different output files within the same command line. You
-may use as many digits in any combination you would like. E.g. "anaannnaana"
-would be valid, but quite insane (see BLOCKS AND BYTES section). Other possible
-approach is MAC. If "MAC" is used, a suffix dmg and several dmgpart will be
-appended. In other words, it will generate a partial disk image file, used by
-the Mac OS X operating system. dmgpart files are usually provided with a
-corresponding dmg file, which is the master file for the split archive. If dmg
-is opened in Mac OS X, all dmgpart will be read too. The last option is WIN,
-which will automatically output file naming of foo.001, foo.002, \.\.\., foo.999,
-foo.1000, \.\.\..
+The file extension format for split operation. You may use "a" for letters
+and "n" for numbers. If you use annn, an extension started as a000 will be
+appended; the last possible extension for this format will be z999.
+splitformat=an will provide a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, b0, b1,
+b2, b3\.\.\. If nothing is specified the default format is "nnn". NOTE: the split
+and splitformat options take effect only for output files (option of=) specified
+AFTER these options appear in the command line (e.g. split=50M splitformat=annn
+of=/tmp/test.iso).
+Likewise, you may specify it several times for different output files within
+the same command line. You may use as many digits in any combination you would
+like. E.g. "anaannnaana" would be valid, but a quite insane (see BLOCKS AND BYTES
+section).
+Other possible approach is MAC. If "MAC" is used, a suffix dmg and several
+dmgpart will be appended. In other words, it will generate a partial disk image
+file, used by the Mac OS X operating system. dmgpart files are usually provided
+with a corresponding dmg file, which is the master file for the split archive.
+If dmg is opened in Mac OS X, all dmgpart will be read too. The last option is
+WIN, which will automatically output file naming of foo.001, foo.002, \.\.\.,
+foo.999, foo.1000, \.\.\..
 .TP
 .B
 vf=FILE
@@ -251,14 +261,14 @@ Continue after read errors.
 .TP
 .B
 sync
-Pad every input block with NULs to ibs-size. When used with block or unblock, pad with spaces rather
-than NULs.
+Pad every input block with NULs to ibs-size. When used with block or unblock, pad with spaces
+rather than NULs.
 .SH FORMAT
 The structure of FORMAT may contain any valid text and special variables. The built-in variables are the
-following format: #variable_name#. To pass FORMAT strings to the program from a command line, it may be necessary to
+following format: #variable_name#. To pass FORMAT strings to the program from a command line, it may be
 .TP
 .B
-surround your FORMAT strings with "quotes."
+necessary to surround your FORMAT strings with "quotes."
 The built-in variables are listed below:
 .TP
 .B
@@ -297,23 +307,134 @@ The FORMAT structure accepts the following escape codes:
 .TP
 .B
 \\n
-Newline.
+Newline
 .TP
 .B
 \\t
-Tab.
+Tab
 .TP
 .B
 \\r
-Carriage return.
+Carriage return
 .TP
 .B
 \\
-Insert the '\\' character.
+Insert the '\\' character
 .TP
 .B
 ##
-Insert the '#' character as text, not a variable.
+Insert the '#' character as text, not a variable
+.SH EXAMPLES
+
+Each following line will create a 100 MiB file containing zeros:
+.PP
+.nf
+.fam C
+    $ dcfldd if=/dev/zero of=test bs=1M count=100
+    $ dcfldd if=/dev/zero of=test bs=100M count=1
+    $ dcfldd if=/dev/zero of=test bs=50M count=2
+    $ dcfldd if=/dev/zero of=test limit=100M
+
+.fam T
+.fi
+To create a copy (forensics image) from a disk called /dev/sdb inside a file, using input/output blocks
+of 4096 bytes (4 KiB) instead of 32 KiB (default):
+.PP
+.nf
+.fam C
+    $ dcfldd if=/dev/sdb bs=4096 of=sdb.img
+
+.fam T
+.fi
+As the last example, plus calculating MD5 and SHA256 hashes, putting the results inside sdb.md5 and
+sdb.sha256. It is very useful for forensics works because the hashes will be processed in real time,
+avoiding a waste of time to make something as 'dd + md5 + sha256'. Considering that I/O disk is very
+slow and RAM is very fast, the hashes will be calculated, bit per bit in memory, when the next portion
+of the disk is read. When all disk was read, all hashes are now ready.
+.PP
+.nf
+.fam C
+    $ dcfldd if=/dev/sdb bs=4096 hash=md5,sha256 md5log=sdb.md5 sha256log=sdb.sha256 of=sdb.img
+
+.fam T
+.fi
+To validate the image file against the original source:
+.PP
+.nf
+.fam C
+    $ dcfldd if=/dev/sdb vf=sdb.img
+
+.fam T
+.fi
+Splitting the image in 500 MiB slices, using the default bs value (32 KiB). Note that split= must be
+put before of= to work:
+.PP
+.nf
+.fam C
+    $ dcfldd if=/dev/sdb split=500M of=sdb.img
+
+.fam T
+.fi
+At the last example, using from a0000 up to z9999 as suffix for each split file:
+.PP
+.nf
+.fam C
+    $ dcfldd if=/dev/sdb split=500M splitformat=annnn of=sdb.img
+
+.fam T
+.fi
+Now, \fBdcfldd\fP will work byte per byte (bs=1) and will hop 1056087439 bytes. After this, \fBdcfldd\fP will collect
+200000 bytes and write the results to a file called airplane.jpg.
+.PP
+.nf
+.fam C
+    $ dcfldd if=/dev/sda3 bs=1 skip=1056087439 count=200000 of=airplane.jpg
+
+.fam T
+.fi
+In the last example, the same result could be obtained using "limit" instead of "count". The main
+difference is that count uses 200000*bs and limit uses 200000 bytes (regardless of the value declared in
+bs option):
+.PP
+.nf
+.fam C
+    $ dcfldd if=/dev/sda3 bs=1 skip=1056087439 limit=200000 of=airplane.jpg
+
+.fam T
+.fi
+To write something inside a file, you can use seek. Suppose you want to write a message from a file called
+message.txt inside a file called target.iso, hopping 200000 bytes from start of file:
+.PP
+.nf
+.fam C
+    $ dcfldd if=message.txt bs=1 seek=200000 of=target.iso
+
+.fam T
+.fi
+\fBdcfldd\fP also can send a result to be processed by an external command:
+.PP
+.nf
+.fam C
+    $ dcfldd if=text.txt  of:="cat | sort -u"
+
+.fam T
+.fi
+To convert a file from ASCII to EBCDIC:
+.PP
+.nf
+.fam C
+    $ dcfldd if=text.asc conv=ebcdic of=text.ebcdic
+
+.fam T
+.fi
+To convert a file from EBCDIC to ASCII:
+.PP
+.nf
+.fam C
+    $ dcfldd if=text.ebcdic conv=ascii of=text.asc
+
+.fam T
+.fi
 .SH SEE ALSO
 \fBdd\fP(1)
 .SH REPORTING BUGS