Update information for current codebase features

Several things like default mount options, mkfs options,
structures, etc are out of date.

This is just a first pass but gets some of the simpler

Also a few minor clarifications, notes, etc were added.

A few odd-character hyphens got fixed as well.

Signed-off-by: Eric Sandeen <sandeen@redhat.com>
Reviewed-by: Christoph Hellwig <hch@lst.de>
diff --git a/XFS_User_Guide/en-US/XFS-Background.xml b/XFS_User_Guide/en-US/XFS-Background.xml
index 3ce07b3..b62939e 100644
--- a/XFS_User_Guide/en-US/XFS-Background.xml
+++ b/XFS_User_Guide/en-US/XFS-Background.xml
@@ -481,17 +481,6 @@
 		<listitem><para>Does not support V1 directories</para></listitem>
 		<listitem><para>Filesystem block size &lt;= PAGE_SIZE only</para></listitem>
-		<listitem><para>Does not support case insensitive directories</para></listitem>
-		<listitem><para>Does not support 64 bit inode numbers on 32 bit platforms
-			<itemizedlist>
-			<listitem><para>Will need XFS changes once generic changes in</para></listitem>
-			</itemizedlist>
-		</para></listitem>
-		<listitem><para>Does not support filestreams allocator
-			<itemizedlist>
-			<listitem><para>Development in progress (Oct 06)</para></listitem>
-			</itemizedlist>
-		</para></listitem>
diff --git a/XFS_User_Guide/en-US/XFS-Overview.xml b/XFS_User_Guide/en-US/XFS-Overview.xml
index 8ae690c..1762b39 100644
--- a/XFS_User_Guide/en-US/XFS-Overview.xml
+++ b/XFS_User_Guide/en-US/XFS-Overview.xml
@@ -77,18 +77,20 @@
 		<title>Unwritten Extents</title>
 		<para>An unwritten extent is an extent which has been marked as "not yet written" ondisk.</para>
-		<para>Unwritten extents can be created by</para>
+		<para>Unwritten extents can be created by preallocating file space using:</para>
-		<listitem><para>Preallocating file space using (currently) XFS specific interfaces
+		<listitem><para>XFS specific interfaces (<command>xfsctl(3)</command>)</para></listitem>
+		<listitem><para><command>sys_fallocate</command> on kernels >= 2.6.23</para></listitem>
+		<listitem><para><command>posix_fallocate(3)</command> on recent glibc
-			<listitem><para>Someday there may be a real kernel fallocate(2) syscall</para></listitem>
+			<listitem><para>falls back to 0-writing if kernel or fs has no support</para></listitem>
+		<listitem><para><command>fallocate(1)</command> on newer glibc versions</para></listitem>
 		<listitem><para>Through direct IOs of specific (un)alignment.</para></listitem>
 		<para>They are a security measure, to ensure allocated but not yet initialised space
 		      ondisk is not visible to arbitrary users</para>
-		<para>mkfs.xfs option to enable or disable, on by default.</para>
 		<para>Unwritten extents apply only to regular files.</para>
 		<para>Once such an extent is written to, or partially written to, a transaction is 
 		      issued to convert the written part into a regular written extent, and mark the 
@@ -106,13 +108,12 @@
 		<para> Linux inode</para>
-		<listitem><para>bhv_vnode_t has the Linux inode embedded in it</para></listitem>
+		<listitem><para>xfs_inode_t has the Linux inode embedded in it</para></listitem>
 		<para>XFS inode</para>
 		<listitem><para>xfs_inode contains the ondisk inode structure in memory</para></listitem>
-		<para>The Linux and XFS inodes have different lifecycles, which can cause problems</para>
 		<title>Directory and File Inodes</title>
diff --git a/XFS_User_Guide/en-US/XFS-allocators.xml b/XFS_User_Guide/en-US/XFS-allocators.xml
index 31b80e8..25ab4df 100644
--- a/XFS_User_Guide/en-US/XFS-allocators.xml
+++ b/XFS_User_Guide/en-US/XFS-allocators.xml
@@ -116,8 +116,8 @@
 fs.xfs.rotorstep = 1
 # sudo sysctl –w fs.xfs.rotorstep=24
 fs.xfs.rotorstep = 24</programlisting></para>
