[PATCH 0/3] xfs_quota: man page fixups

[PATCH 0/3] xfs_quota: man page fixups

[Eric Sandeen]

A handful of small updates & fixes for the xfs_quota man page

[PATCH 1/3] xfs_quota: document how the default quota is stored

[Eric Sandeen]

Nowhere in the man page is the default quota described; what it
does or where it is stored.  Add some brief information about this.

Signed-off-by: Eric Sandeen <sandeen@redhat.com>
---
 man/man8/xfs_quota.8 | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
index dd0479cd..b3c4108e 100644
--- a/man/man8/xfs_quota.8
+++ b/man/man8/xfs_quota.8
@@ -178,6 +178,11 @@ to a file on
 where the user's quota has not been exceeded.
 Then after rectifying the quota situation, the file can be moved back to the
 filesystem it belongs on.
+.SS Default Quotas
+The XFS quota subsystem allows a default quota to be enforced for any user which
+does not have a quota limit explicitly set. These limits are stored in and
+displayed as the "root" user's limits, although they do not actually limit the
+root user.
 .SH USER COMMANDS
 .TP
 .B print
-- 
2.17.0

Re: [PATCH 1/3] xfs_quota: document how the default quota is stored

[Darrick J. Wong]

On Thu, Dec 03, 2020 at 02:00:01PM -0600, Eric Sandeen wrote:
> Nowhere in the man page is the default quota described; what it
> does or where it is stored.  Add some brief information about this.
> 
> Signed-off-by: Eric Sandeen <sandeen@redhat.com>
> ---
>  man/man8/xfs_quota.8 | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
> index dd0479cd..b3c4108e 100644
> --- a/man/man8/xfs_quota.8
> +++ b/man/man8/xfs_quota.8
> @@ -178,6 +178,11 @@ to a file on
>  where the user's quota has not been exceeded.
>  Then after rectifying the quota situation, the file can be moved back to the
>  filesystem it belongs on.
> +.SS Default Quotas
> +The XFS quota subsystem allows a default quota to be enforced for any user which

"user"?  Does this not apply to group or project quotas? ;)

> +does not have a quota limit explicitly set. These limits are stored in and

Usual complaint about starting sentences in column zero in manpage
source. :)

--D

> +displayed as the "root" user's limits, although they do not actually limit the
> +root user.
>  .SH USER COMMANDS
>  .TP
>  .B print
> -- 
> 2.17.0
> 
> 

Re: [PATCH 1/3] xfs_quota: document how the default quota is stored

[Eric Sandeen]

On 12/3/20 2:07 PM, Darrick J. Wong wrote:
> On Thu, Dec 03, 2020 at 02:00:01PM -0600, Eric Sandeen wrote:
>> Nowhere in the man page is the default quota described; what it
>> does or where it is stored.  Add some brief information about this.
>>
>> Signed-off-by: Eric Sandeen <sandeen@redhat.com>
>> ---
>>  man/man8/xfs_quota.8 | 5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
>> index dd0479cd..b3c4108e 100644
>> --- a/man/man8/xfs_quota.8
>> +++ b/man/man8/xfs_quota.8
>> @@ -178,6 +178,11 @@ to a file on
>>  where the user's quota has not been exceeded.
>>  Then after rectifying the quota situation, the file can be moved back to the
>>  filesystem it belongs on.
>> +.SS Default Quotas
>> +The XFS quota subsystem allows a default quota to be enforced for any user which
> 
> "user"?  Does this not apply to group or project quotas? ;)

I thought about that, but the overview section already refers to "users" as a
generic idea, i.e. "Quotas can be set for each individual user on any/all of the
local filesystems."

I mean, I guess I could s/user/ID/ to be more clear or rewrite the whole overview...

>> +does not have a quota limit explicitly set. These limits are stored in and
> 
> Usual complaint about starting sentences in column zero in manpage
> source. :)

grumble grumble random nonobvious rules grumble ok

-Eric

> --D
> 
>> +displayed as the "root" user's limits, although they do not actually limit the
>> +root user.
>>  .SH USER COMMANDS
>>  .TP
>>  .B print
>> -- 
>> 2.17.0
>>
>>
> 

