NEWFS_MSDOS(8)

💾 newfs_msdos(8) — the manual page, but make it cute ✨

okay so you found the newfs_msdos manual page and you're probably like "bestie what is this" — don't worry, I got you. this is from the System Manager's Manual and it's literally the glow-up guide for making MS-DOS (FAT) file systems. let's get into it 💅

---

✨ NAME ✨

newfs_msdos — construct a new MS-DOS (FAT) file system

like, you're building a whole filesystem from scratch. main character energy fr fr 🎀

---

🦋 SYNOPSIS 🦋

newfs_msdos [-N] [-@ offset] [-A] [-B boot] [-C create-size]
            [-F FAT-type] [-I VolumeID] [-L label] [-O OEM]
            [-S sector-size] [-T timestamp] [-a FAT-size]
            [-b block-size] [-c cluster-size] [-e DirEnts] [-f format]
            [-h heads] [-i info] [-k backup] [-m media] [-n FATs]
            [-o hidden] [-r reserved] [-s total] [-u track-size] special
            [disktype]

---

🌸 DESCRIPTION 🌸

so the newfs_msdos utility creates a FAT12, FAT16, or FAT32 file system on the device or file named special, using the disktab(5) entry disktype to figure out geometry, if you even need it. lowkey iconic.

if special doesn't contain a / and you're not using the -C flag, it's assumed to be a device name and /dev/ gets prepended to it to construct the actual device name. so like, it auto-completes your path for you, no cap. if you wanna work with a file in the current directory, just use ./filename — the dot-slash is doing the lords work here 🙏

the options are as follow (and there are SO many, buckle up):

---

💖 OPTIONS 💖

• -N — do NOT create a file system, just print out the parameters. it's giving "window shopping" energy. you're just looking, not committing 🛍️
• -@ offset — build the filesystem at the specified offset in bytes in the device or file. a suffix s, k, m, g (lower or upper case) appended to the offset specifies that the number is in sectors, kilobytes, megabytes or gigabytes, respectively. so like 63s means 63 sectors in. cute!
• -A — attempt to cluster align the data area, useful for flash based storage. this option is enabled by default, unless you specify a number of reserved sectors using the -r option. so it's already on unless you're being extra with -r. slay defaults 💅
• -B boot — get bootstrap from file. like, borrow the boot code from somewhere else. no need to write it yourself, we're not doing all that.
• -C create-size — create the image file with the specified size. a suffix character appended to the size is interpreted as for the -@ option. the file is created by truncating any existing file with the same name and resizing it to the requested size. if the file system supports sparse files, the space occupied on disk may be smaller than the size specified as parameter. so it might look thicc but actually be smol on disk. we love an efficient queen ✨
• -F FAT-type — FAT type, one of 12, 16, or 32. pick your fighter 🥊
• -I VolumeID — Volume ID, a 32 bit number in decimal or hexadecimal (0x...) format. it's your filesystem's social security number basically.
• -L label — Volume label (up to 11 characters). the label should consist of only those characters permitted in regular DOS (8+3) filenames. so no emoji in the label bestie, I know, tragic 😭
• -O OEM — OEM string (up to 8 characters). the default is "BSD4.4 ". that's the factory setting, cute.
• -S sector-size — number of bytes per sector. acceptable values are powers of 2 in the range 512 through 32768, inclusive. powers of two ONLY, we don't do chaos here.
• -T timestamp — create the filesystem as though the current time is timestamp. the default filesystem volume ID is derived from the time. timestamp can be a pathname (where the timestamp is derived from that file) or an integer value interpreted as the number of seconds since the Epoch. time travel but make it filesystem 🕰️
• -a FAT-size — number of sectors per FAT. the FAT is like the map of where everything is, and this is how big it is.
• -b block-size — file system block size (bytes per cluster). this should resolve to an acceptable number of sectors per cluster (see below). don't just put any number, it needs to make sense.
• -c cluster-size — sectors per cluster, also called allocation size. acceptable values are powers of 2 in the range 1 through 128. if the block or cluster size are not specified, the code uses a cluster between 512 bytes and 32K depending on the filesystem size. so it auto-picks for you if you can't decide. thoughtful king 👑
• -e DirEnts — number of root directory entries (FAT12 and FAT16 only). FAT32 girlies don't need this one.
• -f format — specify a standard (floppy disk) format. the standard formats are (capacities in kilobytes): 160, 180, 320, 360, 640, 720, 1200, 1232, 1440, 2880. retro floppy disk realness 💾
• -h heads — number of drive heads. geometry stuff, don't worry about it unless you need to.
• -i info — location of the file system info sector (FAT32 only). a value of 0xffff signifies no info sector. if you don't want an info sector, 0xffff is your "no thanks" button.
• -k backup — location of the backup boot sector (FAT32 only). a value of 0xffff signifies no backup sector. same energy as -i but for the backup boot sector.
• -m media — media descriptor (acceptable range 0xf0 to 0xff). keep it in the range, bestie.
• -n FATs — number of FATs. acceptable values are 1 to 16 inclusive. the default is 2. two FATs is the standard, but you do you.
• -o hidden — number of hidden sectors. sneaky sectors, very mysterious 🕵️‍♀️
• -r reserved — number of reserved sectors. if the -r option is not used, the number of reserved sectors is set to a value that aligns the start of the data area to a multiple of the cluster size. so it auto-aligns unless you interfere. polite!
• -s total — file system size. how big is your filesystem? this is the answer.
• -u track-size — number of sectors per track. more geometry, more fun.

