badblocks_check(9)

📦 version 7.3.1, in nixpkgs unstable

💅 badblocks_check — check a given range for bad sectors

okay bestie so this is from the Kernel API Manual — badblocks_check(9), the little function that looks at a chunk of your disk and goes "hmm, is any of this cursed?" 🦋

✨ NAME ✨

badblocks_check — check a given range for bad sectors 🎀

🌸 SYNOPSIS 🌸

int badblocks_check (struct badblocks *bb , sector_t s , sector_t
       sectors , sector_t *first_bad , sector_t *bad_sectors );

💖 ARGUMENTS 💖

  • bb — the badblocks structure that holds all the badblock information. it's giving main character energy, everything lives here 👑
  • s — sector (start) at which to check for badblocks
  • sectors — number of sectors to check for badblocks
  • first_bad — pointer to store location of the first badblock
  • bad_sectors — pointer to store number of badblocks after first_bad

🌈 DESCRIPTION 🌈

okay so the whole vibe here: we can record which blocks on each device are 'bad' and so just fail those blocks, or that stripe, rather than the whole device. like, we're not gonna nuke the entire disk because one little corner is sus 💀

Entries in the bad-block table are 64 bits wide. This comprises:

  • Length of bad-range, in sectors: 0-511 for lengths 1-512
  • Start of bad-range, sector offset, 54 bits (allows 8 exbibytes)
  • A 'shift' can be set so that larger blocks are tracked and consequently larger devices can be covered ✨

Locking of the bad-block table uses a seqlock so badblocks_check might need to retry if it is very unlucky 😭 no cap, it just happens sometimes. We will sometimes want to check for bad blocks in a bi_end_io function, so we use the write_seqlock_irq variant 🫶

When looking for a bad block we specify a range and want to know if any block in the range is bad. So we binary-search to the last range that starts at-or-before the given endpoint, (or "before the sector after the target range") then see if it ends after the given start. iconic algorithm behaviour, honestly 🌟

🔥 RETURN 🔥

  • 0 — there are no known bad blocks in the range 🎉
  • 1 — there are known bad block which are all acknowledged
  • -1 — there are bad blocks which have not yet been acknowledged in metadata 🙈

plus the start/length of the first bad section we overlap 💅

fr fr, that -1 is the one that means somebody hasn't done their homework yet — the badness is real but nobody's written it down in metadata.

💜 SEE ALSO 💜

that's the whole page bestie, go check those blocks 🧚‍♀️

mwah 💋 — this one's from ./block, dated October 2026, and it's the badblocks_check(9) page, so you know exactly where it came from. no cap, that's the whole sign-off 🎀

📦 where this page comes from