SG_TURS(8)

📦
version 1.49 · 3 versions
, in arch rolling, nixpkgs unstable

💅 sg_turs: SCSI TEST UNIT READY, but make it a vibe ✨

okay bestie, welcome to the SG_TURS(8) page from sg3_utils 🫶. This is the utility that sends one or more SCSI TEST UNIT READY commands, and it's honestly lowkey iconic for timing per-command overhead. Note that TEST UNIT READY has no associated data — just a 6 byte command (with each byte a zero) and a returned SCSI status value. No drama, just status 💅.

✨ NAME ✨

sg_turs — send one or more SCSI TEST UNIT READY commands. That's the whole assignment, and it ate 💖.

🦋 SYNOPSIS 🦋

sg_turs [--ascq=ASC[,ASQ]] [--delay=MS] [--help] [--low] [--num=NUM]
[--number=NUM] [--progress] [--time] [--timeout=SE] [--verbose]
[--version] DEVICE

sg_turs [-d=MS] [-n=NUM] [-p]  [-t] [-v] [-V] DEVICE

🌸 DESCRIPTION 🌸

This utility sends one or more SCSI TEST UNIT READY commands to the DEVICE. This may be useful for timing the per command overhead. And yes, TEST UNIT READY has no associated data — just a 6 byte command (with each byte a zero) and a returned SCSI status value. It's giving minimal, but make it fashion ✨.

This utility supports two command line syntaxes. The preferred one is shown first in the synopsis and explained in this section. A later section on the old command line syntax outlines the second group of options. Two eras, one utility — main character energy fr fr 👑.

🎀 OPTIONS 🎀

Arguments to long options are mandatory for short options as well. No skipping, bestie.

  • -a, --ascq=ASC[,ASQ] — checks the sense data associated with a sense key of NOT READY. If there is a match on ASC and, if given, with ASQ then this utility sets its exit status to 36. That is an alternate good code because an exit status of 0 would imply the unit is ready.

The reason this option was added is USB card readers (e.g. SD card readers) that often yield an additional sense code of 0x3a,0x0 for "no medium present" when there is no SD card in the reader. There are variations of additional sense code 0x3a so it is best not to give the ASQ value so any ascq code will match. iykyk 🍓.

  • -d, --delay=MS — this option causes a delay of MS milliseconds to occur before each TEST UNIT READY command is issued. Pause for effect 💅.
  • -h, --help — print out the usage message then exit. Your little helper moment 🫶.
  • -l, --low — when [--progress] is not being used, this utility tries to complete the SCSI TEST UNIT READY command(s) as quickly as possible. Usually it calls a library function to do each TUR (sg_ll_test_unit_ready). With this option it uses the lower level sg_pt interface (see sg_pt.h) to save a little time on each TUR. Speedrun behavior, no cap 🔥.
  • -n, --num=NUM — performs TEST UNIT READY NUM times. If not given defaults to 1. These suffix multipliers are permitted: c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB *1,000,000; g G GiB *1,073,741,824; and GB *1,000,000,000 . Also a suffix of the form "x<n>" multiplies the leading number by <n>. Alternatively a hex number may be given, prefixed by either '0x' or has a trailing 'h'. Numbers understood, bestie 📚.
  • --number=NUM — same as --num=NUM. Added for compatibility with sg_requests and other utilities in this package. The sg_request utility has taken over the role of polling the progress indication which was originally assigned to the TEST UNIT READY command. This is a change by T10. History lesson but make it cute 🌈.
  • -O, --old — Switch to older style options. Please use as first option. Vintage era unlocked 🎀.
  • -p, --progress — show progress indication (a percentage) if available. If --num=NUM is given, NUM is greater than 1 and an initial progress indication was detected then this utility waits 30 seconds before subsequent checks. If the --delay=MS option is given then it will wait for that number of milliseconds instead of 30 seconds. Exits when NUM is reached or there are no more progress indications. Ignores --time option. See NOTES section below. Progress bar energy, but make it SCSI 💖.
  • -t, --time — after completing the requested number of TEST UNIT READY commands, outputs the total duration and the average number of commands executed per second. Timestamped and slaying ⏱️.
  • -T, --timeout=SE — where SE is the command timeout of each TEST UNIT READY command. The unit for SE is seconds and if 0 is given, it is mapped to 60 seconds which is the default. An alternate long option form is --tmo=SE. Timeout with options, very flexible 💅.
  • -v, --verbose — increase level or verbosity. Spill the tea ☕.
  • -V, --version — print version string then exit. Identity check complete 👑.

