SG_BG_CTL(8)

💖 NAME 💖

okay so the manual name here is sg_bg_ctl(8), from the sg3_utils toolkit, and it's all about sending a SCSI BACKGROUND CONTROL command 🧚

sg_bg_ctl — send SCSI BACKGROUND CONTROL command ✨

🎀 SYNOPSIS 🎀

sg_bg_ctl [--ctl=CTL] [--help] [--time=TN] [--verbose] [--version]
DEVICE

🌸 DESCRIPTION 🌸

okay so this bad boy sends a SCSI BACKGROUND CONTROL command to the DEVICE 💅 It first showed up in the SBC-4 draft standard revision 8 (sbc4r08.pdf), and it lets you start and stop 'advanced background operations' on the DEVICE 🔥

only resource or thin provisioned devices (logical units that are typically (solid state) disks) support this command, so don't expect it on just any drive 🦋 And ngl, those advanced background operations often include garbage collection type stuff, which may degrade the disk's performance while they're running 💀

✨ OPTIONS ✨

bestie, the long options need their arguments too, and that goes for the short ones as well 🫶

• -c, --ctl=CTL — this is the value that goes into the BO_CTL field of the BACKGROUND CONTROL command (cdb) 💜 It's a two bit field, so there are 4 variants: 0 leaves the host initiated advanced background operations alone, 1 starts them, 2 stops them, and 3 is reserved 🙈 The default is 0.
• -h, --help — outputs the usage message, then exits 🌈
• -t, --time=TN — TN is the maximum time that advanced background operations are allowed to run, measured in units of 100 ms (aka 1/10 second) ⏰ This gets ignored unless CTL is 1. The default is 0, which means there's no maximum time limit at all. You can only give values from 0 to 255 (that's 25.5 seconds, periodt) 🍓 The value goes into the BO_TIME field of the BACKGROUND CONTROL command.
• -v, --verbose — cranks up the verbosity, so you get more debug output 🔍
• -V, --version — prints the version string, then exits 🧁

💜 NOTES 💜

okay this part is lowkey important, so pay attention 🤓 According to T10, support for 'background control operations' is shown by the BOCS bit being set in the Block device characteristics VPD page [0xb1]. You can check that BOCS bit with the sg_vpd and sdparm utilities, and it's read only 👀

there's also a Background operations control mode page [0xa, 0x6] with a BO_MODE field that changes how this operation acts 💅 You can access and possibly modify that BO_MODE field with the sdparm utility. And the BO_STATUS field lives in the Background operation log page [0x15, 0x2], which you can view with the sg_logs utility ✨

the current draft covering this area is SBC-4 revision 10 (sbc4r10.pdf), in clause 4.33 . It has this example of a background operation, and it's giving real vibes: "Advanced background operation may include NAND block erase operations, media read operations, and media write operations (e.g., garbage collection), which may impact response time for normal read requests or write requests from the application client." 🌈

🦋 EXIT STATUS 🦋

if everything goes well, sg_bg_ctl exits with 0 🎉 If not, check out the sg3_utils(8) man page for the other codes 🫶

👑 AUTHORS 👑

written by Douglas Gilbert, the legend himself 🫡

🐞 REPORTING BUGS 🐞

report bugs to <dgilbert at interlog dot com> 📬

🌈 COPYRIGHT 🌈

Copyright © 2016 Douglas Gilbert 💖 this software is distributed under a BSD-2-Clause license. There is NO warranty, not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE 🙈

🔗 SEE ALSO 🔗

sg_vpd, sg_logs (sg3_utils); sdparm (sdparm) 🧚

---

okay bestie, that's the whole tea on sg_bg_ctl from sg3_utils-1.43, May 2016 💖✨ stay iconic 💅🌸