Debian Codegraph @

README

raw
1 Introduction
2 ------------
3 ddpt is a utility for copying files like its namesake, the Unix dd command.
4 ddpt is specialized for files that are actually block devices. And if
5 those block devices understand SCSI commands then the copy can be done by
6 using either SCSI READ or WRITE commands (or both). This latter facility
7 is done using a pass-through interface that bypasses the normal operating
8 system block handling. This can give very fine-grained control over the
9 copy process.
10
11 ddpt also supports two forms of offloaded copies, one based on the EXTENDED
12 COPY command introduced in T10's SPC-2 standard. EXTENDED COPY is often
13 abbreviated to XCOPY or xcopy. As new forms of offloaded copy have been
14 added (especially in SPC-4) the original XCOPY is now called XCOPY(LID1)
15 with lot of new feature added to XCOPY(LID4). A subset of XCOPY(LID4) which
16 only supports disk to disk, token based copies, has the market name of ODX.
17 So ddpt supports the original XCOPY(LID1) and uses the term "xcopy" to
18 refer to it. ddpt now also supports ODX and uses the term "odx" to refer
19 to it.
20
21 ddptctl is a helper/auxiliary for the ddpt utility. ddptctl mainly supplies
22 extra functionality for ODX.
23
24 This utility was originally written for Linux. It has been ported to FreeBSD,
25 Solaris and Windows.
26
27 Relationship to sg3_utils
28 -------------------------
29 The sg3_utils (version 1.33) package contains several utilities that mimic
30 the standard Unix dd command. Currently those utilities are sg_dd, sgm_dd,
31 sgp_dd and sg_xcopy. Even though most of the other utilities in the
32 sg3_utils package are ported to other operating systems, sg_dd and friends
33 are not ported since they are too tightly bound to Linux and some of the
34 idiosyncrasies of its SCSI generic (sg) and bsg drivers and the associated
35 SG_IO ioctl. So the ddpt utility drops some Linux specific features while
36 adding some more general features (e.g. write sparing). An attempt has also
37 been made to simplify the command line syntax which is still based on the
38 distinctive dd command line syntax. Note that the dd command line syntax is
39 unlike any other Unix command (probably imported from some IBM OS many
40 years ago).
41
42 This package shares code with sg3_utils (version 1.38). With the subversion
43 revision control system this is done by having ddpt's "include/" and "lib/"
44 sub-directories pointing to the correspondingly named directories in the
45 sg3_utils package using the "svn:externals" property. These two "external"
46 directories include more files than ddpt uses. The excess files include
47 "lib/Makefile.am" and "lib/Makefile.in". The "Makefile.am" in ddpt's "src/"
48 directory does the main part of the build. When the tarball is generated
49 for this utility, various files are "exported" out of the subversion
50 repository and "svn:externals" redirection is no longer visible (but the
51 unused files are visible).
52
53 The ddpt executable may or may not be built depending on the libsgutils
54 (shared) library. Currently the ./configure rules are looking for a library
55 called libsgutils2.a or libsgutils2.so . In Debian those libraries are found
56 only in the libsgutils2-dev package, not the libsgutils2 package. If one of
57 those libraries is detected then ddpt will be built depending on libsgutils
58 (check 'ldd ddpt'). If neither of those libraries is detected at build time,
59 then the ddpt executable built will compile and link the relevant code from
60 its "include/" and "lib/" subdirectories.
61
62 Documentation
63 -------------
64 The utility outputs a usage message when the "--help" (or '-?') option is
65 given. Many syntax errors also result in the usage message being printed.
66 There is also a man page which is in section 8 (administration and privileged
67 commands). It can be accessed with "man ddpt" once this package is installed.
68 Prior to installation the man page can be viewed from this package's main
69 directory with "man doc/ddpt.8".
70
71 There is a web page at https://sg.danny.cz/sg/ddpt.html and a copy of that
72 html file is placed in the "doc" directory.
73
74 Build infrastructure
75 --------------------
76 This package uses the automake and autoconf tools. The generating files
77 (scripts) are configure.ac, Makefile.am, doc/Makefile.am, src/Makefile.am and
78 autogen.sh . The autogen.sh script only needs to be executed if one of the
79 other generating files in the above list is changed.
80
81 There is a rpm "spec" file in the main directory: ddpt.spec . There are Debian
82 build files in the "debian" directory and a script called build_debian.sh in
83 the main directory. Amongst other things debian builds are sensitive to the
84 value in the debian/compat file. If it contains "7" then it works on lenny and
85 gives warning on squeeze (but fails on the earlier etch).
86
87 The ./configure script supports these extra options:
88 - '--disable-libsgutils' stops the build using the libsgutils library
89 if it is found. Instead the copy of those files found under the
90 include and lib directories is used.
91 - '--disable-linuxbsg' does nothing and is only present for backward
92 compatibility
93 for testing and should no longer be necessary.
94 - '--disable-scsistrings' excludes the asc/ascq and command name strings
95 (defined by SCSI/T10) in an attempt to reduce the size of executables.
96 - '--disable-nvme-supp' instructs the build to ignore the added NVMe
97 detection code added in version 0.96
98 - '--disable-fast-lebe' . A header called sg_unaligned.h has several
99 implementations of inline functions for alignment moves and byte
100 swapping. The default is to use little and big endian specific code that
101 depends on the non-standard bswap_<16|32|64> functions. This option
102 forces the use of more generic implementations that depend on C shift
103 operators.
104
105 At the request of some Linux distributions, this package will attempt to
106 use the libsgutils library (name varies between distributions) at build time.
107 If that library is old then the link at the end of build can fail. One way
108 to sidestep that problem is by using './configure --disable-libsgutils'.
109 Another way is to remove the "dev" version of the libsgutils library package
110 (e.g. 'libsgutils2-dev' on a Debian based distribution).
111
112 License
113 -------
114 This utility is covered by a FreeBSD license also known as the BSD 3-clause
115 license (see Wikipedia). The intention of the author is that both open
116 source and commercial entities can re-use this code. Naturally attribution
117 and improvement/bug feedback are encouraged.
118
119 Notes
120 -----
121 Generic information about building this package (i.e. './configure ; make;
122 make install') can be found in the INSTALL file. The contents of COPYING is a
123 FreeBSD license (rather than the GPL v2 found in the usual template).
124
125 Linux port
126 ----------
127 The utility can be used on any storage device.
128
129 To use the "pt" interface the device needs to support the SG_IO ioctl. In
130 the Linux 2.4 series that is only the scsi generic (i.e. /dev/sg* )
131 device nodes. In the Linux 2.6 and 3 series the supported device nodes have
132 expanded to all other SCSI device nodes (e.g. /dev/sd* and /dev/sr*)
133 plus block devices such as /dev/hdc when the associated device is a
134 DVD drive. The man page and sg.danny.cz/sg/ddpt.html web page examples use
135 Linux device node names.
136
137 FreeBSD port
138 ------------
139 See README.freebsd
140
141 Solaris port
142 ------------
143 See README.solaris
144
145 Win32 port
146 ----------
147 See README.win32
148
149
150 Douglas Gilbert
151 3rd March 2020