sg3 utils
reference: The sg3_utils package
Introduction
- Send SCSI commands to devices on transports traditionally associated with SCSI.
- Fibre Channel (FCP)
- Serial Attached SCSI (SAS)
- SCSI Parallel Interface (SPI)
- ATAPI cd/dvd drivers and SATA disks connect via a translation layer or a bridge that use SCSI command sets.
- SCSI command sets
- SCSI Standards Architecture
- common set
- SCSI Primary Commands (SPC)
- SPC-5 [INCITS 502-2019]
- mandatory SCSI INQUIRY
- SCSI Block Commands (SBC)
- direct access devices such as disks.
- MultiMedia Commands (MMC)
- cover CD, DVD and BD drives and the media within them.
Contents of sg3_utils
- No more than one DEVICE can be given.
- Ported symbol
- f = FreeBSD
- s = Solaris
- t = Tru64 (OSF)
- w = Windows
- Main utilities in sg3_utils
| Utility name | Main SCSI commands invoked | CLI | Ported | Notes |
|---|---|---|---|---|
| sginfo [legacy, use sdparm] |
MODE SENSE/SELECT, READ DEFECT [6, 10] [RD: 10, 12] | adhoc | symbolic decoding (optional changing) of mode pages. Can also output (disk) defect lists. Port of older scsiinfo utility. |
|
| sgm_dd | READ, WRITE [6, 10, 12, 16] | dd | sg_dd variant that uses memory mapped IO (only on Linux sg device) | |
| sgp_dd | READ, WRITE [6, 10, 12, 16] | dd | sg_dd variant that uses POSIX thread | |
| sg_bg_ctl | BACKGROUND CONTROL | getopt | f,s,t,w | start/stop advance background control operations on disk |
| sg_compare_and_write | COMPARE AND WRITE | getopt | f,s,t,w | if compare successful then write |
| sg_copy_results | RECEIVE COPY RESULTS | getopt | used to get the results from the previous sg_xcopy (EXTENDED COPY(LID1)) | |
| sg_dd | READ, WRITE [6, 10, 12, 16] | dd | Unix dd command variant, uses SG_IO ioctl to send SCSI commands to copy data. Newer ddpt utility adds features and is ported to “f,s,w” |
|
| sg_decode_sense | getopt | f,s,t,w | decodes sense data given as a string of hexadecimal bytes or in binary. Also may decode command opcodes and sg3_utils exit status values. |
|
| sg_emc_trespass | MODE SELECT | adhoc | utility specialized for EMC Clariion series. | |
| sg_format | FORMAT UNIT (SBC), FORMAT MEDIUM (SSC) and FORMAT WITH PRESET | getopt | f,s,t,w | format or resize a SCSI disk (with FORMAT UNIT). Alternatively sg_format can format a tape (with FORMAT MEDIUM). Support for FORMAT WITH PRESET was added in version 1.45 |
| sg_get_config | GET CONFIGURATION | getopt | f,s,t,w | fetch features and profiles of a cd/dvd drive and/or its current media |
| sg_get_elem_status | GET PHYSICAL ELEMENT STATUS | getopt | f,s,t,w | New in version 1.45, see SBC-4 |
| sg_get_lba_status | GET LBA STATUS | getopt | f,s,t,w | logical block provisioning support |
| sg_ident | REPORT/SET IDENTIFYING INFORMATION | getopt | f,s,t,w | default is to report (fetch) the device identifier. With the ‘–set’ option a new identifier is sent to the device. |
| sg_inq | INQUIRY | getopt+ | f,s,t,w | fetch standard response, VPD pages or version descriptors. Also can perform IDENTIFY (PACKET) DEVICE ATA command in Linux. If given an NVMe device and no VPD page is requested or implied by the given options then show NVMe Identify controller and namespace responses. VPD page decoding also performed by sg_vpd and sdparm. |
| sg_logs | LOG SENSE | getopt+ | f,s,t,w | fetch log sense pages, decode standard and some vendor pages |
| sg_luns | REPORT LUNS | getopt | f,s,t,w | fetch luns reported by a device (lun0 or “well known lu”) |
| sg_map | INQUIRY | adhoc | shows mapping between sg devices and primary device node (if any). Instead of using sg_map, in lk 2.6 and later the lsscsi utility is recommended. |
|
| sg_map26 | getopt | maps between single Linux sg device and primary device node (and vice versa). Also does mapping in to, and out of, sysfs. For the Linux 2.6 series and later. Instead of using sg_map26, the lsscsi utility is recommended. |
||
| sg_modes | MODE SENSE [6, 10] | getopt+ | f,s,t,w | fetch mode pages (output mainly in hex, to decode output use sdparm) |
| sg_opcodes | REPORT SUPPORTED OPERATION CODES | getopt+ | fetch supported SCSI commands or supported task management functions | |
| sg_prevent | PREVENT ALLOW MEDIUM REMOVAL | getopt | f,s,t,w | control media removal, mainly for those SCSI devices which have removable media (e.g., CD/DVD and tape drives) |
| sg_raw | getopt | f,s,t,w | send user supplied sdb | |
| sg_rbuf | READ BUFFER | getopt+ | read from SCSI device cache. Typically for testing the SCSI transport (for throughput or errors) |
|
| sg_rdac | MODE SENSE/SELECT [6, 10] | adhoc | f,s,t,w | display or modify RDAC redundant controller mode page |
| sg_read | READ [6, 10, 12, 16] | dd | read continually from same offset. Syntax similar to sg_dd (without write side). Can test SCSI device cache and transport performance. |
|
| sg_read_attr | READ ATTRIBUTE | getopt+ | f,s,t,w | fetch and decode attributes. Modern tape systems implement this SCSI command. |
| sg_readcap | READ CAPACITY [10, 16] | getopt+ | f,s,t,w | fetch the number of blocks and the individual block size for disks and CD/DVD media |
| sg_read_buffer | READ BUFFER(10) and READ BUFFER(16) | getopt | f,s,t,w | retrive descriptiors, error history or data from device. |
| sg_read_long | READ LONG | getopt | f,s,t,w | read data from given LBA which includes the block and ECC data. |
| sg_reassign | REASSIGN BLOCKS | getopt | f,s,t,w | reassign a LBA from one sector on a disk (typically damaged) to a new (spare) sector. User data copied if it is recoverable. |
| sg_referrals | REPORT REFERRALS | getopt | f,s,t,w | report data segment accessibility from target port groups |
| sg_rep_pip | REPORT PROVISIONING INITIALIZATION PATTERN | getopt | f,s,t,w | calls the SCSI command of that name that was added in sbc4r07.pdf. Format the output for human consumption. |
| sg_rep_zones | REPORT REALMS, REPORT ZONE DOMAINS and REPORT ZONES | getopt | f,s,t,w | sends one of these commands (default is REPORT ZONES) to a ZBC (SMR) device and decodes the reusult. A SAT layer may translate SCSI ZBC commands to ATA ZAC commands that a disk uderstands |
| sg_requests | REQUEST SENSE | getopt | f,s,t,w | fetch sense data from the given device. Modern uses include getting a progress indication (e.g., during a format) or finding the power condition state. |
| sg_reset | - | adhoc | Issue a driver, (SCSI) bus or device (target or lun?) reset. | |
| sg_reset_wp | RESET WRITE POINTER | getopt | f,s,t,w | sends this command to z ZBC (aka shared magnetic recording [SMR]) device. The correspoding ATA standard is known as ZAC. |
| sg_rmsn | READ MEDIA SERIAL NUMBER | getopt | f,s,t,w | Relatively new command added to SPC-3. Format of response is vendor specific so this utility outputs it in hex (default) or binary. |
| sg_rtpg | REPORT TARGET PORT GROUPS | getopt | f,s,t,w | Specialized for multi-ported SCSI devices where one port (or a group of them) is preferred for IO over another (or others). |
| sg_safte | READ BUFFER | getopt | f,s,t,w | fetch information from a SAF-TE processor |
| sg_sanitize | SANITIZE | getopt | f,s,t,w | Send SCSI SANITIZE command |
| sg_sat_identify | ATA PASS-THROUGH [12, 16] | getopt | f,s,t,w | Send ATA IDENTIFY DEVICE or IDENTIFY PACKET DEVICE commands via the SAT ATA PASS-THROUGH SCSI command. |
| sg_sat_phy_event | ATA PASS-THROUGH [12, 16] | getopt | f,s,t,w | Sends an ATA READ LOG EXT command via a SAT to fetch log page 11h which contains SATA phy event counters. |
| sg_sat_read_gplog | ATA PASS-THROUGH [12, 16] | getopt | f,s,t,w | Sends an ATA READ LOG (DMA) EXT command via a SAT to fetch a log page |
| sg_sat_set_features | ATA PASS-THROUGH [12, 16] | getopt | f,s,t,w Sends ATA SET FEATURES command via SAT | |
| sg_scan [.c.linux] | [INQUIRY] | adhoc | Linux only | maps each sg device name to the corresponding numeric <host, channel, target, lun> tuple. In lk 2.6 series (and later) the “lsscsi -g” command is similar. |
| sg_scan [.c.win32] | [INQUIRY] | getopt | win32 only | shows one device per line, with the device’s various names and INQUIRY response string on that line. |
| sg_seek | SEEK, PRE-FETCH [10, 16] | getopt | f,s,t,w | These commands move no data, they suggest to the device what may be useful to add to the device’s cache. Useful for random (i.e., non-sequential as read-ahead is now useless) reads, when the LBA of the next read access is knwon. |
| sg_senddiag | SEND DIAGNOSTIC | getopt+ | f,s,t,w | Issues either a default self test or a short/extended foreground/background self test. With no arguments it uses RECEIVE DIAGNOSTIC RESULTS to list all supported diagnostic pages. |
| sg_ses | SEND/RECEIVE DIAGNOSTIC | getopt | f,s,t,w | Fetches status diagnostic pages from, and sends some control pages to, a SCSI Enclosure Services (SES) device. Can pass-through to NVMe enclosure if present. |
| sg_ses_microcode | SEND/RECEIVE DIAGNOSTIC | getopt | f,s,t,w | This microcode (firmware) download (to device) is SES specific. A more general way, typically used with disks, is with sg_write_buffer. |
| sg_start | START STOP UNIT | getopt+ | f,s,t,w | Controls the power condition state of a SCSI device. Primary use is to spin up and down SCSI disks. Can also load and eject removable media. |
| sg_stpg | SET TARGET PORT GROUPS | getopt | f,s,t,w | Specialized for multi-ported SCSI device where one port (or a group of them) is preferred for IO over another (or others). |
| sg_stream_ctl | STREAM CONTROL, GET STREAM STATUS | getopt | f,s,t,w | these commands together with WRITE STREAM command (in the sg_write_x utility) support streams in SCSI. Streams associate data of similar expected lifetime together. The Block limits VPD page (and the coresponding extension VPD page) contain information about streams on a disk, typically a SSD. |
| sg_sync | SYNCHRONIZE CACHE [10, 16] | getopt | f,s,t,w | Causes disk caches to be flushed to media |
| sg_test_rwbuf | READ/WRITE BUFFER | getopt | Random pattern written to SCSI device buffer then read back and checked. Used in testing for data corruption. |
|
| sg_timestamp | REPORT/SET TIMESTAMP | getopt | f,s,t,w | Report or set timestamp which is a 48 bit unsigned integer containing the number of milliseconds since 1970-01-01 00:00:00 UTC |
| sg_turs | TEST UNIT READY | getopt+ | f,s,t,w | Issue one or more Test Unit Ready commands. Can be used to time SCSI command overhead. |
| sg_unmap | UNMAP | getopt | f,s,t,w | logical block provisioning support (“Trim” in the ATA world) |
| sg_verify | VERIFY [10, 16] | getopt | f,s,t,w | reads indicated blocks on a SCSI disks, stops on the first error found. Does not yield any data. Useful for media scans. |
| sg_vpd | INQUIRY | getopt | f,s,t,w | Decodes standard and some vendor Vital Product Data (VPD) pages. |
| sg_write_buffer | WRITE BUFFER | getopt | f,s,t,w | write data; can be used to download firmware |
| sg_write_long | WRITE LONG [10, 16] | getopt | f,s,t,w | writes to a LBA, data which includes the block and ECC data. Suitable data typically fetched by prior sg_read_long utility. |
| sg_write_same | WRITE SAME [10, 16, 32] | getopt | f,s,t,w | writes a single block to one or more (consecutive) LBAs. Also supports some logical block provisioning options. |
| sg_write_verify | WRITE AND VERIFY [10, 16] | getopt | f,s,t,w | send one or more commands to consecutive LBAs, reading data from a given file or stdin. |
| sg_write_x | WRITE [16, 32], ORWRITE [16, 32], WRITE ATOMIC [16, 32], WRITE SAME [16, 32], WRITE SCATTERED [16, 32], WRITE STREAM [16, 32] | getopt | f,s,t,w | command line options will pick 1 of the 6 variants with 1 of the 2 cdb lengths. Almost all will require the –in=IF option which identifies the file (IF) holding the data (in binary) to be written. The exception is –same=1 which sets the NDOB (no data-out buffer) flag in the WRITE SAME command. Of the 32 byte cdb variants, ORWRITE(32) is the only one that does not require the device to be formatted with either type 1, 2 or 3 protection information. |
| sg_wr_mode | MODE SELECT [6, 10] | getopt | f,s,t,w | writes mode pages supplied in ASCII hex (e.g., from “sg_modes -r”) to the SCSI device. See sdparm for another method of setting mode page parameters. |
| sg_xcopy | EXTENDED COPY(LID1) | dd | Uses the EXTENDED COPY(LID1) command to copy between disks. Note: the ddpt utility contains this functionality and adds ODX (a subset of XCOPY(LID4)) capability. ddpt is ported to f,s,w. Note that “LID1” EXTENDED COPY commands have been removed from SPC-5 drafts. The remaining “LID4” commands in SPC-5 have dropped the “LID4” suffix. |
|
| sg_zone | CLOSE ZONE, FINISH ZONE, OPEN ZONE, SEQUENTIALIZE ZONE | getopt | f,s,t,w | Sends one of these commands to the given ZBC device. See related sg_rep_zones and sg_reset_wp |
- Executable scripts in scripts directory
| script name | Description | |
|---|---|---|
| rescan-scsi-bus.sh | 0 | copy of Kurt Garloff’s useful script with additions from Suse amongst others |
| scsi_logging_level | 0 | create, get or set linux scsi logging level |
| scsi_mandat | 1 | check for mandatory SCSI command support |
| scsi_readcap | 1 or more | use SCSI READ CAPACITY command on each given device |
| scsi_ready | 1 or more | use SCSI TEST UNIT READY on each given |
| scsi_satl | 1 | check for SCSI to ATA Translation Layer (SATL) support |
| scsi_start | 1 or more | use SCSI START STOP UNIT command to start each |
| scsi_stop | 1 or more | use SCSI START STOP UNIT command to stop each |
| scsi_temperature | 1 or more | use SCSI LOG SENSE command to fetch temperature of each |
- Other utilities in sg3_utils or related
| Utility | Main SCSI commands invoked | directory | CLI | Ported | Notes |
|---|---|---|---|---|---|
| ddpt | READ, WRITE | –> | dd | f,s,w | dd variant, rewrite of sg_dd. In its own package: ddpt |
| hxascdmp | - | utils | adhoc | f,s,w | converts stdin (assumed binary) to ASCII hex and ASCII, sending its output to stdout (like the Unix od command and hexdump in BSD) |
| sas_disk_blink | MODE SELECT | –> | script in sdparm package. It blinks the ready LED on a SAS disk |
||
| scsi_inquiry | INQUIRY | examples | adhoc | uses deprecated SCSI_IOCTL_SEND_COMMAND ioctl | |
| sdparm | MODE SENSE/SELECT, INQUIRY | –> | getopt | f,s,t,w | was in the sg3_utils package for a while; now in own package, see sdparm. sdparm manipulates mode pages, reads VPD pages and sends simple commands |
| sg_chk_asc | - | utils | getopt | f,s | check asc/ascq codes from www.t10.org page against sg3_utils internal table |
| sg__sat identify | ATA PASS-THROUGH | examples | adhoc | Simpler version of sg_sat_identify that uses the Linux SG_IO ioctl directly. | |
| sg__sat_phy_event | ATA PASS-THROUGH | examples | getopt | Simpler version of sg_sat_phy_event | |
| sg__sat_set_features | ATA PASS_THROUGH | examples | getopt | Simpler version of sg_sat_set_features that uses the Linux SG_IO ioctl directly. | |
| sg_simple1,2,3,4,5 | INQUIRY, TEST UNIT READY | examples | adhoc | Simple code examples of using the scsi generic (sg) driver interface | |
| sg_simple16 | READ | examples | adhoc | Simple code examples of sending a 16 byte cdb SCSI READ command | |
| smp_discover | SAS SMP commands | –> | f,s, | discover phy attachments within a SAS expander. In separate package: smp_utils |
Exit status
| Exit status | Description | |
|---|---|---|
| 0 | no error detected. Utility completed successfully | |
| 1 | syntax error in command line options or their arguments, or an illegal combination of options | |
| 2 | the device reports that it is not ready for the operation requested. The device may be in the process of becoming ready (e.g., spinning up but not at speed) so the utility may work a little while later | |
| 3 | the device reports a medium or hardware error (or a blank check). For example an attempt to read a corrupted block on a disk will yield this value | |
| 5 | the device reports an “illegal request” with an additional sense code other than “invalid operation code”. This is often a supported command with a field set requesting an unsupported capability. For commands that require a “service action” field (e.g., READ CAPACITY(16)) this value can indicate that the command is not supported | |
| 6 | the device reports a “unit attention” condition. This usually indicate that something, unrelated to the requested command, has occurred (e.g., a device reset) potentially before the current SCSI command was sent. The requested command has not been executed by the device. Note that unit attention conditions are usually only reported once by a device | |
| 7 | the device reports a “data protect” sense key. This implie some mechanism has blocked writes (or possibly all access to the media). | |
| 9 | the device reports an illegal request with an additional sense code of “invalid operation code” which means that the device doesn’t support the requested command | |
| 10 | the device reports a “copy aborted” sense key | |
| 11 | the device (or transport) reports and aborted command. In some cases this can be caused by congestion on the transport and retrying the command may be successful | |
| 14 | the device reports a “miscompare” sense key. sg_verify and sg_compare_and_write may report this. | |
| 15 | the utility is unable to open, close or use the given device or another file. The given file name could be incorrect or there may be permission problems. Adding the ‘-v’ option may give more information “ | |
| 17 | a SCSI “Illegal request” sense code received with a flag indicating the Info field is valid. | |
| 18 | the DEVICE reports a medium or hardware error (or a blank check) with a flag indicating the Info field is valid. This is often a LBA (of the first encountered error) but its meaning is command specific. | |
| 20 | the device reports it has a check condition but “no sense”. Some polling commands (e.g., REQUEST SENSE) can react this way. It is unlikely that this value will occur as an exit status | |
| 21 | the device reports a “recovered error”. The requested command was successful. Most likely a utility will report a recovered error to stderr and continue, probably leaving the utility with an wxit status of 0. | |
| 22 | LBA out-of-range | |
| 24 | the device reports a SCSI status of “reservation conflict”. This implies that some other initiator holds a reservation on this device; that reservation may block writes or almost all access to that device via the current initiator | |
| 25 | the device reports a SCSI status of “condition met”. Currently only the PRE-FETCH command (see SBC-4) yields this status. | |
| 26 | the device reports a SCSI status of “busy”. SAM-5 defines this status as the logical unit is temporarily unable to process a command. It is recommended to re-issue the command. | |
| 27 | the device reports a SCSI status of “task set full”. | |
| 28 | the device reports a SCSI status of “ACA active”. ACA is “auto contingent allegiance” and is seldom used. | |
| 29 | the device reports a SCSI status of “task aborted”. SAM-5 says: “This status shall be returned if a command is aborted by a command or task management function on another I_T nexus and the Control mode page TAS bit is set to one”. | |
| 31 | error involving two or more command line options, or a missing second option that is needed. Often two or more options contradict one another. These tend to be more complicated than “syntax error” (exit status 1) which typically are associated with a single command line option. | |
| 32 | there is a logic error in the utility’s code. This may warrant an email to the author. | |
| 33 | the command sent to the device has timed out. This occurs in Linux, in other ports a command timeout will appear as a transport (or OS) error | |
| 34 | this is a Windows only exit status and indicates that the Windows error number (32 bits) cannot meaningfully be mapped to an equivalent Unix error number returned as the exit status (7 bits) | |
| 36 | no error has occurred plus the utility wants to convey a boolean value of false. The corresponding true value is conveyed by a 0 exit status. | |
| 40 | the command sent to device has received an “aborted command” sense key with an additional sense code of 0x10. This is related to problems with protection information (PI or DIF). Examples include reading unmapped blocks or blocks that have never been written to (since the last format) | |
| 41 | similar to error code 40 plus a flag indicating the Info field is valid | |
| 48 | An NVMe command terminated with a non-zero status (stats = ((SCT «8) | SC)) |
| 49 | Low Level Driver (LLD) reports a residual count that is too high. This means that not enough data has been returned from the device (i.e., the “data-in” buffer) to continue. | |
| 50 | A Unix error (“errno”) has occurred and its value is too large (46<) to fit in the alotted range which is 51 to 95. Since errno=0 means there is no error, this value (50) is used to map all “too large” error_s to. | |
| 51-96 | This is a Unix “errno” value plus 50. Unix errno values are relatively small positive integers. Errno values 1 through 46 are mapped to 51 to 96. All larger errno values are mapped to 50. | |
| 97 | the response to a SCSI command failed sanity checks | |
| 98 | the device reports it has a check condition but the error doesn’t fit into any of the above categories | |
| 99 | any errors that can’t be categorized into values 1 to 98 may yield this value. This includes transport and operating system errors | |
| 100-125 | used by the ddpt utility, mainly for specialized offloaded copy errors. | |
| 126 | utility found but could not be executed. Possibly a permissions problem or executable is for a different architecture | |
| 127 | utility not found | |
| 128+ | utility was interrupted by signal |
|
| 255 | utility tried to yield an exit status of 255 or higher |