xfs_repair: update the manual content about xfs_repair exit status
diff mbox

Message ID 1484111908-12558-1-git-send-email-zlang@redhat.com
State Accepted
Headers show

Commit Message

Zorro Lang Jan. 11, 2017, 5:18 a.m. UTC
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@redhat.com>
---

Hi,

This patch has been stayed in my local xfsprogs repo for a long
time. So I'm sending it out again :)

Thanks,
Zorro

 man/man8/xfs_repair.8 | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

Comments

Eric Sandeen Jan. 11, 2017, 1:47 p.m. UTC | #1
On 1/10/17 11:18 PM, 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@redhat.com>
> ---
> 
> Hi,
> 
> This patch has been stayed in my local xfsprogs repo for a long
> time. So I'm sending it out again :)

Yep, sorry about that.  Last comment on it was that the sentence
had become a run-on sentence ...

How about:

.B xfs_repair
run without the -n option will always return a status code of 0 if it
runs without problems, regardless of whether filesystem corruption was
detected.  If an unexpected runtime error is encountered, it will return
a status code of 1, and xfs_repair should be restarted.  If a dirty
log is encountered which prevents it from continuing, it will return a
status code of 2.

(I think that the right place to document mount/unmount and/or -L is
/not/ in the status code docs - if we need that info, it should go
elsewhere.)

-eric

> Thanks,
> Zorro
> 
>  man/man8/xfs_repair.8 | 10 ++++++++--
>  1 file changed, 8 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man8/xfs_repair.8 b/man/man8/xfs_repair.8
> index 1b4d9e3..314f2c2 100644
> --- a/man/man8/xfs_repair.8
> +++ b/man/man8/xfs_repair.8
> @@ -504,12 +504,18 @@ 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)
> +(no modify mode)
>  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, filesystem
> +may be even more broken than before, so repair needs to be run again,
> +and 0 in all other cases, whether or not filesystem corruption was detected.
>  .SH BUGS
>  The filesystem to be checked and repaired must have been
>  unmounted cleanly using normal system administration procedures
> 
--
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
Darrick J. Wong Jan. 11, 2017, 5:45 p.m. UTC | #2
On Wed, Jan 11, 2017 at 07:47:41AM -0600, Eric Sandeen wrote:
> 
> 
> On 1/10/17 11:18 PM, 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@redhat.com>
> > ---
> > 
> > Hi,
> > 
> > This patch has been stayed in my local xfsprogs repo for a long
> > time. So I'm sending it out again :)
> 
> Yep, sorry about that.  Last comment on it was that the sentence
> had become a run-on sentence ...
> 
> How about:
> 
> .B xfs_repair
> run without the -n option will always return a status code of 0 if it
> runs without problems, regardless of whether filesystem corruption was
> detected.  If an unexpected runtime error is encountered, it will return
> a status code of 1, and xfs_repair should be restarted.  If a dirty
> log is encountered which prevents it from continuing, it will return a
> status code of 2.
> 
> (I think that the right place to document mount/unmount and/or -L is
> /not/ in the status code docs - if we need that info, it should go
> elsewhere.)

We sort of mumble about needing to mount and umount to clear a dirty log
in the BUGS section, but I think we should just add a section about
dirty logs and what to do with them, then link to it from the status
code section and the -L option section.

"DIRTY LOGS

"Due to the design of the XFS log, a dirty log can only be replayed on a
machine having the same CPU architecture as the machine which was
writing to the log.  xfs_repair cannot replay a dirty log and will
return a status code of 2 when it detects a dirty log.

"In this situation, the log can be replayed by mounting and immediately
unmounting the filesystem on the same class of machine that crashed.
Please make sure that the machine's hardware is reliable before
replaying to avoid compounding the problems.

"If mounting fails, the log can be erased by running xfs_repair with
the -L option.  All metadata updates in progress at the time of the
crash will be lost, which may cause significant filesystem damage.  This
should only be used as a last resort."

(If you decide to add that paragraph,
Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>)

Though I wonder why don't just fix the endianness issues with the log,
and teach xfs_repair how to replay them...

--D

> 
> -eric
> 
> > Thanks,
> > Zorro
> > 
> >  man/man8/xfs_repair.8 | 10 ++++++++--
> >  1 file changed, 8 insertions(+), 2 deletions(-)
> > 
> > diff --git a/man/man8/xfs_repair.8 b/man/man8/xfs_repair.8
> > index 1b4d9e3..314f2c2 100644
> > --- a/man/man8/xfs_repair.8
> > +++ b/man/man8/xfs_repair.8
> > @@ -504,12 +504,18 @@ 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)
> > +(no modify mode)
> >  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, filesystem
> > +may be even more broken than before, so repair needs to be run again,
> > +and 0 in all other cases, whether or not filesystem corruption was detected.
> >  .SH BUGS
> >  The filesystem to be checked and repaired must have been
> >  unmounted cleanly using normal system administration procedures
> > 
> --
> 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
Zorro Lang Jan. 12, 2017, 4:53 a.m. UTC | #3
On Wed, Jan 11, 2017 at 07:47:41AM -0600, Eric Sandeen wrote:
> 
> 
> On 1/10/17 11:18 PM, 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@redhat.com>
> > ---
> > 
> > Hi,
> > 
> > This patch has been stayed in my local xfsprogs repo for a long
> > time. So I'm sending it out again :)
> 
> Yep, sorry about that.  Last comment on it was that the sentence
> had become a run-on sentence ...
> 
> How about:
> 
> .B xfs_repair
> run without the -n option will always return a status code of 0 if it
> runs without problems, regardless of whether filesystem corruption was
> detected.  If an unexpected runtime error is encountered, it will return
> a status code of 1, and xfs_repair should be restarted.  If a dirty
> log is encountered which prevents it from continuing, it will return a

