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.\" $FreeBSD$ 27.\" 28.Dd June 14, 2018 29.Dt NEWFS_MSDOS 8 30.Os 31.Sh NAME 32.Nm newfs_msdos 33.Nd construct a new MS-DOS (FAT) file system 34.Sh SYNOPSIS 35.Nm 36.Op Fl N 37.Op Fl @ Ar offset 38.Op Fl A 39.Op Fl B Ar boot 40.Op Fl C Ar create-size 41.Op Fl F Ar FAT-type 42.Op Fl I Ar VolumeID 43.Op Fl L Ar label 44.Op Fl O Ar OEM 45.Op Fl S Ar sector-size 46.Op Fl T Ar timestamp 47.Op Fl a Ar FAT-size 48.Op Fl b Ar block-size 49.Op Fl c Ar cluster-size 50.Op Fl e Ar DirEnts 51.Op Fl f Ar format 52.Op Fl h Ar heads 53.Op Fl i Ar info 54.Op Fl k Ar backup 55.Op Fl m Ar media 56.Op Fl n Ar FATs 57.Op Fl o Ar hidden 58.Op Fl r Ar reserved 59.Op Fl s Ar total 60.Op Fl u Ar track-size 61.Ar special 62.Op Ar disktype 63.Sh DESCRIPTION 64The 65.Nm 66utility creates a FAT12, FAT16, or FAT32 file system on device or file named 67.Ar special , 68using 69.Xr disktab 5 70entry 71.Ar disktype 72to determine geometry, if required. 73.Pp 74If 75.Ar special 76does not contain a 77.Ar / 78and 79.Fl C 80is not used, it is assumed to be a device name and 81.Ar /dev/ 82is prepended to the name to construct the actual device name. 83To work a file in the current directory use 84.Ar ./filename 85.Pp 86The options are as follow: 87.Bl -tag -width indent 88.It Fl N 89Do not create a file system: just print out parameters. 90.It Fl @ Ar offset 91Build the filesystem at the specified offset in bytes in the device or file. 92A suffix s, k, m, g (lower or upper case) 93appended to the offset specifies that the 94number is in sectors, kilobytes, megabytes or gigabytes, respectively. 95.It Fl A 96Attempt to cluster align root directory, useful for SD card. 97.It Fl B Ar boot 98Get bootstrap from file. 99.It Fl C Ar create-size 100Create the image file with the specified size. 101A suffix character appended to the size is interpreted as for the 102.Fl @ 103option. 104The file is created by truncating any existing file with the same name and 105resizing it to the requested size. 106If the file system supports sparse files, the space occupied on disk may be 107smaller than the size specified as parameter. 108.It Fl F Ar FAT-type 109FAT type (one of 12, 16, or 32). 110.It Fl I Ar VolumeID 111Volume ID, a 32 bit number in decimal or hexadecimal (0x...) format. 112.It Fl L Ar label 113Volume label (up to 11 characters). 114The label should consist of 115only those characters permitted in regular DOS (8+3) filenames. 116.It Fl O Ar OEM 117OEM string (up to 8 characters). 118The default is 119.Qq Li "BSD4.4 " . 120.It Fl S Ar sector-size 121Number of bytes per sector. 122Acceptable values are powers of 2 123in the range 512 through 32768, inclusive. 124.It Fl T Ar timestamp 125Create the filesystem as though the current time is 126.Ar timestamp . 127The default filesystem volume ID is derived from the time. 128.Ar timestamp 129can be a pathname (where the timestamp is derived from 130that file) or an integer value interpreted 131as the number of seconds since the Epoch. 132.It Fl a Ar FAT-size 133Number of sectors per FAT. 134.It Fl b Ar block-size 135File system block size (bytes per cluster). 136This should resolve to an 137acceptable number of sectors per cluster (see below). 138.It Fl c Ar cluster-size 139Sectors per cluster. 140Acceptable values are powers of 2 in the range 1411 through 128. 142If the block or cluster size are not specified, the code 143uses a cluster between 512 bytes and 32K depending on 144the filesystem size. 145.It Fl e Ar DirEnts 146Number of root directory entries (FAT12 and FAT16 only). 147.It Fl f Ar format 148Specify a standard (floppy disk) format. 149The standard formats 150are (capacities in kilobytes): 160, 180, 320, 360, 640, 720, 1200, 1511232, 1440, 2880. 152.It Fl h Ar heads 153Number of drive heads. 154.It Fl i Ar info 155Location of the file system info sector (FAT32 only). 156A value of 0xffff signifies no info sector. 157.It Fl k Ar backup 158Location of the backup boot sector (FAT32 only). 159A value 160of 0xffff signifies no backup sector. 161.It Fl m Ar media 162Media descriptor (acceptable range 0xf0 to 0xff). 163.It Fl n Ar FATs 164Number of FATs. 165Acceptable values are 1 to 16 inclusive. 166The default 167is 2. 168.It Fl o Ar hidden 169Number of hidden sectors. 170.It Fl r Ar reserved 171Number of reserved sectors. 172.It Fl s Ar total 173File system size. 174.It Fl u Ar track-size 175Number of sectors per track. 176.El 177.Sh NOTES 178If some parameters (e.g., size, number of sectors, etc.) are not specified 179through options or disktype, the program tries to generate them automatically. 180In particular, the size is determined as the device or file size minus the 181offset specified with the 182.Fl @ 183option. 184When the geometry is not available, it is assumed to be 63 sectors, 255 heads. 185The size is then rounded to become a multiple of the track size and avoid 186complaints by some filesystem code. 187.Pp 188FAT file system parameters occupy a "Boot Sector BPB (BIOS Parameter 189Block)" in the first of the "reserved" sectors which precede the actual 190file system. 191For reference purposes, this structure is presented 192below. 193.Bd -literal 194struct bsbpb { 195 uint16_t bpbBytesPerSec; /* [-S] bytes per sector */ 196 uint8_t bpbSecPerClust; /* [-c] sectors per cluster */ 197 uint16_t bpbResSectors; /* [-r] reserved sectors */ 198 uint8_t bpbFATs; /* [-n] number of FATs */ 199 uint16_t bpbRootDirEnts; /* [-e] root directory entries */ 200 uint16_t bpbSectors; /* [-s] total sectors */ 201 uint8_t bpbMedia; /* [-m] media descriptor */ 202 uint16_t bpbFATsecs; /* [-a] sectors per FAT */ 203 uint16_t bpbSecPerTrack; /* [-u] sectors per track */ 204 uint16_t bpbHeads; /* [-h] drive heads */ 205 uint32_t bpbHiddenSecs; /* [-o] hidden sectors */ 206 uint32_t bpbHugeSectors; /* [-s] big total sectors */ 207}; 208/* FAT32 extensions */ 209struct bsxbpb { 210 uint32_t bpbBigFATsecs; /* [-a] big sectors per FAT */ 211 uint16_t bpbExtFlags; /* control flags */ 212 uint16_t bpbFSVers; /* file system version */ 213 uint32_t bpbRootClust; /* root directory start cluster */ 214 uint16_t bpbFSInfo; /* [-i] file system info sector */ 215 uint16_t bpbBackup; /* [-k] backup boot sector */ 216}; 217.Ed 218.Sh LIMITATION 219The maximum file size is 4GB, even if the file system itself is bigger. 220.Sh EXIT STATUS 221Exit status is 0 on success and 1 on error. 222.Sh EXAMPLES 223Create a file system, using default parameters, on 224.Pa /dev/ada0s1 : 225.Bd -literal -offset indent 226newfs_msdos /dev/ada0s1 227.Ed 228.Pp 229Create a standard 1.44M file system, with volume label 230.Ar foo , 231on 232.Pa /dev/fd0 : 233.Bd -literal -offset indent 234newfs_msdos -f 1440 -L foo fd0 235.Ed 236.Pp 237Create a 30MB image file, with the FAT partition starting 23863 sectors within the image file: 239.Bd -literal -offset indent 240newfs_msdos -C 30M -@63s ./somefile 241.Ed 242.Sh SEE ALSO 243.Xr gpart 8 , 244.Xr newfs 8 245.Sh HISTORY 246The 247.Nm 248utility first appeared in 249.Fx 3.0 . 250.Sh AUTHORS 251.An Robert Nordier Aq Mt rnordier@FreeBSD.org 252