binutils: ar scripts

1 
1 1.2 Controlling 'ar' with a Script
1 ==================================
1 
1      ar -M [ <SCRIPT ]
1 
1    If you use the single command-line option '-M' with 'ar', you can
1 control its operation with a rudimentary command language.  This form of
1 'ar' operates interactively if standard input is coming directly from a
1 terminal.  During interactive use, 'ar' prompts for input (the prompt is
1 'AR >'), and continues executing even after errors.  If you redirect
1 standard input to a script file, no prompts are issued, and 'ar'
1 abandons execution (with a nonzero exit code) on any error.
1 
1    The 'ar' command language is _not_ designed to be equivalent to the
1 command-line options; in fact, it provides somewhat less control over
1 archives.  The only purpose of the command language is to ease the
1 transition to GNU 'ar' for developers who already have scripts written
1 for the MRI "librarian" program.
1 
1    The syntax for the 'ar' command language is straightforward:
1    * commands are recognized in upper or lower case; for example, 'LIST'
1      is the same as 'list'.  In the following descriptions, commands are
1      shown in upper case for clarity.
1 
1    * a single command may appear on each line; it is the first word on
1      the line.
1 
1    * empty lines are allowed, and have no effect.
1 
1    * comments are allowed; text after either of the characters '*' or
1      ';' is ignored.
1 
1    * Whenever you use a list of names as part of the argument to an 'ar'
1      command, you can separate the individual names with either commas
1      or blanks.  Commas are shown in the explanations below, for
1      clarity.
1 
1    * '+' is used as a line continuation character; if '+' appears at the
1      end of a line, the text on the following line is considered part of
1      the current command.
1 
1    Here are the commands you can use in 'ar' scripts, or when using 'ar'
1 interactively.  Three of them have special significance:
1 
1    'OPEN' or 'CREATE' specify a "current archive", which is a temporary
1 file required for most of the other commands.
1 
1    'SAVE' commits the changes so far specified by the script.  Prior to
1 'SAVE', commands affect only the temporary copy of the current archive.
1 
1 'ADDLIB ARCHIVE'
1 'ADDLIB ARCHIVE (MODULE, MODULE, ... MODULE)'
1      Add all the contents of ARCHIVE (or, if specified, each named
1      MODULE from ARCHIVE) to the current archive.
1 
1      Requires prior use of 'OPEN' or 'CREATE'.
1 
1 'ADDMOD MEMBER, MEMBER, ... MEMBER'
1      Add each named MEMBER as a module in the current archive.
1 
1      Requires prior use of 'OPEN' or 'CREATE'.
1 
1 'CLEAR'
1      Discard the contents of the current archive, canceling the effect
1      of any operations since the last 'SAVE'.  May be executed (with no
1      effect) even if no current archive is specified.
1 
1 'CREATE ARCHIVE'
1      Creates an archive, and makes it the current archive (required for
1      many other commands).  The new archive is created with a temporary
1      name; it is not actually saved as ARCHIVE until you use 'SAVE'.
1      You can overwrite existing archives; similarly, the contents of any
1      existing file named ARCHIVE will not be destroyed until 'SAVE'.
1 
1 'DELETE MODULE, MODULE, ... MODULE'
1      Delete each listed MODULE from the current archive; equivalent to
1      'ar -d ARCHIVE MODULE ... MODULE'.
1 
1      Requires prior use of 'OPEN' or 'CREATE'.
1 
1 'DIRECTORY ARCHIVE (MODULE, ... MODULE)'
1 'DIRECTORY ARCHIVE (MODULE, ... MODULE) OUTPUTFILE'
1      List each named MODULE present in ARCHIVE.  The separate command
1      'VERBOSE' specifies the form of the output: when verbose output is
1      off, output is like that of 'ar -t ARCHIVE MODULE...'.  When
1      verbose output is on, the listing is like 'ar -tv ARCHIVE
1      MODULE...'.
1 
1      Output normally goes to the standard output stream; however, if you
1      specify OUTPUTFILE as a final argument, 'ar' directs the output to
1      that file.
1 
1 'END'
1      Exit from 'ar', with a '0' exit code to indicate successful
1      completion.  This command does not save the output file; if you
1      have changed the current archive since the last 'SAVE' command,
1      those changes are lost.
1 
1 'EXTRACT MODULE, MODULE, ... MODULE'
1      Extract each named MODULE from the current archive, writing them
1      into the current directory as separate files.  Equivalent to 'ar -x
1      ARCHIVE MODULE...'.
1 
1      Requires prior use of 'OPEN' or 'CREATE'.
1 
1 'LIST'
1      Display full contents of the current archive, in "verbose" style
1      regardless of the state of 'VERBOSE'.  The effect is like 'ar tv
1      ARCHIVE'.  (This single command is a GNU 'ar' enhancement, rather
1      than present for MRI compatibility.)
1 
1      Requires prior use of 'OPEN' or 'CREATE'.
1 
1 'OPEN ARCHIVE'
1      Opens an existing archive for use as the current archive (required
1      for many other commands).  Any changes as the result of subsequent
1      commands will not actually affect ARCHIVE until you next use
1      'SAVE'.
1 
1 'REPLACE MODULE, MODULE, ... MODULE'
1      In the current archive, replace each existing MODULE (named in the
1      'REPLACE' arguments) from files in the current working directory.
1      To execute this command without errors, both the file, and the
1      module in the current archive, must exist.
1 
1      Requires prior use of 'OPEN' or 'CREATE'.
1 
1 'VERBOSE'
1      Toggle an internal flag governing the output from 'DIRECTORY'.
1      When the flag is on, 'DIRECTORY' output matches output from 'ar -tv
1      '....
1 
1 'SAVE'
1      Commit your changes to the current archive, and actually save it as
1      a file with the name specified in the last 'CREATE' or 'OPEN'
1      command.
1 
1      Requires prior use of 'OPEN' or 'CREATE'.
1