-		<para>Note that the rotorstep value is a global one, so setting it will affect the behaviour of 
-		      all mounted file systems over 1TB in size that use 32 bit inode numbers.</para>
+		<note><para>The rotorstep value is a global one, so setting it will affect the behaviour of 
+		      all mounted file systems over 1TB in size that use 32 bit inode numbers.</para></note>
 		<title>Realtime Allocator</title>
@@ -130,6 +130,8 @@
 		      latencies regardless of the filesystem's contents.</para>
 		<para>By using the realtime allocator in conjunction with an external log volume, it's possible 
 		      to remove most of the unpredictability in disk response times that's caused by metadata overheads.</para>
+		<note><para>The realtime allocator is only available when XFS kernelspace is built with
+			    CONFIG_XFS_RT enabled</para></note>
 		<title>Realtime Allocator Limitations</title>
@@ -284,6 +286,11 @@
 actual 45966, ideal 12398, fragmentation factor 73.03%
 xfs_db: frag -f
 actual 2104856, ideal 2100484, fragmentation factor 0.21%</programlisting></para>
+	<note><para>The fragmentation factor value can be misleading.</para>
+	      <para>It is derived from (actual - ideal) / (ideal) so an average of 5 extents
+		    per file will yield 80%.  For multi-gigabyte files, 5 extents is
+		    not harmful, and the 80% is not representative of a problem.</para>
+	</note>
diff --git a/XFS_User_Guide/en-US/XFS-build.xml b/XFS_User_Guide/en-US/XFS-build.xml
index 98121fa..3bf6c6d 100644
--- a/XFS_User_Guide/en-US/XFS-build.xml
+++ b/XFS_User_Guide/en-US/XFS-build.xml
@@ -10,38 +10,26 @@
 		<listitem><para>obtain the latest XFS source code</para></listitem>
 		<listitem><para>how to build and install the commands and kernel components</para></listitem>
-		<para>The following prerequisite RPMs should be installed</para>
-		<itemizedlist>
-		<listitem><para>xfsprogs-devel</para></listitem>
-		<listitem><para>dmapi-devel</para></listitem>
-		</itemizedlist>
-		<para>These headers and installed can be built from source, but these RPMs will normally suffice
 		<title>XFS Source Code</title>
-		<para>Latest XFS is available via CVS from oss.sgi.com:</para>
+		<para>Latest XFS is available via git from oss.sgi.com:</para>
-> export CVSROOT=':pserver:cvs@oss.sgi.com:/cvs'
-> cvs login
-Logging in to :pserver:cvs@oss.sgi.com:2401/cvs
-CVS password: <emphasis>&lt;password is “cvs”&gt;</emphasis>
-> cvs checkout linux-2.6-xfs
-cvs checkout: Updating linux-2.6-xfs
-U linux-2.6-xfs/.gitignore
-U linux-2.6-xfs/COPYING
-U linux-2.6-xfs/CREDITS
+> git clone git://oss.sgi.com/xfs/xfs.git
-> cvs checkout xfs-cmds</programlisting></para>
+> git clone git://oss.sgi.com/xfs/xfsprogs.git
+> git clone git://oss.sgi.com/xfs/xfsdump.git
 		<title>Building xfs-cmds</title>
-		<para>Building the XFS commands</para>
+		<para>Building the XFS Userspace</para>
-> cd xfs-cmds
+> xfsprogs
 > make
 		<para>RPM packages will be placed in RPMS/&lt;arch&gt;</para>
 > cd RPMS/x86_64
@@ -49,23 +37,15 @@
 > sudo rpm -i xfsdump-2.2.43-1.x86_64.rpm
 		<para>Source RPM packages will be placed in SRPMS/</para>
+		<note><para>Distribution-provided packages are generally preferable to
+			    those generated from this tree, for OS consistency</para></note>
-		<title>Packaging</title>
+		<title>XFS Userspace Packaging</title>
 		<para>XFS uses autoconf/configure</para>
 		<para>Includes internationalization support</para>
 		<para>User space packages</para>
