From stacey@vickiandstacey.com  Wed Mar 10 11:07:38 2004
Return-Path: <stacey@vickiandstacey.com>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id C59D316A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Mar 2004 11:07:38 -0800 (PST)
Received: from heisenberg.zen.co.uk (heisenberg.zen.co.uk [212.23.3.141])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 4809643D2F
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Mar 2004 11:07:38 -0800 (PST)
	(envelope-from stacey@vickiandstacey.com)
Received: from [82.68.31.180] (helo=crom.vickiandstacey.com)
	by heisenberg.zen.co.uk with esmtp (Exim 4.30)
	id 1B193J-0005RN-8n
	for FreeBSD-gnats-submit@freebsd.org; Wed, 10 Mar 2004 19:07:37 +0000
Received: from crom.vickiandstacey.com (localhost [127.0.0.1])
	by crom.vickiandstacey.com (8.12.11/8.12.11) with ESMTP id i2AJ7NAD058234
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 10 Mar 2004 19:07:33 GMT
	(envelope-from stacey@crom.vickiandstacey.com)
Received: (from stacey@localhost)
	by crom.vickiandstacey.com (8.12.11/8.12.11/Submit) id i2AJ7IVv058233;
	Wed, 10 Mar 2004 19:07:18 GMT
	(envelope-from stacey)
Message-Id: <200403101907.i2AJ7IVv058233@crom.vickiandstacey.com>
Date: Wed, 10 Mar 2004 19:07:18 GMT
From: Stacey Roberts <stacey@vickiandstacey.com>
Reply-To: Stacey Roberts <stacey@vickiandstacey.com>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Size of block in File System Quota documentation is ambiguous
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         64063
>Category:       docs
>Synopsis:       Size of block in File System Quota documentation is ambiguous
>Confidential:   no
>Severity:       serious
>Priority:       high
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Wed Mar 10 11:10:04 PST 2004
>Closed-Date:    Sun Feb 27 13:05:51 GMT 2005
>Last-Modified:  Sun Feb 27 13:05:51 GMT 2005
>Originator:     Stacey Roberts
>Release:        FreeBSD 4.9-STABLE i386
>Organization:
>Environment:
System: FreeBSD crom.vickiandstacey.com 4.9-STABLE FreeBSD 4.9-STABLE #0: Sat Mar 6 12:31:02 GMT 2004 root@crom.vickiandstacey.com:/usr/obj/usr/src/sys/SMP i386


>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.

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.

>How-To-Repeat:
N/A

>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
>Release-Note:
>Audit-Trail:

From: Peter Pentchev <roam@ringlet.net>
To: Stacey Roberts <stacey@vickiandstacey.com>
Cc: bug-followup@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@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.
State-Changed-From-To: open->feedback 
State-Changed-By: roam 
State-Changed-When: Fri Nov 5 18:54:12 GMT 2004 
State-Changed-Why:  
Awaiting feedback from the originator on the proposed patch. 

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

From: "Siebrand Mazeland" <s.mazeland@xs4all.nl>
To: <freebsd-gnats-submit@FreeBSD.org>, <stacey@vickiandstacey.com>
Cc:  
Subject: Re: docs/64063: Size of block in File System Quota documentation is ambiguous
Date: Sun, 27 Feb 2005 00:51:38 +0100

 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
 
State-Changed-From-To: feedback->closed 
State-Changed-By: roam 
State-Changed-When: Sun Feb 27 13:00:49 GMT 2005 
State-Changed-Why:  
Feedback timeout, I committed my version of the patch. 
Thanks for bringing this problem to our attention! 

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