BeOS/ar-1.1/docs/ar.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML3.2//EN">
   2 <!-- $Id$ -->
   3 <html> <head>
   4 <title>ar - create and maintain library archives</title>
   5 </head>
   6
   7 <body bgcolor="#ffffcb">
   8 <h1>ar</h1>
   9 <h4 align="right">create and maintain library archives</h4>
  10
  11 <h2>Synopsis</h2>
  12
  13 <pre>
  14 ar [-][dprtx][cuv] <i>archive</i> [<i>file</i> ...]
  15 </pre>
  16
  17 <h2>Options</h2>
  18
  19 <table>
  20 <tr>
  21         <td valign="top"><b>-</b></td>
  22         <td valign="top">
  23         The <b>-</b> is optional for introducing <tt>ar</tt> command-line
  24         arguments; this is a POSIX requirement, and I've never seen anyone
  25         use it.</td>
  26 </tr>
  27
  28 <tr>
  29         <td valign="top"><b>c</b></td>
  30         <td valign="top">
  31         Don't print a diagnostic message to <i>stderr</i> when
  32         <i>archive</i> is created.</td>
  33 </tr>
  34
  35 <tr>
  36         <td valign="top"><b>d</b></td>
  37         <td valign="top">
  38         Delete <i>file(s)</i> from <i>archive</i>.</td>
  39 </tr>
  40
  41 <tr>
  42         <td valign="top"><b>p</b></td>
  43         <td valign="top">
  44         Write the contents of the named <i>file(s)</i> to <i>stdout</i>.
  45         If no <i>file(s)</i> are specified, all of the files in
  46         <i>archive</i> are written in the order of the archive.</td>
  47 </tr>
  48
  49 <tr>
  50         <td valign="top"><b>r</b></td>
  51         <td valign="top">
  52         Replace or add <i>file(s)</i> to the <i>archive</i>.  This will
  53         create <i>archive</i> if it doesn't already exist.</td>
  54 </tr>
  55
  56 <tr>
  57         <td valign="top"><b>t</b></td>
  58         <td valign="top">
  59         Write the table of contents of <i>archive</i> to <i>stdout</i>.
  60         If not <i>file(s)</i> are specified, list all of the files,
  61         otherwise only list the specified files.</td>
  62 </tr>
  63
  64 <tr>
  65         <td valign="top"><b>u</b></td>
  66         <td valign="top">
  67         Update older files.  When used with the <b>r</b> option, files
  68         within the archive are only replaced if <i>file</i> has a
  69         modification date at least as new as the <i>file</i> already in
  70         the archive.</td>
  71 </tr>
  72
  73 <tr>
  74         <td valign="top"><b>v</b></td>
  75         <td valign="top">Give verbose output.</td>
  76 </tr>
  77
  78 <tr>
  79         <td valign="top"><b>x</b></td>
  80         <td valign="top">
  81         Extract <i>file(s)</i> from the <i>archive</i>.  If no
  82         <i>file(s)</i> are specified, all of the files in <i>archive</i>
  83         are extracted.</td>
  84 </tr>
  85
  86 <tr>
  87         <td valign="top"><i>archive</i></td>
  88         <td valign="top">
  89         The pathname of an archive file.</td>
  90 </tr>
  91
  92 <tr>
  93         <td valign="top"><i>file</i></td>
  94         <td valign="top">
  95         One more more pathnames of object files; only the file name is
  96         used when comparing against the names of files in the
  97         archive.</td>
  98 </tr>
  99
 100 </table>
 101
 102 <h2>Description</h2>
 103
 104 <p>The <tt>ar</tt> utility creates and maintains groups of files
 105 combined into a library.  Once a library has been created, you can
 106 add new files, and extract, delete, or replace existing files.</p>
 107
 108 <h2>Exit status</h2>
 109
 110 <p><tt>ar</tt> exits with one of the following values:</p>
 111
 112 <table>
 113 <tr><td valign="top">0</td>
 114         <td valign="top">Successful completion.</td></tr>
 115 <tr><td valign="top">&gt; 0</td>
 116         <td>An error occurred.</td></tr>
 117 </table>
 118
 119 <h2>Bugs</h2>
 120
 121 <p>No known bugs, but <em>please</em> read the comments in the code if
 122 you want to use it in another application.</p>
 123
 124 <h2>Comments</h2>
 125
 126 <p>This is a POSIX 1003.2-1992 based <tt>ar</tt> command; it's not
 127 100% POSIX 1003.2 because POSIX specifies a file format for
 128 <tt>ar</tt> archives.  The BeOS <tt>ar</tt> produces library files
 129 compatible (at least in theory <tt>:-)</tt>) with Metrowerks
 130 CodeWarrior for PowerPC.</p>
 131
 132 <p>This <tt>ar</tt> and its source code were written as a service to
 133 the Be developer community, to make it easier for us to port UNIX
 134 applications and libraries.  The code was written from scratch, after
 135 reverse-engineering the Metrowerks library and object file format
 136 (mostly because the library/object file format documentation was
 137 incorrect).</p>
 138
 139 <p>If you find this useful, please
 140 <a href="mailto:chrish@kagi.com">let me know</a>, and tell me what
 141 you're working on.  Be sure to include a URL for your homepage or your
 142 product homepages for my
 143 <a href="http://www.qnx.com/~chrish/Be/community/">Be Community</a>
 144 pages.</p>
 145
 146 <p>If you find any bugs, please try to fix them, and send me a context
 147 diff (use <tt>diff -c original_file fixed_file</tt>) so I can include
 148 your fixes in the next update.  I <i>have</i> tested this, but these
 149 things have a way of slipping though.</p>
 150
 151 <p>If you'd like to know what other things I'm working on, take a look
 152 at my <a href="http://www.qnx.com/~chrish/Be/software/">Be
 153 Software</a> pages, and my
 154 <a href="http://www.qnx.com/~chrish/Be/">Be Happy!</a> pages.</p>
 155
 156 <h2>License</h2>
 157
 158 <p>This program binary and its source code have been donated to the
 159 BeOS Developer Community by Arcane Dragon Software free of charge.
 160 You can do whatever you want with it.</p>
 161
 162 <p>If you <em>really</em> want to show your appreciation, you could
 163 always send me a gift of some sort; cool software you wrote, nice
 164 pictures for my desktop, ZIP drive disks, RAM, hard drives, post
 165 cards, a pointer to a really cool/useful/interesting web site,
 166 an MPEG audio file of an interesting band (make sure you can give me
 167 enough information to track down their CDs if I like it!), <i>etc.</i>
 168 Send me some <a href="mailto:chrish@kagi.com">email</a> and I'll let you
 169 know where to send it.</p>
 170
 171 <p>But you don't have to do anything.  Just write good BeOS software.
 172 But you're already doing that, right?</p>
 173
 174 <h2>Disclaimer</h2>
 175
 176 <p>You use this at your own risk.  I've tried to ensure that the code
 177 is correct, but software usually has bugs.  If <tt>ar</tt> destroys
 178 your valuable data, formats your hard drive, kicks your cat, and lets
 179 the air out of your tires, I'm not responsible for it.  The code is
 180 here, so you should feel fairly safe that there's nothing evil going
 181 on.</p>
 182
 183 <p>And, as I learned once again in December 1997, you really should
 184 keep backups of everything.  I only lost a day's work, but it was
 185 still annoying, and it could've been much, much worse.</p>
 186
 187 <h3>A word about the code</h3>
 188
 189 <p>This code isn't meant to be the ultimate in efficiency or speed,
 190 it's intended to be fairly easy to understand and maintain
 191 (hopefully).  I was also quite keen on having something that was
 192 correct, without jumping through a lot of unnecessary hoops.</p>
 193
 194 <p>If you think this code sucks, don't use it.  You're already applying
 195 this to your choice of operating system!  <tt>:-)</tt></p>
 196
 197 <h2>Versions</h2>
 198
 199 <dl compact>
 200
 201 <dt><strong>1.1 (April 18, 1998)</strong></dt>
 202 <dd>Changes include:
 203         <ul>
 204           <li>Extract option (<b>x</b>) will preserve a file's mode bits
 205                   when overwriting an existing file (this may go away if it's
 206                   not POSIX behaviour).</li>
 207
 208           <li>Extracted files will now have the proper file type.</li>
 209
 210           <li>Removed attempt to use <i>umask()</i> to set newly created
 211                   archive's mode bits; apparently, I'm not sure how it
 212                   works and my POSIX manual isn't helping.</li>
 213
 214           <li>Should be 100% endian-neutral now; using this on BeOS for
 215                   x86 is only useful if you're manipulating <em>PowerPC</em>
 216                   objects though.  The <tt>ar</tt> in
 217                   <a href="http://www.ninemoons.com/GG/index.html">GeekGadgets</a>
 218                   should work fine for x86 objects/libraries.</li>
 219
 220           <li>Updated the <tt>README.txt</tt> file; now it's got useful
 221                   information about building/using the POSIX ar.</li>
 222         </ul></dd>
 223
 224 <dt><strong>1.0 (January 13, 1998)</strong></dt>
 225 <dd>Initial release.</dd>
 226
 227 </dl>
 228
 229 <hr>
 230 <p>Chris Herborth (<a href="mailto:chrish@qnx.com">chrish@qnx.com</a>)</p>
 231 <!-- hhmts start -->
 232 Last modified: $Date$
 233 <!-- hhmts end -->
 234 </body> </html>