path: root/system/bbf/bbf.8

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BBF" 8 "2023-03-27" "20220524_0e90e04" "SlackBuilds.org"
.SH NAME
bbf \- bad block finder
.\" RST source for bbf(1) man page. Convert with:
.
.\" rst2man.py bbf.rst > bbf.8
.
.SH SYNOPSIS
.sp
bbf [\fIoptions\fP] \fIinstruction\fP \fIpath\fP
.SH DESCRIPTION
.sp
\fBbbf\fP is a safer and more featureful tool for dealing with bad
blocks on hard drives. It\(aqs built around the workflow of dealing with
hard drive bad blocks. It has a number of features to limit risk in
using the tool and provides features to more easily track down what
files are affected by the bad blocks found. It also gives you the
ability to manually mark blocks as corrupted in cases where a block
isn\(aqt technically bad, but is causing issues.
.SH FEATURES
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
readonly scanning of bad blocks
.IP \(bu 2
safe \(aqfix\(aq mode which won\(aqt overwrite good blocks
.IP \(bu 2
burnin mode for checking new drives
.IP \(bu 2
manual marking blocks as corrupted
.IP \(bu 2
find files given list of blocks
.IP \(bu 2
dump list of files and associated block ranges
.IP \(bu 2
dump list of blocks used by a file
.IP \(bu 2
issue secure drive erasure
.IP \(bu 2
filesystem stressing
.UNINDENT
.UNINDENT
.UNINDENT
.SH OPTIONS
.SS Arguments
.INDENT 0.0
.TP
.B  \-f\fP,\fB  \-\-force
override checking if drive is in use when trying to perform destructive actions
.UNINDENT
.INDENT 0.0
.TP
.B \-t, \-\-rwtype \fIos|ata\fP
select between OS or ATA reads and writes (default: os)
.UNINDENT
.INDENT 0.0
.TP
.B  \-q\fP,\fB  \-\-quiet
redirects stdout to /dev/null or otherwise limits output
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-start\-block \fIlba\fP
block to start from (default: 0)
.TP
.B \-e, \-\-end\-block \fIlba\fP
block to stop at (default: last block)
.TP
.B \-S, \-\-stepping \fIn\fP
number of logical blocks to read at a time (default: physical / logical)
.TP
.B \-o, \-\-output \fIfile\fP
file to write bad block list to (default: $HOME/badblocks.*captcha*)
.TP
.B \-i, \-\-input \fIfile\fP
file to read bad block list from (default: $HOME/badblocks.*captcha*)
.TP
.B \-r, \-\-retries \fIcount\fP
number of retries on certain reads & writes
.TP
.B \-c, \-\-captcha \fIcaptcha\fP
needed when performing destructive operations
.TP
.B \-M, \-\-maxerrors \fIn\fP
max r/w errors before exiting (default: 1024)
.UNINDENT
.SS Instructions
.sp
\fBinfo\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a block device. Prints out details about the block device.
.UNINDENT
.UNINDENT
.sp
\fBcaptcha\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a block device. Prints out captcha needed for certain instructions.
.UNINDENT
.UNINDENT
.sp
\fBscan\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a block device. A read\-only scan of the block device for
bad blocks. \fIrwtype=ata\fP will be slower but may catch more.
.sp
Relevant options: rwtype, start block, end block, stepping, max errors, input file, output file.
.UNINDENT
.UNINDENT
.sp
\fBfix\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a block device. Writes to bad blocks in an attempt to
force the drive to reallocate the block. Attempts to read the block
first and will write the read data if successful otherwise it will
write zeros. This means it is pretty safe to use even if the blocks
\(aqfixed\(aq aren\(aqt in fact damaged.
.UNINDENT
.UNINDENT
.sp
\fIrwtype=ata\fP will work better.
.INDENT 0.0
.INDENT 3.5
Requires captcha.
.sp
Relevant options: captcha, rwtype, force, input file.
.UNINDENT
.UNINDENT
.sp
\fBfix\-file\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a file. Gets the list of blocks that a file uses and then
goes through each block reading what is there and then writing it
back which will force reallocation if a block is bad.
.sp
\fIrwtype=ata\fP will work better.
.sp
Requires captcha.
.sp
Relevant options: captcha, rwtype, retries.
.UNINDENT
.UNINDENT
.sp
\fBburnin\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a block device. Iterates through the blocks of the device performing the following:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP 1. 3
Read block data (zero out on failure)
.IP 2. 3
Write 0x00\(aqs and read back to confirm data integrity.
.IP 3. 3
Write 0x55\(aqs and read back to confirm data integrity.
.IP 4. 3
Write 0xAA\(aqs and read back to confirm data integrity.
.IP 5. 3
Write 0xFF\(aqs and read back to confirm data integrity.
.IP 6. 3
Write back originally read data.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Requires captcha.
.sp
Relevant options: rwtype, start block, end block, stepping, max
errors, retries, input file, output file.
.UNINDENT
.UNINDENT
.sp
\fBfsthrash\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a directory. Spawns a number of threads to hammer the
filesystem using a number of functions to stress the filesystem and
underlying device. Functions include: create, open, mkdir, unlink,
rmdir, write, read, close, readdir, stat, chmod, chown, link,
symlink. Cleans up after itself on exit but does consume storage and
inodes as it runs.
.sp
Use \fI\-\-quiet\fP to keep it from printing out what it is doing and improve performance.
.UNINDENT
.UNINDENT
.sp
\fBfilethrash\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a non\-existent file. Creates a file, expands it to fill
up the rest of the filesystem, and spawns a thread per core which
writes 1MB blocks to the file at random offsets to stress the
filesystem and unerlying device.
.UNINDENT
.UNINDENT
.sp
\fBfind\-files\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a filesystem mount point. Attempts to find the
files associated with any blocks listed in the bad block input
file. Useful after running \fIscan\fP to find the files with bad blocks.
.sp
Relevant options: input file.
.UNINDENT
.UNINDENT
.sp
\fBdump\-files\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a filesystem. Scans the filesystem and dumps a list of the files with the blocks on the device it occupies.
.UNINDENT
.UNINDENT
.sp
\fBfile\-blocks\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is an existing file. Prints out a list of all logical blocks the file uses.
.UNINDENT
.UNINDENT
.sp
\fBwrite\-pseudo\-uncorrectable\-wl\fP
.sp
\fBwrite\-pseudo\-uncorrectable\-wol\fP
.sp
\fBwrite\-flagged\-uncorrectable\-wl\fP
.sp
\fBwrite\-flagged\-uncorrectable\-wol\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a block device. Marks blocks listed in the bad block input
file as \(aqpseudo\(aq or \(aqflagged\(aq uncorrectable. Blocks marked \(aqpseudo\(aq,
when read, cause the drive to perform normal error recovery and
return errors if necessary. Blocks marked \(aqflagged\(aq, when read,
will simply return errors indicating it is bad. \(aqwl\(aq means \(aqwith
logging\(aq and if read will result in failed reads being stored in
SMART logs. \(aqwol\(aq means \(aqwithout logging\(aq and will not log any read
failures in the SMART log.
.sp
Relevant options: input file.
.UNINDENT
.UNINDENT
.sp
\fBsecurity\-erase\fP
.INDENT 0.0
.INDENT 3.5
\fIpath\fP is a block device. Issues an ATA Security Erase command to
the device. What this means specifically is device specific but
generally it is supposed to be like a low\-level format. Use with
care.
.sp
Requires captcha.
.sp
Relevant options: captcha.
.UNINDENT
.UNINDENT
.sp
\fBenhanced\-security\-erase\fP
.INDENT 0.0
.INDENT 3.5
Theoretically a more thorough version of the standard ATA Security
Erase command. Similarly its function depends on the device and may
be the same as the regular security erase.
.sp
Requires captcha.
.sp
Relevant options: captcha.
.UNINDENT
.UNINDENT
.SH EXAMPLES
.nf
# bbf info /dev/sdb
/dev/sdi:
.in +2
\- serial_number: XXXXXXXX
\- firmware_revision: SC61
\- model_number: ST8000VN0022\-2EL112
\- RPM: 7200
\- features:
.in +2
\- form_factor: 3.5"
\- write_uncorrectable: 1
\- smart_supported: 1
\- smart_enabled: 1
\- security_supported: 1
\- security_enabled: 0
\- security_locked: 0
\- security_frozen: 0
\- security_count_expired: 0
\- security_enhanced_erase_supported: 1
\- security_normal_erase_time: 698
\- security_enhanced_erase_time: 698
\- block_erase: 0
\- overwrite: 1
\- crypto_scramble: 0
\- sanitize: 1
\- supports_sata_gen1: 1
\- supports_sata_gen2: 1
\- supports_sata_gen3: 1
\- trim_supported: 0
.in -2
\- block_size:
.in +2
\- physical: 4096
\- logical: 512
\- stepping: 8
.in -2
\- block_count:
.in +2
\- physical: 1953506646
\- logical: 15628053168
.in -2
\- size:
.in +2
\- bytes: 8001563222016
\- human:
.in +2
\- base2: 7.28TB
\- base10: 8.00TiB

.in -2
.in -2
.in -2
.fi
.sp
.nf
# bbf \-S 256 \-t ata scan /dev/sdb
start block: 0
end block: 15628053168
stepping: 256
logical block size: 512
physical block size: 4096
read size: 131072
Scanning: 0 \- 15628053168
Current: 2425512192 (15.52%); bps: 179384.74; eta: 20:26:39; bad: 0

.fi
.sp
.nf
# bbf captcha /dev/sdb
Z8400VR0

.fi
.sp
.nf
# bbf \-i ~/badblocks.Z8400VR0 \-c Z8400VR0 fix /dev/sdb

.fi
.sp
.nf
# bbf \-q fsthrash /mnt/mydrive0
CTRL\-C to exit...
^CCleaning up...

.fi
.sp
.nf
# bbf filethrash /mnt/mydrive0/test
Creating file: /mnt/mydrive0/test
Expanding file to fill drive: 200209731584 bytes
Spawning thrashing threads: 4 (one per core)
CTRL\-C to exit...
.fi
.sp
.SH COPYRIGHT
.sp
See the file /usr/doc/bbf\-20220524_0e90e04/LICENSE for license information.
.SH AUTHORS
.sp
\fBbbf\fP was written by Antonio SJ Musumeci <\fI\%trapexit@spawn.link\fP>.
.sp
This man page created for the SlackBuilds.org project by
B. Watson. Since it\(aqs just copy/pasted from README.md, the man page is
licensed the same as \fBbbf\fP itself.
.SH SEE ALSO
.sp
\fBbadblocks\fP(8), \fBsmartctl\fP(8), \fBfsck\fP(8)
.sp
The \fBbbf\fP homepage: \fI\%https://github.com/trapexit/bbf\fP
.\" Generated by docutils manpage writer.
.