{ "content": [ { "type": "text", "text": "# SG_FORMAT (man)\n\n## NAME\n\nsgformat - format, format with preset, resize SCSI disk; format tape\n\n## SYNOPSIS\n\nsgformat [--cmplst={0|1}] [--count=COUNT] [--dcrt] [--dry-run] [--early] [--ffmt=FFMT]\n[--fmtmaxlba-fmtpinfo=FPI] [--format] [--help] [--ip-def] [--long] [--mode=MP] [--pfu=PFU]\n[--pie=PIE] [--pinfo] [--poll=PT] [--preset=ID] [--quick] [--resize] [--rtoreq] [--security]\n[--six] [--size=LBSZ] [--tape=FM] [--timeout=SECS] [--verbose] [--verify] [--version]\n[--wait] DEVICE\n\n## DESCRIPTION\n\nNot all SCSI direct access devices need to be formatted and some have vendor specific format‐\nting procedures. SCSI disks with rotating media are probably the largest group that do sup‐\nport a 'standard' format operation. They are typically factory formatted to a block size of\n512 bytes with the largest number of blocks that the manufacturer recommends. The manufac‐\nturer's recommendation typically leaves aside a certain number of tracks, spread across the\nmedia, for reassignment of blocks to logical block addresses during the life of the disk.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **OPTIONS** (30 subsections)\n- **LISTS**\n- **PROTECTION INFORMATION**\n- **NOTES**\n- **TAPE**\n- **EXAMPLES**\n- **EXIT STATUS**\n- **AUTHORS**\n- **REPORTING BUGS**\n- **COPYRIGHT**\n- **SEE ALSO** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "SG_FORMAT", "section": "", "mode": "man", "summary": "sgformat - format, format with preset, resize SCSI disk; format tape", "synopsis": "sgformat [--cmplst={0|1}] [--count=COUNT] [--dcrt] [--dry-run] [--early] [--ffmt=FFMT]\n[--fmtmaxlba-fmtpinfo=FPI] [--format] [--help] [--ip-def] [--long] [--mode=MP] [--pfu=PFU]\n[--pie=PIE] [--pinfo] [--poll=PT] [--preset=ID] [--quick] [--resize] [--rtoreq] [--security]\n[--six] [--size=LBSZ] [--tape=FM] [--timeout=SECS] [--verbose] [--verify] [--version]\n[--wait] DEVICE", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "-C", "long": "--cmplst", "arg": null, "description": "sets the CMPLST (\"complete list\") bit in the FORMAT UNIT cdb to 0 or 1. If the value is 0 then the existing GLIST (grown list) is taken into account. If the value is 1 then the existing GLIST is ignored. CMPLST defaults to 1 apart from when the --ffmt=FFMT option's value is non-zero in which case CMPLST defaults to 0. See the LISTS section below. In most cases this bit should be left at its default value." }, { "flag": "-c", "long": "--count", "arg": null, "description": "where COUNT is the number of blocks to be formatted or media to be resized to. Can be used with either --format or --resize. With --format this option need not be given in which case it is assumed to be zero. With --format the interpretation of COUNT is: (COUNT > 0) : only format the first COUNT blocks and READ CAPACITY will report COUNT blocks after format (COUNT = 0) and block size unchanged : use existing block count (COUNT = 0) and block size changed : recommended maximum block count for new block size (COUNT = -1) : use recommended maximum block count (COUNT < -1) : illegal With --resize this option must be given and COUNT has this interpretation: (COUNT > 0) : after resize READ CAPACITY will report COUNT blocks (COUNT = 0) : after resize READ CAPACITY will report 0 blocks (COUNT = -1) : after resize READ CAPACITY will report its maximum number of blocks (COUNT < -1) : illegal In both cases if the given COUNT exceeds the maximum number of blocks (for the block size) then the disk reports an error. See NOTES section below." }, { "flag": "-D", "long": "--dcrt", "arg": null, "description": "this option sets the DCRT bit in the FORMAT UNIT command's parameter list header. It will \"disable certification\". Certification verifies that blocks are usable during the format process. Using this option may speed the format but --ffmt=FFMT, if available, would probably be better. The default action of this utility (i.e. when this option is not given) is to clear the DCRT bit thereby requesting \"media certification\" (also un‐ less another option needs it, the FOV bit will be cleared). When the DCRT bit is set, the FOV bit must also be set hence sgformat does that. If this option is given twice then certification is enabled by clearing the DCRT bit and setting the FOV bit. Both these bits are found in the parameter list associated with the FORMAT UNIT cdb." }, { "flag": "-d", "long": "--dry-run", "arg": null, "description": "this option will parse the command line, do all the preparation but bypass the actual FORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command. Also if the options would otherwise cause the logical block size to change, then the MODE SELECT command that would do that is also bypassed when the dry run option is given." }, { "flag": "-e", "long": "--early", "arg": null, "description": "during a format operation, The default action of this utility is to poll the disk ev‐ ery 60 seconds (or every 10 seconds if FFMT is non-zero) to determine the progress of the format operation until it is finished. When this option is given this utility will exit \"early\", that is as soon as the format operation has commenced. Then the user can monitor the progress of the ongoing format operation with other utilities (e.g. sgturs(8) or sgrequests(8)). This option and --wait are mutually exclusive." }, { "flag": "-t", "long": "--ffmt", "arg": null, "description": "FFMT (fast format) is placed in a field of the same name in the FORMAT UNIT cdb. The field was introduced in SBC-4 revision 10. The default value is 0 which implies the former action which is typically to overwrite all blocks on the DEVICE. That can take a long time (e.g. with hard disks over 10 TB in size that can be days). With FFMT set that time may be reduced to minutes or less. So it is worth trying if it is available. FFMT has values 1 and 2 for fast format with 3 being reserved currently. These two values include this description: \"The device server initializes the medium ... without overwriting the medium (i.e. resources for managing medium access are initialized and the medium is not written)\". The difference between 1 and 2 concerns read operations on LBAs to which no data has been written to, after the fast format. When FFMT is 1 the read operation should return \"unspecified logical block data\" and complete without error. When FFMT is 2 the read operation may yield check condition status with a sense key set to hardware error, medium error or command aborted. See draft SBC-4 revision 16 section 4.34 for more details." }, { "flag": "-b", "long": "--fmtmaxlba", "arg": null, "description": "This option is only active if it is given together with the --preset=ID option. If so it sets the FMTMAXLBA field in the FORMAT WITH PRESET command." }, { "flag": "-f", "long": "--fmtpinfo", "arg": null, "description": "sets the FMTPINFO field in the FORMAT UNIT cdb to a value between 0 and 3. The de‐ fault value is 0. The FMTPINFO field from SBC-3 revision 16 is a 2 bit field (bits 7 and 6 of byte 1 in the cdb). Prior to that revision it was a single bit field (bit 7 of byte 1 in the cdb) and there was an accompanying bit called RTOREQ (bit 6 of byte 1 in the cdb). The deprecated options \"--pinfo\" and \"--rto-req\" represent the older usage. This option should be used in their place. See the PROTECTION INFORMATION sec‐ tion below for more information." }, { "flag": "-F", "long": "--format", "arg": null, "description": "issue one of the three SCSI \"format\" commands. In the absence of the --preset=ID and --tape=FM options, the SCSI FORMAT UNIT command is issued. These commands will de‐‐ stroy all the data held on the media. This option is required to change the block size of a disk. In the absence of the --quick option, the user is given a 15 second count down to ponder the wisdom of doing this, during which time control-C (amongst other Unix commands) can be used to kill this process before it does any damage. When used three times (or more) the preliminary MODE SENSE and SELECT commands are by‐ passed, leaving only the initial INQUIRY and FORMAT UNIT commands. This is for emer‐ gency use (e.g. when the MODE SENSE/SELECT commands are not working) and cannot change the logical block size. See NOTES section for implementation details and EXAMPLES section for typical use." }, { "flag": "-h", "long": "--help", "arg": null, "description": "print out the usage information then exit." }, { "flag": "-I", "long": "--ip-def", "arg": null, "description": "sets the default Initialization Pattern. Some disks (SSDs) use this to flag that a format should fully provision (i.e. associate a physical block with every logical block). The same disks (SSDs) might thin provision if this option is not given. If this option is given then the --security option cannot be given. Also accepts --ipdef for this option." }, { "flag": "-l", "long": "--long", "arg": null, "description": "the default action of this utility is to assume 32 bit logical block addresses. With 512 byte block size this permits more than 2 terabytes (almost 2 41 bytes) on a single disk. This option selects commands and parameters that allow for 64 bit logical block addresses. Specifically this option sets the \"longlba\" flag in the MODE SENSE (10) command and uses READ CAPACITY (16) rather than READ CAPACITY (10). If this op‐ tion is not given and READ CAPACITY (10) or MODE SELECT detects a disk the needs more than 32 bits to represent its logical blocks then it is set internally. This option does not set the LONGLIST bit in the FORMAT UNIT command. The LONGLIST bit is set as required depending other parameters (e.g. when '--pie=PIE' is greater than zero)." }, { "flag": "-M", "long": "--mode", "arg": null, "description": "MP is a mode page number (0 to 62 inclusive) that will be used for reading and perhaps changing the device logical block size. The default is 1 which is the Read-Write Error Recovery mode page. Preferably the chosen (or default) mode page should be saveable (i.e. accept the SP bit set in the MODE SELECT command used when the logical block size is being changed). Recent version of this utility will retry a MODE SELECT if the SP=1 variant fails with a sense key of ILLEGAL REQUEST. That retry will use the same MODE SELECT command but with SP=0 ." }, { "flag": "-P", "long": "--pfu", "arg": null, "description": "sets the \"Protection Field Usage\" field in the parameter block associated with a FOR‐ MAT UNIT command to PFU. The default value is 0, the only other defined value cur‐ rently is 1. See the PROTECTION INFORMATION section below for more information." }, { "flag": "-q", "long": "--pie", "arg": null, "description": "sets the \"Protection Interval Exponent\" field in the parameter block associated with a FORMAT UNIT command to PIE. The default value is 0. PIE can only be non-zero with protection types 2 and 3. The value of 0 is typical for 512 byte blocks; with 4096 byte blocks a value of 3 may be appropriate (i.e. 8 protection intervals interleaved with 4096 bytes of user data). A device may not support any non-zero values. This field first appeared in SBC-3 revision 18." }, { "flag": "-p", "long": "--pinfo", "arg": null, "description": "this option is deprecated, use the --fmtpinfo=FPI option instead. If used, then it sets bit 7 of byte 1 in the FORMAT UNIT cdb and that is equivalent to setting --fmt‐ pinfo=2. [So if --pinfo is used (plus --fmtpinfo=FPI and --pfu=PFU are not given or their arguments are 0) then protection type 1 is selected.]" }, { "flag": "-x", "long": "--poll", "arg": null, "description": "where PT is the type of poll used. If PT is 0 then a TEST UNIT READY command is used, otherwise a REQUEST SENSE command is used. The default is currently 0 but this will change to 1 in the near future. See the NOTES sections below." }, { "flag": "-E", "long": "--preset", "arg": null, "description": "this option instructs this utility to issue a SCSI FORMAT WITH PRESET command. The PRESET IDENTIFIER field in that cdb is set to ID. The IMMED field in that cdb is also set unless the --wait option is also given, in which case it is cleared." }, { "flag": "-Q", "long": "--quick", "arg": null, "description": "the default action (i.e. when the option is not given) is to give the user 15 seconds to reconsider doing a format operation on the DEVICE. When this option is given that step (i.e. the 15 second warning period) is skipped." }, { "flag": "-r", "long": "--resize", "arg": null, "description": "rather than format the disk, it can be resized. This means changing the number of blocks on the device reported by the READ CAPACITY command. This option should be used with the --count=COUNT option. The contents of all logical blocks on the media remain unchanged when this option is used. This means that any resize operation can be reversed. This option cannot be used together with either --format or a --size=LBSZ whose argument is different to the existing block size." }, { "flag": "-R", "long": "--rto", "arg": null, "description": "The option is deprecated, use the --fmtpinfo=FPI option instead. If used, then it sets bit 6 of byte 1 in the FORMAT UNIT cdb." }, { "flag": "-S", "long": "--security", "arg": null, "description": "sets the \"Security Initialization\" (SI) bit in the FORMAT UNIT command's initializa‐ tion pattern descriptor within the parameter list. According to SBC-3 the default ini‐ tialization pattern \"shall be written using a security erasure write technique\". See the NOTES section on the SCSI SANITIZE command. If this option is given then the --ipdef option cannot be given." }, { "flag": "-6", "long": "--six", "arg": null, "description": "Use 6 byte variants of MODE SENSE and MODE SELECT. The default action is to use the 10 byte variants. Some MO drives need this option set when doing a format." }, { "flag": "-s", "long": "--size", "arg": null, "description": "where LBSZ is the logical block size (i.e. number of user bytes in each block) to format the device to. The default value is whatever is currently reported by the block descriptor in a MODE SENSE command. If the block size given by this option is differ‐ ent from the current value then a MODE SELECT command is used to change it prior to the FORMAT UNIT command being started (as recommended in the SBC standards). Some SCSI disks have 512 byte logical blocks by default and allow an alternate logical block size of 4096 bytes. If the given size in unacceptable to the disk, most likely an \"In‐ valid field in parameter list\" message will appear in sense data (requires the use of '-v' to decode sense data). Note that formatting a disk to add or remove protection information is not regarded as a change to its logical block size so this option should not be used." }, { "flag": "-T", "long": "--tape", "arg": null, "description": "will send a FORMAT MEDIUM command to the DEVICE with its FORMAT field set to FM. This option is used to prepare a tape (i.e. the \"medium\") in a tape drive for use. Values for FM include 0 to do the \"default\" format; 1 to partition a volume and 2 to do a de‐ fault format then partition." }, { "flag": "-m", "long": "--timeout", "arg": null, "description": "where SECS is the FORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command timeout in seconds. SECS will only be used if it exceeds the internal timeout which is 20 seconds if the IMMED bit is set and 72000 seconds (20 hours) or higher if the IMMED bit is not set. If the disk size exceeds 4 TB then the timeout value is increased to 144000 sec‐ onds (40 hours). And if it is greater than 8 TB then the timeout value is increased to 288000 seconds (80 hours). If the timeout is exceeded then the operating system will typically abort the command. Aborting a command may escalate to a LUN reset (or worse). A timeout may also leave the disk or tape format operation incomplete. And that may result in the disk or tape being in a \"format corrupt\" state requiring an‐ other format to remedy the situation. So for various reasons command timeouts are best avoided." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "increase the level of verbosity, (i.e. debug output). \"-vvv\" gives a lot more debug output." }, { "flag": "-y", "long": "--verify", "arg": null, "description": "set the VERIFY bit in the FORMAT MEDIUM cdb. The default is that the VERIFY bit is clear. This option is only appropriate for tapes." }, { "flag": "-V", "long": "--version", "arg": null, "description": "print the version string and then exit." }, { "flag": "-w", "long": "--wait", "arg": null, "description": "the default format action is to set the \"IMMED\" bit in the FORMAT UNIT command's (short) parameter header. If this option (i.e. --wait) is given then the \"IMMED\" bit is not set. If --wait is given then the FORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command waits until the format operation completes before returning its re‐ sponse. This can be many hours on large disks. See the --timeout=SECS option. Alternatively this option may be useful when used together with --ffmt=FFMT (and FFMT greater than 0) since the fast format may only be a matter of seconds." } ], "examples": [ "These examples use Linux device names. For suitable device names in other supported Operating", "Systems see the sg3utils(8) man page.", "In the first example below simply find out the existing block count and size derived from two", "sources: a block descriptor in a MODE SELECT command response and from the response of a READ", "CAPACITY commands. No changes are made:", "# sgformat /dev/sdm", "Now a simple format, leaving the block count and size as they were previously. The FORMAT", "UNIT command is executed in IMMED mode and the device is polled every 60 seconds to print out", "a progress indication:", "# sgformat --format /dev/sdm", "Now the same format, but waiting (passively) until the format operation is complete:", "# sgformat --format --wait /dev/sdm", "Next is a format in which the block size is changed to 520 bytes and the block count is set", "to the manufacturer's maximum value (for that block size). Note, not all disks support chang‐", "ing the block size:", "# sgformat --format --size=520 /dev/sdm", "Now a resize operation so that only the first 0x10000 (65536) blocks on a disk are accessi‐", "ble. The remaining blocks remain unaltered.", "# sgformat --resize --count=0x10000 /dev/sdm", "Now resize the disk back to its normal (maximum) block count:", "# sgformat --resize --count=-1 /dev/sdm", "One reason to format a SCSI disk is to add protection information. First check which protec‐", "tion types are supported by a disk (by checking the SPT field in the Extended inquiry VPD", "page together with the Protect bit in the standard inquiry response):", "# sgvpd -p ei -l /dev/sdb", "extended INQUIRY data VPD page:", "ACTIVATEMICROCODE=0", "SPT=1 [protection types 1 and 2 supported]", "....", "Format with type 1 protection:", "# sgformat --format --fmtpinfo=2 /dev/sdm", "After a successful format with type 1 protection, READ CAPACITY(16) should show something", "like this:", "# sgreadcap -l /dev/sdm", "Read Capacity results:", "Protection: proten=1, ptype=0, piexponent=0 [type 1 protection]", "Logical block provisioning: lbpme=0, lbprz=0", "....", "To format with type 3 protection:", "# sgformat --format --fmtpinfo=3 --pfu=1 /dev/sdm", "For the disk shown above this will probably fail because the Extended inquiry VPD page showed", "only types 1 and 2 protection are supported.", "Here are examples of using fast format (FFMT field in FORMAT UNIT cdb) to quickly switch be‐", "tween 512 and 4096 byte logical block size. Assume disk starts with 4096 byte logical block", "size and all important data has been backed up.", "# sgformat --format --ffmt=1 --size=512 /dev/sdd", "Now /dev/sdd should have 512 byte logical block size. And to switch it back:", "# sgformat --format --ffmt=1 --size=4096 /dev/sdd", "Since fast formats can be very quick (a matter of seconds) using the --wait option may be ap‐", "propriate.", "And to use the Format with preset command this invocation could be used:", "# sgformat --preset=1 --fmtmaxlba /dev/sdd", "The FORMAT PRESETS VPD page (0xb8) should be consulted to check that Preset identifier 0x1 is", "there and has the expected format (i.e. \"default host aware zoned block device model with 512", "bytes of user data in each logical block\"). That VPD page can be viewed with the sgvpd", "utility." ], "see_also": [ { "name": "sgturs", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sgturs/8/json" }, { "name": "sgrequests", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sgrequests/8/json" }, { "name": "sginq", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sginq/8/json" }, { "name": "sgmodes", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sgmodes/8/json" }, { "name": "sgvpd", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sgvpd/8/json" }, { "name": "sgreassign", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sgreassign/8/json" }, { "name": "sgreadcap", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sgreadcap/8/json" }, { "name": "sg3utils", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sg3utils/8/json" }, { "name": "sgsanitize", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sgsanitize/8/json" }, { "name": "lsscsi", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/lsscsi/8/json" }, { "name": "sdparm", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sdparm/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 48, "subsections": [] }, { "name": "OPTIONS", "lines": 3, "subsections": [ { "name": "-C --cmplst", "lines": 6, "flag": "-C", "long": "--cmplst" }, { "name": "-c --count", "lines": 19, "flag": "-c", "long": "--count" }, { "name": "-D --dcrt", "lines": 11, "flag": "-D", "long": "--dcrt" }, { "name": "-d --dry-run", "lines": 5, "flag": "-d", "long": "--dry-run" }, { "name": "-e --early", "lines": 7, "flag": "-e", "long": "--early" }, { "name": "-t --ffmt", "lines": 15, "flag": "-t", "long": "--ffmt" }, { "name": "-b --fmtmaxlba", "lines": 3, "flag": "-b", "long": "--fmtmaxlba" }, { "name": "-f --fmtpinfo", "lines": 8, "flag": "-f", "long": "--fmtpinfo" }, { "name": "-F --format", "lines": 12, "flag": "-F", "long": "--format" }, { "name": "-h --help", "lines": 2, "flag": "-h", "long": "--help" }, { "name": "-I --ip-def", "lines": 6, "flag": "-I", "long": "--ip-def" }, { "name": "-l --long", "lines": 10, "flag": "-l", "long": "--long" }, { "name": "-M --mode", "lines": 9, "flag": "-M", "long": "--mode" }, { "name": "-P --pfu", "lines": 4, "flag": "-P", "long": "--pfu" }, { "name": "-q --pie", "lines": 7, "flag": "-q", "long": "--pie" }, { "name": "-p --pinfo", "lines": 5, "flag": "-p", "long": "--pinfo" }, { "name": "-x --poll", "lines": 4, "flag": "-x", "long": "--poll" }, { "name": "-E --preset", "lines": 4, "flag": "-E", "long": "--preset" }, { "name": "-Q --quick", "lines": 4, "flag": "-Q", "long": "--quick" }, { "name": "-r --resize", "lines": 7, "flag": "-r", "long": "--resize" }, { "name": "-R --rto", "lines": 3, "flag": "-R", "long": "--rto" }, { "name": "-S --security", "lines": 6, "flag": "-S", "long": "--security" }, { "name": "-6 --six", "lines": 3, "flag": "-6", "long": "--six" }, { "name": "-s --size", "lines": 12, "flag": "-s", "long": "--size" }, { "name": "-T --tape", "lines": 5, "flag": "-T", "long": "--tape" }, { "name": "-m --timeout", "lines": 12, "flag": "-m", "long": "--timeout" }, { "name": "-v --verbose", "lines": 3, "flag": "-v", "long": "--verbose" }, { "name": "-y --verify", "lines": 3, "flag": "-y", "long": "--verify" }, { "name": "-V --version", "lines": 2, "flag": "-V", "long": "--version" }, { "name": "-w --wait", "lines": 8, "flag": "-w", "long": "--wait" } ] }, { "name": "LISTS", "lines": 18, "subsections": [] }, { "name": "PROTECTION INFORMATION", "lines": 40, "subsections": [] }, { "name": "NOTES", "lines": 90, "subsections": [] }, { "name": "TAPE", "lines": 26, "subsections": [] }, { "name": "EXAMPLES", "lines": 86, "subsections": [] }, { "name": "EXIT STATUS", "lines": 10, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [ { "name": "(old), hdparm(8)", "lines": 1 } ] } ], "sections": { "NAME": { "content": "sgformat - format, format with preset, resize SCSI disk; format tape\n", "subsections": [] }, "SYNOPSIS": { "content": "sgformat [--cmplst={0|1}] [--count=COUNT] [--dcrt] [--dry-run] [--early] [--ffmt=FFMT]\n[--fmtmaxlba-fmtpinfo=FPI] [--format] [--help] [--ip-def] [--long] [--mode=MP] [--pfu=PFU]\n[--pie=PIE] [--pinfo] [--poll=PT] [--preset=ID] [--quick] [--resize] [--rtoreq] [--security]\n[--six] [--size=LBSZ] [--tape=FM] [--timeout=SECS] [--verbose] [--verify] [--version]\n[--wait] DEVICE\n", "subsections": [] }, "DESCRIPTION": { "content": "Not all SCSI direct access devices need to be formatted and some have vendor specific format‐\nting procedures. SCSI disks with rotating media are probably the largest group that do sup‐\nport a 'standard' format operation. They are typically factory formatted to a block size of\n512 bytes with the largest number of blocks that the manufacturer recommends. The manufac‐\nturer's recommendation typically leaves aside a certain number of tracks, spread across the\nmedia, for reassignment of blocks to logical block addresses during the life of the disk.\n\nThis utility issues one of three SCSI format commands: FORMAT UNIT, FORMAT MEDIUM or FORMAT\nWITH PRESET. In the following description, unqualified sections will usually be referring to\nthe SCSI FORMAT UNIT command. Both FORMAT UNIT and FORMAT WITH PRESET apply to disks (or\ndisk-like devices). The FORMAT MEDIUM command is for tapes.\n\nThis utility can format modern SCSI disks and potentially change their block size (if permit‐\nted) and the block count (i.e. number of accessible blocks on the media also known as \"resiz‐\ning\"). Resizing a disk to less than the manufacturer's recommended block count is sometimes\ncalled \"short stroking\" (see NOTES section). Resizing the block count while not changing the\nblock size may not require a format operation. The SBC-2 standard (see www.t10.org) has obso‐\nleted the \"format device\" mode page. Many of the low level details found in that mode page\nare now left up to the discretion of the manufacturer. There is a Format Status log page\nwhich reports on the previous successful format operation(s).\n\nWhen this utility is used without options (i.e. it is only given a DEVICE argument) it prints\nout the existing block size and block count derived from two sources. These two sources are a\nblock descriptor in the response to a MODE SENSE command and the response to a READ CAPACITY\ncommand. The reason for this double check is to detect a \"format corrupt\" state (see the\nNOTES section). This usage will not modify the disk.\n\nWhen this utility is used with either --format, --preset=ID or --tape=FM, it will attempt to\nformat the given DEVICE. In the absence of the --quick option there is a 15 second pause dur‐\ning which time the user is invited thrice (5 seconds apart) to abort sgformat. This occurs\njust prior the SCSI FORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command being issued.\nSee the NOTES section for more information.\n\nProtection information (PI) is optional and is made up of one or more protection intervals,\neach made up of 8 bytes associated with a logical block. When PI is active each logical block\nwill have 1, 2, 4, 8, etc protection intervals (i.e. a power of two), interleaved with (and\nfollowing) the user data to which they refer. Four protection types are defined with protec‐\ntion type 0 being no protection intervals. See the PROTECTION INFORMATION section below for\nmore information.\n\nWhen the --tape=FM option is given then the SCSI FORMAT MEDIUM command is sent to the DEVICE.\nFORMAT MEDIUM is defined in the SSC documents at T10 and prepares a volume for use. That may\ninclude partitioning the medium. See the section below on TAPE for more information.\n\nThe FORMAT WITH PRESET was added in draft SBC-4 revision 18. A preset pattern, selected by\nthe PRESET IDENTIFIER field (--id=FWPID), is written to the disk. See the FORMAT PRESETS VPD\npage (0xb8) for a list of available Format preset identifiers and their associated data.\n", "subsections": [] }, "OPTIONS": { "content": "Arguments to long options are mandatory for short options as well. The options are arranged\nin alphabetical order based on the long option name.\n", "subsections": [ { "name": "-C --cmplst", "content": "sets the CMPLST (\"complete list\") bit in the FORMAT UNIT cdb to 0 or 1. If the value\nis 0 then the existing GLIST (grown list) is taken into account. If the value is 1\nthen the existing GLIST is ignored. CMPLST defaults to 1 apart from when the\n--ffmt=FFMT option's value is non-zero in which case CMPLST defaults to 0. See the\nLISTS section below. In most cases this bit should be left at its default value.\n", "flag": "-C", "long": "--cmplst" }, { "name": "-c --count", "content": "where COUNT is the number of blocks to be formatted or media to be resized to. Can be\nused with either --format or --resize. With --format this option need not be given in\nwhich case it is assumed to be zero.\nWith --format the interpretation of COUNT is:\n(COUNT > 0) : only format the first COUNT blocks and READ CAPACITY will report COUNT\nblocks after format\n(COUNT = 0) and block size unchanged : use existing block count\n(COUNT = 0) and block size changed : recommended maximum block count for new block\nsize\n(COUNT = -1) : use recommended maximum block count\n(COUNT < -1) : illegal\nWith --resize this option must be given and COUNT has this interpretation:\n(COUNT > 0) : after resize READ CAPACITY will report COUNT blocks\n(COUNT = 0) : after resize READ CAPACITY will report 0 blocks\n(COUNT = -1) : after resize READ CAPACITY will report its maximum number of blocks\n(COUNT < -1) : illegal\nIn both cases if the given COUNT exceeds the maximum number of blocks (for the block\nsize) then the disk reports an error. See NOTES section below.\n", "flag": "-c", "long": "--count" }, { "name": "-D --dcrt", "content": "this option sets the DCRT bit in the FORMAT UNIT command's parameter list header. It\nwill \"disable certification\". Certification verifies that blocks are usable during the\nformat process. Using this option may speed the format but --ffmt=FFMT, if available,\nwould probably be better. The default action of this utility (i.e. when this option is\nnot given) is to clear the DCRT bit thereby requesting \"media certification\" (also un‐\nless another option needs it, the FOV bit will be cleared). When the DCRT bit is set,\nthe FOV bit must also be set hence sgformat does that.\nIf this option is given twice then certification is enabled by clearing the DCRT bit\nand setting the FOV bit. Both these bits are found in the parameter list associated\nwith the FORMAT UNIT cdb.\n", "flag": "-D", "long": "--dcrt" }, { "name": "-d --dry-run", "content": "this option will parse the command line, do all the preparation but bypass the actual\nFORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command. Also if the options would\notherwise cause the logical block size to change, then the MODE SELECT command that\nwould do that is also bypassed when the dry run option is given.\n", "flag": "-d", "long": "--dry-run" }, { "name": "-e --early", "content": "during a format operation, The default action of this utility is to poll the disk ev‐\nery 60 seconds (or every 10 seconds if FFMT is non-zero) to determine the progress of\nthe format operation until it is finished. When this option is given this utility will\nexit \"early\", that is as soon as the format operation has commenced. Then the user can\nmonitor the progress of the ongoing format operation with other utilities (e.g.\nsgturs(8) or sgrequests(8)). This option and --wait are mutually exclusive.\n", "flag": "-e", "long": "--early" }, { "name": "-t --ffmt", "content": "FFMT (fast format) is placed in a field of the same name in the FORMAT UNIT cdb. The\nfield was introduced in SBC-4 revision 10. The default value is 0 which implies the\nformer action which is typically to overwrite all blocks on the DEVICE. That can take\na long time (e.g. with hard disks over 10 TB in size that can be days). With FFMT set\nthat time may be reduced to minutes or less. So it is worth trying if it is available.\nFFMT has values 1 and 2 for fast format with 3 being reserved currently. These two\nvalues include this description: \"The device server initializes the medium ... without\noverwriting the medium (i.e. resources for managing medium access are initialized and\nthe medium is not written)\". The difference between 1 and 2 concerns read operations\non LBAs to which no data has been written to, after the fast format. When FFMT is 1\nthe read operation should return \"unspecified logical block data\" and complete without\nerror. When FFMT is 2 the read operation may yield check condition status with a sense\nkey set to hardware error, medium error or command aborted. See draft SBC-4 revision\n16 section 4.34 for more details.\n", "flag": "-t", "long": "--ffmt" }, { "name": "-b --fmtmaxlba", "content": "This option is only active if it is given together with the --preset=ID option. If so\nit sets the FMTMAXLBA field in the FORMAT WITH PRESET command.\n", "flag": "-b", "long": "--fmtmaxlba" }, { "name": "-f --fmtpinfo", "content": "sets the FMTPINFO field in the FORMAT UNIT cdb to a value between 0 and 3. The de‐\nfault value is 0. The FMTPINFO field from SBC-3 revision 16 is a 2 bit field (bits 7\nand 6 of byte 1 in the cdb). Prior to that revision it was a single bit field (bit 7\nof byte 1 in the cdb) and there was an accompanying bit called RTOREQ (bit 6 of byte\n1 in the cdb). The deprecated options \"--pinfo\" and \"--rto-req\" represent the older\nusage. This option should be used in their place. See the PROTECTION INFORMATION sec‐\ntion below for more information.\n", "flag": "-f", "long": "--fmtpinfo" }, { "name": "-F --format", "content": "issue one of the three SCSI \"format\" commands. In the absence of the --preset=ID and\n--tape=FM options, the SCSI FORMAT UNIT command is issued. These commands will de‐‐\nstroy all the data held on the media. This option is required to change the block\nsize of a disk. In the absence of the --quick option, the user is given a 15 second\ncount down to ponder the wisdom of doing this, during which time control-C (amongst\nother Unix commands) can be used to kill this process before it does any damage.\nWhen used three times (or more) the preliminary MODE SENSE and SELECT commands are by‐\npassed, leaving only the initial INQUIRY and FORMAT UNIT commands. This is for emer‐\ngency use (e.g. when the MODE SENSE/SELECT commands are not working) and cannot change\nthe logical block size.\nSee NOTES section for implementation details and EXAMPLES section for typical use.\n", "flag": "-F", "long": "--format" }, { "name": "-h --help", "content": "print out the usage information then exit.\n", "flag": "-h", "long": "--help" }, { "name": "-I --ip-def", "content": "sets the default Initialization Pattern. Some disks (SSDs) use this to flag that a\nformat should fully provision (i.e. associate a physical block with every logical\nblock). The same disks (SSDs) might thin provision if this option is not given. If\nthis option is given then the --security option cannot be given. Also accepts --ipdef\nfor this option.\n", "flag": "-I", "long": "--ip-def" }, { "name": "-l --long", "content": "the default action of this utility is to assume 32 bit logical block addresses. With\n512 byte block size this permits more than 2 terabytes (almost 2 41 bytes) on a\nsingle disk. This option selects commands and parameters that allow for 64 bit logical\nblock addresses. Specifically this option sets the \"longlba\" flag in the MODE SENSE\n(10) command and uses READ CAPACITY (16) rather than READ CAPACITY (10). If this op‐\ntion is not given and READ CAPACITY (10) or MODE SELECT detects a disk the needs more\nthan 32 bits to represent its logical blocks then it is set internally. This option\ndoes not set the LONGLIST bit in the FORMAT UNIT command. The LONGLIST bit is set as\nrequired depending other parameters (e.g. when '--pie=PIE' is greater than zero).\n", "flag": "-l", "long": "--long" }, { "name": "-M --mode", "content": "MP is a mode page number (0 to 62 inclusive) that will be used for reading and perhaps\nchanging the device logical block size. The default is 1 which is the Read-Write Error\nRecovery mode page.\nPreferably the chosen (or default) mode page should be saveable (i.e. accept the SP\nbit set in the MODE SELECT command used when the logical block size is being changed).\nRecent version of this utility will retry a MODE SELECT if the SP=1 variant fails with\na sense key of ILLEGAL REQUEST. That retry will use the same MODE SELECT command but\nwith SP=0 .\n", "flag": "-M", "long": "--mode" }, { "name": "-P --pfu", "content": "sets the \"Protection Field Usage\" field in the parameter block associated with a FOR‐\nMAT UNIT command to PFU. The default value is 0, the only other defined value cur‐\nrently is 1. See the PROTECTION INFORMATION section below for more information.\n", "flag": "-P", "long": "--pfu" }, { "name": "-q --pie", "content": "sets the \"Protection Interval Exponent\" field in the parameter block associated with a\nFORMAT UNIT command to PIE. The default value is 0. PIE can only be non-zero with\nprotection types 2 and 3. The value of 0 is typical for 512 byte blocks; with 4096\nbyte blocks a value of 3 may be appropriate (i.e. 8 protection intervals interleaved\nwith 4096 bytes of user data). A device may not support any non-zero values. This\nfield first appeared in SBC-3 revision 18.\n", "flag": "-q", "long": "--pie" }, { "name": "-p --pinfo", "content": "this option is deprecated, use the --fmtpinfo=FPI option instead. If used, then it\nsets bit 7 of byte 1 in the FORMAT UNIT cdb and that is equivalent to setting --fmt‐\npinfo=2. [So if --pinfo is used (plus --fmtpinfo=FPI and --pfu=PFU are not given or\ntheir arguments are 0) then protection type 1 is selected.]\n", "flag": "-p", "long": "--pinfo" }, { "name": "-x --poll", "content": "where PT is the type of poll used. If PT is 0 then a TEST UNIT READY command is used,\notherwise a REQUEST SENSE command is used. The default is currently 0 but this will\nchange to 1 in the near future. See the NOTES sections below.\n", "flag": "-x", "long": "--poll" }, { "name": "-E --preset", "content": "this option instructs this utility to issue a SCSI FORMAT WITH PRESET command. The\nPRESET IDENTIFIER field in that cdb is set to ID. The IMMED field in that cdb is also\nset unless the --wait option is also given, in which case it is cleared.\n", "flag": "-E", "long": "--preset" }, { "name": "-Q --quick", "content": "the default action (i.e. when the option is not given) is to give the user 15 seconds\nto reconsider doing a format operation on the DEVICE. When this option is given that\nstep (i.e. the 15 second warning period) is skipped.\n", "flag": "-Q", "long": "--quick" }, { "name": "-r --resize", "content": "rather than format the disk, it can be resized. This means changing the number of\nblocks on the device reported by the READ CAPACITY command. This option should be\nused with the --count=COUNT option. The contents of all logical blocks on the media\nremain unchanged when this option is used. This means that any resize operation can be\nreversed. This option cannot be used together with either --format or a --size=LBSZ\nwhose argument is different to the existing block size.\n", "flag": "-r", "long": "--resize" }, { "name": "-R --rto", "content": "The option is deprecated, use the --fmtpinfo=FPI option instead. If used, then it\nsets bit 6 of byte 1 in the FORMAT UNIT cdb.\n", "flag": "-R", "long": "--rto" }, { "name": "-S --security", "content": "sets the \"Security Initialization\" (SI) bit in the FORMAT UNIT command's initializa‐\ntion pattern descriptor within the parameter list. According to SBC-3 the default ini‐\ntialization pattern \"shall be written using a security erasure write technique\". See\nthe NOTES section on the SCSI SANITIZE command. If this option is given then the\n--ipdef option cannot be given.\n", "flag": "-S", "long": "--security" }, { "name": "-6 --six", "content": "Use 6 byte variants of MODE SENSE and MODE SELECT. The default action is to use the 10\nbyte variants. Some MO drives need this option set when doing a format.\n", "flag": "-6", "long": "--six" }, { "name": "-s --size", "content": "where LBSZ is the logical block size (i.e. number of user bytes in each block) to\nformat the device to. The default value is whatever is currently reported by the block\ndescriptor in a MODE SENSE command. If the block size given by this option is differ‐\nent from the current value then a MODE SELECT command is used to change it prior to\nthe FORMAT UNIT command being started (as recommended in the SBC standards). Some SCSI\ndisks have 512 byte logical blocks by default and allow an alternate logical block\nsize of 4096 bytes. If the given size in unacceptable to the disk, most likely an \"In‐\nvalid field in parameter list\" message will appear in sense data (requires the use of\n'-v' to decode sense data).\nNote that formatting a disk to add or remove protection information is not regarded as\na change to its logical block size so this option should not be used.\n", "flag": "-s", "long": "--size" }, { "name": "-T --tape", "content": "will send a FORMAT MEDIUM command to the DEVICE with its FORMAT field set to FM. This\noption is used to prepare a tape (i.e. the \"medium\") in a tape drive for use. Values\nfor FM include 0 to do the \"default\" format; 1 to partition a volume and 2 to do a de‐\nfault format then partition.\n", "flag": "-T", "long": "--tape" }, { "name": "-m --timeout", "content": "where SECS is the FORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command timeout in\nseconds. SECS will only be used if it exceeds the internal timeout which is 20 seconds\nif the IMMED bit is set and 72000 seconds (20 hours) or higher if the IMMED bit is not\nset. If the disk size exceeds 4 TB then the timeout value is increased to 144000 sec‐\nonds (40 hours). And if it is greater than 8 TB then the timeout value is increased\nto 288000 seconds (80 hours). If the timeout is exceeded then the operating system\nwill typically abort the command. Aborting a command may escalate to a LUN reset (or\nworse). A timeout may also leave the disk or tape format operation incomplete. And\nthat may result in the disk or tape being in a \"format corrupt\" state requiring an‐\nother format to remedy the situation. So for various reasons command timeouts are\nbest avoided.\n", "flag": "-m", "long": "--timeout" }, { "name": "-v --verbose", "content": "increase the level of verbosity, (i.e. debug output). \"-vvv\" gives a lot more debug\noutput.\n", "flag": "-v", "long": "--verbose" }, { "name": "-y --verify", "content": "set the VERIFY bit in the FORMAT MEDIUM cdb. The default is that the VERIFY bit is\nclear. This option is only appropriate for tapes.\n", "flag": "-y", "long": "--verify" }, { "name": "-V --version", "content": "print the version string and then exit.\n", "flag": "-V", "long": "--version" }, { "name": "-w --wait", "content": "the default format action is to set the \"IMMED\" bit in the FORMAT UNIT command's\n(short) parameter header. If this option (i.e. --wait) is given then the \"IMMED\" bit\nis not set. If --wait is given then the FORMAT UNIT, FORMAT WITH PRESET or FORMAT\nMEDIUM command waits until the format operation completes before returning its re‐\nsponse. This can be many hours on large disks. See the --timeout=SECS option.\nAlternatively this option may be useful when used together with --ffmt=FFMT (and FFMT\ngreater than 0) since the fast format may only be a matter of seconds.\n", "flag": "-w", "long": "--wait" } ] }, "LISTS": { "content": "The SBC-3 draft (revision 20) defines PLIST, CLIST, DLIST and GLIST in section 4.10 on\n\"Medium defects\". Briefly, the PLIST is the \"primary\" list of manufacturer detected defects,\nthe CLIST (\"certification\" list) contains those detected during the format operation, the\nDLIST is a list of defects that can be given to the format operation. The GLIST is the grown\nlist which starts in the format process as CLIST+DLIST and can \"grow\" later due to automatic\nreallocation (see the ARRE and AWRE bits in the Read-Write Error Recovery mode page (see sd‐\nparm(8))) and use of the SCSI REASSIGN BLOCKS command (see sgreassign(8)).\n\nBy the SBC-3 standard (following draft revision 36) the CLIST and DLIST had been removed,\nleaving PLIST and GLIST. Only PLIST and GLIST are found in the SBC-4 drafts.\n\nThe CMPLST bit (controlled by the --cmplst=0|1 option) determines whether the existing GLIST,\nwhen the format operation is invoked, is taken into account. The sgformat utility sets the\nFOV bit to zero which causes DPRY=0, so the PLIST is taken into account, and DCRT=0, so the\nCLIST is generated and used during the format process.\n\nThe sgformat utility does not permit a user to provide a defect list (i.e. DLIST).\n", "subsections": [] }, "PROTECTION INFORMATION": { "content": "Protection Information (PI) is additional information held with logical blocks so that an ap‐\nplication and/or host bus adapter can check the correctness of those logical blocks. PI is\nplaced in one or more protection intervals interleaved in each logical block. Each protection\ninterval follows the user data to which it refers. A protection interval contains 8 bytes\nmade up of a 2 byte \"logical block guard\" (CRC), a 2 byte \"logical block application guard\",\nand a 4 byte \"logical block reference tag\". Devices with 512 byte logical block size typi‐\ncally have one protection interval appended, making its logical block data 520 bytes long.\nDevices with 4096 byte logical block size often have 8 protection intervals spread across its\nlogical block data for a total size of 4160 bytes. Note that for all other purposes the logi‐\ncal block size is considered to be 512 and 4096 bytes respectively.\n\nThe SBC-3 standard have added several \"protection types\" to the PI introduced in the SBC-2\nstandard. SBC-3 defines 4 protection types (types 0 to 3) with protection type 0 meaning no\nPI is maintained. While a device may support one or more protection types, it can only be\nformatted with 1 of the 4. To change a device's protection type, it must be re-formatted.\nFor more information see the Protection Information in section 4.21 of draft SBC-4 revision\n16.\n\nA device that supports PI information (i.e. supports one or more protection types 1, 2 and 3)\nsets the \"PROTECT\" bit in its standard INQUIRY response. It also sets the SPT field in the\nEXTENDED INQUIRY VPD page response to indicate which protection types it supports. Given PRO‐\nTECT=1 then SPT=0 implies the device supports PI type 1 only, SPT=1 implies the device sup‐\nports PI types 1 and 2, and various other non-obvious mappings up to SPT=7 which implies pro‐\ntection types 1, 2 and 3 are supported. The current protection type of a disk can be found in\nthe \"PTYPE\" and \"PROTEN\" fields in the response of a READ CAPACITY (16) command (e.g. with\nthe 'sgreadcap --long' utility).\n\nGiven that a device supports a particular protection type, a user can then choose to format\nthat disk with that protection type by setting the \"FMTPINFO\" and \"Protection Field Usage\"\nfields in the FORMAT UNIT command. Those fields correspond to the --fmtpinfo=FPI and the\n--pfu=PFU options in this utility. The list below shows the four protection types followed by\nthe options of this utility needed to select them:\n0 : --fmtpinfo=0 --pfu=0\n1 : --fmtpinfo=2 --pfu=0\n2 : --fmtpinfo=3 --pfu=0\n3 : --fmtpinfo=3 --pfu=1\nThe default value of FPI (in --fmtpinfo=FPI) is 0 and the default value of PFU (in --pfu=PFU)\nis 0. So if neither --fmtpinfo=FPI nor --pfu=PFU are given then protection type 0 (i.e. no\nprotection information) is chosen.\n", "subsections": [] }, "NOTES": { "content": "After a format that changes the logical block size or the number of logical blocks on a disk,\nthe operating system may need to be told to re-initialize its setting for that disk. In Linux\nthat can be done with:\necho 1 > /sys/block/sd{letter(s)}/device/rescan\nwhere \"letter(s)\" will be between 'a' and 'zzz'. The lsscsi utility in Linux can be used to\ncheck the various namings of a disk.\n\nThe SBC-2 standard states that the REQUEST SENSE command should be used for obtaining\nprogress indication when the format command is underway. However, tests on a selection of\ndisks shows that TEST UNIT READY commands yield progress indications (but not REQUEST SENSE\ncommands). So the current version of this utility defaults to using TEST UNIT READY commands\nto poll the disk to find out the progress of the format. The --poll=PT option has been added\nto control this.\n\nWhen the --format, --preset=ID or --tape=FM option is given without the --wait option then\nthe corresponding SCSI command is issued with the IMMED bit set which causes the SCSI command\nto return after it has started the format operation. The --early option will cause sgformat\nto exit at that point. Otherwise the DEVICE is polled every 60 seconds or every 10 seconds if\nFFMT is non-zero. The poll is with TEST UNIT READY or REQUEST SENSE commands until one re‐\nports an \"all clear\" (i.e. the format operation has completed). Normally these polling com‐\nmands will result in a progress indicator (expressed as a percentage) being output to the\nscreen. If the user gets bored watching the progress report then sgformat process can be\nterminated (e.g. with control-C) without affecting the format operation which continues. How‐\never a target or device reset (or a power cycle) will probably cause the format to cease and\nthe DEVICE to become \"format corrupt\".\n\nWhen the --format (--preset=ID or --tape) and --wait options are both given then this utility\nmay take a long time to return. In this case care should be taken not to send any other SCSI\ncommands to the disk as it may not respond leaving those commands queued behind the active\nformat command. This may cause a timeout in the OS driver (in a lot shorter period than 20\nhours applicable to some format operations). This may result in the OS resetting the disk\nleaving the format operation incomplete. This may leave the disk in a \"format corrupt\" state\nrequiring another format to remedy the situation. Modern SCSI devices should yield a \"not\nready\" sense key with an additional sense indicating a format is in progress. With older de‐\nvices the user should take precautions that nothing attempts to access a device while it is\nbeing formatted. Unmounting in mounted file systems on a DEVICE prior to calling this utility\nis strongly advised.\n\nWhen the block size (i.e. the number of bytes in each block) is changed on a disk two SCSI\ncommands must be sent: a MODE SELECT to change the block size followed by a FORMAT command.\nIf the MODE SELECT command succeeds and the FORMAT fails then the disk may be in a state that\nthe standard calls \"format corrupt\". A block descriptor in a subsequent MODE SENSE will re‐\nport the requested new block size while a READ CAPACITY command will report the existing\n(i.e. previous) block size. Alternatively the READ CAPACITY command may fail, reporting the\ndevice is not ready, potentially requiring a format. The solution to this situation is to do\na format again (and this time the new block size does not have to be given) or change the\nblock size back to the original size.\n\nThe SBC-2 standard states that the block count can be set back to the manufacturer's maximum\nrecommended value in a format or resize operation. This can be done by placing an address of\n0xffffffff (or the 64 bit equivalent) in the appropriate block descriptor field to a MODE SE‐\nLECT command. In signed (two's complement) arithmetic that value corresponds to '-1'. So a\n--count=-1 causes the block count to be set back to the manufacturer's maximum recommended\nvalue. To see exactly which SCSI commands are being executed and parameters passed add the\n\"-vvv\" option to the sgformat command line.\n\nThe FMTDATA field shown in the FORMAT UNIT cdb does not have a corresponding option in this\nutility. When set in the cdb it indicates an additional parameter list will be sent to the\nDEVICE along with the cdb. It is set as required, basically when any field in the parameter\nlist header is set.\n\nShort stroking is a technique to trade off capacity for performance on hard disks. \"Hard\"\ndisk is often used to mean a storage device with spinning platters which contain the user\ndata. Solid State Disk (SSD) is the newer form of storage device that contains no moving\nparts. Hard disk performance is usually highest on the outer tracks (usually the lower logi‐\ncal block addresses) so by resizing or reformatting a disk to a smaller capacity, average\nperformance will usually be increased.\n\nOther utilities may be useful in finding information associated with formatting. These in‐\nclude sginq(8) to fetch standard INQUIRY information (e.g. the PROTECT bit) and to fetch the\nEXTENDED INQUIRY VPD page (e.g. RTO and GRDCHK bits). The sdparm(8) utility can be used to\naccess and potentially change the now obsolete format mode page.\n\nscsiformat is another utility available for formatting SCSI disks with Linux. It dates from\n1997 (most recent update) and may be useful for disks whose firmware is of that vintage.\n\nThe COUNT numeric argument may include a multiplicative suffix or be given in hexadecimal.\nSee the \"NUMERIC ARGUMENTS\" section in the sg3utils(8) man page.\n\nThe SCSI SANITIZE command was introduced in SBC-3 revision 27. It is closely related to the\nATA sanitize disk feature set and can be used to remove all existing data from a disk. Sani‐\ntize is more likely to be implemented on modern disks (including SSDs) than FORMAT UNIT's se‐\ncurity initialization feature (see the --security option) and in some cases much faster.\n\nSSDs that support thin provisioning will typically unmap all logical blocks during a format.\nThe reason is to improve the SSD's endurance. Also thin provisioned formats typically com‐\nplete faster than fully provisioned ones on the same disk (see the --ipdef option). In ei‐\nther case format operations on SSDs tend to be a lot faster than they are on hard disks with\nspinning media.\n", "subsections": [] }, "TAPE": { "content": "Tape system use a variant of the FORMAT UNIT command used on disks. Tape systems use the FOR‐\nMAT MEDIUM command which is simpler with only three fields in the cdb typically used. Apart\nfrom sharing the same opcode the cdbs of FORMAT UNIT and FORMAT MEDIUM are quite different.\nFORMAT MEDIUM's fields are VERIFY, IMMED and FORMAT (with TRANSFER LENGTH always set to 0).\nThe VERIFY bit field is set with the --verify option. The IMMED bit is manipulated by the\n--wait option in the same way it is for disks; one difference is that if the --poll=PT option\nis not given then it defaults to PT of 1 which means the poll is done with REQUEST SENSE com‐\nmands.\n\nThe argument given to the --tape=FM option is used to set the FORMAT field. FM can take val‐\nues from \"-1\" to \"15\" where \"-1\" (the default) means don't do a tape format; value \"8\" to\n\"15\" are for vendor specific formats. The --early option may also be used to set the IMMED\nbit and then exit this utility (rather than poll periodically until it is finished). In this\ncase the tape drive will still be busy doing the format for some time but, according to T10,\nshould still respond in full to the INQUIRY and REPORT LUNS commands. Other commands (includ‐\ning REQUEST SENSE) should yield a \"not ready\" sense key with an additional sense code of\n\"Logical unit not ready, format in progress\". Additionally REQUEST SENSE should contain a\nprogress indication in its sense data.\n\nWhen FM is 1 or 2 then the settings in the Medium partition mode page control the partition‐\ning. That mode page can be viewed and modified with the sdparm utility.\n\nPrior to invoking this utility the tape may need to be positioned to the beginning of parti‐\ntion 0. In Linux that can typically be done with the mt utility (e.g. 'mt -f /dev/st0\nrewind').\n", "subsections": [] }, "EXAMPLES": { "content": "These examples use Linux device names. For suitable device names in other supported Operating\nSystems see the sg3utils(8) man page.\n\nIn the first example below simply find out the existing block count and size derived from two\nsources: a block descriptor in a MODE SELECT command response and from the response of a READ\nCAPACITY commands. No changes are made:\n\n# sgformat /dev/sdm\n\nNow a simple format, leaving the block count and size as they were previously. The FORMAT\nUNIT command is executed in IMMED mode and the device is polled every 60 seconds to print out\na progress indication:\n\n# sgformat --format /dev/sdm\n\nNow the same format, but waiting (passively) until the format operation is complete:\n\n# sgformat --format --wait /dev/sdm\n\nNext is a format in which the block size is changed to 520 bytes and the block count is set\nto the manufacturer's maximum value (for that block size). Note, not all disks support chang‐\ning the block size:\n\n# sgformat --format --size=520 /dev/sdm\n\nNow a resize operation so that only the first 0x10000 (65536) blocks on a disk are accessi‐\nble. The remaining blocks remain unaltered.\n\n# sgformat --resize --count=0x10000 /dev/sdm\n\nNow resize the disk back to its normal (maximum) block count:\n\n# sgformat --resize --count=-1 /dev/sdm\n\nOne reason to format a SCSI disk is to add protection information. First check which protec‐\ntion types are supported by a disk (by checking the SPT field in the Extended inquiry VPD\npage together with the Protect bit in the standard inquiry response):\n\n# sgvpd -p ei -l /dev/sdb\nextended INQUIRY data VPD page:\nACTIVATEMICROCODE=0\nSPT=1 [protection types 1 and 2 supported]\n....\n\nFormat with type 1 protection:\n\n# sgformat --format --fmtpinfo=2 /dev/sdm\n\nAfter a successful format with type 1 protection, READ CAPACITY(16) should show something\nlike this:\n\n# sgreadcap -l /dev/sdm\nRead Capacity results:\nProtection: proten=1, ptype=0, piexponent=0 [type 1 protection]\nLogical block provisioning: lbpme=0, lbprz=0\n....\n\nTo format with type 3 protection:\n\n# sgformat --format --fmtpinfo=3 --pfu=1 /dev/sdm\n\nFor the disk shown above this will probably fail because the Extended inquiry VPD page showed\nonly types 1 and 2 protection are supported.\n\nHere are examples of using fast format (FFMT field in FORMAT UNIT cdb) to quickly switch be‐\ntween 512 and 4096 byte logical block size. Assume disk starts with 4096 byte logical block\nsize and all important data has been backed up.\n\n# sgformat --format --ffmt=1 --size=512 /dev/sdd\n\nNow /dev/sdd should have 512 byte logical block size. And to switch it back:\n\n# sgformat --format --ffmt=1 --size=4096 /dev/sdd\n\nSince fast formats can be very quick (a matter of seconds) using the --wait option may be ap‐\npropriate.\n\nAnd to use the Format with preset command this invocation could be used:\n\n# sgformat --preset=1 --fmtmaxlba /dev/sdd\n\nThe FORMAT PRESETS VPD page (0xb8) should be consulted to check that Preset identifier 0x1 is\nthere and has the expected format (i.e. \"default host aware zoned block device model with 512\nbytes of user data in each logical block\"). That VPD page can be viewed with the sgvpd\nutility.\n", "subsections": [] }, "EXIT STATUS": { "content": "The exit status of sgformat is 0 when it is successful. Otherwise see the sg3utils(8) man\npage. Unless the --wait option is given, the exit status may not reflect the success of oth‐\nerwise of the format. Using sgturs(8) and sgreadcap(8) after the format operation may be\nwise.\n\nThe Unix convention is that \"no news is good news\" but that can be a bit unnerving after an\noperation like format, especially if it finishes quickly (i.e. before the first progress poll\nis sent). Giving the --verbose option once should supply enough additional output to settle\nthose nerves.\n", "subsections": [] }, "AUTHORS": { "content": "Written by Grant Grundler, James Bottomley and Douglas Gilbert.\n", "subsections": [] }, "REPORTING BUGS": { "content": "Report bugs to .\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 2005-2020 Grant Grundler, James Bottomley and Douglas Gilbert\nThis software is distributed under the GPL version 2. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n", "subsections": [] }, "SEE ALSO": { "content": "sgturs(8), sgrequests(8), sginq(8), sgmodes(8), sgvpd(8), sgreassign(8), sgreadcap(8),\nsg3utils(8), sgsanitize(8) [all in sg3utils], lsscsi(8), mt(mt-st), sdparm(8), scsiformat", "subsections": [ { "name": "(old), hdparm(8)", "content": "sg3utils-1.45 January 2020 SGFORMAT(8)" } ] } } } }