unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 xargs(1)                                                           xargs(1)




 NAME
      xargs - construct argument list(s) and execute command

 SYNOPSIS
      xargs [options] [command [initial-arguments]]

 DESCRIPTION
      xargs combines the fixed initial-arguments with arguments read from
      standard input to execute the specified command one or more times.
      The number of arguments read for each command invocation and the
      manner in which they are combined are determined by the options
      specified.

      command, which can be a shell file, is searched for, using the $PATH
      environment variable.  If command is omitted, /usr/bin/echo is used.

      Arguments read in from standard input are defined to be contiguous
      strings of characters delimited by one or more blanks, tabs, or new-
      lines; empty lines are always discarded.  Spaces and tabs can be
      embedded as part of an argument if escaped or quoted.  Characters
      enclosed in quotes (single or double) are taken literally, and the
      delimiting quotes are removed.  Outside of quoted strings, a backslash
      (\) escapes the next character.

      The amount of memory available for the execution of command is limited
      by the system parameter ARG_MAX.  By default, the size of the argument
      list is limited to LINE_MAX bytes.  See limits(5) and sysconf(2) for a
      description of these system parameters and how their values can be
      determined.  To increase the available argument list space, use the -s
      option.

      Each argument list is constructed starting with the initial-arguments,
      followed by some number of arguments read from standard input
      (exception: see -i or -I option).  The -i, -I, -l, -L, and -n options
      determine how arguments are selected for each command invocation.
      When none of these options is specified, the initial-arguments are
      followed by arguments read continuously from standard input until an
      internal buffer is full, then command is executed with the accumulated
      args.  This process is repeated until there are no more args.  When
      there are option conflicts (such as -l or -L versus -n), the last
      option has precedence.  option values are:

           -L number      command is executed for each non-empty number
                          lines of arguments from standard input.  The last
                          invocation of command will be with fewer lines of
                          arguments if fewer than number remain.  A line is
                          considered to end with the first new-line unless
                          the last character of the line is a blank or a
                          tab; a trailing blank/tab signals continuation
                          through the next non-empty line.  The -L, -l, and
                          -n options are mutually exclusive. The last one



 Hewlett-Packard Company            - 1 -   HP-UX Release 11i: November 2000






 xargs(1)                                                           xargs(1)




                          specified takes effect.

           -l[ number ]   This option is equivalent to the -L option.  1 is
                          assumed if number is omitted or is given as the
                          empty string ( "" ).  Option -x is forced.

           -I replstr     Insert mode: command is executed for each line
                          from standard input, taking the entire line as a
                          single arg, inserting it in initial-arguments for
                          each occurrence of replstr.  A maximum of 5
                          arguments in initial-arguments can each contain
                          one or more instances of replstr.  Blanks and tabs
                          at the beginning of each line are discarded.
                          Constructed arguments must not grow larger than
                          255 bytes, and option -x is also forced.  The -I
                          and -i options are mutually exclusive. The last
                          one specified takes effect.

           -i[ repstr ]   This option is equivalent to the -I option.  {} is
                          assumed if replstr is omitted or is given as the
                          empty string ( "" ).

           -n number      Execute command using as many standard input
                          arguments as possible, up to number arguments
                          maximum.  Fewer arguments are used if their total
                          size is greater than size bytes, and for the last
                          invocation if there are fewer than number
                          arguments remaining.  If option -x is also coded,
                          each number arguments must fit in the size
                          limitation or xargs terminates execution.

           -s size        The maximum total size of each argument list is
                          set to size bytes; size must be a positive integer
                          less than LINE_MAX (see limits(5), sysconf(2)).
                          If -s is not coded, LINE_MAX is taken as the
                          default.  Note that the bytes count for size
                          includes one extra bytes for each argument and the
                          count of bytes in the command name.

           -t             Trace mode: The command and each constructed
                          argument list are echoed to standard error just
                          prior to their execution.

           -p             Prompt mode: The user is asked whether to execute
                          command prior to each invocation.  Trace mode (-t)
                          is turned on to print the command instance to be
                          executed, followed by a ?... prompt.  An
                          affirmative reply (by default, an affirmative
                          reply is y optionally followed by anything)
                          executes the command; anything else, including
                          pressing Return, skips that particular invocation



 Hewlett-Packard Company            - 2 -   HP-UX Release 11i: November 2000






 xargs(1)                                                           xargs(1)




                          of command.

           -x             Causes xargs to terminate if any argument list
                          would be greater than size bytes.  -x is forced by
                          the options -i, -I, -l, and -L.  When none of the
                          options -i, -I, -l, -L, or -n is coded, the total
                          length of all arguments must be within the size
                          limit.

           -e[ eofstr ]   eofstr is taken as the logical end-of-file string.
                          Underscore (_) is assumed for the logical EOF
                          string if neither -e nor -E is used.  The value -e
                          with eofstr given as the empty string ( "" ) turns
                          off the logical EOF string capability (underscore
                          is taken literally).  xargs reads standard input
                          until either end-of-file or the logical EOF string
                          is encountered.

           -E eofstr      Specify a logical end-of-file string to replace
                          the default underscore (_) character. Equivalent
                          to the -e option above.

      xargs terminates if it receives a return code of -1 from command or if
      it cannot execute command.  When command is a shell program, it should
      explicitly exit (see sh(1)) with an appropriate value to avoid
      accidentally returning with -1.

 RETURN VALUE
      xargs exits with one of the following values:

            0   All invocations of command completed successfully.

           1-125
                One or more invocations of command did not complete
                successfully.

           126  The command specified was found but could not be invoked.

           127  The command specified could not be found.

 EXTERNAL INFLUENCES
    Environment Variables
      LC_CTYPE determines the space characters and the interpretation of
      text as single- and/or multi-byte characters.

      LC_MESSAGES determines the language in which messages are displayed,
      and the local language equivalent of an affirmative reply when the -p
      prompt option is specified.

      If LC_CTYPE or LC_MESSAGES is not specified in the environment or is
      set to the empty string, the value of LANG is used as a default for



 Hewlett-Packard Company            - 3 -   HP-UX Release 11i: November 2000






 xargs(1)                                                           xargs(1)




      each unspecified or empty variable.  If LANG is not specified or is
      set to the empty string, a default of "C" (see lang(5)) is used
      instead of LANG.

      If any internationalization variable contains an invalid setting,
      xargs behaves as if all internationalization variables are set to "C".
      See environ(5).

    International Code Set Support
      Single- and multi-byte character code sets are supported.

 EXAMPLES
      Move all files from directory $1 to directory $2, and echo each move
      command just before doing it:

           ls $1 | xargs -i -t mv $1/{} $2/{}

      Combine the output of the parenthesized commands onto one line, then
      echo to the end of file log:

           (logname; date; echo $0 $*) | xargs >&gt&gt>>&gt&gt>log

      Ask the user which files in the current directory are to be archived
      then archive them into arch one at a time:

           ls | xargs -p -l ar r arch

      or many at a time:

           ls | xargs -p -l | xargs ar r arch

      Execute diff (see diff(1)) with successive pairs of arguments
      originally typed as shell arguments:

           echo $* | xargs -n2 diff

 SEE ALSO
      sh(1).

 STANDARDS CONFORMANCE
      xargs: SVID2, SVID3, XPG2, XPG3, XPG4, POSIX.2













 Hewlett-Packard Company            - 4 -   HP-UX Release 11i: November 2000