*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> xargs (1)              



NAME    [Toc]    [Back]

       xargs - Constructs argument lists and runs commands

SYNOPSIS    [Toc]    [Back]

       xargs  [-e[eofstr]] [-E eofstr] [-i[replstr]] [-I replstr]
       [-l[number]] [-L number] [-n[number]]  [-ptrx]  [-slength]
       [CommandString] [argument...]

       The xargs command constructs a command line by combining a
       command string, containing a command and  its  options  or
       arguments,  with  additional  arguments read from standard

STANDARDS    [Toc]    [Back]

       Interfaces documented on this reference  page  conform  to
       industry standards as follows:

       xargs:  XCU5.0

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

OPTIONS    [Toc]    [Back]

       Sets the logical end-of-file string to eofstr.  The  xargs
       command reads standard input until it encounters either an
       end-of-file character or the logical  end-of-file  string.
       If  you do (underline).  If you specify -e with no eofstr,
       xargs interprets the  underline  character  as  a  literal
       character,  rather  than as an end-of-file marker.  Specifies
 a logical end-of-file string to replace  the  default
       underscore.   The xargs command reads standard input until
       either an end-of-file character or the logical end-of-file
       string  is  encountered.  Takes an entire line as a single
       argument and inserts it in each instance of replstr  found
       in the command string.  A maximum of five arguments in the
       command string can each contain one or more  instances  of
       replstr.   The  xargs  command discards spaces and tabs at
       the beginning of each line.  The argument constructed cannot
  be larger than 255 bytes.  The default replstr is {}.
       This option also turns on the  -x  option.   Insert  mode:
       command  is  executed  for  each line from standard input,
       taking the entire line as a single argument, inserting  it
       in  arguments  for  each  occurrence of replstr. Any blank
       characters at the beginning of each line are ignored. Constructed
  arguments  cannot  grow  larger  than 255 bytes.
       Option -x is forced on. The -I and -i options are mutually
       exclusive;  the last one specified takes effect.  Runs the
       command string with the specified number of nonempty argument
  lines read from standard input.  The last invocation
       of the command string can have  fewer  argument  lines  if
       fewer than number remain.  A line ends with the first newline
 character unless the last character of the line is  a
       space  or a tab.  A trailing space or tab indicates a continuation
 through the next nonempty line. The default number
  is  1.  This option turns on the -x option.  The command
 is executed for each non-empty number lines of  argument
  from  standard input. The last invocation of command
       has fewer lines of argument if fewer than number remain. A
       line is considered to end with the first newline character
       unless the last character of the line is a  blank  character.
  A  trailing  blank character signals continuation to
       the next non-empty line, inclusive.  The  -L,  -l  and  -n
       options are mutually exclusive; the last one takes effect.
       Executes the command string using as many  standard  input
       arguments  as  possible,  up  to a maximum of number.  The
       xargs command uses fewer arguments if their  total  length
       is  greater than the number of characters specified by the
       -s [length] option.  It also uses fewer arguments for  the
       last  invocation  if  fewer  than number arguments remain.
       When -x is present, each  number  argument  must  fit  the
       length limitation specified by -s.  Asks whether or not to
       run the command string.  It displays the constructed  command
  line,  followed  by a ?...  prompt.  Press y, or the
       locale's equivalent of a y, to  run  the  command  string.
       Any  other  response  causes xargs to skip that particular
       invocation of the command string.   You  are  asked  about
       each  invocation.   Sets  the maximum total length of each
       argument list. The length must be a positive integer  less
       than  or  equal  to 470.  The default length is 470 bytes.
       Note that the character  count  for  length  includes  one
       extra  character for each argument and the number of characters
 in the command name.  Echoes the command string and
       each  constructed argument list to file descriptor 2 (usually
 standard error).  Stops running xargs if any argument
       list is greater than the number of characters specified by
       the -s length option.  This option is  turned  on  if  you
       specify  either the -i or -l options.  If you do not specify
 -i, -l, or -n, the total length of all arguments  must
       be within the length limit.

OPERANDS    [Toc]    [Back]

       The  name of the command to be invoked, found by searching
       the path using the PATH environment variable.  If CommandString
  is  omitted,  the default is the echo command.  An
       initial option or operand for the invocation  of  CommandString.

DESCRIPTION    [Toc]    [Back]

       The xargs command runs the command string as many times as
       necessary to process all  input  arguments.   The  default
       command string is echo.

       Arguments  read  from standard input are character strings
       delimited by one or more spaces, tabs, or newline  characters.
  You can embed a space or a tab in arguments by preceding
 it with a \ (backslash)  or  by  quoting  it.   The
       xargs  command reads characters enclosed in single or double
 quotes as literals and removes the delimiting  quotes.
       It always discards empty lines.

       The xargs command ends if it cannot run the command string
       or if it receives an exit code of -1.   When  the  command
       string calls a shell procedure, the shell procedure should
       explicitly exit with an appropriate value to  avoid  accidentally
 returning -1.  (See the sh command.)

       The  LC_MESSAGES variables determines the locale's equivalent
 of y and n (for yes/no queries).

