man-page-fs-read-not-list-20080711
[openafs.git] / doc / man-pages / pod1 / fs_listquota.pod
index 7302dc6..eaee582 100644 (file)
 =head1 NAME
 
-fs listquota - Displays quota information for the volume containing a file or
-directory.
+fs_listquota - Displays quota information for a volume
 
 =head1 SYNOPSIS
 
-B<fs listquota> [B<-path> <I<dir/file path>>+]  [-help]  
+=for html
+<div class="synopsis">
 
-B<fs listq> [B<-p> <I<dir/file path>>+]  [-h]
+B<fs listquota> S<<< [B<-path> <I<dir/file path>>+] >>> [B<-help>]
 
-B<fs lq> [B<-p> <I<dir/file path>>+]  [-h]
+B<fs listq> S<<< [B<-p> <I<dir/file path>>+] >>> [B<-h>]
+
+B<fs lq> S<<< [B<-p> <I<dir/file path>>+] >>> [B<-h>]
+
+=for html
+</div>
 
 =head1 DESCRIPTION
 
-The fs listquota command displays information about the volume
-containing each specified directory or file (its name, quota, and amount of
-disk space used), along with an indicator of the percentage of space used on
-the host partition.
+The B<fs listquota> command displays information about the volume
+containing each specified directory or file (its name, quota, and amount
+of disk space used), along with an indicator of the percentage of space
+used on the host partition.
+
+To display more information about the host partition, use the B<fs
+examine> command.
+
+To set volume quota, use the B<fs setquota> or B<fs setvol> command.
 
-To display more information about the host partition, use the fs
-examine command.
+=head1 CAUTIONS
 
-To set volume quota, use the B<fs setquota> or fs setvol
-command.
+Currently, the maximum size of a volume is 2 terabytes (2^31 bytes)
+and the maximum size of a /vicepX partition on a fileserver is also 2
+terabytes. The fileserver will not report an error when it has access
+to a partition larger than 2 terabytes, but it will probably fail if
+the administrator attempts to use more than 2 terabytes of space. In
+addition, there are reports of erroneous disk usage numbers when
+B<vos partinfo> or other OpenAFS disk reporting tools are used with
+partitions larger than 2 terabytes.
 
 =head1 OPTIONS
 
 =over 4
 
-=item -path
+=item B<-path> <I<dir/file path>>+
 
 Names a file or directory that resides in the volume about which to
-produce output. Partial pathnames are interpreted relative to the
-current working directory, which is also the default value if this argument is
+produce output. Partial pathnames are interpreted relative to the current
+working directory, which is also the default value if this argument is
 omitted.
 
-=item -help
+=item B<-help>
 
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
 
 =back
 
 =head1 OUTPUT
 
-The output displays information about the volume that houses each specified
-directory or file, in a tabular format that uses the following headers:
+The output displays information about the volume that houses each
+specified directory or file, in a tabular format that uses the following
+headers:
 
 =over 4
 
-=item C<Volume Name
->
+=item Volume Name
 
 The name of the volume.
 
-=item C<Quota
->
+=item Quota
 
-The volume's quota in kilobytes, or the string C<no limit> to
-indicate an unlimited quota.
+The volume's quota in kilobytes, or the string C<no limit> to indicate an
+unlimited quota.
 
-=item C<Used
->
+=item Used
 
 The number of kilobytes of quota used.
 
-=item C<% Used
->
+=item % Used
 
-The percentage of the volume's quota that is used (the
-C<Used> statistic divided by the C<Quota> statistic, times
-100).
+The percentage of the volume's quota that is used (the C<Used> statistic
+divided by the C<Quota> statistic, times 100).
 
-=item C<Partition
->
+=item Partition
 
 The percentage of space used on the partition that houses the
-volume. Although not directly related to how much of the user's
-quota is used, it is reported because a full partition can cause writing of
-data back to the volume to fail even when the volume has not reached its
-quota.
+volume. Although not directly related to how much of the user's quota is
+used, it is reported because a full partition can cause writing of data
+back to the volume to fail even when the volume has not reached its quota.
 
 =back
 
 =head1 EXAMPLES
 
-The following example shows the output for the volume
-B<user.smith>:
+The following example shows the output for the volume C<user.smith>:
 
    % fs listquota -path /afs/abc.com/usr/smith
-   Volume Name     Quota    Used    % Used   Partition 
-   user.smith      15000    5071       34%         86%   
+   Volume Name     Quota    Used    % Used   Partition
+   user.smith      15000    5071       34%         86%
 
 =head1 PRIVILEGE REQUIRED
 
-The issuer must have the B<l> (lookup) permission on the
-ACL of the root directory of the volume that houses the file or directory
-named by the B<-path> argument, and on the ACL of each directory that
-precedes it in the pathname.
+The issuer must have the C<r> (read) permission on the ACL of the root
+directory of the volume that houses the file or directory named by the
+B<-path> argument, and C<l> (list) permission on the ACL of each 
+directory that precedes it in the pathname.
 
 =head1 SEE ALSO