From 523ee45c64e1c8c66d02ecc5fcece19911c3a4eb Mon Sep 17 00:00:00 2001
From: jay <jay>
Date: Sat, 21 Jun 2003 09:04:56 +0000
Subject: [PATCH] Document the fact that xargs exits immediately with an error
 message if the command it executes exits with a status of 255.

---
 xargs/xargs.1 | 53 ++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 42 insertions(+), 11 deletions(-)

diff --git a/xargs/xargs.1 b/xargs/xargs.1
index b6c10a3..96ba6b2 100644
--- a/xargs/xargs.1
+++ b/xargs/xargs.1
@@ -23,17 +23,10 @@ and executes the
 followed by arguments read from standard input.  Blank lines on the
 standard input are ignored.
 .P
-.B xargs
-exits with the following status:
-.nf
-0 if it succeeds
-123 if any invocation of the command exited with status 1-125
-124 if the command exited with status 255
-125 if the command is killed by a signal
-126 if the command cannot be run
-127 if the command is not found
-1 if some other error occurred.
-.fi
+If any invocation of the command exits with a status of 255, 
+.B xargs 
+will stop immediately without reading any firther input.  An error
+message is issued on stderr when this happens.
 .SS OPTIONS
 .TP
 .I "\-\-null, \-0"
@@ -107,6 +100,44 @@ Run up to \fImax-procs\fR processes at a time; the default is 1.  If
 \fImax-procs\fR is 0, \fBxargs\fR will run as many processes as
 possible at a time.  Use the \fI\-n\fR option with \fI\-P\fR;
 otherwise chances are that only one exec will be done.
+.SH "EXAMPLES"
+.nf
+.B find /tmp -name core -type f -print | xargs /bin/rm -f
+
+.fi
+Find files named 
+.B core
+in or below the directory 
+.B /tmp 
+and delete them.
+.P
+.B find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f
+
+.fi
+Find files named 
+.B core
+in or below the directory 
+.B /tmp 
+and delete them, processing filenames in such a way that file or 
+directory names containing spaces or newlines are correctly handled.
+.P
+.nf
+.B cut -d: -f1 < /etc/passwd | sort | xargs echo
+
+.fi
+Generates a compact listing of all the users on the system.
+.SH "EXIT STATUS"
+.B xargs
+exits with the following status:
+.nf
+0 if it succeeds
+123 if any invocation of the command exited with status 1-125
+124 if the command exited with status 255
+125 if the command is killed by a signal
+126 if the command cannot be run
+127 if the command is not found
+1 if some other error occurred.
+.fi
 .SH "SEE ALSO"
 \fBfind\fP(1L), \fBlocate\fP(1L), \fBlocatedb\fP(5L), \fBupdatedb\fP(1)
 \fBFinding Files\fP (on-line in Info, or printed)
-- 
2.11.4.GIT