Re: [PATCH 1/3] xfs_quota: document how the default quota is stored

[Darrick J. Wong]

On Thu, Dec 03, 2020 at 02:12:58PM -0600, Eric Sandeen wrote:
> On 12/3/20 2:07 PM, Darrick J. Wong wrote:
> > On Thu, Dec 03, 2020 at 02:00:01PM -0600, Eric Sandeen wrote:
> >> Nowhere in the man page is the default quota described; what it
> >> does or where it is stored.  Add some brief information about this.
> >>
> >> Signed-off-by: Eric Sandeen <sandeen@redhat.com>
> >> ---
> >>  man/man8/xfs_quota.8 | 5 +++++
> >>  1 file changed, 5 insertions(+)
> >>
> >> diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
> >> index dd0479cd..b3c4108e 100644
> >> --- a/man/man8/xfs_quota.8
> >> +++ b/man/man8/xfs_quota.8
> >> @@ -178,6 +178,11 @@ to a file on
> >>  where the user's quota has not been exceeded.
> >>  Then after rectifying the quota situation, the file can be moved back to the
> >>  filesystem it belongs on.
> >> +.SS Default Quotas
> >> +The XFS quota subsystem allows a default quota to be enforced for any user which
> > 
> > "user"?  Does this not apply to group or project quotas? ;)
> 
> I thought about that, but the overview section already refers to "users" as a
> generic idea, i.e. "Quotas can be set for each individual user on any/all of the
> local filesystems."
> 
> I mean, I guess I could s/user/ID/ to be more clear or rewrite the whole overview...

<shrug> "The XFS quota subsystem allows a default quota to be enforced
for any user, group or project which does not have a quota limit
explicitly set."

> >> +does not have a quota limit explicitly set. These limits are stored in and

"These limits are stored in and displayed as ID 0's limits."

since id==0 doesn't necessarily map to "root" unless
/etc/{passwd,group,projid} explicitly defines that.

--D

> > 
> > Usual complaint about starting sentences in column zero in manpage
> > source. :)
> 
> grumble grumble random nonobvious rules grumble ok
> 
> -Eric
> 
> > --D
> > 
> >> +displayed as the "root" user's limits, although they do not actually limit the
> >> +root user.
> >>  .SH USER COMMANDS
> >>  .TP
> >>  .B print
> >> -- 
> >> 2.17.0
> >>
> >>
> > 
> 

[PATCH 1/3 V2] xfs_quota: document how the default quota is stored

[Eric Sandeen]

Nowhere in the xfs_quota man page is the default quota described;
what it does or where it is stored.  Add some brief information
about this.

Signed-off-by: Eric Sandeen <sandeen@redhat.com>
---
 man/man8/xfs_quota.8 | 5 +++++
 1 file changed, 5 insertions(+)

V2: use "user" only in the generic sense as the rest of the overview does, and
do not refer to the "root user" specifically, rather to the root/#0 ID.

(project lists "#0" and user/group lists "root")

diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
index dd0479cd..be04fb30 100644
--- a/man/man8/xfs_quota.8
+++ b/man/man8/xfs_quota.8
@@ -178,6 +178,11 @@ to a file on
 where the user's quota has not been exceeded.
 Then after rectifying the quota situation, the file can be moved back to the
 filesystem it belongs on.
+.SS Default Quotas
+The XFS quota subsystem allows a default quota to be enforced for any user which
+does not have a quota limit explicitly set.
+These limits are stored in and displayed as the root / ID #0 limits, although
+they do not actually limit the root user.
 .SH USER COMMANDS
 .TP
 .B print

[PATCH 1/3 V3] xfs_quota: document how the default quota is stored

[Eric Sandeen]

Nowhere in the man page is the default quota described; what it
does or where it is stored.  Add some brief information about this.

Signed-off-by: Eric Sandeen <sandeen@redhat.com>
---

V3: stop trying, and just use Darrick's nice words.

diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
index dd0479cd..2a911969 100644
--- a/man/man8/xfs_quota.8
+++ b/man/man8/xfs_quota.8
@@ -178,6 +178,12 @@ to a file on
 where the user's quota has not been exceeded.
 Then after rectifying the quota situation, the file can be moved back to the
 filesystem it belongs on.
