Documentation update for the above change.
On Sun, May 19, 2024 at 11:18 AM James Youngman <j...@gnu.org> wrote:
> This patch addresses the POSIX compliance aspect explained by Geoff
> Clare. A test is included.
>
>
>
From 9fed05088f5bfe5d7d7b5e92ae301517e84760f8 Mon Sep 17 00:00:00 2001
From: James Youngman <ja...@youngman.org>
Date: Sun, 19 May 2024 11:27:46 +0100
Subject: [PATCH 2/2] [doc] Mention the changes to xargs -P
To: findutils-patc...@gnu.org
* doc/find.texi: explain how xargs -P affects the handling of the
SIGUSR1 and SIGUSR2 signals.
* xargs/xargs.1: Likewise.
---
doc/find.texi | 19 +++++++++++++------
xargs/xargs.1 | 19 +++++++++++++++++++
2 files changed, 32 insertions(+), 6 deletions(-)
diff --git a/doc/find.texi b/doc/find.texi
index 48ecdb68..b50cb4e3 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -2745,12 +2745,19 @@ still wait for all child processes to exit (before version 4.9.0 this
might not happen).
@end table
-For example, suppose you have a directory tree of large image files
-and a @code{makeallsizes} script that takes a single file name and
-creates various sized images from it (thumbnail-sized, web-page-sized,
-printer-sized, and the original large file). The script is doing enough
-work that it takes significant time to run, even on a single image.
-You could run:
+If @code{xargs} is run without the @samp{-P} option, it will not
+change the handling of the @code{SIGUSR1} and @code{SIGUSR2} signals.
+This means they will terminate the @code{xargs} program unless those
+signals were set to be ignored in the parent process of @code{xargs}.
+If you do not want parallel execution but you also do not want these
+signals to be fatal, you can specify @code{-P 1}.
+
+Suppose you have a directory tree of large image files and a
+@code{makeallsizes} script that takes a single file name and creates
+various sized images from it (thumbnail-sized, web-page-sized,
+printer-sized, and the original large file). The script is doing
+enough work that it takes significant time to run, even on a single
+image. You could run:
@example
find originals -name '*.jpg' | xargs -L 1 makeallsizes
diff --git a/xargs/xargs.1 b/xargs/xargs.1
index df9ac11f..e6cae3d7 100644
--- a/xargs/xargs.1
+++ b/xargs/xargs.1
@@ -229,6 +229,16 @@ another.
always waits for all child processes to exit before exiting itself
(but see BUGS).
+If you do not use the
+.B \-P
+option,
+.B xargs
+will not handle the SIGUSR1 and SIGUSR2 signals, meaning that they
+will terminate the program (unless they were blocked in the parent
+process before
+.B xargs
+was started).
+
.B Please note
that it is up to the called processes to properly manage parallel
access to shared resources.
@@ -462,6 +472,15 @@ The
.B \-\-show\-limits
option can be used to discover the actual limits in force on the
current system.
+
+In versions of
+.B xargs
+up to and including version 4.9.0, SIGUSR1 and SIGUSR2 would
+not cause
+.B xargs
+to terminate even if the
+.B \-P
+option was not used.
.
.SH "HISTORY"
--
2.39.2
