From 72e9e595cc4251d00d42880d3d0c5a42fb7a4f69 Mon Sep 17 00:00:00 2001 From: James Youngman Date: Sat, 26 Oct 2013 14:56:17 +0100 Subject: [PATCH] Clearly explain the result of -exec/-execdir ... + * doc/find.texi (Single File): Explain that "-exec command ;" returns true of the command exited with a status of 0. (Multiple Files): Explain that "-execdir command +" always returns true. Likewise for "-exec command +". * find/find.1: similar changes. --- ChangeLog | 9 +++++++++ doc/find.texi | 32 +++++++++++++++++--------------- find/find.1 | 21 +++++++++++++++++++-- 3 files changed, 45 insertions(+), 17 deletions(-) diff --git a/ChangeLog b/ChangeLog index 70141f7d..10339bd5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2013-10-26 James Youngman + + Clearly explain the result of -exec/-execdir ... + + * doc/find.texi (Single File): Explain that "-exec command ;" + returns true of the command exited with a status of 0. + (Multiple Files): Explain that "-execdir command +" always returns + true. Likewise for "-exec command +". + * find/find.1: similar changes. + 2013-09-24 James Youngman Fix bug #40094: minor inconsistencies in xargs option descriptions. diff --git a/doc/find.texi b/doc/find.texi index f913965f..ac29aad1 100644 --- a/doc/find.texi +++ b/doc/find.texi @@ -2111,7 +2111,7 @@ perform arbitrary actions on the files. Here is how to run a command on one file at a time. @deffn Action -execdir command ; -Execute @var{command}; true if zero status is returned. @code{find} +Execute @var{command}; true if @var{command} returns zero. @code{find} takes all arguments after @samp{-execdir} to be part of the command until an argument consisting of @samp{;} is reached. It replaces the string @samp{@{@}} by the current file name being processed everywhere it @@ -2158,11 +2158,12 @@ problems surrounding @samp{-exec}. @deffn Action -exec command ; This insecure variant of the @samp{-execdir} action is specified by -POSIX. The main difference is that the command is executed in the -directory from which @code{find} was invoked, meaning that @samp{@{@}} -is expanded to a relative path starting with the name of one of the -starting directories, rather than just the basename of the matched -file. +POSIX. Like @samp{-execdir command ;} it is true if zero is +returned by @var{command}. The main difference is that the command is +executed in the directory from which @code{find} was invoked, meaning +that @samp{@{@}} is expanded to a relative path starting with the name +of one of the starting directories, rather than just the basename of +the matched file. While some implementations of @code{find} replace the @samp{@{@}} only where it appears on its own in an argument, GNU @code{find} replaces @@ -2182,14 +2183,15 @@ The @samp{-execdir} and @samp{-exec} actions have variants that build command lines containing as many matched files as possible. @deffn Action -execdir command @{@} + -This works as for @samp{-execdir command ;}, except that the -@samp{@{@}} at the end of the command is expanded to a list of names -of matching files. This expansion is done in such a way as to avoid -exceeding the maximum command line length available on the system. -Only one @samp{@{@}} is allowed within the command, and it must appear -at the end, immediately before the @samp{+}. A @samp{+} appearing in -any position other than immediately after @samp{@{@}} is not -considered to be special (that is, it does not terminate the command). +This works as for @samp{-execdir command ;}, except that the result is +always true, and the @samp{@{@}} at the end of the command is expanded +to a list of names of matching files. This expansion is done in such +a way as to avoid exceeding the maximum command line length available +on the system. Only one @samp{@{@}} is allowed within the command, +and it must appear at the end, immediately before the @samp{+}. A +@samp{+} appearing in any position other than immediately after +@samp{@{@}} is not considered to be special (that is, it does not +terminate the command). @end deffn @@ -2199,7 +2201,7 @@ POSIX. The main difference is that the command is executed in the directory from which @code{find} was invoked, meaning that @samp{@{@}} is expanded to a relative path starting with the name of one of the starting directories, rather than just the basename of the matched -file. +file. The result is always true. @end deffn Before @code{find} exits, any partially-built command lines are diff --git a/find/find.1 b/find/find.1 index b916ad01..231c1103 100644 --- a/find/find.1 +++ b/find/find.1 @@ -1018,7 +1018,9 @@ the command. The command is executed in the starting directory. If .B find encounters an error, this can sometimes cause an immediate exit, so some pending commands may not be run -at all. +at all. This variant of +.B \-exec +always returns true. .IP "\-execdir \fIcommand\fR ;" .IP "\-execdir \fIcommand\fR {} +" @@ -1051,7 +1053,22 @@ which are empty or which are not absolute directory names. If .B find encounters an error, this can sometimes cause an immediate exit, so some pending commands may not be run -at all. +at all. The result of the action depends on whether the +.B + +or the +.B ; +variant is being used; +.B \-execdir +.I command +.B {} + +always returns true, while +.B \-execdir +.I command +.B {} ; +returns true only if +.I command +returns 0. + .IP "\-fls \fIfile\fR" True; like