+.SS Default Quotas
+The XFS quota subsystem allows a default quota to be enforced
+for any user, group or project which does not have a quota limit
+explicitly set.
+These limits are stored in and displayed as ID 0's limits, although they
+do not actually limit ID 0.
 .SH USER COMMANDS
 .TP
 .B print

Re: [PATCH 1/3 V3] xfs_quota: document how the default quota is stored

[Darrick J. Wong]

On Thu, Dec 03, 2020 at 02:46:10PM -0600, Eric Sandeen wrote:
> Nowhere in the man page is the default quota described; what it
> does or where it is stored.  Add some brief information about this.
> 
> Signed-off-by: Eric Sandeen <sandeen@redhat.com>

Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>

--D

> ---
> 
> V3: stop trying, and just use Darrick's nice words.
> 
> diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
> index dd0479cd..2a911969 100644
> --- a/man/man8/xfs_quota.8
> +++ b/man/man8/xfs_quota.8
> @@ -178,6 +178,12 @@ to a file on
>  where the user's quota has not been exceeded.
>  Then after rectifying the quota situation, the file can be moved back to the
>  filesystem it belongs on.
> +.SS Default Quotas
> +The XFS quota subsystem allows a default quota to be enforced
> +for any user, group or project which does not have a quota limit
> +explicitly set.
> +These limits are stored in and displayed as ID 0's limits, although they
> +do not actually limit ID 0.
>  .SH USER COMMANDS
>  .TP
>  .B print
> 
> 

[PATCH 2/3] xfs_quota: Remove delalloc caveat from man page

[Eric Sandeen]

Ever since
89605011915a ("xfs: include reservations in quota reporting")
xfs quota has been in sync with delayed allocations, so this caveat
is no longer relevant or correct; remove it.

Signed-off-by: Eric Sandeen <sandeen@redhat.com>
---
 man/man8/xfs_quota.8 | 11 +----------
 1 file changed, 1 insertion(+), 10 deletions(-)

diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
index b3c4108e..bfdc2e4f 100644
--- a/man/man8/xfs_quota.8
+++ b/man/man8/xfs_quota.8
@@ -725,17 +725,8 @@ Same as above without a need for configuration files.
 .in -5
 .fi
 .SH CAVEATS
-XFS implements delayed allocation (aka. allocate-on-flush) and this
-has implications for the quota subsystem.
-Since quota accounting can only be done when blocks are actually
-allocated, it is possible to issue (buffered) writes into a file
-and not see the usage immediately updated.
-Only when the data is actually written out, either via one of the
-kernels flushing mechanisms, or via a manual
-.BR sync (2),
-will the usage reported reflect what has actually been written.
 .PP
-In addition, the XFS allocation mechanism will always reserve the
+The XFS allocation mechanism will always reserve the
 maximum amount of space required before proceeding with an allocation.
 If insufficient space for this reservation is available, due to the
 block quota limit being reached for example, this may result in the
-- 
2.17.0

Re: [PATCH 2/3] xfs_quota: Remove delalloc caveat from man page

[Darrick J. Wong]

On Thu, Dec 03, 2020 at 02:00:42PM -0600, Eric Sandeen wrote:
> Ever since
> 89605011915a ("xfs: include reservations in quota reporting")
> xfs quota has been in sync with delayed allocations, so this caveat
> is no longer relevant or correct; remove it.
> 
> Signed-off-by: Eric Sandeen <sandeen@redhat.com>

Looks good,
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>

--D

