All of lore.kernel.org
 help / color / mirror / Atom feed
From: "Darrick J. Wong" <darrick.wong@oracle.com>
To: Eric Sandeen <sandeen@sandeen.net>
Cc: sandeen@redhat.com, linux-xfs@vger.kernel.org
Subject: Re: [PATCH 09/10] xfs_spaceman: add a man page
Date: Wed, 14 Jun 2017 13:49:27 -0700	[thread overview]
Message-ID: <20170614204927.GX4530@birch.djwong.org> (raw)
In-Reply-To: <996ddf19-1bf9-44c8-f41d-93ac45c354e3@sandeen.net>

On Wed, Jun 14, 2017 at 11:06:44AM -0500, Eric Sandeen wrote:
> On 6/2/17 2:52 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Add a manual page describing xfs_spaceman's behavior.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man8/xfs_spaceman.8 |  102 +++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 102 insertions(+)
> >  create mode 100644 man/man8/xfs_spaceman.8
> > 
> > 
> > diff --git a/man/man8/xfs_spaceman.8 b/man/man8/xfs_spaceman.8
> > new file mode 100644
> > index 0000000..c1d19c0
> > --- /dev/null
> > +++ b/man/man8/xfs_spaceman.8
> > @@ -0,0 +1,102 @@
> > +.TH xfs_spaceman 8
> > +.SH NAME
> > +xfs_spaceman \- show free space information about an XFS filesystem
> > +.SH SYNOPSIS
> > +.B xfs_spaceman
> > +[
> > +.B \-c
> > +.I cmd
> > +]
> > +.I file
> > +.br
> > +.B xfs_spaceman \-V
> > +.SH DESCRIPTION
> > +.B xfs_spaceman
> > +reports and controls free space usage in an XFS filesystem.
> > +.SH OPTIONS
> > +.TP 1.0i
> > +.BI \-c " cmd"
> > +.B xfs_spaceman
> > +commands may be run interactively (the default) or as arguments on
> > +the command line. Multiple
> > +.B \-c
> > +arguments may be given. The commands are run in the sequence given,
> > +then the program exits.
> > +
> > +.SH COMMANDS
> > +.TP
> > +.BI "freesp [ \-sr ] [ \-b | \-e bsize | \-h h1 [ \-m bmult ]] [-a agno]"
> 
> Hmm this differs from program help:
> 
> freesp [-bdgsr] [-a agno] [-e bsize] [-h h1]... [-m bmult] 
> 
> are -b, -e, and -h mutually exclusive or not?
> 
> xfs_spaceman> freesp -b
>    from      to extents  blocks    pct
>       2       3       1       3   0.00
>   32768   65536       4  259537 100.00
> xfs_spaceman> freesp -e 4096
>    from      to extents  blocks    pct
>       1    4096       1       3   0.00
>   61441   65536       4  259537 100.00
> xfs_spaceman> freesp -e 4096 -b
> xfs_spaceman> 
> 
> Also, where are -g and -d ?

-g is in the next patch.

-d needs to be added.
> 
> 
> [-a agno]...
> 
> (multiple allowed)

Oh heck this manpage is so hard to read I'm going to reflow the whole
section to be easier on the eyes:

freesp [ -drs ] [-a agno] [ -b | -e bsize | -h bsize | -m factor ]
      With  no  arguments,  freesp shows a histogram of all free space
      extents in the filesystem.   The  command  takes  the  following
      options:

	 -a agno
	     Collect  free  space  information  from  this  allocation
	     group.  This option can be specified  multiple  times  to
	     collect from multiple groups.

	 -b  This  argument  establishes  that the histogram bin sizes
	     are successive powers of two.  This is the  default,  and
	     is mutually exclusive with the -e, -h, and -m options.

	 -d  Print  debugging  information  such as the raw free space
	     extent information.

	 -e bsize
	     Set all histogram bin sizes to a  specific  value.   This
	     option  is  mutually  exclusive  with  the -b, -h, and -m
	     options.

	 -h bsize
	     Create a histogram bin with a lower bound of this  value.
	     The  upper  bound  of  this bin will be one less than the
	     lower bound of the  next  highest  histogram  bin.   This
	     option  can  be given multiple times to control the exact
	     bin sizes.  This option is mutually  exclusive  with  the
	     -b, -e, and -m options.

	 -m factor
	     Create  each  histogram bin with a size that is this many
	     times the size of the prvious bin created.   This  option
	     is mutually exclusive with the -b, -e, and -h options.

	 -r  Query the realtime device for free space information.

	 -s  Display a summary of the free space information found.


