[PATCH v2] xfs_repair: update the manual content about xfs_repair exit status

[Dave Chinner]

On Tue, Sep 13, 2016 at 11:57:59AM -0500, Eric Sandeen wrote:
> On 9/13/16 11:32 AM, Darrick J. Wong wrote:
> > On Tue, Sep 13, 2016 at 11:54:36PM +0800, Zorro Lang wrote:
> >> The man 8 xfs_repair said "xfs_repair run without the -n option will
> >> always return a status code of 0". That's not correct.
> >>
> >> xfs_repair will return 2 if it finds a fs log which needs to be
> >> replayed or cleared, 1 if runtime error is encountered, and 0 for
> >> all other cases.
> >>
> >> Signed-off-by: Zorro Lang <zlang at redhat.com>
> >> ---
> >>
> >> Hi,
> >>
> >> V2 patch did below things:
> >>  - change the description for xfs_repair
> >>  - remove the description for "xfs_repair -L"
> >>
> >> Thanks,
> >> Zorro
> >>
> >>  man/man8/xfs_repair.8 | 7 ++++++-
> >>  1 file changed, 6 insertions(+), 1 deletion(-)
> >>
> >> diff --git a/man/man8/xfs_repair.8 b/man/man8/xfs_repair.8
> >> index 1b4d9e3..e45fd90 100644
> >> --- a/man/man8/xfs_repair.8
> >> +++ b/man/man8/xfs_repair.8
> >> @@ -504,12 +504,17 @@ that is known to be free. The entry is therefore invalid and is deleted.
> >>  This message refers to a large directory.
> >>  If the directory were small, the message would read "junking entry ...".
> >>  .SH EXIT STATUS
> >> +.TP
> >>  .B xfs_repair \-n
> >>  (no modify node)
> >>  will return a status of 1 if filesystem corruption was detected and
> >>  0 if no filesystem corruption was detected.
> >> +.TP
> >>  .B xfs_repair
> >> -run without the \-n option will always return a status code of 0.
> >> +run without the \-n option will return a status code of 2 if it finds a
> >> +filesystem log which needs to be replayed(by a mount/umount cycle) or
> >> +cleared(by -L option), 1 if a runtime error is encountered, and 0 in all
> >> +other cases, whether or not filesystem corruption was detected.
> > 
> > So... I'd rather the documentation about the return code reflect the
> > status of the filesystem -- 2 means "unclean log, replay it or zap it",
> > 1 means "errors encountered, fs may not be correct", and 0 /should/ mean
> > "fs is correct".
> > 
> > OTOH I don't know for sure that xfs_repair always cleans up the fs on
> > the first try.
> 
> That's certainly the intent; I can't imagine a manpage documenting
> return codes qualified with "... unless bugs happen." :)

Right - if we hit bugs, all bets are off. But otherwise, the fs
should be repaired and clean after a single pass.

> >  ISTR
> > asking Dave about this, and I think he said that the FS should be clean
> > if repair returns 0.  But I'll let him reiterate that if it's true;
> > don't trust my crummy memory, that's why I have filesystems. ;)
> 
> Did you have an alternate wording in mind?

Yup, 0 = " fs is clean", 1 = "fs is still b0rken",
2 = "couldn't run for whatever reason given"

Cheers,

Dave.
-- 
Dave Chinner
david at fromorbit.com