Appendix A. Sg3_utils package

The sg3_utils package is a collection of programs that use the sg interface. The utilities can be categorized as follows:

• variants of the Unix dd command: sg_dd, sgp_dd, sgq_dd and sgm_dd,

• scanning and mapping utilities: sg_scan, sg_map and scsi_devfs_scan,

• SCSI support: sg_inq, scsi_inquiry, sginfo, sg_readcap, sg_start and sg_reset,

• timing and testing: sg_rbuf, sg_test_rwbuf, sg_read, sg_turs and sg_debug,

• example programs: sg_simple1..4 and sg_simple16,

The "dd" family of utilities take a sg device file name as input (i.e. if=<sg_dev_filen_name>), as output of both. They can also take raw device file names [1] instead of sg device file names. One important difference from the standard dd command is that the value given to the block size (bs=) argument must be the exact block size of that device and not a integral multiple as allowed by dd. These "dd" variants are suitable for SCSI Direct Access Devices such as disk and CDROMs (but are not suitable for SCSI tape devices).

The sg3_utils package is designed to be used with the sg version 3 driver found in the lk 2.4 series. There is also a sg_utils package that supports a subset of these commands for the sg version 2 driver (with some support for the original sg driver) which is found in the lk 2.2 series (from and after lk 2.2.6). There are links to the most recent sg3_utils (and sg_utils) packages at the sg website at www.torque.net/sg. There are tarballs and both source and binary rpm packages. At the time of writing the latest sg3_utils tarball is at www.torque.net/sg/p/sg3_utils-0.97.tgz. There is a README file in that tarball that should be examined for up to date information. The more important utility commands (e.g. sg_dd) have "man" pages. [2]

Almost all of the sg device driver capabilities discussed in this document appear in code in one or more of these programs. For example the recently added mmap-ed IO can be found in sgm_dd, sg_read and sg_rbuf.

The sg3_utils package also provides some functions that may be useful for applications that use sg. The functions declared in sg_err.h and defined in sg_err.c categorize SCSI subsystem errors that are returned to an application in a read() or a ioctl(SG_IO). In the case of sense buffers, they are decoded into text message (as per SCSI 2 definitions). There is also a function to do a 64 bit seek (llseek.h).