Bug 64063

Summary:	Size of block in File System Quota documentation is ambiguous
Product:	Documentation	Reporter:	Stacey Roberts <stacey>
Component:	Books & Articles	Assignee:	freebsd-doc (Nobody) <doc>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description Stacey Roberts 2004-03-10 19:10:04 UTC

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.

When compared to man du(1) notes:
ENVIRONMENT
BLOCKSIZE If the environment variable BLOCKSIZE is set, and the -k
option is not specified, the block counts will be displayed in
units of that size block. If BLOCKSIZE is not set, and the -k
option is not specified, the block counts will be displayed in
512-byte blocks.

man ls(1):
-s Display the number of file system blocks actually used by each
file, in units of 512 bytes, where partial units are rounded up
to the next integer value. If the output is to a terminal, a
total sum for all the file sizes is output on a line before the
listing. The environment variable BLOCKSIZE overrides the unit
size of 512 bytes.

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.

Fix:

Suggesting: -
1] Addition to Chapter 12.13 of the HandBook of a statement that clearly states what the sizeof a block is (currently?) supposed to be.

2] One or two examples for illustrative purposes
How-To-Repeat: N/A

Comment 1 Peter Pentchev 2004-11-05 18:40:33 UTC

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@ringlet.net    roam@cnsys.bg    roam@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.

Comment 2 Peter Pentchev freebsd_committer

2004-11-05 18:54:12 UTC

State Changed
From-To: open->feedback

Awaiting feedback from the originator on the proposed patch.

Comment 3 Siebrand Mazeland 2005-02-26 23:51:38 UTC

I suggest time for submitter's feedback is over (waiting since Fri Nov 5
18:54:12 GMT 2004). Please commmit.

http://www.freebsd.org/cgi/query-pr.cgi?pr=docs/64063

Comment 4 Peter Pentchev freebsd_committer

2005-02-27 13:00:49 UTC

State Changed
From-To: feedback->closed

Feedback timeout, I committed my version of the patch. 
Thanks for bringing this problem to our attention!