---

🧚 NOTES 🧚

if some parameters (e.g., size, number of sectors, etc.) are not specified through options or disktype, the program tries to generate them automatically. so it's got your back if you forget stuff. in particular, the size is determined as the device or file size minus the offset specified with the -@ option. when the geometry is not available, it is assumed to be 63 sectors, 255 heads. the size is then rounded to become a multiple of the track size and avoid complaints by some filesystem code. so it's rounding up like when you say "I'll be there in 5 minutes" and you mean 15. relatable 💀

FAT file system parameters occupy a "Boot Sector BPB (BIOS Parameter Block)" in the first of the "reserved" sectors which precede the actual file system. for reference purposes, this structure is presented below. it's giving "here's the blueprint" energy:

struct bsbpb {
    uint16_t    bpbBytesPerSec;         /* [-S] bytes per sector */
    uint8_t     bpbSecPerClust;         /* [-c] sectors per cluster */
    uint16_t    bpbResSectors;          /* [-r] reserved sectors */
    uint8_t     bpbFATs;                /* [-n] number of FATs */
    uint16_t    bpbRootDirEnts;         /* [-e] root directory entries */
    uint16_t    bpbSectors;             /* [-s] total sectors */
    uint8_t     bpbMedia;               /* [-m] media descriptor */
    uint16_t    bpbFATsecs;             /* [-a] sectors per FAT */
    uint16_t    bpbSecPerTrack;         /* [-u] sectors per track */
    uint16_t    bpbHeads;               /* [-h] drive heads */
    uint32_t    bpbHiddenSecs;          /* [-o] hidden sectors */
    uint32_t    bpbHugeSectors;         /* [-s] big total sectors */
};
/* FAT32 extensions */
struct bsxbpb {
    uint32_t    bpbBigFATsecs;          /* [-a] big sectors per FAT */
    uint16_t    bpbExtFlags;            /* control flags */
    uint16_t    bpbFSVers;              /* file system version */
    uint32_t    bpbRootClust;           /* root directory start cluster */
    uint16_t    bpbFSInfo;              /* [-i] file system info sector */
    uint16_t    bpbBackup;              /* [-k] backup boot sector */
};

the comments literally tell you which flag maps to which field, so it's like a cheat sheet. iykyk 🫶

---

🔥 LIMITATION 🔥

the maximum file size is 4GB, even if the file system itself is bigger. so you can't put a whole 8GB movie file on there, bestie. not this filesystem's fault, it's just built that way. 💀

---

👑 EXIT STATUS 👑

exit status is 0 on success and 1 on error. so if you get a 0, you ate and left no crumbs. if you get a 1, something went wrong, check yourself before you wreck yourself.

---

🌈 EXAMPLES 🌈

create a file system, using default parameters, on /dev/ada0s1:

newfs_msdos /dev/ada0s1

simple, clean, no extra drama. the default girlies know what's up. ✨

create a FAT32 filesystem with a 32K allocation size on /dev/mmcsd0s1:

newfs_msdos -F 32 -A -c 64 /dev/mmcsd0s1

FAT32 with cluster alignment on, and 64 sectors per cluster (which is 32K). this one's for the flash storage girlies 💅

create a standard 1.44M file system, with volume label foo, on /dev/fd0:

newfs_msdos -f 1440 -L foo fd0

note that fd0 doesn't have a slash, so it becomes /dev/fd0 automatically. the convenience is real. label is foo because why not. iconic. 🎀

create a 30MB image file, with the FAT partition starting 63 sectors within the image file:

newfs_msdos -C 30M -@63s ./somefile

-C 30M makes a 30MB image file, -@63s puts the filesystem 63 sectors in from the start. and ./somefile is the name. perfect for when you want a filesystem inside a file, very inception vibes. 🌀

---

🦋 SEE ALSO 🦋

msdosfs(4), gpart(8), newfs(8)

like, go read those too if you want to be a well-rounded Unix bestie. knowledge is power, periodt.

---

💜 HISTORY 💜

the newfs_msdos utility first appeared in FreeBSD 3.0. so it's been around for a minute. an OG. respect the elders. 🫡

---

🌟 AUTHORS 🌟

Robert Nordier <rnordier@FreeBSD.org>

big thanks to Robert for giving us this tool. we appreciate you, king. 💖

---

okay and that's the whole manual page bestie. we did it. and one last thing — the original footer said this was from Debian, June 6, 2024. so yeah, that's the version and date, not just my imagination. you're welcome 💅✨🍓