2015-12-18 James Youngman <jay@gnu.org>

	* doc/find.texi (Run Commands): Add a new subsection and menu
	item, Child Exit Status.
	(Child Exit Status): New subsection, describing how the exit
	status of find is affected (or not) by the exit status of the
	commands run by  -exec and similar actions.
	* find/find.1 (-exec): Explain how the exit status of the child
	affects (or not) the exit status of find.
	(-execdir): Likewise.
	(EXIT STATUS): Likewise.
	* NEWS: mention these changes.

3 files changed, 80 insertions, 3 deletions

diff --git a/NEWS b/NEWS
index a8b883b0..74c445a7 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,13 @@ GNU findutils NEWS - User visible changes.      -*- outline -*- (allout)
 
 * Major changes in release 4.5.16-git, 2015-12-DD
 
+** Documentation Changes
+
+The man page and Texinfo documentation how have clearer descriptions
+of how find's own exit status is affected when a command run by -exec
+exits with a non-zero status.  Likewise for the other actions similar
+to -exec.
+
 * Major changes in release 4.5.15, 2015-12-18
 
 ** Bug Fixes
diff --git a/doc/find.texi b/doc/find.texi
index a83a645d..bd1d6a16 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -2113,6 +2113,7 @@ perform arbitrary actions on the files.
 * Single File::
 * Multiple Files::
 * Querying::
+* Child Exit Status::
 @end menu
 
 @node Single File
@@ -2764,6 +2765,44 @@ from the terminal.  Only run the command line if the response starts
 with @samp{y} or @samp{Y}.  Implies @samp{-t}.
 @end table
 
+
+@node Child Exit Status
+@subsection Child Exit Status
+
+The handling of the exit status of commands run by @code{find} depends
+on which action was used to launch the command.  Single-argument
+actions carry the exit status of the child forward as the result of
+the action itself.  Multiple-argument actions always return true, but
+if the launched command exits with a non-zero status, the exit status
+of @code{find} itself will be non-zero.
+
+The effect of a non-zero command exit status is as follows:
+
+@table @samp
+@item -exec ... ;
+The action returns false; the exit status of @code{find} is unaffected.
+@item -execdir ... ;
+The action returns false; the exit status of @code{find} is unaffected.
+@item -ok ... ;
+The action returns false; the exit status of @code{find} is unaffected.
+@item -okdir ... ;
+The action returns false; the exit status of @code{find} is unaffected.
+@item -exec ... +
+The action returns true; the exit status of @code{find} will be non-zero.
+@item -execdir ... +
+The action returns true; the exit status of @code{find} will be non-zero.
+@item -ok ... +
+The action returns true; the exit status of @code{find} will be non-zero.
+@item -okdir ... +
+The action returns true; the exit status of @code{find} will be non-zero.
+@end table
+
+If a command cannot be launched at all and the failure occurs in the
+parent process (i.e. the running @code{find} program) it will exit
+with a non-zero status.  If the failure occurs in the child process,
+it is unspecified whether or not this is distinguished from a failure
+of the command itself.
+
 @node Delete Files
 @section Delete Files
 
diff --git a/find/find.1 b/find/find.1
index cc3f9d46..a42dfe0f 100644
--- a/find/find.1
+++ b/find/find.1
@@ -975,7 +975,10 @@ and
 together.
 
 .IP "\-exec \fIcommand\fR ;"
-Execute \fIcommand\fR; true if 0 status is returned.  All following
+Execute \fIcommand\fR; true if 0 status is returned.  The exit status
+of
+.B find
+itself is not affected.  All following
 arguments to
 .B find
 are taken to be arguments to the command until an argument consisting
@@ -1015,7 +1018,12 @@ encounters an error, this can sometimes cause an
 immediate exit, so some pending commands may not be run
 at all.  This variant of
 .B \-exec
-always returns true.
+always returns true.  When the invoked command exits
+with a non-zero status, the exit status of
+.B find
+itself is non-zero, but the
+.B \-exec
+action itself will still have evaluated as true.
 
 .IP "\-execdir \fIcommand\fR ;"
 .IP "\-execdir \fIcommand\fR {} +"
@@ -1062,7 +1070,10 @@ always returns true, while
 .B {} ;
 returns true only if
 .I command
-returns 0.
+returns 0.  The exit status of
+.B find
+itself is affected or not according to the rule for
+.BR \-exec .
 
 
 .IP "\-fls \fIfile\fR"
@@ -2051,6 +2062,26 @@ or
 .B \-execdir ... {} +
 may not have been performed.
 
+If a command run by
+.B \-exec ... {} +
+or
+.B \-execdir ... {} +
+or
+.B \-ok ... {} +
+or
+.B \-okdir ... {} +
+exits with a non-zero status, the exit status of
+.B find
+will also be non-zero (though it is not guaranteed to be the same
+value).  The equivalent actions when terminated by
+.B ;
+instead of
+.B +
+do not affect the exit status, except in some cases of failure to
+invoke the command itself (for example, failure of the
+.BR fork (2)
+system call).
+
 
 .SH "SEE ALSO"
 \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1), \fBxargs\fP(1),