-		<listitem><para>acl
-			<itemizedlist>
-			<listitem><para>libacl</para></listitem>
-			</itemizedlist>
-		</para></listitem>
-		<listitem><para>attr
-			<itemizedlist>
-			<listitem><para>libattr (incl. IRIX compatibility API for xfsdump/restore/...)</para></listitem>
-			</itemizedlist>
-		</para></listitem>
 			<listitem><para>libhandle, libxfs, libxlog, libdisk</para></listitem>
@@ -98,15 +78,11 @@
 		<listitem><para>support for the data management API (requires generic kernel DMAPI support)</para></listitem>
-		<para>CONFIG_XFS_SECURITY</para>
-		<itemizedlist>
-		<listitem><para>support for alternate access control models (ie SELinux).</para></listitem>
-		</itemizedlist>
 		<listitem><para>support for Access Control Lists.</para></listitem>
-		<para>CONFIG_XFS_REALTIME</para>
+		<para>CONFIG_XFS_RT</para>
 		<listitem><para>support for the realtime allocator that provides deterministic data rates.</para></listitem>
@@ -114,16 +90,14 @@
 		<listitem><para>include debugging features in the build (ie ASSERTs, sanity checking code, etc).</para></listitem>
-		<para>CONFIG_XFS_TRACING</para>
-		<itemizedlist>
-		<listitem><para>include support for activity tracing of inodes, buffers, locks, the log, I/O path, etc.</para></listitem>
-		</itemizedlist>
+		<warning><para>A debug XFS build is not recommended for production use - some error conditions
+			       will panic the box to aid debugging.</para></warning>
 		<title>Build Kernel Components</title>
 		<para>Configure and build kernel and modules</para>
-> cd linux-2.6-xfs
+> cd xfs
 > make xconfig
 > make bzImage
 > make modules
@@ -132,7 +106,7 @@
 # cp arch/&lt;arch&gt;/boot/bzImage /boot/vmlinuz
 # cp System.map /boot/System.map
-# lilo
+# vim /boot/grub/menu.lst
 # reboot</programlisting></para>
diff --git a/XFS_User_Guide/en-US/XFS-mkfs.xml b/XFS_User_Guide/en-US/XFS-mkfs.xml
index 7ed9e7e..ce26572 100644
--- a/XFS_User_Guide/en-US/XFS-mkfs.xml
+++ b/XFS_User_Guide/en-US/XFS-mkfs.xml
@@ -20,26 +20,26 @@
 		<para>Also provides the capability to pre-initialise the filesystem with directories and inodes, which is useful for testing</para>
-		<title>mkfs – Allocation Block Size</title>
+		<title>mkfs - Allocation Block Size</title>
 		<para>Specify the fundamental block size of the filesystem.</para>
 		<para>The default value is 4096 bytes (4 KB), the minimum is 512, and the maximum is 65536 (64 KB).</para>
 		<para>XFS on Linux currently only supports pagesize or smaller blocks.</para>
 		<para>To create a filesystem with a block size of 2048 bytes you would use:</para>
-		<para><command>mkfs –b size=2048 device</command></para>
+		<para><command>mkfs.xfs -b size=2048 device</command></para>
 		<para><emphasis>Smaller block sizes reduce wasted space for lots of small files.</emphasis></para>
-		<title>mkfs – Allocation groups</title>
+		<title>mkfs - Allocation groups</title>
 		<para>The data section of an XFS filesystem is divided into allocation groups</para>
 		<para>More allocation groups imply more parallelism when allocation blocks and inodes.</para>
 		<para>To create filesystem with 16 allocation groups you would use:</para>
-		<para><command>mkfs –d acount=16 device</command></para>
+		<para><command>mkfs.xfs -d acount=16 device</command></para>
 		<para>To create a filesystem with fixed size allocation groups</para>
-		<para><command>mkfs –d agsize=4g device</command></para>
+		<para><command>mkfs.xfs -d agsize=4g device</command></para>
 		<para><emphasis>Filesystems with too few or too many allocation groups should be avoided.</emphasis></para>