> > +With no arguments,
> > +.B freesp
> > +shows a histogram of all free space extents in the filesystem.
> > +The
> > +.B -b
> > +argument establishes that the histogram bins are successive powers of two.
> > +This is the default.
> > +The
> > +.BR -h " and " -m
> > +options can be used to specify a custom histogram bin size as well as a
> > +multiplication factor for subsequent bin sizes.
> > +The
> > +.BR -e
> > +option fixes the histogram size to a particular value.
> > +The
> > +.BR -a " and " -r
> > +options constrain the free space information report to a particular AG
> > +or the realtime device, respectively.  The
> > +.B -a
> > +option may be specified multiple times.
> > +A summary of free space information will be printed if the
> > +.B -s
> > +option is given.
> > +.TP
> > +.BR "help [ " command " ]"
> > +Display a brief description of one or all commands.
> > +.TP
> > +.BI "prealloc [ \-ugp id ] [ \-m minlen ] [ \-s ]"
> > +Controls speculative preallocation.  The
> > +.BR -u ","
> > +.BR -g ","
> > +and
> > +.B -p
> > +options will clear all speculative preallocations for a given user,
> > +group, or project ID, respectively.
> > +The
> > +.B -m
> > +option causes the operation to ignore any file with a size smaller than
> > +.BR minlen "."
> > +The
> > +.B -s
> > +option will flush all dirty data and metadata to disk.
> > +.TP
> > +.B print
> > +Display a list of all open files.
> > +.TP
> > +.B quit
> > +Exit
> > +.BR xfs_spaceman .
> > +.TP
> > +.BI "trim [ \-f ] [ \-a agno ] [ \-m minlen ] [" " offset length " ]
> 
> Hm, this looks like -f / -a / offset/length are all optional, and not
> mutually exclusive.
> 
> If this were in a SYNOPSIS section, it'd require 3 synopses I think.
> 
> Perhaps here it should be:
> 
> trim -f [ -m minlen ] [ offset length ]
> trim -a agno [ -m minlen ] [ offset length ]
> trim offset length [ -m minlen ]
> 
> as 3 separate invocation methods?

Only problem is that if we add general options in the future we'll have
to add them to all three invocations.

trim ( -a agno | -f | offset length ) [ -m minlen ]

How about that instead?

> 
> > +Instructs the underlying storage device to release all storage that may
> > +be backing free space in the filesystem.
> > +The
> > +.B -f
> > +option trims all free space in the entire filesystem.
> > +The
> > +.B -a
> > +option trims only the free space in a given AG.
> > +The
> > +.B -m
> > +option only trims free space extents that are longer than
> > +.IR minlen "."
> 
> units?  (suffixes?)

I'll add that.

> > +The
> > +.IR offset " and " length
> > +arguments trim all free space between
> > +.I offset
> > +and
> > +.IR "offset+length" "."
> 
> Units?

and that.

--D

> 
> > +The
> > +.BR -a " and " -f
> > +options are mutually exclusive with each other as well as with the
> > +.IR offset " and " length
> > +arguments.
> > 
> > --
> > To unsubscribe from this list: send the line "unsubscribe linux-xfs" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> > 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-xfs" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

  reply	other threads:[~2017-06-14 20:49 UTC|newest]

Thread overview: 29+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-06-02 19:51 [PATCH v8 00/10] xfsprogs 4.12: GETFSMAP support Darrick J. Wong
2017-06-02 19:51 ` [PATCH 01/10] xfs: introduce the XFS_IOC_GETFSMAP ioctl Darrick J. Wong
2017-06-02 19:51 ` [PATCH 02/10] xfs_io: refactor numlen into a library function Darrick J. Wong
2017-06-13 21:09   ` Eric Sandeen
2017-06-02 19:51 ` [PATCH 03/10] xfs_io: support the new getfsmap ioctl Darrick J. Wong
2017-06-13 22:20   ` Eric Sandeen
2017-06-14  0:23     ` Darrick J. Wong
2017-06-02 19:51 ` [PATCH 04/10] xfs_repair: replace rmap_compare with libxfs version Darrick J. Wong
2017-06-13 22:34   ` Eric Sandeen
2017-06-02 19:51 ` [PATCH 05/10] xfs_spaceman: space management tool Darrick J. Wong
2017-06-14 14:15   ` Eric Sandeen
2017-06-14 16:16     ` Darrick J. Wong
2017-06-02 19:51 ` [PATCH 06/10] xfs_spaceman: add FITRIM support Darrick J. Wong
2017-06-14 15:32   ` Eric Sandeen
2017-06-14 16:32     ` Darrick J. Wong
2017-06-02 19:51 ` [PATCH 07/10] xfs_spaceman: add new speculative prealloc control Darrick J. Wong
2017-06-14 15:05   ` Eric Sandeen
2017-06-14 16:39     ` Darrick J. Wong
2017-06-02 19:52 ` [PATCH 08/10] xfs_spaceman: Free space mapping command Darrick J. Wong
2017-06-14 15:43   ` Eric Sandeen
2017-06-14 16:43     ` Darrick J. Wong
2017-06-14 16:04   ` Eric Sandeen
2017-06-14 16:57     ` Darrick J. Wong
2017-06-02 19:52 ` [PATCH 09/10] xfs_spaceman: add a man page Darrick J. Wong
2017-06-14 16:06   ` Eric Sandeen
2017-06-14 20:49     ` Darrick J. Wong [this message]
2017-06-02 19:52 ` [PATCH 10/10] xfs_spaceman: add group summary mode Darrick J. Wong
2017-06-14 16:23   ` Eric Sandeen
2017-06-14 17:22     ` Darrick J. Wong

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170614204927.GX4530@birch.djwong.org \
    --to=darrick.wong@oracle.com \
    --cc=linux-xfs@vger.kernel.org \
    --cc=sandeen@redhat.com \
    --cc=sandeen@sandeen.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.