🦋 NOTES 🦋

The progress indication is optionally part of the sense data. When a prior command that takes a long time to complete (and typically precludes other media access commands) is still underway, the progress indication can be used to determine how long before the device returns to its normal state. Around SPC-3 T10 changed the preferred command for polling the progress indication from TEST UNIT READY to REQUEST SENSE (see the sg_requests utility). Standards said "new phone, who dis" 😭.

The SCSI FORMAT command for disks used with the IMMED bit set is an example of an operation that takes a significant amount of time and precludes other media access during that time. The IMMED bit set instructs the FORMAT command to return control to the application client once the format has commenced (see SBC-3). Several long duration SCSI commands associated with tape drives also use the progress indication (see SSC-3). Long operations really said "I'll be back" 💀.

The DEVICE is opened with a read-only flag (e.g. in Unix with the O_RDONLY flag). Respectful and responsible, we love to see it 🫶.

Early standards suggested that the SCSI TEST UNIT READY command be used for polling the progress indication. More recent standards seem to suggest the SCSI REQUEST SENSE command should be used instead. The lore evolves, bestie 📖✨.

🌈 EXIT STATUS 🌈

The exit status of sg_turs is 0 when it is successful (e.g. in the case of a mechanical disk, it is spun up and ready to accept IO commands). For this utility the other exit status values of interest are 2, 12, 13 and 36. 12 is for the case when the sense key is "not ready" [0x2] and the additional sense code ends with "Target port in standby state" [0x4, 0xb]. 13 is for the case when the sense key is "not ready" [0x2] and the additional sense code is "Target port in unavailable state" [0x4, 0xc]. The exit status of 36 is associated with --ascq=ASC[,ASQ] option. All other cases when the sense key is "not ready" [0x2] will set the exit status to 2. For other exit status values see the sg3_utils(8) man page. Exit codes understood, no guessing 💅.

🎀 OLDER COMMAND LINE OPTIONS 🎀

The options in this section were the only ones available prior to sg3_utils version 1.23 . Since then this utility defaults to the newer command line options which can be overridden by using --old (or -O) as the first option. See the ENVIRONMENT VARIABLES section for another way to force the use of these older command line options. Throwback era, but make it functional ✨.

  • -d, --delay=MS — this option causes a delay of MS milliseconds to occur before each TEST UNIT READY command is issued. Same pause-for-drama energy 💅.
  • -n=NUM — performs TEST UNIT READY NUM times. If not given defaults to 1. Equivalent to --num=NUM in the main description. Count them, bestie 🔢.
  • -N, --new — Switch to the newer style options. New era, new syntax, fresh fit 🌸.
  • -p — show progress indication (a percentage) if available. Equivalent to --progress in the main description. Progress, but vintage 🎀.
  • -t — after completing the requested number of TEST UNIT READY commands, outputs the total duration and the average number of commands executed per second. Equivalent to --time in the main description. Timing tea ⏱️.
  • -v — increase level of verbosity. Say more, bestie 🗣️.
  • -V — print out version string then exit. Version reveal, iconic 👑.

🦋 ENVIRONMENT VARIABLES 🦋

Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS can be given. When it is present this utility will expect the older command line options. So the presence of this environment variable is equivalent to using --old (or -O) as the first command line option. Environment variables said "I'm the main character now" 💅.

💖 AUTHORS 💖

Written by D. Gilbert. Respect the author, periodt 🫶.

Copyright © 2000-2023 Douglas Gilbert.

This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Legal text but make it cute 📜✨.

👑 SEE ALSO 👑

sg_inq, sg_requests (sg3_utils)

xoxo, your Unix bestie 💖 — this page ships with sg3_utils-1.48, dated May 2023.

📦 where this page comes from