doc/binutils.html/ar.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1991-2021 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts.  A copy of the license is included in the
section entitled "GNU Free Documentation License".
 -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Binary Utilities: ar</title>

<meta name="description" content="GNU Binary Utilities: ar">
<meta name="keywords" content="GNU Binary Utilities: ar">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Binutils-Index.html#Binutils-Index" rel="index" title="Binutils Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="index.html#Top" rel="up" title="Top">
<link href="ar-cmdline.html#ar-cmdline" rel="next" title="ar cmdline">
<link href="index.html#Top" rel="previous" title="Top">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="ar"></a>
<div class="header">
<p>
Next: <a href="nm.html#nm" accesskey="n" rel="next">nm</a>, Previous: <a href="index.html#Top" accesskey="p" rel="previous">Top</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Binutils-Index.html#Binutils-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="ar-1"></a>
<h2 class="chapter">1 ar</h2>

<a name="index-ar"></a>
<a name="index-archives"></a>
<a name="index-collections-of-files"></a>


<div class="smallexample">
<pre class="smallexample">ar [-]<var>p</var>[<var>mod</var>] [<samp>--plugin</samp> <var>name</var>] [<samp>--target</samp> <var>bfdname</var>] [<samp>--output</samp> <var>dirname</var>] [<samp>--record-libdeps</samp> <var>libdeps</var>] [<var>relpos</var>] [<var>count</var>] <var>archive</var> [<var>member</var>&hellip;]
ar -M [ &lt;mri-script ]
</pre></div>


<p>The <small>GNU</small> <code>ar</code> program creates, modifies, and extracts from
archives.  An <em>archive</em> is a single file holding a collection of
other files in a structure that makes it possible to retrieve
the original individual files (called <em>members</em> of the archive).
</p>
<p>The original files&rsquo; contents, mode (permissions), timestamp, owner, and
group are preserved in the archive, and can be restored on
extraction.
</p>
<a name="index-name-length"></a>
<p><small>GNU</small> <code>ar</code> can maintain archives whose members have names of any
length; however, depending on how <code>ar</code> is configured on your
system, a limit on member-name length may be imposed for compatibility
with archive formats maintained with other tools.  If it exists, the
limit is often 15 characters (typical of formats related to a.out) or 16
characters (typical of formats related to coff).
</p>
<a name="index-libraries"></a>
<p><code>ar</code> is considered a binary utility because archives of this sort
are most often used as <em>libraries</em> holding commonly needed
subroutines.  Since libraries often will depend on other libraries,
<code>ar</code> can also record the dependencies of a library when the
<samp>--record-libdeps</samp> option is specified.
</p>
<a name="index-symbol-index"></a>
<p><code>ar</code> creates an index to the symbols defined in relocatable
object modules in the archive when you specify the modifier &lsquo;<samp>s</samp>&rsquo;.
Once created, this index is updated in the archive whenever <code>ar</code>
makes a change to its contents (save for the &lsquo;<samp>q</samp>&rsquo; update operation).
An archive with such an index speeds up linking to the library, and
allows routines in the library to call each other without regard to
their placement in the archive.
</p>
<p>You may use &lsquo;<samp>nm -s</samp>&rsquo; or &lsquo;<samp>nm --print-armap</samp>&rsquo; to list this index
table.  If an archive lacks the table, another form of <code>ar</code> called
<code>ranlib</code> can be used to add just the table.
</p>
<a name="index-thin-archives"></a>
<p><small>GNU</small> <code>ar</code> can optionally create a <em>thin</em> archive,
which contains a symbol index and references to the original copies
of the member files of the archive.  This is useful for building
libraries for use within a local build tree, where the relocatable
objects are expected to remain available, and copying the contents of
each object would only waste time and space.
</p>
<p>An archive can either be <em>thin</em> or it can be normal.  It cannot
be both at the same time.  Once an archive is created its format
cannot be changed without first deleting it and then creating a new
archive in its place.
</p>
<p>Thin archives are also <em>flattened</em>, so that adding one thin
archive to another thin archive does not nest it, as would happen with
a normal archive.  Instead the elements of the first archive are added
individually to the second archive.
</p>
<p>The paths to the elements of the archive are stored relative to the
archive itself.
</p>
<a name="index-compatibility_002c-ar"></a>
<a name="index-ar-compatibility"></a>
<p><small>GNU</small> <code>ar</code> is designed to be compatible with two different
facilities.  You can control its activity using command-line options,
like the different varieties of <code>ar</code> on Unix systems; or, if you
specify the single command-line option <samp>-M</samp>, you can control it
with a script supplied via standard input, like the MRI &ldquo;librarian&rdquo;
program.
</p>

<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top">&bull; <a href="ar-cmdline.html#ar-cmdline" accesskey="1">ar cmdline</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Controlling <code>ar</code> on the command line
</td></tr>
<tr><td align="left" valign="top">&bull; <a href="ar-scripts.html#ar-scripts" accesskey="2">ar scripts</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Controlling <code>ar</code> with a script
</td></tr>
</table>

<hr>
<div class="header">
<p>
Next: <a href="nm.html#nm" accesskey="n" rel="next">nm</a>, Previous: <a href="index.html#Top" accesskey="p" rel="previous">Top</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Binutils-Index.html#Binutils-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>