If we use "dirty log" at here, I think maybe many people don't know how to deal
with "dirty log" (even what's dirty log:)

> status code of 2.
> 
> (I think that the right place to document mount/unmount and/or -L is
> /not/ in the status code docs - if we need that info, it should go
> elsewhere.)

Hmm, that sounds make sense, maybe I can add those description about
"-L" behind the "-L" option description line.

Thanks,
Zorro

> 
> -eric
> 
> > Thanks,
> > Zorro
> > 
> >  man/man8/xfs_repair.8 | 10 ++++++++--
> >  1 file changed, 8 insertions(+), 2 deletions(-)
> > 
> > diff --git a/man/man8/xfs_repair.8 b/man/man8/xfs_repair.8
> > index 1b4d9e3..314f2c2 100644
> > --- a/man/man8/xfs_repair.8
> > +++ b/man/man8/xfs_repair.8
> > @@ -504,12 +504,18 @@ 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)
> > +(no modify mode)
> >  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, filesystem
> > +may be even more broken than before, so repair needs to be run again,
> > +and 0 in all other cases, whether or not filesystem corruption was detected.
> >  .SH BUGS
> >  The filesystem to be checked and repaired must have been
> >  unmounted cleanly using normal system administration procedures
> > 
--
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
Zorro Lang Jan. 12, 2017, 5 a.m. UTC | #4
On Wed, Jan 11, 2017 at 09:45:30AM -0800, Darrick J. Wong wrote:
> On Wed, Jan 11, 2017 at 07:47:41AM -0600, Eric Sandeen wrote:
> > 
> > 
> > On 1/10/17 11:18 PM, 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@redhat.com>
> > > ---
> > > 
> > > Hi,
> > > 
> > > This patch has been stayed in my local xfsprogs repo for a long
> > > time. So I'm sending it out again :)
> > 
> > Yep, sorry about that.  Last comment on it was that the sentence
> > had become a run-on sentence ...
> > 
> > How about:
> > 
> > .B xfs_repair
> > run without the -n option will always return a status code of 0 if it
> > runs without problems, regardless of whether filesystem corruption was
> > detected.  If an unexpected runtime error is encountered, it will return
> > a status code of 1, and xfs_repair should be restarted.  If a dirty
> > log is encountered which prevents it from continuing, it will return a
> > status code of 2.
> > 
> > (I think that the right place to document mount/unmount and/or -L is
> > /not/ in the status code docs - if we need that info, it should go
> > elsewhere.)
> 
> We sort of mumble about needing to mount and umount to clear a dirty log
> in the BUGS section, but I think we should just add a section about
> dirty logs and what to do with them, then link to it from the status
> code section and the -L option section.
> 
> "DIRTY LOGS
> 
> "Due to the design of the XFS log, a dirty log can only be replayed on a
> machine having the same CPU architecture as the machine which was
> writing to the log.  xfs_repair cannot replay a dirty log and will
> return a status code of 2 when it detects a dirty log.
> 
> "In this situation, the log can be replayed by mounting and immediately
> unmounting the filesystem on the same class of machine that crashed.
> Please make sure that the machine's hardware is reliable before
> replaying to avoid compounding the problems.
> 
> "If mounting fails, the log can be erased by running xfs_repair with
> the -L option.  All metadata updates in progress at the time of the
> crash will be lost, which may cause significant filesystem damage.  This
> should only be used as a last resort."

Ah, this's what I said on my last email. If we use 'dirty log' directly,
maybe we should explain what's dirty log and how to deal with it simply :)

I think there's no the best way to describe something in doc, so I'd
like to follow the maintainer's preference :)

Thanks,
Zorro

> 
> (If you decide to add that paragraph,
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>)
> 
> Though I wonder why don't just fix the endianness issues with the log,
> and teach xfs_repair how to replay them...
> 
> --D
> 
> > 
> > -eric
> > 
> > > Thanks,
> > > Zorro
> > > 
> > >  man/man8/xfs_repair.8 | 10 ++++++++--
> > >  1 file changed, 8 insertions(+), 2 deletions(-)
> > > 
> > > diff --git a/man/man8/xfs_repair.8 b/man/man8/xfs_repair.8
> > > index 1b4d9e3..314f2c2 100644
> > > --- a/man/man8/xfs_repair.8
> > > +++ b/man/man8/xfs_repair.8
> > > @@ -504,12 +504,18 @@ 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)
> > > +(no modify mode)
> > >  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, filesystem
> > > +may be even more broken than before, so repair needs to be run again,
> > > +and 0 in all other cases, whether or not filesystem corruption was detected.
> > >  .SH BUGS
> > >  The filesystem to be checked and repaired must have been
> > >  unmounted cleanly using normal system administration procedures
> > > 
> > --
> > 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
--
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

Patch
diff mbox

diff --git a/man/man8/xfs_repair.8 b/man/man8/xfs_repair.8
index 1b4d9e3..314f2c2 100644
--- a/man/man8/xfs_repair.8
+++ b/man/man8/xfs_repair.8
@@ -504,12 +504,18 @@  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)
+(no modify mode)
 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, filesystem
+may be even more broken than before, so repair needs to be run again,
+and 0 in all other cases, whether or not filesystem corruption was detected.
 .SH BUGS
 The filesystem to be checked and repaired must have been
 unmounted cleanly using normal system administration procedures