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