-		<title>mkfs – Stripe Alignment</title>
+		<title>mkfs - Stripe Alignment</title>
 		<para>Aligning file data on stripe width boundaries can significantly improve performance on large RAIDs</para>
 		<listitem><para>A 2MB write to filesystem with a 2MB stripe width and 512KB stripe unit will result in four 
@@ -47,22 +47,15 @@
 				and one I/O to the other three, taking longer than it should.</para></listitem>
 		<para>To create a filesystem with a stripe unit of 1MB for an 8+1 RAID you would use:</para>
-		<para><command>mkfs –d sunit=2048,swidth=16384 device</command></para>
+		<para><command>mkfs.xfs -d sunit=2048,swidth=16384 device</command></para>
-		<para><command>mkfs –d su=1m,sw=8m device</command></para>
+		<para><command>mkfs.xfs -d su=1m,sw=8m device</command></para>
+		<note><para>xfsprogs 3.1.0 and newer will use the blkid library to correctly identify
+			    stripe geometry for lvm, md, and some hardware raid devices which export this
+			    information</para></note>
-		<title>mkfs – Unwritten Extents</title>
-		<para>Unwritten extents are used to support pre-allocation.</para>
-		<para>Default is enabled.</para>
-		<para>To disable unwritten extents you would use:</para>
-		<para><command>mkfs –d unwritten=0 device</command></para>
-		<para><emphasis>Filesystem write performance may be negatively affected for unwritten file extents, 
-				since extra filesystem transactions are required to convert extent flags for the range 
-				of the file written.</emphasis></para>
-	</section>
-	<section>
-		<title>mkfs – Inode Options</title>
+		<title>mkfs - Inode Options</title>
 		<para>The mkfs inode options allow the user to change</para>
 		<listitem><para>The size of the inode from the default 256 bytes to up 2048 bytes</para></listitem>
@@ -76,28 +69,30 @@
 		<listitem><para>how much data may be associated with the inode before data goes out of line</para></listitem>
 		<para>To allocate 512 bytes to each inode:</para>
-		<para><command>mkfs –i size=512 device</command></para>
+		<para><command>mkfs.xfs -i size=512 device</command></para>
-		<title>mkfs – Extended Attributes</title>
+		<title>mkfs - Extended Attributes</title>
 		<para>Specify the version of extended attribute inline allocation policy to be used.</para>
 		<para>Default is zero, when extended attributes are used for the first time the version 
 		      will be set to either one or two.</para>
 		<para>Version two uses a more efficient algorithm for managing the available inline inode space 
 		      than version one, however, for backward compatibility, version one is selected by default.</para>
 		<para>To force the use of version two extended attributes you would use:</para>
-		<para><command>mkfs –i attr=2 device</command></para>
+		<para><command>mkfs.xfs -i attr=2 device</command></para>
-		<title>mkfs – Naming options</title>
+		<title>mkfs - Naming options</title>
 		<para>Specify the version and size parameters for the naming (directory) area of the filesystem.</para>
 		<para>The naming (directory) version is 1 or 2, defaulting to 2 if unspecified.</para>
 		<para>XFS on Linux does not support naming (directory) version 1.</para>
 		<para>To create a filesystem with a directory block size of 16KB you would use:</para>
-		<para><command>mkfs –n size=16384 device</command></para>
+		<para><command>mkfs.xfs -n size=16384 device</command></para>
+		<para>ASCII-only case-insensitive naming is also supported:</para>
+		<para><command>mkfs.xfs -n version=ci device</command></para>
-		<title>mkfs – External Log</title>
+		<title>mkfs - External Log</title>
 		<para>The journal log can be on a different device to the rest of the filesystem</para>
 		<listitem><para>At least 512 blocks.</para></listitem>
@@ -108,8 +103,8 @@
 		<listitem><para>15K RPM disk or battery-backed memory</para></listitem>
-		<para><command>mkfs.xfs –l logdev=log_device device</command></para>
-		<para><command>mount –o logdev=log_device device path</command></para>
+		<para><command>mkfs.xfs -l logdev=log_device device</command></para>
+		<para><command>mount -o logdev=log_device device path</command></para>
 		<para>XXX Image goes here</para>
