{ "content": [ { "type": "text", "text": "# sg_xcopy(8) (man)\n\n**Summary:** sgxcopy - copy data to and from files and devices using SCSI EXTENDED COPY (XCOPY)\n\n**Synopsis:** sgxcopy [bs=BS] [conv=CONV] [count=COUNT] [ibs=BS] [if=IFILE] [iflag=FLAGS] [obs=BS]\n[of=OFILE] [oflag=FLAGS] [seek=SEEK] [skip=SKIP] [--help] [--version]\n[app=0|1] [bpt=BPT] [cat=0|1] [dc=0|1] [fco=0|1] [idusage={hold|discard|disable}]\n[listid=ID] [prio=PRIO] [time=0|1] [verbose=VERB] [--ondst|--onsrc] [--verbose]\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| -h | --help | — | outputs usage message and exits. --ondst send the XCOPY command to the output file/device (i.e. OFILE). This is the defa |\n| -v | --verbose | — | equivalent to verbose=1. When used twice, equivalent to verbose=2, etc. |\n| -V | --version | — | outputs version number information and exits. |\n\n## Examples\n\n- `Copy 2M of data from the start of one device to another:`\n- `# sgxcopy if=/dev/sdo of=/dev/sdp count=2048 listid=2 dc=1`\n- `sgxcopy: if=/dev/sdo skip=0 of=/dev/sdp seek=0 count=1024`\n- `Start of loop, count=1024, bpt=65535, lbain=0, lbaout=0`\n- `sgxcopy: 1024 blocks, 1 command`\n- `Check the status of the EXTENDED COPY command:`\n- `# sgcopyresults --status --listid=2 /dev/sdp`\n- `Receive copy results (copy status):`\n- `Held data discarded: Yes`\n- `Copy manager status: Operation completed without errors`\n- `Segments processed: 1`\n- `Transfer count units: 0`\n- `Transfer count: 0`\n\n## See Also\n\n- dd(1)\n- sgcopyresults(sg3utils)\n- ddrescue(GNU)\n- ddptctl(ddpt)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (6 lines)\n- **DESCRIPTION** (26 lines)\n- **OPTIONS** (110 lines) — 3 subsections\n - -h --help (10 lines)\n - -v --verbose (2 lines)\n - -V --version (2 lines)\n- **FLAGS** (25 lines)\n- **HANDLING OF RESIDUAL DATA** (21 lines)\n- **ENVIRONMENT VARIABLES** (6 lines)\n- **RETIRED OPTIONS** (6 lines)\n- **NOTES** (35 lines)\n- **EXAMPLES** (17 lines)\n- **SIGNALS** (5 lines)\n- **EXIT STATUS** (6 lines)\n- **AUTHORS** (2 lines)\n- **REPORTING BUGS** (2 lines)\n- **COPYRIGHT** (4 lines)\n- **SEE ALSO** (10 lines) — 1 subsections\n - parm(sdparm) (5 lines)\n\n## Full Content\n\n### NAME\n\nsgxcopy - copy data to and from files and devices using SCSI EXTENDED COPY (XCOPY)\n\n### SYNOPSIS\n\nsgxcopy [bs=BS] [conv=CONV] [count=COUNT] [ibs=BS] [if=IFILE] [iflag=FLAGS] [obs=BS]\n[of=OFILE] [oflag=FLAGS] [seek=SEEK] [skip=SKIP] [--help] [--version]\n\n[app=0|1] [bpt=BPT] [cat=0|1] [dc=0|1] [fco=0|1] [idusage={hold|discard|disable}]\n[listid=ID] [prio=PRIO] [time=0|1] [verbose=VERB] [--ondst|--onsrc] [--verbose]\n\n### DESCRIPTION\n\nCopy data to and from any files. Specialized for \"files\" that are Linux SCSI devices that\nsupport the SCSI EXTENDED COPY (XCOPY) command.\n\nThis utility has similar syntax and semantics to dd(1) but with no \"conversions\" is sup‐\nported.\n\nThe first group in the synopsis above are \"standard\" Unix dd(1) operands. The second group\nare extra options added by this utility. Both groups are defined below in combined, alpha‐\nbetical order.\n\nBy default the XCOPY command is sent to OFILE. This can be changed with the --onsrc or\niflag=xflag options which cause the XCOPY command to be sent to IFILE instead. Also see the\nsection on ENVIRONMENT VARIABLES.\n\nIn the SPC-4 standard the T10 committee has expanded the XCOPY command so that it now has two\nvariants: \"LID1\" (for a List Identifier length of 1 byte) and \"LID4\" (for a List Identifier\nlength of 4 bytes). This utility supports the older, LID1 variant which is also found in\nSPC-3 and earlier. While the LID1 variant in SPC-4 is command level (binary) compatible with\nXCOPY as defined in SPC-3, some of the command naming has changed. This utility uses the\nolder, SPC-3 XCOPY names.\n\nThe ddpt utility supports the same xcopy(LID1) functionality as this utility with the same\noptions and flags. Additionally ddpt supports a subset of xcopy(LID4) functionality variously\ncalled \"xcopy version 2, lite\" or ODX. ODX is a market name and stands for Offloaded Data\nXfer (i.e. transfer).\n\n### OPTIONS\n\napp={0|1}\nif 1 start the destination of the copy at the end of OFILE. This assumes that OFILE is\na regular file. The default is 0 in which case the destination of the copy starts at\nthe beginning of OFILE (possibly offset be SEEK). This option cannot be used with the\nseek=SEEK option.\n\nbpt=BPT\neach IO transaction will be made using BPT blocks (or less if near the end of the\ncopy). Default is 128 for logical block sizes less that 2048 bytes, otherwise the de‐\nfault is 32. So for bs=512 the reads and writes will each convey 64 KiB of data by de‐\nfault (less if near the end of the transfer or memory restrictions). When cd/dvd\ndrives are accessed, the logical block size is typically 2048 bytes and bpt defaults\nto 32 which again implies 64 KiB transfers.\n\nbs=BS where BS must be the logical block size of the physical device (if either the input or\noutput files are accessed via SCSI commands). Note that this differs from dd(1) which\npermits BS to be an integral multiple. Defaults to the device logical block size.\n\ncat={0|1}\nsets the SCSI EXTENDED COPY command segment descriptor CAT bit to 0 or 1 (default: 0).\nThe CAT bit (in conjunction with the PAD bit) controls the handling of residual data.\nSee section HANDLING OF RESIDUAL DATA for details.\n\nconv=CONV\nall CONV arguments are ignored.\n\ncount=COUNT\ncopy COUNT blocks from IFILE to OFILE. Default is the minimum (IFILE if dc=0 or OFILE\nif dc=1) number of blocks that SCSI devices report from SCSI READ CAPACITY commands or\nthat block devices (or their partitions) report. Normal files are not probed for their\nsize. If skip=SKIP or seek=SEEK are given and the count is derived (i.e. not explic‐\nitly given) then the derived count is scaled back so that the copy will not overrun\nthe device. If the file name is a block device partition and COUNT is not given then\nthe size of the partition rather than the size of the whole device is used. If COUNT\nis not given (or count=-1) and cannot be derived then an error message is issued and\nno copy takes place.\n\ndc={0|1}\nsets the SCSI EXTENDED COPY command segment descriptor DC bit to 0 or 1 (default: 0).\nThe DC bit controls whether COUNT refers to the source (dc=0) or the target (dc=1) de‐\nscriptor.\n\nfco={0|1}\nsets the SCSI EXTENDED COPY command segment descriptor FCO bit to 0 or 1 (default: 0).\nThe Fast Copy Only (FCO) bit set will result in the copy being done but a technique\nfaster than SCSI READ and WRITE commands. If the copy cannot but done in a faster\nmanner then a sense key of \"Copy aborted\" with and additional sense of \"Fast copy not\npossible\" is returned.\n\nibs=BS if given must be the same as BS given to 'bs=' option.\n\nidusage={hold|discard|disable}\nsets the SCSI EXTENDED COPY command parameter list field called LIST ID USAGE to 0 if\nthe argument is 'hold', to 2 if the argument is 'discard', or to '3' if the argument\nis 'disable'.\nIf the device has the ability to hold data (as indicated by \"held data limit\" being\ngreater than zero) then idusage defaults to 'hold' otherwise it defaults to 'dis‐\ncard'.\n\nif=IFILE\nread from IFILE instead of stdin. If IFILE is '-' then stdin is read. Starts reading\nat the beginning of IFILE unless SKIP is given.\n\niflag=FLAGS\nwhere FLAGS is a comma separated list of one or more flags outlined below. These\nflags are associated with IFILE and are ignored when IFILE is stdin.\n\nlistid=ID\nsets the SCSI EXTENDED COPY command parameter list field called LIST IDENTIFIER to ID.\nID should be a value between 0 and 255 (inclusive). ID usually defaults to 1 unless\nidusage=disable in which case it defaults to 0.\n\nobs=BS if given must be the same as BS given to 'bs=' option.\n\nof=OFILE\nwrite to OFILE instead of stdout. If OFILE is '-' then writes to stdout. If OFILE is\n/dev/null then no actual writes are performed. If OFILE is '.' (period) then it is\ntreated the same way as /dev/null (this is a shorthand notation). If OFILE exists then\nit is not truncated; it is overwritten from the start of OFILE unless 'oflag=append'\nor SEEK is given.\n\noflag=FLAGS\nwhere FLAGS is a comma separated list of one or more flags outlined below. These\nflags are associated with OFILE and are ignored when OFILE is /dev/null, '.' (period),\nor stdout.\n\nprio=PRIO\nsets the SCSI EXTENDED COPY command parameter list field called PRIORITY to PRIO. The\ndefault value is 1.\n\nseek=SEEK\nstart writing SEEK bs-sized blocks from the start of OFILE. Default is block 0 (i.e.\nstart of file).\n\nskip=SKIP\nstart reading SKIP bs-sized blocks from the start of IFILE. Default is block 0 (i.e.\nstart of file).\n\ntime={0|1}\nwhen 1, times transfer and does throughput calculation, outputting the results (to\nstderr) at completion. When 0 (default) doesn't perform timing.\n\nverbose=VERB\nas VERB increases so does the amount of debug output sent to stderr. Default value is\nzero which yields the minimum amount of debug output. A value of 1 reports extra in‐\nformation that is not repetitive. A value 2 reports cdbs and responses for SCSI com‐\nmands that are not repetitive (i.e. other that READ and WRITE). Error processing is\nnot considered repetitive. Values of 3 and 4 yield output for all SCSI commands (and\nUnix read() and write() calls) so there can be a lot of output.\n\n#### -h --help\n\noutputs usage message and exits.\n\n--ondst\nsend the XCOPY command to the output file/device (i.e. OFILE). This is the default un‐\nless overridden by the --onsrc or iflag=xflag options. Also see the section below on\nENVIRONMENT VARIABLES.\n\n--onsrc\nsend the XCOPY command to the input file/device (i.e. IFILE).\n\n#### -v --verbose\n\nequivalent to verbose=1. When used twice, equivalent to verbose=2, etc.\n\n#### -V --version\n\noutputs version number information and exits.\n\n### FLAGS\n\nHere is a list of flags and their meanings:\n\nappend causes the OAPPEND flag to be added to the open of OFILE. For regular files this will\nlead to data appended to the end of any existing data. Cannot be used together with\nthe seek=SEEK option as they conflict. The default action of this utility is to over‐\nwrite any existing data from the beginning of the file or, if SEEK is given, starting\nat block SEEK. Note that attempting to 'append' to a device file (e.g. a disk) will\nusually be ignored or may cause an error to be reported.\n\nexcl causes the OEXCL flag to be added to the open of IFILE and/or OFILE.\n\nflock after opening the associated file (i.e. IFILE and/or OFILE) an attempt is made to get\nan advisory exclusive lock with the flock() system call. The flock arguments are\n\"FLOCKEX | FLOCKNB\" which will cause the lock to be taken if available else a \"tem‐\nporarily unavailable\" error is generated. An exit status of 90 is produced in the lat‐\nter case and no copy is done.\n\nnull has no affect, just a placeholder.\n\npad sets the SCSI EXTENDED COPY command segment descriptor PAD bit. The PAD bit (in con‐\njunction with the CAT bit) controls the handling of residual data.(See section HAN‐‐\nDLING OF RESIDUAL DATA for details.\n\nxcopy has no affect; for compatibility with ddpt.\n\n### HANDLING OF RESIDUAL DATA\n\nThe pad and cat bits control the handling of residual data. As the data can be specified ei‐\nther in terms of source or target logical block size and both might have different block\nsizes residual data is likely to happen in these cases. If both logical block sizes are\nidentical these bits have no effect as residual data will not occur.\n\nIf none of these bits are set, the EXTENDED COPY command will be aborted with additional\nsense 'UNEXPECTED INEXACT SEGMENT'.\n\nIf only the cat bit is set the residual data will be retained and made available for subse‐\nquent segment descriptors. Residual data will be discarded for the last segment descriptor.\n\nIf the pad bit is set for the source descriptor only, any residual data for both source or\ndestination will be discarded.\n\nIf the pad bit is set for the target descriptor only any residual source data will be handled\nas if the cat bit is set, but any residual destination data will be padded to make a whole\nblock transfer.\n\nIf the pad bit is set for both source and target any residual source data will be discarded,\nand any residual destination data will be padded.\n\n### ENVIRONMENT VARIABLES\n\nIf the command line invocation does not explicitly (and unambiguously) indicate whether the\nXCOPY SCSI command should be sent to IFILE (i.e. the source) or OFILE (i.e. the destination)\nthen a check is made for the presence of the XCOPYTOSRC and XCOPYTODST environment vari‐\nables. If either one exists (but not both) then it indicates where the SCSI XCOPY command\nwill be sent. By default the XCOPY command is sent to OFILE.\n\n### RETIRED OPTIONS\n\nHere are some retired options that are still present:\n\nappend=0 | 1\nwhen set, equivalent to 'oflag=append'. When clear the action is to overwrite the ex‐\nisting file (if it exists); this is the default. See the 'append' flag.\n\n### NOTES\n\nCopying data behind an Operating System's back can cause problems. In the case of Linux,\nusers should look at this link: http://linux-mm.org/DropCaches\nThis command sequence may be useful:\nsync; echo 3 > /proc/sys/vm/dropcaches\n\nVarious numeric arguments (e.g. SKIP) may include multiplicative suffixes or be given in\nhexadecimal. See the \"NUMERIC ARGUMENTS\" section in the sg3utils(8) man page.\n\nThe COUNT, SKIP and SEEK arguments can take 64 bit values (i.e. very big numbers). Other val‐\nues are limited to what can fit in a signed 32 bit number.\n\nAll informative, warning and error output is sent to stderr so that dd's output file can be\nstdout and remain unpolluted. If no options are given, then the usage message is output and\nnothing else happens.\n\nIf a device supports xcopy operations then it should set the 3PC field (3PC stands for Third\nParty Copy) in its standard INQUIRY response. This utility will attempt a xcopy operation\nirrespective of the value in the 3PC field but if it is zero (cleared) one would expect the\nxcopy operation to fail.\n\nThe status of the SCSI EXTENDED COPY command can be queried with sgcopyresults(sg3utils)\n\nCurrently only block-to-block transfers are implemented; IFILE and OFILE must refer to a SCSI\nblock device.\n\nNo account is taken of partitions so, for example, /dev/sbc2, /dev/sdc, /dev/sg2, and\n/dev/bsg/3:0:0:1 would all refer to the same thing: the whole logical unit (i.e. the whole\ndisk) starting at LBA 0. So any partition indication (e.g. /dev/sdc2) is ignored. The user\nshould set SKIP, SEEK and COUNT with information obtained from a command like 'fdisk -l -u\n/dev/sdc' to account for partitions.\n\nXCOPY (LID1) capability has been added to the ddpt utility which is in a package of the same\nname. The ddpt utility will run on other OSes (e.g. FreeBSD and Windows) while sgxcopy only\nruns on Linux. Also ddpt permits the arguments to ibs= and ibs= to be different.\n\n### EXAMPLES\n\nCopy 2M of data from the start of one device to another:\n\n# sgxcopy if=/dev/sdo of=/dev/sdp count=2048 listid=2 dc=1\nsgxcopy: if=/dev/sdo skip=0 of=/dev/sdp seek=0 count=1024\nStart of loop, count=1024, bpt=65535, lbain=0, lbaout=0\nsgxcopy: 1024 blocks, 1 command\n\nCheck the status of the EXTENDED COPY command:\n\n# sgcopyresults --status --listid=2 /dev/sdp\nReceive copy results (copy status):\nHeld data discarded: Yes\nCopy manager status: Operation completed without errors\nSegments processed: 1\nTransfer count units: 0\nTransfer count: 0\n\n### SIGNALS\n\nThe signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIGPIPE output the number\nof remaining blocks to be transferred and the records in + out counts; then they have their\ndefault action. SIGUSR1 causes the same information to be output yet the copy continues.\nAll output caused by signals is sent to stderr.\n\n### EXIT STATUS\n\nThe exit status of sgxcopy is 0 when it is successful. Otherwise see the sg3utils(8) man\npage.\n\nAn additional exit status of 90 is generated if the flock flag is given and some other\nprocess holds the advisory exclusive lock.\n\n### AUTHORS\n\nWritten by Hannes Reinecke and Douglas Gilbert.\n\n### REPORTING BUGS\n\nReport bugs to .\n\n### COPYRIGHT\n\nCopyright © 2000-2019 Hannes Reinecke and Douglas Gilbert\nThis software is distributed under the GPL version 2. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\n### SEE ALSO\n\nThere is a web page discussing sgdd at http://sg.danny.cz/sg/sgdd.html\n\nA POSIX threads version of this utility called sgpdd is in the sg3utils package. Another\nversion from that package is called sgmdd and it uses memory mapped IO to speed transfers\nfrom sg devices.\n\nThe lmbench package contains lmdd which is also interesting. For moving data to and from\ntapes see dt which is found at http://www.scsifaq.org/RMillerTools/index.html\n\nTo change mode parameters that effect a SCSI device's caching and error recovery see sd‐‐\n\n#### parm(sdparm)\n\nSee also dd(1), sgcopyresults(sg3utils), ddrescue(GNU), ddpt,ddptctl(ddpt)\n\n\n\nsg3utils-1.45 February 2019 SGXCOPY(8)\n\n" } ], "structuredContent": { "command": "sg_xcopy", "section": "8", "mode": "man", "summary": "sgxcopy - copy data to and from files and devices using SCSI EXTENDED COPY (XCOPY)", "synopsis": "sgxcopy [bs=BS] [conv=CONV] [count=COUNT] [ibs=BS] [if=IFILE] [iflag=FLAGS] [obs=BS]\n[of=OFILE] [oflag=FLAGS] [seek=SEEK] [skip=SKIP] [--help] [--version]\n[app=0|1] [bpt=BPT] [cat=0|1] [dc=0|1] [fco=0|1] [idusage={hold|discard|disable}]\n[listid=ID] [prio=PRIO] [time=0|1] [verbose=VERB] [--ondst|--onsrc] [--verbose]", "flags": [ { "flag": "-h", "long": "--help", "arg": null, "description": "outputs usage message and exits. --ondst send the XCOPY command to the output file/device (i.e. OFILE). This is the default un‐ less overridden by the --onsrc or iflag=xflag options. Also see the section below on ENVIRONMENT VARIABLES. --onsrc send the XCOPY command to the input file/device (i.e. IFILE)." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "equivalent to verbose=1. When used twice, equivalent to verbose=2, etc." }, { "flag": "-V", "long": "--version", "arg": null, "description": "outputs version number information and exits." } ], "examples": [ "Copy 2M of data from the start of one device to another:", "# sgxcopy if=/dev/sdo of=/dev/sdp count=2048 listid=2 dc=1", "sgxcopy: if=/dev/sdo skip=0 of=/dev/sdp seek=0 count=1024", "Start of loop, count=1024, bpt=65535, lbain=0, lbaout=0", "sgxcopy: 1024 blocks, 1 command", "Check the status of the EXTENDED COPY command:", "# sgcopyresults --status --listid=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" ], "see_also": [ { "name": "dd", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/dd/1/json" }, { "name": "sgcopyresults", "section": "sg3utils", "url": "https://www.chedong.com/phpMan.php/man/sgcopyresults/sg3utils/json" }, { "name": "ddrescue", "section": "GNU", "url": "https://www.chedong.com/phpMan.php/man/ddrescue/GNU/json" }, { "name": "ddptctl", "section": "ddpt", "url": "https://www.chedong.com/phpMan.php/man/ddptctl/ddpt/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 26, "subsections": [] }, { "name": "OPTIONS", "lines": 110, "subsections": [ { "name": "-h --help", "lines": 10, "flag": "-h", "long": "--help" }, { "name": "-v --verbose", "lines": 2, "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "lines": 2, "flag": "-V", "long": "--version" } ] }, { "name": "FLAGS", "lines": 25, "subsections": [] }, { "name": "HANDLING OF RESIDUAL DATA", "lines": 21, "subsections": [] }, { "name": "ENVIRONMENT VARIABLES", "lines": 6, "subsections": [] }, { "name": "RETIRED OPTIONS", "lines": 6, "subsections": [] }, { "name": "NOTES", "lines": 35, "subsections": [] }, { "name": "EXAMPLES", "lines": 17, "subsections": [] }, { "name": "SIGNALS", "lines": 5, "subsections": [] }, { "name": "EXIT STATUS", "lines": 6, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 10, "subsections": [ { "name": "parm(sdparm)", "lines": 5 } ] } ] } }