Initial commit for platform/external/newfs_msdos.
Bug: http://b/110053628
Test: N/A
Change-Id: I4432b7d20fc4bac0ed331797023543db02bfcd19
diff --git a/newfs_msdos.8 b/newfs_msdos.8
new file mode 100644
index 0000000..61639f5
--- /dev/null
+++ b/newfs_msdos.8
@@ -0,0 +1,248 @@
+.\" 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: head/sbin/newfs_msdos/newfs_msdos.8 318366 2017-05-16 19:03:26Z emaste $
+.\"
+.Dd May 16, 2017
+.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 T Ar timestamp
+.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 T Ar timestamp
+Create the filesystem as though the current time is
+.Ar timestamp .
+The default filesystem volume ID is derived from the time.
+.Ar timestamp
+can be a pathname (where the timestamp is derived from
+that file) or an integer value interpreted
+as the number of seconds since the Epoch.
+.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