EXIT STATUS    [Toc]    [Back]

       The following exit values are returned: All invocations of
       CommandString  returned  exit status zero.  A command line
       meeting the specified requirements could not be assembled,
       one or more of the invocations of CommandString returned a
       non-zero exit status, or some other error  occurred.   The
       command specified by CommandString was found but could not
       be invoked.  The command specified by CommandString  could
       not be found.

EXAMPLES    [Toc]    [Back]

       To  use  a  command  on  files whose names are listed in a
       file, use a command line similar to the  following:  xargs
       lint  -a  < cfiles

              If  cfiles  contains  the text, enter: main.c  readit.c
 gettoken.c putobj.c

              then xargs constructs and runs  the  command:  lint
              -a  main.c  readit.c  gettoken.c  putobj.c

              Each  shell  command  line  can  be up to 470 bytes
              long. If cfiles contains more file namess than  fit
              on  a single line, then xargs runs the lint command
              with the file namess that fit.  It then  constructs
              and  runs  another lint command using the remaining
              file namess.  Depending  on  the  names  listed  in
              cfiles, the commands might look like the following:

              lint  -a  main.c  readit.c  gettoken.c...  lint  -a
              getisx.c  getprp.c  getpid.c...  lint  -a  fltadd.c
              fltmult.c  fltdiv.c...

              This is not quite the same  as  running  lint  once
              with  all the file namess.  The lint command checks
              cross-references between files.  However,  in  this
              example   it   cannot   check  between  main.c  and
              fltadd.c, or between any two files listed on  separate
 command lines.

              For  this  reason you might want to run the command
              only if all the file namess fit  on  one  line.  Do
              this  by  using xargs with the -x option: xargs  -x
              lint  -a  <cfiles

              If all the file names in cfiles do not fit  on  one
              command line, then xargs displays an error message.
              To construct commands that contain a certain number
              of  file  namess, use a command line similar to the
              following: xargs  -t   -n2   diff   <<end  starting
              chap1  concepts  chap2  writing chap3 end

              This constructs and runs diff commands that contain
              two file names each (-n2):

              diff  starting  chap1 diff   concepts   chap2  diff
              writing  chap3

              The  -t  option tells xargs to display each command
              before running it so that you can see what is  happening.
   The <<end and end arguments define a Here
              Document, which uses the text  entered  before  the
              end  line  as standard input for the xargs command.
              (For more details, see  the  section  Inline  Input
              (Here)  Documents in the sh(1) reference page.)  To
              insert file namess into the middle of commands, use
              a  command  line  similar  to  the following: ls  |
              xargs  -t  -i  mv  {}  {}.old

              This renames all files in the current directory  by
              adding to the end of each name.  The -i tells xargs
              to insert each line of  the  ls  directory  listing
              where  {  } (braces) appear.  If the current directory
 contains the files chap1,  chap2,  and  chap3,
              then this constructs the following commands:

              mv  chap1  chap1.old mv  chap2  chap2.old mv  chap3
              chap3.old To run a command on files that you select
              individually,  use  a  command  line similar to the
              following: ls  |  xargs  -p  -n1  ar  r  lib.a

              This allows you to  select  files  to  add  to  the
              library  lib.a.   The -p option tells xargs to display
 each ar command it constructs and ask  if  you
              want  to  run it.  Press y, or the locale's equivalent
 of a y, and press <Return> to run the command.
              Press  <Return> alone if you do not want to run it.


       The following environment variables affect  the  execution
       of  xargs: Provides a default value for the internationalization
 variables that are unset or null. If LANG is unset
       or  null,  the corresponding value from the default locale
       is used.  If any  of  the  internationalization  variables
       contain an invalid setting, the utility behaves as if none
       of the variables had been defined.  If set to a  non-empty
       string value, overrides the values of all the other internationalization
 variables.  Determines the locale for  the
       interpretation of sequences of bytes of text data as characters
 (for example, single-byte as opposed  to  multibyte
       characters  in arguments and input files) and the behavior
       of character classes used for yesexprlocal keyword in  the
       LC_MESSAGES  category.  Determines the locale for the format
 and contents of diagnostic messages written  to  standard
 error.  Determines the location of message catalogues
       for the processing of LC_MESSAGES.  Determines  the  location
 of CommandString.

SEE ALSO    [Toc]    [Back]

       Commands:  ksh(1), Bourne shell sh(1b), POSIX shell sh(1p)

       Standards:  standards(5)

[ Back ]
 Similar pages
Name OS Title
spread IRIX Constructs an array from several copies of an actual argument
batch Tru64 Runs commands at a later time
at Tru64 Runs commands at a later time
dxdw Tru64 Runs and repeats command line commands
va_end FreeBSD variable argument lists
stdarg OpenBSD variable argument lists
va_arg OpenBSD variable argument lists
va_copy OpenBSD variable argument lists
va_end OpenBSD variable argument lists
va_start OpenBSD variable argument lists
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service