man-page-more-fs-commands-20090517

LICENSE IPL10
FIXES 124756

Add man pages for fs cscpolicy, fs getfid, and fs memdump.

doc/man-pages/README

@@ -233,9 +233,6 @@ Known Problems
 
        compile_et.afs
        copyauth
-       fs cscpolicy
-       fs getfid
-       fs memdump
        fs monitor
        fs rxstatpeer
        fs rxstatproc

doc/man-pages/pod1/fs.pod

@@ -45,6 +45,7 @@ Commands to administer server machines, volumes or partitions that house a
 given file or directory:
 L<B<fs diskfree>|fs_diskfree(1)>,
 L<B<fs examine>|fs_examine(1)>,
+L<B<fs getfid>|fs_getfid(1)>,
 L<B<fs listquota>|fs_listquota(1)>,
 L<B<fs quota>|fs_quota(1)>,
 L<B<fs setquota>|fs_setquota(1)>,
@@ -56,6 +57,7 @@ and L<B<fs whichcell>|fs_whichcell(1)>.
 
 Commands to administer the local client cache and related information:
 L<B<fs checkvolumes>|fs_checkvolumes(1)>,
+L<B<fs cscpolicy>|fs_cscpolicy(1)>,
 L<B<fs flush>|fs_flush(1)>,
 L<B<fs flushall>|fs_flushall(1)>,
 L<B<fs flushvolume>|fs_flushvolume(1)>,
@@ -75,6 +77,7 @@ and L<B<fs rmmount>|fs_rmmount(1)>.
 
 Commands to control monitoring and tracing:
 L<B<fs debug>|fs_debug(1)>,
+L<B<fs memdump>|fs_memdump(1)>,
 and L<B<fs messages>|fs_messages(1)>.
 
 =item *

doc/man-pages/pod1/fs_cscpolicy.pod

@@ -0,0 +1,107 @@
+=head1 NAME
+
+fs_cscpolicy - Change client side caching policy for AFS shares
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<fs cscpolicy> S<<< [B<-share> I<sharename> [B<-manual>|B<-programs>|B<-documents>|B<-disable>] ] >>>
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+The fs cscpolicy command sets the client side caching policy for a
+particular AFS share, or displays a list of policies.
+
+This command can change the policy of only one share at a time.
+
+Only one of the policy options B<-manual>, B<-programs>, B<-documents>, or
+B<-disable>, may be selected.  The default policy is B<-manual>.
+
+After changing the policy for a share, you must close all applications
+that accessed files on this share, or restart AFS Client, for the change
+to take effect.
+
+=head1 CAUTIONS
+
+This command is only available on Windows.
+
+Use of this functionality is not recommended.  Windows Offline Folders do
+not work well with AFS since the AFS server is always present.  When this
+functionality was contributed and incorporated, it was believed to be safe
+for the AFS cache manager to return BADNETPATH errors when a single file
+server or volume was inaccessible.  It is now known that returning such
+errors causes the Microsoft SMB redirector to drop the connection to the
+AFS server resulting in serious side effects.
+
+This functionality is specific to use with the Microsoft SMB redirector.
+Client Side Caching (Offline Folders) is built into that driver and will
+not be present in the native AFS redirector, so this functionality will be
+removed at a future date.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-share> I<sharename>
+
+The name of the share whose policy is to be changed.  (If omitted, no
+share policy is changed.)
+
+=item B<-manual>
+
+Specifies manual caching of documents.
+
+=item B<-programs>
+
+Specifies automatic caching of programs and documents.
+
+=item B<-documents>
+
+Specifies automatic caching of documents.
+
+=item B<-disable>
+
+Disables caching.
+
+=back
+
+=head1 OUTPUT
+
+When changing the policy of a share, the output is:
+
+   CSC policy on share "share" changed to "policy".
+   Close all applications that accessed files on this share or restart AFS Client for the change to take effect.
+
+When displaying policies, the output is:
+
+   policyname = policy
+
+=head1 EXAMPLES
+
+The following command disables all caching on the share "AFS1":
+
+   % fs cscpolicy -share AFS1 -disable
+
+The following command displays all policies currently in effect:
+
+   % fs cscpolicy
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be have AFS Client Administrator access, either to display
+or to set policies.
+
+In addition, to change policies, the issuer must be a Windows
+Administrator, since policy information is stored in a protected area of
+the Windows Registry.
+
+=head1 COPYRIGHT
+
+This document was written by Mike Robinson, and is released under the IBM
+Public License Version 1.0.  Jeffrey Altman made several corrections,
+clarifications, and additions.

