# sg_xcopy(8) - man - phpMan [SG_XCOPY(8)](https://www.chedong.com/phpMan.php/man/SGXCOPY/8/markdown) SG3_UTILS [SG_XCOPY(8)](https://www.chedong.com/phpMan.php/man/SGXCOPY/8/markdown) ## NAME sg_xcopy - copy data to and from files and devices using SCSI EXTENDED COPY (XCOPY) ## SYNOPSIS **sg**___**xcopy** [_bs=BS_] [_conv=CONV_] [_count=COUNT_] [_ibs=BS_] [_if=IFILE_] [_iflag=FLAGS_] [_obs=BS_] [_of=OFILE_] [_oflag=FLAGS_] [_seek=SEEK_] [_skip=SKIP_] [_--help_] [_--version_] [_app=_0|1] [_bpt=BPT_] [_cat=_0|1] [_dc=_0|1] [_fco=_0|1] [_id_usage=_{hold|discard|disable}] [_list_id=ID_] [_prio=PRIO_] [_time=_0|1] [_verbose=VERB_] [_--on_dst|--on_src_] [_--verbose_] ## DESCRIPTION Copy data to and from any files. Specialized for "files" that are Linux SCSI devices that support the SCSI EXTENDED COPY (XCOPY) command. This utility has similar syntax and semantics to [**dd(1)](https://www.chedong.com/phpMan.php/man/dd/1/markdown)** but with no "conversions" is sup‐ ported. The first group in the synopsis above are "standard" Unix [**dd(1)](https://www.chedong.com/phpMan.php/man/dd/1/markdown)** operands. The second group are extra options added by this utility. Both groups are defined below in combined, alpha‐ betical order. By default the XCOPY command is sent to _OFILE_. This can be changed with the _--on_src_ or _iflag=xflag_ options which cause the XCOPY command to be sent to _IFILE_ instead. Also see the section on ENVIRONMENT VARIABLES. In the SPC-4 standard the T10 committee has expanded the XCOPY command so that it now has two variants: "LID1" (for a List Identifier length of 1 byte) and "LID4" (for a List Identifier length of 4 bytes). This utility supports the older, LID1 variant which is also found in SPC-3 and earlier. While the LID1 variant in SPC-4 is command level (binary) compatible with XCOPY as defined in SPC-3, some of the command naming has changed. This utility uses the older, SPC-3 XCOPY names. The ddpt utility supports the same xcopy(LID1) functionality as this utility with the same options and flags. Additionally ddpt supports a subset of xcopy(LID4) functionality variously called "xcopy version 2, lite" or ODX. ODX is a market name and stands for Offloaded Data Xfer (i.e. transfer). ## OPTIONS **app**={0|1} if 1 start the destination of the copy at the end of OFILE. This assumes that OFILE is a regular file. The default is 0 in which case the destination of the copy starts at the beginning of OFILE (possibly offset be SEEK). This option cannot be used with the _seek=SEEK_ option. **bpt**=_BPT_ each IO transaction will be made using _BPT_ blocks (or less if near the end of the copy). Default is 128 for logical block sizes less that 2048 bytes, otherwise the de‐ fault is 32. So for bs=512 the reads and writes will each convey 64 KiB of data by de‐ fault (less if near the end of the transfer or memory restrictions). When cd/dvd drives are accessed, the logical block size is typically 2048 bytes and bpt defaults to 32 which again implies 64 KiB transfers. **bs**=_BS_ where _BS_ **must** be the logical block size of the physical device (if either the input or output files are accessed via SCSI commands). Note that this differs from [**dd(1)](https://www.chedong.com/phpMan.php/man/dd/1/markdown)** which permits _BS_ to be an integral multiple. Defaults to the device logical block size. **cat**={0|1} sets the SCSI EXTENDED COPY command segment descriptor CAT bit to 0 or 1 (default: 0). The CAT bit (in conjunction with the PAD bit) controls the handling of residual data. See section **HANDLING** **OF** **RESIDUAL** **DATA** for details. **conv**=**CONV** all **CONV** arguments are ignored. **count**=_COUNT_ copy _COUNT_ blocks from _IFILE_ to _OFILE_. Default is the minimum (_IFILE_ if _dc=0_ or _OFILE_ if _dc=1_) 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 _skip=SKIP_ or _seek=SEEK_ are given and the count is derived (i.e. not explic‐ itly 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 _COUNT_ is not given then the size of the partition rather than the size of the whole device is used. If _COUNT_ is not given (or _count=-1_) and cannot be derived then an error message is issued and no copy takes place. **dc**={0|1} sets the SCSI EXTENDED COPY command segment descriptor DC bit to 0 or 1 (default: 0). The DC bit controls whether _COUNT_ refers to the source (_dc=0_) or the target (_dc=1_) de‐ scriptor. **fco**={0|1} sets the SCSI EXTENDED COPY command segment descriptor FCO bit to 0 or 1 (default: 0). The Fast Copy Only (FCO) bit set will result in the copy being done but a technique faster than SCSI READ and WRITE commands. If the copy cannot but done in a faster manner then a sense key of "Copy aborted" with and additional sense of "Fast copy not possible" is returned. **ibs**=_BS_ if given must be the same as _BS_ given to 'bs=' option. **id**___**usage**={hold|discard|disable} sets the SCSI EXTENDED COPY command parameter list field called LIST ID USAGE to 0 if the argument is 'hold', to 2 if the argument is 'discard', or to '3' if the argument is 'disable'. If the device has the ability to hold data (as indicated by "held data limit" being greater than zero) then _id_usage_ defaults to 'hold' otherwise it defaults to 'dis‐ card'. **if**=_IFILE_ read from _IFILE_ instead of stdin. If _IFILE_ is '-' then stdin is read. Starts reading at the beginning of _IFILE_ unless _SKIP_ is given. **iflag**=_FLAGS_ where _FLAGS_ is a comma separated list of one or more flags outlined below. These flags are associated with _IFILE_ and are ignored when _IFILE_ is stdin. **list**___**id**=_ID_ sets the SCSI EXTENDED COPY command parameter list field called LIST IDENTIFIER to _ID_. _ID_ should be a value between 0 and 255 (inclusive). _ID_ usually defaults to 1 unless _id_usage=disable_ in which case it defaults to 0. **obs**=_BS_ if given must be the same as _BS_ given to 'bs=' option. **of**=_OFILE_ write to _OFILE_ instead of stdout. If _OFILE_ is '-' then writes to stdout. If _OFILE_ is /dev/null then no actual writes are performed. If _OFILE_ is '.' (period) then it is treated the same way as /dev/null (this is a shorthand notation). If _OFILE_ exists then it is _not_ truncated; it is overwritten from the start of _OFILE_ unless 'oflag=append' or _SEEK_ is given. **oflag**=_FLAGS_ where _FLAGS_ is a comma separated list of one or more flags outlined below. These flags are associated with _OFILE_ and are ignored when _OFILE_ is /dev/null, '.' (period), or stdout. **prio**=_PRIO_ sets the SCSI EXTENDED COPY command parameter list field called PRIORITY to _PRIO_. The default value is 1. **seek**=_SEEK_ start writing _SEEK_ bs-sized blocks from the start of _OFILE_. Default is block 0 (i.e. start of file). **skip**=_SKIP_ start reading _SKIP_ bs-sized blocks from the start of _IFILE_. Default is block 0 (i.e. start of file). **time**={0|1} when 1, times transfer and does throughput calculation, outputting the results (to stderr) at completion. When 0 (default) doesn't perform timing. **verbose**=_VERB_ as _VERB_ 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 in‐ formation that is not repetitive. A value 2 reports cdbs and responses for SCSI com‐ mands 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. ### -h --help outputs usage message and exits. **--on**___**dst** send the XCOPY command to the output file/device (i.e. _OFILE_). This is the default un‐ less overridden by the _--on_src_ or _iflag=xflag_ options. Also see the section below on ENVIRONMENT VARIABLES. **--on**___**src** send the XCOPY command to the input file/device (i.e. _IFILE_). ### -v --verbose equivalent to _verbose=1_. When used twice, equivalent to _verbose=2_, etc. ### -V --version outputs version number information and exits. ## FLAGS Here is a list of flags and their meanings: append causes the O_APPEND flag to be added to the open of _OFILE_. For regular files this will lead to data appended to the end of any existing data. Cannot be used together with the _seek=SEEK_ option as they conflict. The default action of this utility is to over‐ write any existing data from the beginning of the file or, if _SEEK_ is given, starting at block _SEEK_. 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. excl causes the O_EXCL flag to be added to the open of _IFILE_ and/or _OFILE_. flock after opening the associated file (i.e. _IFILE_ and/or _OFILE_) 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 "tem‐ porarily unavailable" error is generated. An exit status of 90 is produced in the lat‐ ter case and no copy is done. null has no affect, just a placeholder. pad sets the SCSI EXTENDED COPY command segment descriptor PAD bit. The PAD bit (in con‐ junction with the CAT bit) controls the handling of residual data.(See section **HAN**‐‐ **DLING** **OF** **RESIDUAL** **DATA** for details. xcopy has no affect; for compatibility with ddpt. ## HANDLING OF RESIDUAL DATA The _pad_ and _cat_ bits control the handling of residual data. As the data can be specified ei‐ ther in terms of source or target logical block size and both might have different block sizes residual data is likely to happen in these cases. If both logical block sizes are identical these bits have no effect as residual data will not occur. If none of these bits are set, the EXTENDED COPY command will be aborted with additional sense 'UNEXPECTED INEXACT SEGMENT'. If only the _cat_ bit is set the residual data will be retained and made available for subse‐ quent segment descriptors. Residual data will be discarded for the last segment descriptor. If the _pad_ bit is set for the source descriptor only, any residual data for both source or destination will be discarded. If the _pad_ bit is set for the target descriptor only any residual source data will be handled as if the _cat_ bit is set, but any residual destination data will be padded to make a whole block transfer. If the _pad_ bit is set for both source and target any residual source data will be discarded, and any residual destination data will be padded. ## ENVIRONMENT VARIABLES If the command line invocation does not explicitly (and unambiguously) indicate whether the XCOPY SCSI command should be sent to _IFILE_ (i.e. the source) or _OFILE_ (i.e. the destination) then a check is made for the presence of the XCOPY_TO_SRC and XCOPY_TO_DST environment vari‐ ables. If either one exists (but not both) then it indicates where the SCSI XCOPY command will be sent. By default the XCOPY command is sent to _OFILE_. ## RETIRED OPTIONS Here are some retired options that are still present: append=0 | 1 when set, equivalent to 'oflag=append'. When clear the action is to overwrite the ex‐ isting file (if it exists); this is the default. See the 'append' flag. ## NOTES Copying data behind an Operating System's back can cause problems. In the case of Linux, users should look at this link: This command sequence may be useful: sync; echo 3 > /proc/sys/vm/drop_caches Various numeric arguments (e.g. _SKIP_) may include multiplicative suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section in the [sg3_utils(8)](https://www.chedong.com/phpMan.php/man/sg3utils/8/markdown) man page. The _COUNT_, _SKIP_ and _SEEK_ arguments can take 64 bit values (i.e. very big numbers). Other val‐ ues are limited to what can fit in a signed 32 bit number. 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. If a device supports xcopy operations then it should set the 3PC field (3PC stands for Third Party Copy) in its standard INQUIRY response. This utility will attempt a xcopy operation irrespective of the value in the 3PC field but if it is zero (cleared) one would expect the xcopy operation to fail. The status of the SCSI EXTENDED COPY command can be queried with **sg**___**copy**___**results(sg3**___**utils)** Currently only block-to-block transfers are implemented; _IFILE_ and _OFILE_ must refer to a SCSI block device. No account is taken of partitions so, for example, /dev/sbc2, /dev/sdc, /dev/sg2, and /dev/bsg/3:0:0:1 would all refer to the same thing: the whole logical unit (i.e. the whole disk) starting at LBA 0. So any partition indication (e.g. /dev/sdc2) is ignored. The user should set _SKIP_, _SEEK_ and _COUNT_ with information obtained from a command like 'fdisk -l -u /dev/sdc' to account for partitions. XCOPY (LID1) capability has been added to the ddpt utility which is in a package of the same name. The ddpt utility will run on other OSes (e.g. FreeBSD and Windows) while sg_xcopy only runs on Linux. Also ddpt permits the arguments to _ibs=_ and _ibs=_ to be different. ## EXAMPLES Copy 2M of data from the start of one device to another: # sg_xcopy if=/dev/sdo of=/dev/sdp count=2048 list_id=2 dc=1 sg_xcopy: if=/dev/sdo skip=0 of=/dev/sdp seek=0 count=1024 Start of loop, count=1024, bpt=65535, lba_in=0, lba_out=0 sg_xcopy: 1024 blocks, 1 command Check the status of the EXTENDED COPY command: # sg_copy_results --status --list_id=2 /dev/sdp Receive copy results (copy status): Held data discarded: Yes Copy manager status: Operation completed without errors Segments processed: 1 Transfer count units: 0 Transfer count: 0 ## 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. ## EXIT STATUS The exit status of sg_xcopy is 0 when it is successful. Otherwise see the [sg3_utils(8)](https://www.chedong.com/phpMan.php/man/sg3utils/8/markdown) man page. An additional exit status of 90 is generated if the flock flag is given and some other process holds the advisory exclusive lock. ## AUTHORS Written by Hannes Reinecke and Douglas Gilbert. ## REPORTING BUGS Report bugs to . ## COPYRIGHT Copyright © 2000-2019 Hannes Reinecke and Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MER‐ CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. ## SEE ALSO There is a web page discussing sg_dd at A POSIX threads version of this utility called **sgp**___**dd** is in the sg3_utils package. Another version from that package is called **sgm**___**dd** and it uses memory mapped IO to speed transfers from sg devices. The lmbench package contains **lmdd** which is also interesting. For moving data to and from tapes see **dt** which is found at To change mode parameters that effect a SCSI device's caching and error recovery see **sd**‐‐ ### parm(sdparm) See also [**dd(1)](https://www.chedong.com/phpMan.php/man/dd/1/markdown),** **sg**___**copy**___**results(sg3**___**utils),** **ddrescue(GNU),** **ddpt,ddptctl(ddpt)** sg3_utils-1.45 February 2019 [SG_XCOPY(8)](https://www.chedong.com/phpMan.php/man/SGXCOPY/8/markdown)