xargs/xargs.1

   1 .\"     $NetBSD: xargs.1,v 1.7 1997/06/24 00:45:28 lukem Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" John B. Roll Jr. and the Institute of Electrical and Electronics
   8 .\" Engineers, Inc.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"     This product includes software developed by the University of
  21 .\"     California, Berkeley and its contributors.
  22 .\" 4. Neither the name of the University nor the names of its contributors
  23 .\"    may be used to endorse or promote products derived from this software
  24 .\"    without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  27 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  28 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  29 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  30 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  31 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  32 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  33 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  34 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  35 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  36 .\" SUCH DAMAGE.
  37 .\"
  38 .\"     @(#)xargs.1     8.1 (Berkeley) 6/6/93
  39 .\"
  40 .Dd June 6, 1993
  41 .Dt XARGS 1
  42 .Os
  43 .Sh NAME
  44 .Nm xargs
  45 .Nd "construct argument list(s) and execute utility"
  46 .Sh SYNOPSIS
  47 .Nm
  48 .Op Fl 0
  49 .Op Fl t
  50 .Oo Op Fl x
  51 .Fl n Ar number
  52 .Oc
  53 .Op Fl s Ar size
  54 .Op Ar utility Op Ar arguments ...
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 utility reads space, tab, newline and end-of-file delimited arguments
  59 from the standard input and executes the specified
  60 .Ar utility
  61 with them as
  62 arguments.
  63 .Pp
  64 The utility and any arguments specified on the command line are given
  65 to the
  66 .Ar utility
  67 upon each invocation, followed by some number of the arguments read
  68 from standard input.
  69 The
  70 .Ar utility
  71 is repeatedly executed until standard input is exhausted.
  72 .Pp
  73 Spaces, tabs and newlines may be embedded in arguments using single
  74 (``\ '\ '')
  75 or double (``"'') quotes or backslashes (``\e'').
  76 Single quotes escape all non-single quote characters, excluding newlines,
  77 up to the matching single quote.
  78 Double quotes escape all non-double quote characters, excluding newlines,
  79 up to the matching double quote.
  80 Any single character, including newlines, may be escaped by a backslash.
  81 .Pp
  82 The options are as follows:
  83 .Bl -tag -width Fl
  84 .It Fl 0
  85 Use NUL
  86 (``\e0'')
  87 instead of whitespace as the argument separator.
  88 This can be used in conjuction with the
  89 .Fl print0
  90 option of
  91 .Xr find 1 .
  92 .It Fl n Ar number
  93 Set the maximum number of arguments taken from standard input for each
  94 invocation of the utility.
  95 An invocation of
  96 .Ar utility
  97 will use less than
  98 .Ar number
  99 standard input arguments if the number of bytes accumulated (see the
 100 .Fl s
 101 option) exceeds the specified
 102 .Ar size
 103 or there are fewer than
 104 .Ar number
 105 arguments remaining for the last invocation of
 106 .Ar utility .
 107 The current default value for
 108 .Ar number
 109 is 5000.
 110 .It Fl s Ar size
 111 Set the maximum number of bytes for the command line length provided to
 112 .Ar utility .
 113 The sum of the length of the utility name and the arguments passed to
 114 .Ar utility
 115 (including
 116 .Dv NULL
 117 terminators) will be less than or equal to this number.
 118 The current default value for
 119 .Ar size
 120 is
 121 .Dv ARG_MAX
 122 - 2048.
 123 .It Fl t
 124 Echo the command to be executed to standard error immediately before it
 125 is executed.
 126 .It Fl x
 127 Force
 128 .Nm
 129 to terminate immediately if a command line containing
 130 .Ar number
 131 arguments will not fit in the specified (or default) command line length.
 132 .El
 133 .Pp
 134 If no
 135 .Ar utility
 136 is specified,
 137 .Xr echo 1
 138 is used.
 139 .Pp
 140 Undefined behavior may occur if
 141 .Ar utility
 142 reads from the standard input.
 143 .Pp
 144 The
 145 .Nm
 146 utility exits immediately (without processing any further input) if a
 147 command line cannot be assembled,
 148 .Ar utility
 149 cannot be invoked, an invocation of the utility is terminated by a signal
 150 or an invocation of the utility exits with a value of 255.
 151 .Sh DIAGNOSTICS
 152 .Nm
 153 exits with one of the following values:
 154 .Bl -tag -width Ds -compact
 155 .It 0
 156 All invocations of
 157 .Ar utility
 158 returned a zero exit status.
 159 .It 123
 160 One or more invocations of
 161 .Ar utility
 162 returned a nonzero exit status.
 163 .It 124
 164 The
 165 .Ar utility
 166 exited with a 255 exit status.
 167 .It 125
 168 The
 169 .Ar utility
 170 was killed or stopped by a signal.
 171 .It 126
 172 The
 173 .Ar utility
 174 was found but could not be invoked.
 175 .It 127
 176 The
 177 .Ar utility
 178 could not be found.
 179 .It 1
 180 Some other error occurred.
 181 .El
 182 .Sh SEE ALSO
 183 .Xr echo 1 ,
 184 .Xr find 1
 185 .Sh STANDARDS
 186 The
 187 .Nm
 188 utility is expected to be
 189 .St -p1003.2
 190 compliant.
 191 .Sh HISTORY
 192 The meaning of 123, 124, and 125 exit values were taken from GNU xargs.