[docs][llvm-ar] Update llvm-ar command guide

[gbreynoo]

Summary

The llvm-ar command guide has not been updated in some time, it is missing current functionality and contains information that is out of date.
This diff:

• Updates the use of reStructuredText directives, as seen in other tools command guides.
• Updates the command synopsis.
• Updates the descriptions of the tool behaviour.
• Updates the options section.
• Adds details of MRI script functionality.
• Removes the sections "Standards" and "File Format", they appear to be out of date and out of scope for a command guide. I can't find these sections in the other tool command guides.

[rupprecht]

Mostly nits, I have a couple larger suggestions that I'm ok skipping because better documentation is better than bad documentation :)

llvm/docs/CommandGuide/llvm-ar.rst

15

nit: missing space after period before "It"

28–29

I compared what options were provided on the GNU ar on my workstation, and found the following not implemented by llvm-ar:

[f] - truncate inserted filenames
[O] - display offsets of files
[V] - display version

(actually, we should note the first two, but just implement llvm-ar V... I might take a look at that now)

I *think* we do actually implement all of them, i.e. there are none that we "implement but ignore for compatibility", but it would be good to double check that -- if there are any like that, we should also add them here.

36–38

Is this a difference anymore? It sounds like this used to be a limitation that no longer holds.

39

Additionally llvm-ar is deterministic by default, vs GNU ar (and GNU binutils in general), which is only deterministic if it's been configured that way at build time (and I think the default is non-deterministic). So I think that's an important thing to call out. For example:

*Deterministic Archives*

By default, :program:`llvm-ar` always uses zero for timestamps and UIDs/GIDs to write archives in a deterministic mode.
This is equivalent to the :option:`D` modifier being enabled by default. If you wish to maintain compatibility with other
:program:`ar` implementations, you can pass the :option:`U` modifier to write actual timestamps and UIDs/GIDs.

324

This is a dead link for me - https://llvm.org/docs/CommandGuide/ar.html

[rupprecht]

llvm/docs/CommandGuide/llvm-ar.rst

28–29

See D69007 for [V]

[ruiu]

Thank you for doing this!

llvm/docs/CommandGuide/llvm-ar.rst

36–38

I thought that too.

55

I see why you named this section "Long Options", but the section that would have been named "short options" is actually named "operations", and this section contains short options such as -h, so this section name seems a bit odd to me.

[gbreynoo]

Fix nits, add missing options, remove old limitation and add information regarding deterministic archives.

[gbreynoo]

llvm/docs/CommandGuide/llvm-ar.rst

55

I think the distinction between "Operation", "Modifier" and "Other" is helpful to the user but I'm not sure what to call this "Other" section. "Non key letter" feels long winded, and -h doesn't fit that either.

Maybe it should be called "Other" and put underneath the other two sections. M and h could be moved to the "Operation" section and --help would be considered a synonym. What do you think?

324

This was a carry over from the current guide. Should a link to the gnu-ar command guide be put here instead or would it be best to remove the section all together?

[rupprecht]

Thanks! Please wait for Rui to take another look, but this looks good enough to me.

llvm/docs/CommandGuide/llvm-ar.rst

41

Since GNU ar seems to also accept but ignore this arg, is it worth mentioning at all? Or are there other archiver programs that do use it?

324

I think we can just remove it. All the other docs in the "GNU binutils replacements" sections only have a "See also" section if they refer to other llvm tools (e.g. llvm-objcopy refers to llvm-strip). We already advertise heavily in the intro that this is a suitable replacement for GNU ar.

[MaskRay]

llvm/docs/CommandGuide/llvm-ar.rst

106

P can affect d.

Can T affect the d operation?

152

P affects r

209

L is an extension. Shall we mention the fact?

[ruiu]

LGTM

llvm/docs/CommandGuide/llvm-ar.rst

55

I think "Other" is a better name.

[gbreynoo]

Renamed "Long Options" to "Other" and moved it below the other options, removed bad link to gnu-ar and updated with changes from D69087.

[gbreynoo]

llvm/docs/CommandGuide/llvm-ar.rst

41

I know this is mentioned in the help text, but as this effects Command Line I think it belongs here. I can't tell you which archiver used this option originally.

106

As a general modifier I haven't been explicit with which commands use P, this is consistent with the other general modifiers. Regarding T with D, current llvm-ar behaviour will convert thin to full archives if T is not included with a write command. I'm not sure if this is the behaviour we want.

