sbin/newfs_msdos/newfs_msdos.8

   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 September 9, 2019
  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
  64 The
  65 .Nm
  66 utility creates a FAT12, FAT16, or FAT32 file system on device or file named
  67 .Ar special ,
  68 using
  69 .Xr disktab 5
  70 entry
  71 .Ar disktype
  72 to determine geometry, if required.
  73 .Pp
  74 If
  75 .Ar special
  76 does not contain a
  77 .Ar /
  78 and
  79 .Fl C
  80 is not used, it is assumed to be a device name and
  81 .Ar /dev/
  82 is prepended to the name to construct the actual device name.
  83 To work a file in the current directory use
  84 .Ar ./filename
  85 .Pp
  86 The options are as follows:
  87 .Bl -tag -width indent
  88 .It Fl N
  89 Do not create a file system: just print out parameters.
  90 .It Fl @ Ar offset
  91 Build the filesystem at the specified offset in bytes in the device or file.
  92 A suffix s, k, m, g (lower or upper case)
  93 appended to the offset specifies that the
  94 number is in sectors, kilobytes, megabytes or gigabytes, respectively.
  95 .It Fl A
  96 Attempt to cluster align root directory, useful for SD card.
  97 .It Fl B Ar boot
  98 Get bootstrap from file.
  99 .It Fl C Ar create-size
 100 Create the image file with the specified size.
 101 A suffix character appended to the size is interpreted as for the
 102 .Fl @
 103 option.
 104 The file is created by truncating any existing file with the same name and
 105 resizing it to the requested size.
 106 If the file system supports sparse files, the space occupied on disk may be
 107 smaller than the size specified as parameter.
 108 .It Fl F Ar FAT-type
 109 FAT type (one of 12, 16, or 32).
 110 .It Fl I Ar VolumeID
 111 Volume ID, a 32 bit number in decimal or hexadecimal (0x...) format.
 112 .It Fl L Ar label
 113 Volume label (up to 11 characters).
 114 The label should consist of
 115 only those characters permitted in regular DOS (8+3) filenames.
 116 .It Fl O Ar OEM
 117 OEM string (up to 8 characters).
 118 The default is
 119 .Qq Li "BSD4.4  " .
 120 .It Fl S Ar sector-size
 121 Number of bytes per sector.
 122 Acceptable values are powers of 2
 123 in the range 512 through 32768, inclusive.
 124 .It Fl T Ar timestamp
 125 Create the filesystem as though the current time is
 126 .Ar timestamp .
 127 The default filesystem volume ID is derived from the time.
 128 .Ar timestamp
 129 can be a pathname (where the timestamp is derived from
 130 that file) or an integer value interpreted
 131 as the number of seconds since the Epoch.
 132 .It Fl a Ar FAT-size
 133 Number of sectors per FAT.
 134 .It Fl b Ar block-size
 135 File system block size (bytes per cluster).
 136 This should resolve to an
 137 acceptable number of sectors per cluster (see below).
 138 .It Fl c Ar cluster-size
 139 Sectors per cluster.
 140 Acceptable values are powers of 2 in the range
 141 1 through 128.
 142 If the block or cluster size are not specified, the code
 143 uses a cluster between 512 bytes and 32K depending on
 144 the filesystem size.
 145 .It Fl e Ar DirEnts
 146 Number of root directory entries (FAT12 and FAT16 only).
 147 .It Fl f Ar format
 148 Specify a standard (floppy disk) format.
 149 The standard formats
 150 are (capacities in kilobytes): 160, 180, 320, 360, 640, 720, 1200,
 151 1232, 1440, 2880.
 152 .It Fl h Ar heads
 153 Number of drive heads.
 154 .It Fl i Ar info
 155 Location of the file system info sector (FAT32 only).
 156 A value of 0xffff signifies no info sector.
 157 .It Fl k Ar backup
 158 Location of the backup boot sector (FAT32 only).
 159 A value
 160 of 0xffff signifies no backup sector.
 161 .It Fl m Ar media
 162 Media descriptor (acceptable range 0xf0 to 0xff).
 163 .It Fl n Ar FATs
 164 Number of FATs.
 165 Acceptable values are 1 to 16 inclusive.
 166 The default
 167 is 2.
 168 .It Fl o Ar hidden
 169 Number of hidden sectors.
 170 .It Fl r Ar reserved
 171 Number of reserved sectors.
 172 .It Fl s Ar total
 173 File system size.
 174 .It Fl u Ar track-size
 175 Number of sectors per track.
 176 .El
 177 .Sh NOTES
 178 If some parameters (e.g., size, number of sectors, etc.) are not specified
 179 through options or disktype, the program tries to generate them automatically.
 180 In particular, the size is determined as the device or file size minus the
 181 offset specified with the
 182 .Fl @
 183 option.
 184 When the geometry is not available, it is assumed to be 63 sectors, 255 heads.
 185 The size is then rounded to become a multiple of the track size and avoid
 186 complaints by some filesystem code.
 187 .Pp
 188 FAT file system parameters occupy a "Boot Sector BPB (BIOS Parameter
 189 Block)" in the first of the "reserved" sectors which precede the actual
 190 file system.
 191 For reference purposes, this structure is presented
 192 below.
 193 .Bd -literal
 194 struct 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 */
 209 struct 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
 219 The maximum file size is 4GB, even if the file system itself is bigger.
 220 .Sh EXIT STATUS
 221 .Ex -std
 222 .Sh EXAMPLES
 223 Create a file system, using default parameters, on
 224 .Pa /dev/da0s1 :
 225 .Bd -literal -offset indent
 226 newfs_msdos /dev/da0s1
 227 .Ed
 228 .Pp
 229 Create a standard 1.44M file system, with volume label
 230 .Ar foo ,
 231 on
 232 .Pa /dev/fd0 :
 233 .Bd -literal -offset indent
 234 newfs_msdos -f 1440 -L foo fd0
 235 .Ed
 236 .Pp
 237 Create a 30MB image file, with the FAT partition starting
 238 63 sectors within the image file:
 239 .Bd -literal -offset indent
 240 newfs_msdos -C 30M -@63s ./somefile
 241 .Ed
 242 .Sh SEE ALSO
 243 .Xr disktab 5 ,
 244 .Xr disklabel 8 ,
 245 .Xr fdisk 8 ,
 246 .Xr newfs 8
 247 .Sh HISTORY
 248 The
 249 .Nm
 250 utility first appeared in
 251 .Fx 3.0 .
 252 .Sh AUTHORS
 253 .An Robert Nordier Aq Mt rnordier@FreeBSD.org