docs/64063: Size of block in File System Quota documentation is ambiguous

[Peter Pentchev]

The following reply was made to PR docs/64063; it has been noted by GNATS.

From: Peter Pentchev <roam at ringlet.net>
To: Stacey Roberts <stacey at vickiandstacey.com>
Cc: bug-followup at FreeBSD.org
Subject: Re: docs/64063: Size of block in File System Quota documentation is ambiguous
Date: Fri, 5 Nov 2004 20:40:33 +0200

 On Wed, Mar 10, 2004 at 07:07:18PM +0000, Stacey Roberts wrote:
 > 
 > >Number:         64063
 > >Category:       docs
 > >Synopsis:       Size of block in File System Quota documentation is ambiguous
 [snip]
 > 
 > >Description:
 > In attempting to follow the online HandBook on setting up per-user
 > File System Quotas as described at
 > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/quotas.html,
 > it is not clear what the size of a block is, as used by the FreeBSD
 > Quota system.
 [snip]
 > it is not clear *what* the size of a block is supposed to be. Together
 > with the PR submitted here:
 > http://www.freebsd.org/cgi/query-pr.cgi?pr=41936, this issue is
 > further complicated by the lack of a clear, unambiguous statement in
 > Chapter 12.13 in the HandBook.
 
 Well, PR 41936 was committed, so edquota(8) uses 'kbytes' instead of
 'blocks' now, and in a separate commit to quota(8), it reports 'usage'
 and not 'blocks', too.  What do you think about the following patch to
 the Handbook, making it reflect the current state of affairs?
 
 Index: disks/chapter.sgml
 ===================================================================
 RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/disks/chapter.sgml,v
 retrieving revision 1.223
 diff -u -r1.223 chapter.sgml
 --- disks/chapter.sgml	1 Nov 2004 18:56:50 -0000	1.223
 +++ disks/chapter.sgml	5 Nov 2004 18:33:16 -0000
 @@ -3339,9 +3339,9 @@
        <para>A hard limit may not be exceeded.  Once a user reaches his
  	hard limit he may not make any further allocations on the file
  	system in question.  For example, if the user has a hard limit of
 -	500 blocks on a file system and is currently using 490 blocks, the
 -	user can only allocate an additional 10 blocks.  Attempting to
 -	allocate an additional 11 blocks will fail.</para>
 +	500 kbytes on a file system and is currently using 490 kbytes, the
 +	user can only allocate an additional 10 kbytes.  Attempting to
 +	allocate an additional 11 kbytes will fail.</para>
  
        <indexterm><primary>soft limit</primary></indexterm>
        <para>Soft limits, on the other hand, can be exceeded for a limited
 @@ -3363,9 +3363,9 @@
        <screen>&prompt.root; <userinput>edquota -u test</userinput></screen>
  
        <programlisting>Quotas for user test:
 -/usr: blocks in use: 65, limits (soft = 50, hard = 75)
 +/usr: kbytes in use: 65, limits (soft = 50, hard = 75)
          inodes in use: 7, limits (soft = 50, hard = 60)
 -/usr/var: blocks in use: 0, limits (soft = 50, hard = 75)
 +/usr/var: kbytes in use: 0, limits (soft = 50, hard = 75)
          inodes in use: 0, limits (soft = 50, hard = 60)</programlisting>
  
        <para>You will normally see two lines for each file system that has
 @@ -3375,11 +3375,11 @@
  	from a soft limit of 50 and a hard limit of 75 to a soft limit of
  	500 and a hard limit of 600, change:</para>
  
 -      <programlisting>/usr: blocks in use: 65, limits (soft = 50, hard = 75)</programlisting>
 +      <programlisting>/usr: kbytes in use: 65, limits (soft = 50, hard = 75)</programlisting>
  
        <para>to:</para>
  
 -      <programlisting> /usr: blocks in use: 65, limits (soft = 500, hard = 600)</programlisting>
 +      <programlisting> /usr: kbytes in use: 65, limits (soft = 500, hard = 600)</programlisting>
  
        <para>The new quota limits will be in place when you exit the
  	editor.</para>
 @@ -3421,14 +3421,14 @@
  	limits on two file systems.</para>
  
        <programlisting>Disk quotas for user test (uid 1002):
 -     Filesystem  blocks   quota   limit   grace   files   quota   limit   grace
 +     Filesystem  usage    quota   limit   grace   files   quota   limit   grace
             /usr      65*     50      75   5days       7      50      60
         /usr/var       0      50      75               0      50      60</programlisting>
  
        <indexterm><primary>grace period</primary></indexterm>
        <para>On the <filename>/usr</filename> file system in the above
 -	example, this user is currently 15 blocks over the soft limit of
 -	50 blocks and has 5 days of the grace period left.  Note the
 +	example, this user is currently 15 kbytes over the soft limit of
 +	50 kbytes and has 5 days of the grace period left.  Note the
  	asterisk <literal>*</literal> which indicates that the user is
  	currently over his quota limit.</para>
  
 
 G'luck,
 Peter
 
 -- 
 Peter Pentchev	roam at ringlet.net    roam at cnsys.bg    roam at FreeBSD.org
 PGP key:	http://people.FreeBSD.org/~roam/roam.key.asc
 Key fingerprint	FDBA FD79 C26F 3C51 C95E  DF9E ED18 B68D 1619 4553
 because I didn't think of a good beginning of it.