[gbreynoo]

Fixed two format issues.

[MaskRay]

llvm/docs/CommandGuide/llvm-ar.rst

9

Add O

[MaskRay]

llvm/docs/CommandGuide/llvm-ar.rst

9

<archive> -> archive

A mandatory argument is not surrounded by <>. See objcopy and llvm-objcopy for an example.

llvm/docs/CommandGuide/llvm-ar.rst

 llvm-ar - LLVM archiver
 =======================
 
 .. program:: llvm-ar
 
 SYNOPSIS
 --------
 
-**llvm-ar** [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...]
+:program:`llvm-ar` [-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive [files...]
 
 DESCRIPTION
 -----------
 
-The **llvm-ar** command is similar to the common Unix utility, ``ar``. It
-archives several files together into a single file. The intent for this is
-to produce archive libraries by LLVM bitcode that can be linked into an
-LLVM program. However, the archive can contain any kind of file. By default,
-**llvm-ar** generates a symbol table that makes linking faster because
-only the symbol table needs to be consulted, not each individual file member
-of the archive.
-
-The **llvm-ar** command can be used to *read* SVR4, GNU and BSD style archive
-files. However, right now it can only write in the GNU format. If an
-SVR4 or BSD style archive is used with the ``r`` (replace) or ``q`` (quick
-update) operations, the archive will be reconstructed in GNU format.
+The :program:`llvm-ar` command is similar to the common Unix utility,
+:program:`ar`. It archives several files, such as objects and LLVM bitcode
+files into a single archive library that can be linked into a program. However,
+the archive can contain any kind of file. By default, :program:`llvm-ar`
+generates a symbol table that makes linking faster because only the symbol
+table needs to be consulted, not each individual file member of the archive.
 
-Here's where **llvm-ar** departs from previous ``ar`` implementations:
+The :program:`llvm-ar` command can be used to *read* archive files in SVR4,
+GNU, BSD and Darwin format, and *write* in the GNU, BSD, and Darwin style
+archive files. If an SVR4 format archive is used with the :option:`r`
+(replace), :option:`d` (delete), :option:`m` (move) or :option:`q`
+(quick update) operations, the archive will be reconstructed in the format
+defined by :option:`--format`.
+
+Here's where :program:`llvm-ar` departs from previous :program:`ar` 
+implementations:
+
+*The following option is not supported*
+ 
+ [f] - truncate inserted filenames
+ 
+*The following options are ignored for compatibility*
+
+ --plugin=<string> - load a plugin which adds support for other file formats
+ 
+ [l] - ignored in :program:`ar` 
 
 *Symbol Table*
 
- Since **llvm-ar** supports bitcode files. The symbol table it creates
- is in GNU format and includes both native and bitcode files.
+ Since :program:`llvm-ar` supports bitcode files, the symbol table it creates
+ includes both native and bitcode symbols.
  
-*Long Paths*
+*Deterministic Archives*
 
- Currently **llvm-ar** can read GNU and BSD long file names, but only writes
- archives with the GNU format.
+ By default, :program:`llvm-ar` always uses zero for timestamps and UIDs/GIDs
+ to write archives in a deterministic mode. This is equivalent to the 
+ :option:`D` modifier being enabled by default. If you wish to maintain
+ compatibility with other :program:`ar` implementations, you can pass the
+ :option:`U` modifier to write actual timestamps and UIDs/GIDs.
  
 *Windows Paths*
 
- When on Windows **llvm-ar** treats the names of archived *files* in the same
+ When on Windows :program:`llvm-ar` treats the names of archived *files* in the same
  case sensitive manner as the operating system. When on a non-Windows machine
- **llvm-ar** does not consider character case.
+ :program:`llvm-ar` does not consider character case.
 
 OPTIONS
 -------
 
-The options to **llvm-ar** are compatible with other ``ar`` implementations.
-However, there are a few modifiers (*R*) that are not found in other ``ar``
-implementations. The options to **llvm-ar** specify a single basic operation to
-perform on the archive, a variety of modifiers for that operation, the name of
-the archive file, and an optional list of file names. These options are used to
-determine how **llvm-ar** should process the archive file.
-
-The Operations and Modifiers are explained in the sections below. The minimal
-set of options is at least one operator and the name of the archive. Typically
-archive files end with a ``.a`` suffix, but this is not required. Following
-the *archive-name* comes a list of *files* that indicate the specific members
-of the archive to operate on. If the *files* option is not specified, it
-generally means either "none" or "all" members, depending on the operation.
+:program:`llvm-ar` operations are compatible with other :program:`ar`
+implementations. However, there are a few modifiers (:option:`L`) that are not
+found in other :program:`ar` implementations. The options for 
+:program:`llvm-ar` specify a single basic Operation to perform on the archive,
+a variety of Modifiers for that Operation, the name of the archive file, and an
+optional list of file names. If the *files* option is not specified, it
+generally means either "none" or "all" members, depending on the operation. The
+Options, Operations and Modifiers are explained in the sections below.
+
+The minimal set of options is at least one operator and the name of the
+archive.
 
 Operations
 ~~~~~~~~~~
 
-d
+.. option:: d [NT]
+
+ Delete files from the ``archive``. The :option:`N` and :option:`T` modifiers
+ apply to this operation. The *files* options specify which members should be
+ removed from the archive. It is not an error if a specified file does not
+ appear in the archive. If no *files* are specified, the archive is not
+ modified.
 
- Delete files from the archive. No modifiers are applicable to this operation.
- The *files* options specify which members should be removed from the
- archive. It is not an error if a specified file does not appear in the archive.
- If no *files* are specified, the archive is not modified.
+.. option:: m [abi]
 
-m[abi]
+ Move files from one location in the ``archive`` to another. The :option:`a`,
+ :option:`b`, and :option:`i` modifiers apply to this operation. The *files*
+ will all be moved to the location given by the modifiers. If no modifiers are
+ used, the files will be moved to the end of the archive. If no *files* are
+ specified, the archive is not modified.
 
- Move files from one location in the archive to another. The *a*, *b*, and
- *i* modifiers apply to this operation. The *files* will all be moved
- to the location given by the modifiers. If no modifiers are used, the files
- will be moved to the end of the archive. If no *files* are specified, the
- archive is not modified.
+.. option:: p [v]
 
-p
+ Print *files* to the standard output stream. If no *files* are specified, the
+ entire ``archive`` is printed. With the :option:`v` modifier,
+ :program:`llvm-ar` also prints out the name of the file being output. Printing
+ binary files is  ill-advised as they might confuse your terminal settings. The
+ :option:`p` operation never modifies the archive.
 
- Print files to the standard output. This operation simply prints the
- *files* indicated to the standard output. If no *files* are
- specified, the entire  archive is printed.  Printing bitcode files is
- ill-advised as they might confuse your terminal settings. The *p*
- operation never modifies the archive.
+.. option:: q [LT]
 
-q
+ Quickly append files to the end of the ``archive`` without removing
+ duplicates. If no *files* are specified, the archive is not modified. The
+ behavior when appending one archive to another depends upon whether the
+ :option:`L` and :option:`T` modifiers are used:
 
- Quickly append files to the end of the archive.  This operation quickly adds the
- *files* to the archive without checking for duplicates that should be
- removed first. If no *files* are specified, the archive is not modified.
- Because of the way that **llvm-ar** constructs the archive file, its dubious
- whether the *q* operation is any faster than the *r* operation.
+ * Appending a regular archive to a regular archive will append the archive
+   file. If the :option:`L` modifier is specified the members will be appended
+   instead.
 
-r[abu]
+ * Appending a regular archive to a thin archive requires the :option:`T`
+   modifier and will append the archive file. The :option:`L` modifier is not
+   supported.
 
- Replace or insert file members. The *a*, *b*,  and *u*
- modifiers apply to this operation. This operation will replace existing
- *files* or insert them at the end of the archive if they do not exist. If no
- *files* are specified, the archive is not modified.
+ * Appending a thin archive to a regular archive will append the archive file.
+   If the :option:`L` modifier is specified the members will be appended
+   instead.
 
-t[vO]
+ * Appending a thin archive to a thin archive will always quick append its
+   members.
+
+.. option:: r [abTu]
+
+ Replace existing *files* or insert them at the end of the ``archive`` if
+ they do not exist. The :option:`a`, :option:`b`, :option:`T` and :option:`u`
+ modifiers apply to this operation. If no *files* are specified, the archive
+ is not modified.
+ 
+t[v]
+.. option:: t [vO]
 
  Print the table of contents. Without any modifiers, this operation just prints
- the names of the members to the standard output. With the *v* modifier,
- **llvm-ar** also prints out the file type (B=bitcode, S=symbol
- table, blank=regular file), the permission mode, the owner and group, the
- size, and the date. With the :option:`O` modifier, display member offsets.
- If any *files* are specified, the listing is only for those files. If no
- *files* are specified, the table of contents for the whole archive is printed.
-
-x[oP]
-
- Extract archive members back to files. The *o* modifier applies to this
- operation. This operation retrieves the indicated *files* from the archive
- and writes them back to the operating system's file system. If no
- *files* are specified, the entire archive is extract.
+ the names of the members to the standard output stream. With the :option:`v`
+ modifier, :program:`llvm-ar` also prints out the file type (B=bitcode,
+ S=symbol table, blank=regular file), the permission mode, the owner and group,
+ are ignored when extracting *files* and set to placeholder values when adding
+ size, and the date. With the :option:`O` modifier, display member offsets. If
+ any *files* are specified, the listing is only for those files. If no *files*
+ are specified, the table of contents for the whole archive is printed.
+ 
+.. option:: V
+
+ A synonym for the :option:`--version` option. 
+
+.. option:: x [oP]
+
+ Extract ``archive`` members back to files. The :option:`o` modifier applies
+ to this operation. This operation retrieves the indicated *files* from the
+ archive and writes them back to the operating system's file system. If no
+ *files* are specified, the entire archive is extracted.
 
 Modifiers (operation specific)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The modifiers below are specific to certain operations. See the Operations
-section (above) to determine which modifiers are applicable to which operations.
+section to determine which modifiers are applicable to which operations.
+
+.. option:: a
+
+ When inserting or moving member files, this option specifies the destination
+ of the new files as being after the *relpos* member. If *relpos* is not found,
+ the files are placed at the end of the ``archive``. *relpos* cannot be
+ consumed without either :option:`a`, :option:`b` or :option:`i`.
+
+.. option:: b
+
+ When inserting or moving member files, this option specifies the destination
+ of the new files as being before the *relpos* member. If *relpos* is not
+ found, the files are placed at the end of the ``archive``. *relpos* cannot
+ be consumed without either :option:`a`, :option:`b` or :option:`i`. This
+ modifier is identical to the :option:`i` modifier.
 
-[a]
+.. option:: i
 
- When inserting or moving member files, this option specifies the destination of
- the new files as being after the *relpos* member. If *relpos* is not found,
- the files are placed at the end of the archive.
+ A synonym for the :option:`b` option. 
 
-[b]
+.. option:: L
 
- When inserting or moving member files, this option specifies the destination of
- the new files as being before the *relpos* member. If *relpos* is not
- found, the files are placed at the end of the archive. This modifier is
- identical to the *i* modifier.
+ When quick appending an ``archive``, instead quick append its members. This
+ is a feature for :program:`llvm-ar` that is not found in gnu-ar.
 
-[i]
+.. option:: N
 
- A synonym for the *b* option.
+ When extracting or deleting a member that shares its name with another member,
+ the *count* parameter allows you to supply a positive whole number that
+ selects the instance of the given name, with "1" indicating the first
+ instance. If :option:`N` is not specified the first member of that name will
+ be selected. If *count* is not supplied, the operation fails.*count* cannot be
  
-[o]
+.. option:: o
 
- When extracting files, this option will cause **llvm-ar** to preserve the
- original modification times of the files it writes.
+ When extracting files, use the modification times of any *files* as they
+ appear in the ``archive``. By default *files* extracted from the archive
+ use the time of extraction.
  
 .. option:: O
 
  Display member offsets inside the archive.
 
-[u]
+.. option:: T
 
- When replacing existing files in the archive, only replace those files that have
- a time stamp than the time stamp of the member in the archive.
+ When creating or modifying an archive, this option specifies that the
+ ``archive`` will be thin. By default, archives are not created as thin
+ archives and when modifying a thin archive, it will be converted to a regular
+ archive.
+
+.. option:: v
+
+ When printing *files* or the ``archive`` table of contents, this modifier
+ instructs :program:`llvm-ar` to include additional information in the output.
 
 Modifiers (generic)
 ~~~~~~~~~~~~~~~~~~~
 
 The modifiers below may be applied to any operation.
 
-[c]
+.. option:: c
+
+ For the :option:`r` (replace)and :option:`q` (quick update) operations,
+ :program:`llvm-ar` will always create the archive if it doesn't exist.
+ Normally, :program:`llvm-ar` will print a warning message indicating that the
+ ``archive`` is being created. Using this modifier turns off
+ that warning.
+
+.. option:: D
 
- For all operations, **llvm-ar** will always create the archive if it doesn't
- exist. Normally, **llvm-ar** will print a warning message indicating that the
- archive is being created. Using this modifier turns off that warning.
+ Use zero for timestamps and UIDs/GIDs. This is set by default.
 
+.. option:: P
 
-[s]
+ Use full paths when matching member names rather than just the file name.
+ This can be useful when manipulating an ``archive`` generated by another
+ archiver, as some allow paths as member names. This is the default behavior
+ for thin archives.
+
+.. option:: s
 
  This modifier requests that an archive index (or symbol table) be added to the
- archive. This is the default mode of operation. The symbol table will contain
- all the externally visible functions and global variables defined by all the
- bitcode files in the archive.
-
-[S]
-
- This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to
- not build the symbol table. If both *s* and *S* are used, the last modifier to
- occur in the options will prevail.
-
-[v]
-
- This modifier instructs **llvm-ar** to be verbose about what it is doing. Each
- editing operation taken against the archive will produce a line of output saying
- what is being done.
-
-STANDARDS
----------
-
-The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2
-(POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or
-macOS) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations
-then **llvm-ar** will write SVR4 compatible archives. Without this modifier,
-**llvm-ar** will write BSD4.4 compatible archives that have long names
-immediately after the header and indicated using the "#1/ddd" notation for the
-name in the header.
+ ``archive``, as if using ranlib. The symbol table will contain all the
+ externally visible functions and global variables defined by all the bitcode
+ files in the archive. By default :program:`llvm-ar` generates symbol tables in
+ archives. This can also be used as an operation.
 
-FILE FORMAT
------------
+.. option:: S
 
-The file format for LLVM Archive files is similar to that of BSD 4.4 or macOS
-archive files. In fact, except for the symbol table, the ``ar`` commands on those
-operating systems should be able to read LLVM archive files. The details of the
-file format follow.
-
-Each archive begins with the archive magic number which is the eight printable
-characters "!<arch>\n" where \n represents the newline character (0x0A).
-Following the magic number, the file is composed of even length members that
-begin with an archive header and end with a \n padding character if necessary
-(to make the length even). Each file member is composed of a header (defined
-below), an optional newline-terminated "long file name" and the contents of
-the file.
-
-The fields of the header are described in the items below. All fields of the
-header contain only ASCII characters, are left justified and are right padded
-with space characters.
-
-name - char[16]
-
- This field of the header provides the name of the archive member. If the name is
- longer than 15 characters or contains a slash (/) character, then this field
- contains ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/``
- is literal.  In this case, the actual name of the file is provided in the ``nnn``
- bytes immediately following the header. If the name is 15 characters or less, it
- is contained directly in this field and terminated with a slash (/) character.
-
-date - char[12]
-
- This field provides the date of modification of the file in the form of a
- decimal encoded number that provides the number of seconds since the epoch
- (since 00:00:00 Jan 1, 1970) per Posix specifications.
-
-uid - char[6]
-
- This field provides the user id of the file encoded as a decimal ASCII string.
- This field might not make much sense on non-Unix systems. On Unix, it is the
- same value as the st_uid field of the stat structure returned by the stat(2)
- operating system call.
-
-gid - char[6]
-
- This field provides the group id of the file encoded as a decimal ASCII string.
- This field might not make much sense on non-Unix systems. On Unix, it is the
- same value as the st_gid field of the stat structure returned by the stat(2)
- operating system call.
-
-mode - char[8]
-
- This field provides the access mode of the file encoded as an octal ASCII
- string. This field might not make much sense on non-Unix systems. On Unix, it
- is the same value as the st_mode field of the stat structure returned by the
- stat(2) operating system call.
-
-size - char[10]
-
- This field provides the size of the file, in bytes, encoded as a decimal ASCII
- string.
-
-fmag - char[2]
-
- This field is the archive file member magic number. Its content is always the
- two characters back tick (0x60) and newline (0x0A). This provides some measure
- utility in identifying archive files that have been corrupted.
-
-offset - vbr encoded 32-bit integer
-
- The offset item provides the offset into the archive file where the bitcode
- member is stored that is associated with the symbol. The offset value is 0
- based at the start of the first "normal" file member. To derive the actual
- file offset of the member, you must add the number of bytes occupied by the file
- signature (8 bytes) and the symbol tables. The value of this item is encoded
- using variable bit rate encoding to reduce the size of the symbol table.
- Variable bit rate encoding uses the high bit (0x80) of each byte to indicate
- if there are more bytes to follow. The remaining 7 bits in each byte carry bits
- from the value. The final byte does not have the high bit set.
-
-length - vbr encoded 32-bit integer
-
- The length item provides the length of the symbol that follows. Like this
- *offset* item, the length is variable bit rate encoded.
-
-symbol - character array
-
- The symbol item provides the text of the symbol that is associated with the
- *offset*. The symbol is not terminated by any character. Its length is provided
- by the *length* field. Note that is allowed (but unwise) to use non-printing
- characters (even 0x00) in the symbol. This allows for multiple encodings of
- symbol names.
+ This modifier is the opposite of the :option:`s` modifier. It instructs
+ :program:`llvm-ar` to not build the symbol table. If both :option:`s` and
+ :option:`S` are used, the last modifier to occur in the options will prevail.
  
-EXIT STATUS
+.. option:: u
+
+ Only update ``archive`` members with *files* that have more recent
+ timestamps.
+ 
+.. option:: U
+
+ Use actual timestamps and UIDs/GIDs.
+
+Other
+~~~~~
+
+.. option:: --format=<type>
+
+ This option allows for default, gnu, darwin or bsd ``<type>`` to be selected.
+ When creating an ``archive``, ``<type>`` will default to that of the host
+ machine.
+
+.. option:: -h, --help
+
+ Print a summary of command-line options and their meanings.
+
+.. option:: -M
+
+ This option allows for MRI scripts to be read through the standard input
+ stream. No other options are compatible with this option.
+
+.. option:: --version
+
+ Display the version of the :program:`llvm-ar` executable.
+
+.. option:: @<FILE>
+
+  Read command-line options and commands from response file ``<FILE>``.
+
+MRI SCRIPTS
 -----------
 
-If **llvm-ar** succeeds, it will exit with 0.  A usage error, results
-in an exit code of 1. A hard (file system typically) error results in an
-exit code of 2. Miscellaneous or unknown errors result in an
-exit code of 3.
+:program:`llvm-ar` understands a subset of the MRI scripting interface commonly
+supported by archivers following in the ar tradition. An MRI script contains a
+sequence of commands to be executed by the archiver. The :option:`-M` option
+allows for an MRI script to be passed to :program:`llvm-ar` through the
+standard input stream. 
  
-SEE ALSO
---------
+Note that :program:`llvm-ar` has known limitations regarding the use of MRI
+scripts:
+ 
+* Each script can only create one archive.
+* Existing archives can not be modified.
+
+MRI Script Commands
+~~~~~~~~~~~~~~~~~~~
+
+Each command begins with the command's name and must appear on its own line.
+Some commands have arguments, which must be separated from the name by
+whitespace. An MRI script should begin with either a :option:`CREATE` or
+:option:`CREATETHIN` command and will typically end with a :option:`SAVE`
+command. Any text after either '*' or ';' is treated as a comment.
+
+.. option:: CREATE archive
+
+ Begin creation of a regular archive with the specified name. Subsequent
+ commands act upon this ``archive``.
+
+.. option:: CREATETHIN archive
+
+ Begin creation of a thin archive with the specified name. Subsequent
+ commands act upon this ``archive``.
+
+.. option:: ADDLIB archive
+
+ Append the contents of ``archive`` to the current archive.
+
+.. option:: ADDMOD <file>
+
+ Append ``<file>`` to the current archive.
+
+.. option:: DELETE <file>
+
+ Delete the member of the current archive whose file name, excluding directory
+ components, matches ``<file>``.
+
+.. option:: SAVE
+
+ Write the current archive to the path specified in the previous
+ :option:`CREATE`/:option:`CREATETHIN` command.
+
+.. option:: END
+
+ Ends the MRI script (optional).
+
+EXIT STATUS
+-----------
 
-ar(1)
+If :program:`llvm-ar` succeeds, it will exit with 0.  Otherwise, if an error occurs, it
+will exit with a non-zero value.