@@ -122,36 +117,40 @@
 		<listitem><para>Bitmap allocator only has to manage file data allocations</para></listitem>
-		<para><command>mkfs.xfs –l logdev=log_device –r rtdev=rt_device device</command></para>
-		<para><command>mount –o logdev=log_device,rtdev=rt_device device path</command></para>
+		<para><command>mkfs.xfs -l logdev=log_device -r rtdev=rt_device device</command></para>
+		<para><command>mount -o logdev=log_device,rtdev=rt_device device path</command></para>
 		<para><emphasis>rt_device</emphasis> is the device for the file data, device is for the metadata</para>
 		<para>Receives limited testing and support in Linux</para>
+		<note><para>Filesystems created with a realtime subvolume can only be mounted on kernels
+			    with CONFIG_XFS_RT enabled</para></note>
 		<para>XXX Image goes here</para>
-		<title>mkfs – Filesystem Image</title>
+		<title>mkfs - Filesystem Image</title>
 		<para>mkfs allows you to create a filesystem as a regular file</para>
 		<para>This can be used to create a filesystem on a loop-back device</para>
-		<para><command>mkfs –d file=1,name=filename,size=2g filename</command></para>
+		<para><command>mkfs.xfs -d file=1,name=filename,size=2g filename</command></para>
-		<title>mkfs – Sector Size</title>
+		<title>mkfs - Sector Size</title>
 		<para>Specifies the fundamental sector size of the filesystem.</para>
 		<para>Default value is 512 bytes.</para>
 		<para>The minimum value for sector size is 512; the maximum is 32768 (32 KB) or the filesystem block size (whichever is smaller).</para>
 		<para>To create a filesystem on a device that has a sector size of 1KB you would use:</para>
-		<para><command>mkfs –s size=1024 device</command></para>
+		<para><command>mkfs.xfs -s size=1024 device</command></para>
+		<note><para>xfsprogs 3.1.0 and newer will automatically detect the appropriate sector size for a device</para></note>
-		<title>mkfs – Filesystem Label</title>
+		<title>mkfs - Filesystem Label</title>
 		<para>Set the filesystem label.</para>
 		<para>XFS filesystem labels can be at most 12 characters long.</para>
 		<para>To create a filesystem and specify the label you would use:</para>
-		<para><command>mkfs –L label device</command></para>
+		<para><command>mkfs.xfs -L label device</command></para>
+		<note><para>A label may later be added or changed by using the <command>xfs_admin</command> command</para></note>
-		<title>mkfs – Prototype Filesystem</title>
-		<para>The –p option to mkfs allows you to specify a prototype file</para>
+		<title>mkfs - Prototype Filesystem</title>
+		<para>The -p option to mkfs allows you to specify a prototype file</para>
 		<para>The prototype file lists inodes and their metadata that mkfs will add to the filesystem when it is created</para>
 		<para>Since the filesystem is not mounted at this time no logging is required, so mkfs can create millions 
 		      of inodes at a much faster rate than on a live filesystem</para>
diff --git a/XFS_User_Guide/en-US/XFS-mount.xml b/XFS_User_Guide/en-US/XFS-mount.xml
index 759047f..f179287 100644
--- a/XFS_User_Guide/en-US/XFS-mount.xml
+++ b/XFS_User_Guide/en-US/XFS-mount.xml
@@ -23,14 +23,14 @@
 		<para>What common Linux mount options does XFS not support?</para>
-		<title>Mount Options – Log &amp; Realtime Devices</title>
+		<title>Mount Options - Log &amp; Realtime Devices</title>
 		<para>Use an external log (metadata journal) device:</para>
 		<para><command>mount -o logdev=log_device device mountpoint</command></para>
 		<para>Use an external log (metadata journal) and real-time device:</para>
 		<para><command>mount -o logdev=log_device,rtdev=rt_device device mountpoint</command></para>
-		<title>Mount Options – 64bit Inodes</title>
+		<title>Mount Options - 64bit Inodes</title>
 		<para>By default XFS uses 32bit inodes</para>
 		<listitem><para>The inode’s number roughly equates to its location on disk
@@ -74,7 +74,7 @@
-		<title>Mount Options – Large I/O</title>
+		<title>Mount Options - Large I/O</title>
 		<listitem><para>A filesystem that has a <command>swidth</command> specified will return the 
@@ -93,8 +93,8 @@
-		<title>Mount Options – Performance Tweaks</title>
-		<para><command>osyncisdsync</command></para>
+		<title>Mount Options - Performance Tweaks</title>
+		<para><command>osyncisdsync (default/deprecated)</command></para>
 		<listitem><para>Writes to files opened with the O_SYNC flag set will behave as if the O_DSYNC 
 				flag had been used instead.</para></listitem>
@@ -102,19 +102,14 @@
 		<listitem><para>However timestamp updates from O_SYNC writes can be lost if the system crashes. 
 				Use osyncisosync to disable this setting.</para></listitem>
-		<para><command>ihashsize</command></para>
-		<itemizedlist>
-		<listitem><para>Sets the number of hash buckets available for hashing the in-memory inodes of the
-				specified mount point.</para></listitem>
-		</itemizedlist>
 		<listitem><para>When inode clusters are emptied of inodes, keep them around on the disk.</para></listitem>
-		<title>Mount Options – Extended Attributes</title>
-		<para><command>attr2</command></para>
+		<title>Mount Options - Extended Attributes</title>
+		<para><command>attr2 (default)</command></para>
 		<listitem><para>Enable the use of version two of the extended attribute inline allocation policy.</para></listitem>
@@ -127,7 +122,7 @@
 		<para><command>mount -o attr2 device mountpoint</command></para>
-		<title>Mount Options – Group Ids</title>
+		<title>Mount Options - Group Ids</title>
 		<para>These options define what group ID a newly created file gets.</para>
@@ -141,7 +136,7 @@
-		<title>Mount Options – Recovery</title>
+		<title>Mount Options - Recovery</title>
 		<para>An XFS filesystem can be mounted without running log recovery.</para>
 		<para>If the filesystem was not cleanly unmounted, it is likely to be inconsistent when mounted 
 		      in <command>norecovery</command> mode. Some files or directories may not be accessible because of this.</para>
@@ -160,10 +155,10 @@
 		<listitem><para>Ensures that the log entry is written before any other data</para></listitem>
-		<para>Write barriers are enabled by default in SLES10</para>
+		<para>Write barriers are enabled by default in XFS</para>
 		<listitem><para>Filesystem will attempt to determine is barriers are supported and will 
-				issue a warning if they are not</para></listitem>
+				issue a warning to the syslog if they are not</para></listitem>
 		<listitem><para>The <command>nobarrier</command> option disables write barriers</para></listitem>
@@ -173,7 +168,7 @@
-		<title>Mount Options – User/Group/Project Quotas</title>
+		<title>Mount Options - User/Group/Project Quotas</title>
 		<para>User disk quota accounting enabled, and limits (optionally) enforced.</para>
 		<para><command>mount -o uquota device mountpoint</command></para>
 		<para>Group disk quota accounting enabled, and limits (optionally) enforced.</para>
@@ -184,7 +179,7 @@
 		      <command>pqnoenforce</command> to use soft limits.</para>
-		<title>Mount Options – DMAPI</title>
+		<title>Mount Options - DMAPI</title>
 		<listitem><para>Enable the DMAPI (Data Management API) event callouts.</para></listitem>
diff --git a/XFS_User_Guide/en-US/XFS-repair.xml b/XFS_User_Guide/en-US/XFS-repair.xml
index 3f53cdb..a4d1c51 100644
--- a/XFS_User_Guide/en-US/XFS-repair.xml
+++ b/XFS_User_Guide/en-US/XFS-repair.xml
@@ -207,5 +207,7 @@
 		<para>But in this case, the only option may be to throw the log away:</para>
 # xfs_repair -L</programlisting></para>
+		<warning><para>Destroying the log throws away valuable metadata, and may cause further corruption.
+				Attempt a mount before using -L, and use this option only as a last resort</para></warning>