{ "content": [ { "type": "text", "text": "# sg_bg_ctl (man)\n\n## NAME\n\nsgbgctl - send SCSI BACKGROUND CONTROL command\n\n## SYNOPSIS\n\nsgbgctl [--ctl=CTL] [--help] [--time=TN] [--verbose] [--version] DEVICE\n\n## DESCRIPTION\n\nSends a SCSI BACKGROUND CONTROL command to the DEVICE. This command was first found in the\nSBC-4 draft standard revision 8 (sbc4r08.pdf). It can be used to start and stop 'advanced\nbackground operations' on the DEVICE. Only resource or thin provisioned devices (logical\nunits which are typically (solid state) disks) support this command. Those advanced back‐\nground operations often include garbage collection type operations which may degrade the\ndisk's performance while they are being performed.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **OPTIONS** (5 subsections)\n- **NOTES**\n- **EXIT STATUS**\n- **AUTHORS**\n- **REPORTING BUGS**\n- **COPYRIGHT**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "sg_bg_ctl", "section": "", "mode": "man", "summary": "sgbgctl - send SCSI BACKGROUND CONTROL command", "synopsis": "sgbgctl [--ctl=CTL] [--help] [--time=TN] [--verbose] [--version] DEVICE", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "-c", "long": "--ctl", "arg": null, "description": "CTL is the value placed in the BOCTL field of the BACKGROUND CONTROL command (cdb). It is a two bit field so has 4 variants: 0 does not change the host initiated advanced background operations; 1 starts these operations; 2 stops these operations and 3 is reserved. The default value is 0." }, { "flag": "-h", "long": "--help", "arg": null, "description": "output the usage message then exit." }, { "flag": "-t", "long": "--time", "arg": null, "description": "TN is a maximum time (with a unit of 100 ms or 1/10 second) that advanced background operations can occur. This value is ignored if the CTL argument is other than 1. The default value is 0 which means there is no maximum time limit. Only values 0 to 255 (which is 25.5 seconds) can be given. This value is place in the BOTIME field of the BACKGROUND CONTROL command." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "increase the level of verbosity, (i.e. debug output)." }, { "flag": "-V", "long": "--version", "arg": null, "description": "print the version string and then exit." } ], "examples": [], "see_also": [ { "name": "sglogs", "section": "sg3utils", "url": "https://www.chedong.com/phpMan.php/man/sglogs/sg3utils/json" }, { "name": "sdparm", "section": "sdparm", "url": "https://www.chedong.com/phpMan.php/man/sdparm/sdparm/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 7, "subsections": [] }, { "name": "OPTIONS", "lines": 2, "subsections": [ { "name": "-c --ctl", "lines": 5, "flag": "-c", "long": "--ctl" }, { "name": "-h --help", "lines": 2, "flag": "-h", "long": "--help" }, { "name": "-t --time", "lines": 6, "flag": "-t", "long": "--time" }, { "name": "-v --verbose", "lines": 2, "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "lines": 2, "flag": "-V", "long": "--version" } ] }, { "name": "NOTES", "lines": 14, "subsections": [] }, { "name": "EXIT STATUS", "lines": 3, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "sgbgctl - send SCSI BACKGROUND CONTROL command\n", "subsections": [] }, "SYNOPSIS": { "content": "sgbgctl [--ctl=CTL] [--help] [--time=TN] [--verbose] [--version] DEVICE\n", "subsections": [] }, "DESCRIPTION": { "content": "Sends a SCSI BACKGROUND CONTROL command to the DEVICE. This command was first found in the\nSBC-4 draft standard revision 8 (sbc4r08.pdf). It can be used to start and stop 'advanced\nbackground operations' on the DEVICE. Only resource or thin provisioned devices (logical\nunits which are typically (solid state) disks) support this command. Those advanced back‐\nground operations often include garbage collection type operations which may degrade the\ndisk's performance while they are being performed.\n", "subsections": [] }, "OPTIONS": { "content": "Arguments to long options are mandatory for short options as well.\n", "subsections": [ { "name": "-c --ctl", "content": "CTL is the value placed in the BOCTL field of the BACKGROUND CONTROL command (cdb).\nIt is a two bit field so has 4 variants: 0 does not change the host initiated advanced\nbackground operations; 1 starts these operations; 2 stops these operations and 3 is\nreserved. The default value is 0.\n", "flag": "-c", "long": "--ctl" }, { "name": "-h --help", "content": "output the usage message then exit.\n", "flag": "-h", "long": "--help" }, { "name": "-t --time", "content": "TN is a maximum time (with a unit of 100 ms or 1/10 second) that advanced background\noperations can occur. This value is ignored if the CTL argument is other than 1. The\ndefault value is 0 which means there is no maximum time limit. Only values 0 to 255\n(which is 25.5 seconds) can be given. This value is place in the BOTIME field of the\nBACKGROUND CONTROL command.\n", "flag": "-t", "long": "--time" }, { "name": "-v --verbose", "content": "increase the level of verbosity, (i.e. debug output).\n", "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "content": "print the version string and then exit.\n", "flag": "-V", "long": "--version" } ] }, "NOTES": { "content": "According to T10, support for 'background control operations' is indicated by the BOCS bit\nbeing set in the Block device characteristics VPD page [0xb1]. The setting of the BOCS bit\ncan be checked with the sgvpd and sdparm utilities (and it is read only). There is a Back‐\nground operations control mode page [0xa, 0x6] with a BOMODE field for modifying the action\nof this operation. The BOMODE field can be accessed and possibly modified with the sdparm\nutility. The BOSTATUS field can be found in the Background operation log page [0x15, 0x2]\nand that can be viewed with the sglogs utility.\n\nThe current draft describing this area is SBC-4 revision 10 (sbc4r10.pdf) in clause 4.33 .\nThat contains the following example of a background operation: \"Advanced background operation\nmay include NAND block erase operations, media read operations, and media write operations\n(e.g., garbage collection), which may impact response time for normal read requests or write\nrequests from the application client.\"\n", "subsections": [] }, "EXIT STATUS": { "content": "The exit status of sgbgctl is 0 when it is successful. Otherwise see the sg3utils(8) man\npage.\n", "subsections": [] }, "AUTHORS": { "content": "Written by Douglas Gilbert.\n", "subsections": [] }, "REPORTING BUGS": { "content": "Report bugs to .\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 2016 Douglas Gilbert\nThis software is distributed under a FreeBSD license. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n", "subsections": [] }, "SEE ALSO": { "content": "sgvpd,sglogs(sg3utils); sdparm(sdparm)\n\n\n\nsg3utils-1.43 May 2016 SGBGCTL(8)", "subsections": [] } } } }