From d5ba6fa9ca39e29c1186c1f68501d0015a10a375 Mon Sep 17 00:00:00 2001
From: jay <jay>
Date: Sun, 8 Aug 2004 10:36:23 +0000
Subject: [PATCH] Better documentation for the -i option

---
 xargs/xargs.1 | 33 +++++++++++++++++++++++++++++++-
 xargs/xargs.c | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+), 1 deletion(-)

diff --git a/xargs/xargs.1 b/xargs/xargs.1
index f31c152..e6d3338 100644
--- a/xargs/xargs.1
+++ b/xargs/xargs.1
@@ -154,12 +154,43 @@ exits with the following status:
 127 if the command is not found
 1 if some other error occurred.
 .fi
+.P
+Exit codes greater than 128 are used by the shell to indicate that 
+a program died due to a fatal signal.
 .SH "SEE ALSO"
-\fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1)
+\fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1),
 \fBFinding Files\fP (on-line in Info, or printed)
 .SH "BUGS"
 .P
 Some options exist in POSIX but are not yet implemented.
+.P 
+When you use the \-i option, each line read from the input is buffered 
+internally.   This means that there is an upper limit on the length 
+of input line that 
+.B xargs 
+will accept when used with the \-i option.  To work around this 
+limitation, you can use the \-s option to increase the amount of
+buffer space that 
+.B xargs 
+uses, and you can also use an extra invocation of 
+.B xargs 
+to ensure that very long lines do not occur.  
+For example: 
+.P
+.B echo * | xargs -s 50000 echo | xargs -i -s 100000 rm '{}'
+.P
+Here, the first invocation of 
+.B xargs 
+has no input line length limit
+because it doesn't use the \-i option.  The second invocation of
+.B xargs 
+does have such a limit, but we have ensured that the it never encounters 
+a line which is longer than it can handle.   This is not an ideal 
+solution.  Instead, the \-i option should not impose a line length
+limit, which is why this discussion is listed in the BUGS section.
+The problem doesn't occur with the output of 
+.BR find (1) 
+because it emits just one filename per line.
 .P
 The best way to report a bug is to use the form at
 http://savannah.gnu.org/bugs/?group=findutils.  
diff --git a/xargs/xargs.c b/xargs/xargs.c
index af5542e..44a7b0e 100644
--- a/xargs/xargs.c
+++ b/xargs/xargs.c
@@ -491,6 +491,61 @@ main (int argc, char **argv)
   exit (child_error);
 }
 
+#if 0
+static int
+append_char_to_buf(char **pbuf, char **pend, char **pp, int c)
+{
+  char *end_of_buffer = *pend;
+  char *start_of_buffer = *pbuf;
+  char *p = *pp;
+  if (p >= end_of_buffer)
+    {
+      if (replace_pat)
+	{
+	  size_t len = end_of_buffer - start_of_buffer;
+	  size_t offset = p - start_of_buffer;
+	  len *= 2;
+	  start_of_buffer = xrealloc(start_of_buffer, len*2);
+	  if (NULL != start_of_buffer)
+	    {
+	      end_of_buffer = start_of_buffer + len;
+	      p = start_of_buffer + offset;
+	      *p++ = c;
+
+	      /* Update the caller's idea of where the buffer is. */
+	      *pbuf = start_of_buffer;
+	      *pend = end_of_buffer;
+	      *pp = p;
+	      
+	      return 0;
+	    }
+	  else
+	    {
+	      /* Failed to reallocate. */
+	      return -1;
+	    }
+	}
+      else
+	{
+	  /* I suspect that this can never happen now, because append_char_to_buf()
+	   * should only be called wen replace_pat is true.
+	   */
+	  error (1, 0, _("argument line too long"));
+	  /*NOTREACHED*/
+	  return -1;
+	}
+    }
+  else
+    {
+      /* Enough space remains. */
+      *p++ = c;
+      *pp = p;
+      return 0;
+    }
+}
+#endif
+
+
 /* Read a line of arguments from stdin and add them to the list of
    arguments to pass to the command.  Ignore blank lines and initial blanks.
    Single and double quotes and backslashes quote metacharacters and blanks
@@ -609,9 +664,13 @@ read_line (void)
 	  state = NORM;
 	  break;
 	}
+#if 1
       if (p >= endbuf)
 	error (1, 0, _("argument line too long"));
       *p++ = c;
+#else
+      append_char_to_buf(&linebuf, &endbuf, &p, c);
+#endif
     }
 }
 
@@ -763,6 +822,7 @@ push_arg (char *arg, size_t len)
 	{
 	  if (initial_args || cmd_argc == initial_argc)
 	    error (1, 0, _("can not fit single argument within argument list size limit"));
+	  /* option -i (replace_pat) implies -x (exit_if_size_exceeded) */
 	  if (replace_pat
 	      || (exit_if_size_exceeded &&
 		  (lines_per_exec || args_per_exec)))
-- 
2.11.4.GIT