manpages for sg_xcopy and sg_copy_results; sg_dd cleanup

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@452 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 246 insertions, 0 deletions

diff --git a/doc/sg_xcopy.8 b/doc/sg_xcopy.8
new file mode 100644
index 00000000..1c9ecdfa
--- /dev/null
+++ b/doc/sg_xcopy.8
@@ -0,0 +1,246 @@
+.TH SG_XCOPY "8" "September 2012" "sg3_utils\-1.34" SG3_UTILS
+.SH NAME
+sg_xcopy \- copies data to and from files and devices. Specialised for
+devices that support the SCSI EXTENDED COPY command.
+.SH SYNOPSIS
+.B sg_xcopy
+[\fIbs=BS\fR] [\fIconv=CONV\fR] [\fIcount=COUNT\fR] [\fIibs=BS\fR]
+[\fIif=IFILE\fR] [\fIiflag=FLAGS\fR] [\fIobs=BS\fR] [\fIof=OFILE\fR]
+[\fIoflag=FLAGS\fR] [\fIseek=SEEK\fR] [\fIskip=SKIP\fR] [\fI\-\-help\fR]
+[\fI\-\-version\fR]
+.PP
+[\fIbpt=BPT\fR] [\fIcat=\fR0|1] [\fIdc=\fR0|1] [\fIid_usage=\fRhold|discard]
+[\fIlist_id=ID\fR] [\fIprio=PRIO\fR] [\fItime=\fR0|1] [\fIverbose=VERB\fR]
+[\fI\-h\fR] [\fI\-V\fR]
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Copy data to and from any files. Specialized for "files" that are Linux SCSI
+devices that support the SCSI EXTENDED COPY command. Similar syntax and
+semantics to
+.B dd(1)
+but with no "conversions" is supported.
+.PP
+The first group in the synopsis above are "standard" Unix
+.B dd(1)
+operands. The second group are extra options added by this utility.
+Both groups are defined below.
+.SH OPTIONS
+.TP
+\fBbpt\fR=\fIBPT\fR
+each IO transaction will be made using \fIBPT\fR blocks (or less if near
+the end of the copy). Default is 128 for block sizes less that 2048
+bytes, otherwise the default is 32. So for bs=512 the reads and writes
+will each convey 64 KiB of data by default (less if near the end of the
+transfer or memory restrictions). When cd/dvd drives are accessed, the
+block size is typically 2048 bytes and bpt defaults to 32 which again
+implies 64 KiB transfers.
+.TP
+\fBbs\fR=\fIBS\fR
+where \fIBS\fR
+.B must
+be the block size of the physical device (if either the input or output
+files are accessed via SCSI commands). Note that this differs from
+.B dd(1)
+which permits \fIBS\fR to be an integral multiple. Default is 512 which
+is usually correct for disks but incorrect for cdroms (which normally
+have 2048 byte blocks). For this utility the maximum size of each individual
+IO operation is \fIBS\fR * \fIBPT\fR bytes.
+.TP
+\fBcat\fR=0 | 1
+sets the SCSI EXTENDED COPY command segment descriptor CAT bit to 0 or
+1 (default: 0).
+.TP
+\fBdc\fR=0 | 1
+sets the SCSI EXTENDED COPY command segment descriptor DC bit to 0 or
+1 (default: 0).
+.TP
+\fBconv\fR=\fBCONV\fR
+all \fBCONV\fR arguments are ignored.
+.TP
+\fBcount\fR=\fICOUNT\fR
+copy \fICOUNT\fR blocks from \fIIFILE\fR to \fIOFILE\fR. Default is the
+minimum (of \fIIFILE\fR and \fIOFILE\fR) number of blocks that SCSI devices
+report from SCSI READ CAPACITY commands or that block devices (or their
+partitions) report. Normal files are not probed for their size. If
+\fIskip=SKIP\fR or \fIskip=SEEK\fR are given and the count is derived (i.e.
+not explicitly given) then the derived count is scaled back so that the
+copy will not overrun the device. If the file name is a block device
+partition and \fICOUNT\fR is not given then the size of the partition
+rather than the size of the whole device is used. If \fICOUNT\fR is not
+given (or \fIcount=-1\fR) and cannot be derived then an error message is
+issued and no copy takes place.
+.TP
+\fBibs\fR=\fIBS\fR
+if given must be the same as \fIBS\fR given to 'bs=' option.
+.TP
+\fBid_usage\fR=hold | discard
+sets the SCSI EXTENDED COPY command parameter list field called LIST ID
+USAGE to 0 if the argument is 'hold' or to 2 if the argument is 'discard'.
+.TP
+\fBif\fR=\fIIFILE\fR
+read from \fIIFILE\fR instead of stdin. If \fIIFILE\fR is '\-' then stdin
+is read. Starts reading at the beginning of \fIIFILE\fR unless \fISKIP\fR
+is given.
+.TP
+\fBiflag\fR=\fIFLAGS\fR
+where \fIFLAGS\fR is a comma separated list of one or more flags outlined
+below.  These flags are associated with \fIIFILE\fR and are ignored when
+\fIIFILE\fR is stdin.
+.TP
+\fBobs\fR=\fIBS\fR
+if given must be the same as \fIBS\fR given to 'bs=' option.
+.TP
+\fBof\fR=\fIOFILE\fR
+write to \fIOFILE\fR instead of stdout. If \fIOFILE\fR is '\-' then writes
+to stdout.  If \fIOFILE\fR is /dev/null then no actual writes are performed.
+If \fIOFILE\fR is '.' (period) then it is treated the same way as
+/dev/null (this is a shorthand notation). If \fIOFILE\fR exists then it
+is _not_ truncated; it is overwritten from the start of \fIOFILE\fR
+unless 'oflag=append' or \fISEEK\fR is given.
+.TP
+\fBoflag\fR=\fIFLAGS\fR
+where \fIFLAGS\fR is a comma separated list of one or more flags outlined
+below.  These flags are associated with \fIOFILE\fR and are ignored when
+\fIOFILE\fR is /dev/null, '.' (period), or stdout.
+.TP
+\fBlist_id\fR=\fIID\fR
+sets the SCSI EXTENDED COPY command parameter list field called LIST
+IDENTIFIER to \fIID\fR. \fIID\fR should be a value between 0 and
+255 (inclusive) and the default value is 1.
+.TP
+\fBprio\fR=\fIPRIO\fR
+sets the SCSI EXTENDED COPY command parameter list field called PRIORITY
+to \fIPRIO\fR.  The default value is 1.
+.TP
+\fBseek\fR=\fISEEK\fR
+start writing \fISEEK\fR bs\-sized blocks from the start of \fIOFILE\fR.
+Default is block 0 (i.e. start of file).
+.TP
+\fBskip\fR=\fISKIP\fR
+start reading \fISKIP\fR bs\-sized blocks from the start of \fIIFILE\fR.
+Default is block 0 (i.e. start of file).
+.TP
+\fBtime\fR=0 | 1
+when 1, times transfer and does throughput calculation, outputting the
+results (to stderr) at completion. When 0 (default) doesn't perform timing.
+.TP
+\fBverbose\fR=\fIVERB\fR
+as \fIVERB\fR increases so does the amount of debug output sent to stderr.
+Default value is zero which yields the minimum amount of debug output.
+A value of 1 reports extra information that is not repetitive. A value
+2 reports cdbs and responses for SCSI commands that are not repetitive
+(i.e. other that READ and WRITE). Error processing is not considered
+repetitive. Values of 3 and 4 yield output for all SCSI commands (and
+Unix read() and write() calls) so there can be a lot of output.
+.TP
+\fB\-\-help\fR
+outputs usage message and exits.
+.TP
+\fB\-\-version\fR
+outputs version number information and exits.
+.TP
+\fB\-h\fR
+outputs usage message and exits.
+.TP
+\fB\-V\fR
+outputs version number information and exits.
+.SH FLAGS
+Here is a list of flags and their meanings:
+.TP
+append
+causes the O_APPEND flag to be added to the open of \fIOFILE\fR. For regular
+files this will lead to data appended to the end of any existing data.
+Cannot be used together with the \fIseek=SEEK\fR option as they conflict.
+The default action of this utility is to overwrite any existing data
+from the beginning of the file or, if \fISEEK\fR is given, starting at
+block \fISEEK\fR. Note that attempting to 'append' to a device file (e.g.
+a disk) will usually be ignored or may cause an error to be reported.
+.TP
+cat
+sets the SCSI EXTENDED COPY command segment descriptor CAT bit.
+.TP
+dc
+sets the SCSI EXTENDED COPY command segment descriptor DC bit.
+.TP
+excl
+causes the O_EXCL flag to be added to the open of \fIIFILE\fR and/or
+\fIOFILE\fR.
+.TP
+flock
+after opening the associated file (i.e. \fIIFILE\fR and/or \fIOFILE\fR)
+an attempt is made to get an advisory exclusive lock with the flock()
+system call. The flock arguments are "FLOCK_EX | FLOCK_NB" which will
+cause the lock to be taken if available else a "temporarily unavailable"
+error is generated. An exit status of 90 is produced in the latter case
+and no copy is done.
+.TP
+null
+has no affect, just a placeholder.
+.SH RETIRED OPTIONS
+Here are some retired options that are still present:
+.TP
+append=0 | 1
+when set, equivalent to 'oflag=append'. When clear the action is
+to overwrite the existing file (if it exists); this is the default.
+See the 'append' flag.
+.SH NOTES
+Various numeric arguments (e.g. \fISKIP\fR) may include multiplicative
+suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
+in the sg3_utils(8) man page.
+.PP
+The \fICOUNT\fR, \fISKIP\fR and \fISEEK\fR arguments can take 64 bit
+values (i.e. very big numbers). Other values are limited to what can fit in
+a signed 32 bit number.
+.PP
+All informative, warning and error output is sent to stderr so that
+dd's output file can be stdout and remain unpolluted. If no options
+are given, then the usage message is output and nothing else happens.
+.PP
+Disk partition information can often be found with
+.B fdisk(8)
+[the "\-ul" argument is useful in this respect].
+.SH EXAMPLES
+xxxxxxxxx >>>> Some examples might be (very) useful!
+.SH SIGNALS
+The signal handling has been borrowed from dd: SIGINT, SIGQUIT and
+SIGPIPE output the number of remaining blocks to be transferred and
+the records in + out counts; then they have their default action.
+SIGUSR1 causes the same information to be output yet the copy continues.
+All output caused by signals is sent to stderr.
+.SH EXIT STATUS
+The exit status of sg_xcopy is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.PP
+An additional exit status of 90 is generated if the flock flag is given
+and some other process holds the advisory exclusive lock.
+.SH AUTHORS
+Written by Hannes Reinecke and Douglas Gilbert.
+.SH "REPORTING BUGS"
+Report bugs to <dgilbert at interlog dot com>.
+.SH COPYRIGHT
+Copyright \(co 2000\-2012 Hannes Reinecke and Douglas Gilbert
+.br
+This software is distributed under the GPL version 2. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+There is a web page discussing sg_dd at http://sg.danny.cz/sg/sg_dd.html
+.PP
+A POSIX threads version of this utility called
+.B sgp_dd
+is in the sg3_utils package. Another version from that package is called
+.B sgm_dd
+and it uses memory mapped IO to speed transfers from sg devices.
+.PP
+The lmbench package contains
+.B lmdd
+which is also interesting. For moving data to and from tapes see
+.B dt
+which is found at http://www.scsifaq.org/RMiller_Tools/index.html
+.PP
+To change mode parameters that effect a SCSI device's caching and error
+recovery see
+.B sdparm(sdparm)
+.PP
+See also
+.B dd(1), ddrescue(GNU), ddpt