doc/man-pages/pod1/fs_getfid.pod

@@ -0,0 +1,82 @@
+=head1 NAME
+
+fs_getfid - Display the fid for a given path in AFS
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<fs getfid> S<<< [B<-path>] I<path> >>> [B<-help>]
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+The fs getfid command displays the FID for a given path in AFS.  The FID
+is the internal identifier used by AFS encoding the volume name and the
+file within a volume.
+
+=head1 CAUTIONS
+
+This command is not available on Windows prior to version 1.5.60.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-path> I<path>
+
+The path of the file (or directory).
+
+=item B<-literal>
+
+Windows only: for a symlink or mount point, evaluates the specified object
+rather than the object it refers to.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The output contains the name of the file or directory, the FID, and the
+volume containing the FID.  The Windows version also outputs the object
+type instead of using "File" to describe all objects.
+
+=head1 EXAMPLES
+
+On Unix:
+
+   % fs getfid .
+   File . (536870918.1.1) contained in volume 536870918
+
+   % fs getfid /afs/example.com/foo 
+   File /afs/example.com/foo (536870918.20404.20997) contained in volume 536870918
+
+On Windows:
+
+   % fs.exe getfid \\afs\example.edu\user\b\o\bob \
+       \\afs\example.org\usr\bob\linktests\broken
+   Directory \\afs\example.edu\user\b\o\bob (537235559.1.1) contained in cell example.edu
+   fs: File '\\afs\example.org\usr\bob\linktests\broken' doesn't exist
+
+   % fs.exe getfid \\afs\example.edu\user\b\o\bob \
+       \\afs\example.org\usr\bob\linktests\broken -literal
+   Mountpoint \\afs\example.edu\user\b\o\bob (536873032.1162.16997) contained in cell example.edu
+   Symlink \\afs\example.org\usr\bob\linktests\broken (536874416.27618.488969) contained in cell example.org
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be have read access in the directory containing the path
+to be resolved.
+
+=head1 COPYRIGHT
+
+This document was written by Steven Jenkins, and is released under the IBM
+Public License Version 1.0.  Jeffrey Altman made several suggestions and
+additions.

doc/man-pages/pod1/fs_memdump.pod

@@ -0,0 +1,71 @@
+=head1 NAME
+
+fs_memdump - Dump AFS cache state and memory allocations
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<fs memdump> S<<< [B<-begin>|B<-end>] >>>
+
+=for html
+</div>
+
+=head1 DESCRIPTION
+
+This command dumps the state of AFS cache manager objects and statistics.
+If a checked build of the C run-time library is in use, memory allocations
+will also be included.
+
+=head1 CAUTIONS
+
+This command is only available on Windows.
+
+=head1 OPTIONS
+
+(One of either B<-begin> or B<-end> must be specified.)
+
+=over 4
+
+=item B<-begin>
+
+Set a memory checkpoint.
+
+=item B<-end>
+
+Create a dump-file containing information about memory allocation that has
+taken place since the B<-begin> command was issued.
+
+=back
+
+=head1 OUTPUT
+
+If successful, the output of this command (for B<-begin> I<or> B<-end>)
+will be:
+
+   AFS memdump created
+
+If unsuccessful:
+
+   AFS memdump failed
+
+=head1 EXAMPLES
+
+The following command starts a memory allocation dump:
+
+   % fs memdump -begin
+
+The following command ends it:
+
+   % fs memdump -end
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be have AFS Client Administrator access to issue this
+command.
+
+=head1 COPYRIGHT
+
+This document was written by Mike Robinson, and is released under the IBM
+Public License Version 1.0.