Fix Savannah bug #26327: xargs man page is vague about the number of times command is executed. * xargs/xargs.1 (DESCRIPTION): Explain more clearly that the command will be executed many times. Indicate that -L can also be useful with -P. * NEWS: Mention this change. --- ChangeLog | 9 +++++++++ NEWS | 4 ++++ xargs/xargs.1 | 19 +++++++++++++++++++ 3 files changed, 32 insertions(+), 0 deletions(-)
diff --git a/ChangeLog b/ChangeLog index cccc2f9..22b68f2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2009-07-12 James Youngman <[email protected]> + + Fix Savannah bug #26327: xargs man page is vague about the number + of times command is executed. + * xargs/xargs.1 (DESCRIPTION): Explain more clearly that the + command will be executed many times. Indicate that -L can also be + useful with -P. + * NEWS: Mention this change. + 2009-07-11 James Youngman <[email protected]> * NEWS: Set the version to 4.5.6-git, so that we can make test diff --git a/NEWS b/NEWS index 25a17f6..b7ae0af 100644 --- a/NEWS +++ b/NEWS @@ -8,6 +8,10 @@ GNU findutils NEWS - User visible changes. -*- outline -*- (allout) #19120: Patch to fix single quotes in man page find(1) +** Documentation Changes + +#26327: xargs man page is vague about the number of times command is executed. + * Major changes in release 4.5.5, 2009-07-06 xargs now handles the case where the system's actual exec limits are diff --git a/xargs/xargs.1 b/xargs/xargs.1 index 57c37d5..84564e6 100644 --- a/xargs/xargs.1 +++ b/xargs/xargs.1 @@ -49,6 +49,23 @@ one or more times with any followed by items read from standard input. Blank lines on the standard input are ignored. .P +The command line for +.I command +is built up until it reaches a system-defined limit (unless the +.B \-n +and +.B \-L +options are used). The specified +.I command +will be invoked as many times as necessary to use up the list of input +items. In general, there will be many fewer invocations of +.I command +than there were items in the input. This will normally have +significant performance benefits. Some commands can usefully be +executed in prarallel too; see the +.B \-P +option. +.P Because Unix filenames can contain blanks and newlines, this default behaviour is often problematic; filenames containing blanks and/or newlines are incorrectly processed by @@ -299,6 +316,8 @@ is 0, will run as many processes as possible at a time. Use the .B \-n +option or the +.B \-L option with .BR \-P ; otherwise chances are that only one exec will be done. -- 1.5.6.5
