1.\" Copyright (c) 1998 Robert Nordier 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in 11.\" the documentation and/or other materials provided with the 12.\" distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS 15.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 16.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY 18.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 20.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 22.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 24.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd June 6, 2024 27.Dt NEWFS_MSDOS 8 28.Os 29.Sh NAME 30.Nm newfs_msdos 31.Nd construct a new MS-DOS (FAT) file system 32.Sh SYNOPSIS 33.Nm 34.Op Fl N 35.Op Fl @ Ar offset 36.Op Fl A 37.Op Fl B Ar boot 38.Op Fl C Ar create-size 39.Op Fl F Ar FAT-type 40.Op Fl I Ar VolumeID 41.Op Fl L Ar label 42.Op Fl O Ar OEM 43.Op Fl S Ar sector-size 44.Op Fl T Ar timestamp 45.Op Fl a Ar FAT-size 46.Op Fl b Ar block-size 47.Op Fl c Ar cluster-size 48.Op Fl e Ar DirEnts 49.Op Fl f Ar format 50.Op Fl h Ar heads 51.Op Fl i Ar info 52.Op Fl k Ar backup 53.Op Fl m Ar media 54.Op Fl n Ar FATs 55.Op Fl o Ar hidden 56.Op Fl r Ar reserved 57.Op Fl s Ar total 58.Op Fl u Ar track-size 59.Ar special 60.Op Ar disktype 61.Sh DESCRIPTION 62The 63.Nm 64utility creates a FAT12, FAT16, or FAT32 file system on device or file named 65.Ar special , 66using 67.Xr disktab 5 68entry 69.Ar disktype 70to determine geometry, if required. 71.Pp 72If 73.Ar special 74does not contain a 75.Ar / 76and 77.Fl C 78is not used, it is assumed to be a device name and 79.Ar /dev/ 80is prepended to the name to construct the actual device name. 81To work a file in the current directory use 82.Ar ./filename 83.Pp 84The options are as follow: 85.Bl -tag -width indent 86.It Fl N 87Do not create a file system: just print out parameters. 88.It Fl @ Ar offset 89Build the filesystem at the specified offset in bytes in the device or file. 90A suffix s, k, m, g (lower or upper case) 91appended to the offset specifies that the 92number is in sectors, kilobytes, megabytes or gigabytes, respectively. 93.It Fl A 94Attempt to cluster align the data area, useful for flash based storage. 95This option is enabled by default, unless a number of reserved sectors 96is specified using the 97.Fl r 98option. 99.It Fl B Ar boot 100Get bootstrap from file. 101.It Fl C Ar create-size 102Create the image file with the specified size. 103A suffix character appended to the size is interpreted as for the 104.Fl @ 105option. 106The file is created by truncating any existing file with the same name and 107resizing it to the requested size. 108If the file system supports sparse files, the space occupied on disk may be 109smaller than the size specified as parameter. 110.It Fl F Ar FAT-type 111FAT type (one of 12, 16, or 32). 112.It Fl I Ar VolumeID 113Volume ID, a 32 bit number in decimal or hexadecimal (0x...) format. 114.It Fl L Ar label 115Volume label (up to 11 characters). 116The label should consist of 117only those characters permitted in regular DOS (8+3) filenames. 118.It Fl O Ar OEM 119OEM string (up to 8 characters). 120The default is 121.Qq Li "BSD4.4 " . 122.It Fl S Ar sector-size 123Number of bytes per sector. 124Acceptable values are powers of 2 125in the range 512 through 32768, inclusive. 126.It Fl T Ar timestamp 127Create the filesystem as though the current time is 128.Ar timestamp . 129The default filesystem volume ID is derived from the time. 130.Ar timestamp 131can be a pathname (where the timestamp is derived from 132that file) or an integer value interpreted 133as the number of seconds since the Epoch. 134.It Fl a Ar FAT-size 135Number of sectors per FAT. 136.It Fl b Ar block-size 137File system block size (bytes per cluster). 138This should resolve to an 139acceptable number of sectors per cluster (see below). 140.It Fl c Ar cluster-size 141Sectors per cluster, also called allocation size. 142Acceptable values are powers of 2 in the range 1431 through 128. 144If the block or cluster size are not specified, the code 145uses a cluster between 512 bytes and 32K depending on 146the filesystem size. 147.It Fl e Ar DirEnts 148Number of root directory entries (FAT12 and FAT16 only). 149.It Fl f Ar format 150Specify a standard (floppy disk) format. 151The standard formats 152are (capacities in kilobytes): 160, 180, 320, 360, 640, 720, 1200, 1531232, 1440, 2880. 154.It Fl h Ar heads 155Number of drive heads. 156.It Fl i Ar info 157Location of the file system info sector (FAT32 only). 158A value of 0xffff signifies no info sector. 159.It Fl k Ar backup 160Location of the backup boot sector (FAT32 only). 161A value 162of 0xffff signifies no backup sector. 163.It Fl m Ar media 164Media descriptor (acceptable range 0xf0 to 0xff). 165.It Fl n Ar FATs 166Number of FATs. 167Acceptable values are 1 to 16 inclusive. 168The default 169is 2. 170.It Fl o Ar hidden 171Number of hidden sectors. 172.It Fl r Ar reserved 173Number of reserved sectors. 174If the 175.Fl r 176option is not used, the number of reserved sectors is set to a value that 177aligns the start of the data area to a multiple of the cluster size. 178.It Fl s Ar total 179File system size. 180.It Fl u Ar track-size 181Number of sectors per track. 182.El 183.Sh NOTES 184If some parameters (e.g., size, number of sectors, etc.) are not specified 185through options or disktype, the program tries to generate them automatically. 186In particular, the size is determined as the device or file size minus the 187offset specified with the 188.Fl @ 189option. 190When the geometry is not available, it is assumed to be 63 sectors, 255 heads. 191The size is then rounded to become a multiple of the track size and avoid 192complaints by some filesystem code. 193.Pp 194FAT file system parameters occupy a "Boot Sector BPB (BIOS Parameter 195Block)" in the first of the "reserved" sectors which precede the actual 196file system. 197For reference purposes, this structure is presented 198below. 199.Bd -literal 200struct bsbpb { 201 uint16_t bpbBytesPerSec; /* [-S] bytes per sector */ 202 uint8_t bpbSecPerClust; /* [-c] sectors per cluster */ 203 uint16_t bpbResSectors; /* [-r] reserved sectors */ 204 uint8_t bpbFATs; /* [-n] number of FATs */ 205 uint16_t bpbRootDirEnts; /* [-e] root directory entries */ 206 uint16_t bpbSectors; /* [-s] total sectors */ 207 uint8_t bpbMedia; /* [-m] media descriptor */ 208 uint16_t bpbFATsecs; /* [-a] sectors per FAT */ 209 uint16_t bpbSecPerTrack; /* [-u] sectors per track */ 210 uint16_t bpbHeads; /* [-h] drive heads */ 211 uint32_t bpbHiddenSecs; /* [-o] hidden sectors */ 212 uint32_t bpbHugeSectors; /* [-s] big total sectors */ 213}; 214/* FAT32 extensions */ 215struct bsxbpb { 216 uint32_t bpbBigFATsecs; /* [-a] big sectors per FAT */ 217 uint16_t bpbExtFlags; /* control flags */ 218 uint16_t bpbFSVers; /* file system version */ 219 uint32_t bpbRootClust; /* root directory start cluster */ 220 uint16_t bpbFSInfo; /* [-i] file system info sector */ 221 uint16_t bpbBackup; /* [-k] backup boot sector */ 222}; 223.Ed 224.Sh LIMITATION 225The maximum file size is 4GB, even if the file system itself is bigger. 226.Sh EXIT STATUS 227Exit status is 0 on success and 1 on error. 228.Sh EXAMPLES 229Create a file system, using default parameters, on 230.Pa /dev/ada0s1 : 231.Bd -literal -offset indent 232newfs_msdos /dev/ada0s1 233.Ed 234.Pp 235Create a FAT32 filesystem with a 32K allocation size on 236.Pa /dev/mmcsd0s1 : 237.Bd -literal -offset indent 238newfs_msdos -F 32 -A -c 64 /dev/mmcsd0s1 239.Ed 240.Pp 241Create a standard 1.44M file system, with volume label 242.Ar foo , 243on 244.Pa /dev/fd0 : 245.Bd -literal -offset indent 246newfs_msdos -f 1440 -L foo fd0 247.Ed 248.Pp 249Create a 30MB image file, with the FAT partition starting 25063 sectors within the image file: 251.Bd -literal -offset indent 252newfs_msdos -C 30M -@63s ./somefile 253.Ed 254.Sh SEE ALSO 255.Xr gpart 8 , 256.Xr newfs 8 257.Sh HISTORY 258The 259.Nm 260utility first appeared in 261.Fx 3.0 . 262.Sh AUTHORS 263.An Robert Nordier Aq Mt rnordier@FreeBSD.org 264