Annotation of src/usr.bin/xargs/xargs.1, Revision 1.1
1.1 ! deraadt 1: .\" $NetBSD: xargs.1,v 1.6 1994/11/14 06:51:40 jtc 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 xargs
! 48: .Op Fl t
! 49: .Oo Op Fl x
! 50: .Fl n Ar number
! 51: .Oc
! 52: .Op Fl s Ar size
! 53: .Op Ar utility Op Ar arguments ...
! 54: .Sh DESCRIPTION
! 55: The
! 56: .Nm xargs
! 57: utility reads space, tab, newline and end-of-file delimited arguments
! 58: from the standard input and executes the specified
! 59: .Ar utility
! 60: with them as
! 61: arguments.
! 62: .Pp
! 63: The utility and any arguments specified on the command line are given
! 64: to the
! 65: .Ar utility
! 66: upon each invocation, followed by some number of the arguments read
! 67: from standard input.
! 68: The
! 69: .Ar utility
! 70: is repeatedly executed until standard input is exhausted.
! 71: .Pp
! 72: Spaces, tabs and newlines may be embedded in arguments using single
! 73: (``\ '\ '')
! 74: .Ek
! 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 indent
! 84: .It Fl n Ar number
! 85: Set the maximum number of arguments taken from standard input for each
! 86: invocation of the utility.
! 87: An invocation of
! 88: .Ar utility
! 89: will use less than
! 90: .Ar number
! 91: standard input arguments if the number of bytes accumulated (see the
! 92: .Fl s
! 93: option) exceeds the specified
! 94: .Ar size
! 95: or there are fewer than
! 96: .Ar number
! 97: arguments remaining for the last invocation of
! 98: .Ar utility .
! 99: The current default value for
! 100: .Ar number
! 101: is 5000.
! 102: .It Fl s Ar size
! 103: Set the maximum number of bytes for the command line length provided to
! 104: .Ar utility .
! 105: The sum of the length of the utility name and the arguments passed to
! 106: .Ar utility
! 107: (including
! 108: .Dv NULL
! 109: terminators) will be less than or equal to this number.
! 110: The current default value for
! 111: .Ar size
! 112: is
! 113: .Dv ARG_MAX
! 114: - 2048.
! 115: .It Fl t
! 116: Echo the command to be executed to standard error immediately before it
! 117: is executed.
! 118: .It Fl x
! 119: Force
! 120: .Nm xargs
! 121: to terminate immediately if a command line containing
! 122: .Ar number
! 123: arguments will not fit in the specified (or default) command line length.
! 124: .El
! 125: .Pp
! 126: If no
! 127: .Ar utility
! 128: is specified,
! 129: .Xr echo 1
! 130: is used.
! 131: .Pp
! 132: Undefined behavior may occur if
! 133: .Ar utility
! 134: reads from the standard input.
! 135: .Pp
! 136: The
! 137: .Nm xargs
! 138: utility exits immediately (without processing any further input) if a
! 139: command line cannot be assembled,
! 140: .Ar utility
! 141: cannot be invoked, an invocation of the utility is terminated by a signal
! 142: or an invocation of the utility exits with a value of 255.
! 143: .Sh DIAGNOSTICS
! 144: .Nm xargs
! 145: exits with one of the following values:
! 146: .Bl -tag -width Ds -compact
! 147: .It 0
! 148: All invocations of
! 149: .Ar utility
! 150: returned a zero exit status.
! 151: .It 123
! 152: One or more invocations of
! 153: .Ar utility
! 154: returned a nonzero exit status.
! 155: .It 124
! 156: The
! 157: .Ar utility
! 158: exited with a 255 exit status.
! 159: .It 125
! 160: The
! 161: .Ar utility
! 162: was killed or stopped by a signal.
! 163: .It 126
! 164: The
! 165: .Ar utility
! 166: was found but could not be invoked.
! 167: .It 127
! 168: The
! 169: .Ar utility
! 170: could not be found.
! 171: .It 1
! 172: Some other error occurred.
! 173: .El
! 174: .Sh SEE ALSO
! 175: .Xr echo 1 ,
! 176: .Xr find 1
! 177: .Sh STANDARDS
! 178: The
! 179: .Nm xargs
! 180: utility is expected to be
! 181: .St -p1003.2
! 182: compliant.
! 183: .Sh HISTORY
! 184: The meaning of 123, 124, and 125 exit values were taken from GNU xargs.