docs/114715: incorrect use of FATxx and ``extended file system'' in handbook/install

Thu Jul 19 02:00:09 UTC 2007

>Number:         114715
>Category:       docs
>Synopsis:       incorrect use of FATxx and ``extended file system'' in handbook/install
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Jul 19 02:00:08 GMT 2007
>Closed-Date:
>Last-Modified:
>Originator:     Ben Kaduk
>Release:        7.0-CURRENT
>Organization:
>Environment:
System: FreeBSD prolepsis.scs.uiuc.edu 7.0-CURRENT FreeBSD 7.0-CURRENT #1: Sun Apr 1 16:59:00 UTC 2007 kaduk at prolepsis.scs.uiuc.edu:/usr/obj/usr/src/sys/GENERIC i386
>Description:
bde@, in his unbounded-but-not-infinite (because that's just impossible) wisdom, remarks:

--------- begin bde@ text ------------
On Fri, 13 Jul 2007, Ben Kaduk wrote:

> I recently got a patch committed to the installation chapter of the
> handbook, which included two occasions of clarifying ``MS-DOS
> filesystem'' as ``FAT16 or FAT32'' [1,2 for present incarnation].  I
> am too young to remember the existence of FAT12, so I'll have to defer
> to others as to whether the handbook should mention FAT12 in the same
> breath as FAT16 and FAT32.  What do you think?

I think FAT* is newspeak :-).  The file system is named msdosfs, not FAT.
Anyway, the number of bits per FAT entry is of no interest in most cases,
so it shouldn't be emphasized.  newfs_msdos will choose the best number,
or if you tell it, any number that can work.  newfs_msdos(8) says
"construct a new MS-DOS (FAT) file system ... creates a FAT12, FAT16 or
FAT32 file system".  It doesn't say anything about how newfs_msdos chooses
the best FAT size or other important parameters.  newfs_msdos still hasn't
caught up with the renaming of file systems from foo to foofs.

> [1]
> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/install-pre.html
> [2]
> http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/install-trouble.html

A quick reading showed some bugs in [2]:
- just after "FAT16 and FAT32", it says "The utility most common usage is
  # mount_msdosfs /dev/ad0s1 /mnt".  It should say something like "This
  utility's most common usage is indirectly via a line in /etc/fstab or
  mount -t msdosfs.  [Example line in fstab, and the above command line
  with direct use of mount_msdosfs fixed.]  This [section of?] the
  handbook is too small to describe utilities in not most common usage
  like newfs_msdos."

- a little later, it says It says "Extended MS-DOS file systems are usually
  mapped after FreeBSD partitions ... with the extended MS-DOS partition
  located on /dev/ad0s3", but there is no such thing as an extended MS-DOS
  file system.  It should say something like "MS-DOS logical drives are
  usually mapped after primary partitions ... with the first logical drive
  being /dev/ad0s3" and possibly add some details ("partition" here means
  an MS-DOS primary partition; MS-DOS extended partitions aren't mapped;
  MS-DOS logical drives correspond to FreeBSD slices, except for primary
  partitions the partitions correspond to slices; check that in MS-DOS
  speak, primary partitions aren't described as logical drives; logical
  drives may or may not contain a file system, but in this example
  /dev/ad0s3 has an MS-DOS file system, and I didn't reword things enough
  to describe this).
---------------- end bde@ text -------------

The attached patch removes the explicit reference to FATxx (but mentions that some people call msdosfs ``FAT''), fixes the ``most common usage'', and clarifies the note about numbering of extended (msdos) partitions.
>How-To-Repeat:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/install-trouble.html
>Fix:


Patch attached with submission follows:

--- chapter.sgml.orig	2007-07-14 16:51:56.000000000 -0500
+++ chapter.sgml	2007-07-18 20:47:48.000000000 -0500
@@ -3967,24 +3967,37 @@
 	located in the <guimenuitem>Start</guimenuitem>> <guimenuitem>Programs</guimenuitem> >
 	<guimenuitem>System Tools</guimenuitem> menu.</para>
 
-      <para>&os; can support &ms-dos; based file systems (FAT16 and FAT32).
-	This requires you use the &man.mount.msdosfs.8; command
-	with the required parameters.  The utility most common usage is:</para>
+      <para>&os; can support &ms-dos; file systems (sometimes called FAT file systems).
+	The &man.mount.msdosfs.8; command grafts such file systems onto the
+	existing directory hierarchy, allowing the file system's contents
+	to be accessed.  &man.mount.msdosfs.8; is not usually invoked directly;
+	instead, it is called by the system through a line in
+	<filename>/etc/fstab</filename> or by a call to the &man.mount.8;
+	utility with the appropriate parameters.</para>
 
-      <screen>&prompt.root; <userinput>mount_msdosfs /dev/ad0s1 /mnt</userinput></screen>
+	<para>A typical line in <filename>/etc/fstab</filename> is:</para>
+
+	<programlisting>/dev/ad0sN	/dos	msdosfs	rw	0	0</programlisting>
+
+	<note>the <filename>/dos</filename> directory must already
+	exist for this to work.  For details about the format of
+	</filename>/etc/fstab</filename>, see &man.fstab.5;.</note>
+
+	<para>A typicall call to &man.mount.8; for a &ms-dos; file system is:</para>
+
+	<screen>&prompt.root; <userinput>mount -t msdosfs /dev/ad0s1 /mnt</userimput></screen>
 
       <para>In this example, the &ms-dos; file system is located on the first partition of
 	the primary hard disk.  Your situation may be different, check the output from
 	the <command>dmesg</command>, and <command>mount</command> commands.  They should
 	produce enough information to give an idea of the partition layout.</para>
 
-      <note><para>Extended &ms-dos; file systems are usually mapped after the &os;
-	partitions.  In other words, the slice number may be higher than the ones
-	&os; is using.  For instance, the first &ms-dos; partition may be
-	<filename>/dev/ad0s1</filename>, the &os; partition may be
-	<filename>/dev/ad0s2</filename>, with the extended &ms-dos; partition being
-	located on <filename>/dev/ad0s3</filename>.  To some, this can be confusing
-	at first.</para></note>
+      <note><para>&os; may number disk slices (that is, &ms-dos; partitions)
+        differently than other operating systems.  In particular, extended
+        &ms-dos; partitions are usually given higher slice numbers than
+        primary &ms-dos; partitions.  The &man.fdisk.8; utility can help
+        determine which slices belong to &os; and which belong to other
+        operating systems.</para></note>
 
       <para>NTFS partitions can also be mounted in a similar manner
 	using the &man.mount.ntfs.8; command.</para>


>Release-Note:
>Audit-Trail:
>Unformatted:

