doc: Add 'fs precache' manpage

Change-Id: Ib4101fdb37cf91a547974216425e4a005392d988
Reviewed-on: http://gerrit.openafs.org/10413
Reviewed-by: Derrick Brashear <shadow@your-file-system.com>
Tested-by: Derrick Brashear <shadow@your-file-system.com>

diff --git a/doc/man-pages/pod1/fs_precache.pod b/doc/man-pages/pod1/fs_precache.pod
new file mode 100644 (file)
index 0000000..115ca11
--- /dev/null
+++ b/doc/man-pages/pod1/fs_precache.pod
@@ -0,0 +1,80 @@
+=head1 NAME
+
+fs_precache - Set precache size
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<fs precache> S<<< B<-blocks> <I<size in 1K blocks>> >>>
+    [B<-help>]
+
+B<fs p> S<<< B<-b> <I<size in 1K blocks>> >>>
+    [B<-h>]
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+The B<fs precache> command configures to what degree the Cache Manager will
+attempt to prefetch cache blocks when an application opens a file for reading.
+If this behavior is enabled, whenever a file is opened for reading, the Cache
+Manager will immediately initiate an asynchronous fetch request for that file.
+This fetch request will fetch the configured amount of data for that file, and
+store the data in the cache. In some scenarios, this can improve performance.
+
+Note that this prefetching behavior is done by the Cache Manager itself. The
+underlying Operating System may also perform its own prefetching behavior,
+depending on various settings or application hints.
+
+This command was introduced in OpenAFS 1.5.37.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-blocks> <I<size in 1K blocks>>
+
+Specifies how much data to prefetch for each applicable file, in 1024-byte
+blocks. Specify 0 to disable prefetching behavior. By default, prefetching is
+disabled.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+If the specified precache size has been set successfully, the following message
+will be printed:
+
+   New precache size set.
+
+=head1 EXAMPLES
+
+The following command configures the Cache Manager to prefetch the first 100
+kilobytes of any file that's opened for reading:
+
+   % fs precache -blocks 100
+   New precache size set.
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser C<root>.
+
+=head1 SEE ALSO
+
+L<afsd(8)>
+
+=head1 COPYRIGHT
+
+Copyright 2013 Sine Nomine Associates
+
+This documentation is covered by the BSD License as written in the
+doc/LICENSE file. This man page was written by Andrew Deason for
+OpenAFS.