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