> ---
>  man/man8/xfs_quota.8 | 11 +----------
>  1 file changed, 1 insertion(+), 10 deletions(-)
> 
> diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
> index b3c4108e..bfdc2e4f 100644
> --- a/man/man8/xfs_quota.8
> +++ b/man/man8/xfs_quota.8
> @@ -725,17 +725,8 @@ Same as above without a need for configuration files.
>  .in -5
>  .fi
>  .SH CAVEATS
> -XFS implements delayed allocation (aka. allocate-on-flush) and this
> -has implications for the quota subsystem.
> -Since quota accounting can only be done when blocks are actually
> -allocated, it is possible to issue (buffered) writes into a file
> -and not see the usage immediately updated.
> -Only when the data is actually written out, either via one of the
> -kernels flushing mechanisms, or via a manual
> -.BR sync (2),
> -will the usage reported reflect what has actually been written.
>  .PP
> -In addition, the XFS allocation mechanism will always reserve the
> +The XFS allocation mechanism will always reserve the
>  maximum amount of space required before proceeding with an allocation.
>  If insufficient space for this reservation is available, due to the
>  block quota limit being reached for example, this may result in the
> -- 
> 2.17.0
> 
> 

[PATCH 3/3] xfs_quota: make manpage non-male-specific

[Eric Sandeen]

Users are not exclusively male, so fix that implication.

Signed-off-by: Eric Sandeen <sandeen@redhat.com>
---
 man/man8/xfs_quota.8 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
index bfdc2e4f..beb6da13 100644
--- a/man/man8/xfs_quota.8
+++ b/man/man8/xfs_quota.8
@@ -128,7 +128,7 @@ To most users, disk quotas are either of no concern or a fact of life
 that cannot be avoided.
 There are two possible quotas that can be imposed \- a limit can be set
 on the amount of space a user can occupy, and there may be a limit on
-the number of files (inodes) he can own.
+the number of files (inodes) they can own.
 .PP
 The
 .B quota
@@ -167,10 +167,10 @@ the file, not only are the recent changes lost, but possibly much, or even
 all, of the contents that previously existed.
 .br
 There are several possible safe exits for a user caught in this situation.
-He can use the editor shell escape command to examine his file space
+They can use the editor shell escape command to examine his file space
 and remove surplus files.  Alternatively, using
 .BR sh (1),
-he can suspend
+they can suspend
 the editor, remove some files, then resume it.
 A third possibility is to write the file to some other filesystem (perhaps
 to a file on
-- 
2.17.0

Re: [PATCH 3/3] xfs_quota: make manpage non-male-specific

[Darrick J. Wong]

On Thu, Dec 03, 2020 at 02:01:24PM -0600, Eric Sandeen wrote:
> Users are not exclusively male, so fix that implication.

Why not fix configure.ac too?  Surely ./configure users are not also
exclusively male? ;)

"If the user choses a different prefix assume he just wants..."

--D

> Signed-off-by: Eric Sandeen <sandeen@redhat.com>
> ---
>  man/man8/xfs_quota.8 | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
> index bfdc2e4f..beb6da13 100644
> --- a/man/man8/xfs_quota.8
> +++ b/man/man8/xfs_quota.8
> @@ -128,7 +128,7 @@ To most users, disk quotas are either of no concern or a fact of life
>  that cannot be avoided.
>  There are two possible quotas that can be imposed \- a limit can be set
>  on the amount of space a user can occupy, and there may be a limit on
> -the number of files (inodes) he can own.
> +the number of files (inodes) they can own.
>  .PP
>  The
>  .B quota
> @@ -167,10 +167,10 @@ the file, not only are the recent changes lost, but possibly much, or even
>  all, of the contents that previously existed.
>  .br
>  There are several possible safe exits for a user caught in this situation.
> -He can use the editor shell escape command to examine his file space
> +They can use the editor shell escape command to examine his file space
>  and remove surplus files.  Alternatively, using
>  .BR sh (1),
> -he can suspend
> +they can suspend
>  the editor, remove some files, then resume it.
>  A third possibility is to write the file to some other filesystem (perhaps
>  to a file on
> -- 
> 2.17.0
> 

Re: [PATCH 3/3] xfs_quota: make manpage non-male-specific

[Eric Sandeen]

On 12/3/20 2:10 PM, Darrick J. Wong wrote:
> On Thu, Dec 03, 2020 at 02:01:24PM -0600, Eric Sandeen wrote:
>> Users are not exclusively male, so fix that implication.
> 
> Why not fix configure.ac too?  Surely ./configure users are not also
> exclusively male? ;)
> 
> "If the user choses a different prefix assume he just wants..."

