sbin/newfs_msdos/newfs_msdos.8

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