hm ok, I only searched man pages.

xfsprogs: don't be male-specific? :)

-Eric

[PATCH 3/3 V2] xfsprogs: make things non-gender-specific

[Eric Sandeen]

Users are not exclusively male, so fix that implication
in the xfs_quota manpage and the configure.ac comments.

Signed-off-by: Eric Sandeen <sandeen@redhat.com>
---

V2: Fix configure.ac comments too, and fix a missed "him" in the manpage
    also "choses" is not a word :)

diff --git a/configure.ac b/configure.ac
index 645e4572..48f3566d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -113,7 +113,7 @@ esac
 # Some important tools should be installed into the root partitions.
 #
 # Check whether exec_prefix=/usr: and install them to /sbin in that
-# case.  If the user choses a different prefix assume he just wants
+# case.  If the user chooses a different prefix assume they just want
 # a local install for testing and not a system install.
 #
 case $exec_prefix:$prefix in
diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
index 74c24916..cfb87621 100644
--- a/man/man8/xfs_quota.8
+++ b/man/man8/xfs_quota.8
@@ -128,7 +128,7 @@ To most users, disk quotas are either of no concern or a fact of life
 that cannot be avoided.
 There are two possible quotas that can be imposed \- a limit can be set
 on the amount of space a user can occupy, and there may be a limit on
-the number of files (inodes) he can own.
+the number of files (inodes) they can own.
 .PP
 The
 .B quota
@@ -167,10 +167,10 @@ the file, not only are the recent changes lost, but possibly much, or even
 all, of the contents that previously existed.
 .br
 There are several possible safe exits for a user caught in this situation.
-He can use the editor shell escape command to examine his file space
+They can use the editor shell escape command to examine their file space
 and remove surplus files.  Alternatively, using
 .BR sh (1),
-he can suspend
+they can suspend
 the editor, remove some files, then resume it.
 A third possibility is to write the file to some other filesystem (perhaps
 to a file on

Re: [PATCH 3/3 V2] xfsprogs: make things non-gender-specific

[Darrick J. Wong]

On Thu, Dec 03, 2020 at 02:33:26PM -0600, Eric Sandeen wrote:
> Users are not exclusively male, so fix that implication
> in the xfs_quota manpage and the configure.ac comments.
> 
> Signed-off-by: Eric Sandeen <sandeen@redhat.com>

Looks good now,
Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>

--D

> ---
> 
> V2: Fix configure.ac comments too, and fix a missed "him" in the manpage
>     also "choses" is not a word :)
> 
> diff --git a/configure.ac b/configure.ac
> index 645e4572..48f3566d 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -113,7 +113,7 @@ esac
>  # Some important tools should be installed into the root partitions.
>  #
>  # Check whether exec_prefix=/usr: and install them to /sbin in that
> -# case.  If the user choses a different prefix assume he just wants
> +# case.  If the user chooses a different prefix assume they just want
>  # a local install for testing and not a system install.
>  #
>  case $exec_prefix:$prefix in
> diff --git a/man/man8/xfs_quota.8 b/man/man8/xfs_quota.8
> index 74c24916..cfb87621 100644
> --- a/man/man8/xfs_quota.8
> +++ b/man/man8/xfs_quota.8
> @@ -128,7 +128,7 @@ To most users, disk quotas are either of no concern or a fact of life
>  that cannot be avoided.
>  There are two possible quotas that can be imposed \- a limit can be set
>  on the amount of space a user can occupy, and there may be a limit on
> -the number of files (inodes) he can own.
> +the number of files (inodes) they can own.
>  .PP
>  The
>  .B quota
> @@ -167,10 +167,10 @@ the file, not only are the recent changes lost, but possibly much, or even
>  all, of the contents that previously existed.
>  .br
>  There are several possible safe exits for a user caught in this situation.
> -He can use the editor shell escape command to examine his file space
> +They can use the editor shell escape command to examine their file space
>  and remove surplus files.  Alternatively, using
>  .BR sh (1),
> -he can suspend
> +they can suspend
>  the editor, remove some files, then resume it.
>  A third possibility is to write the file to some other filesystem (perhaps
>  to a file on
>