# ar

#### create and maintain library archives

## Synopsis

    ar [-][dprtx][cuv] archive [file ...]

## Options

- | The - is optional for introducing `ar` command-line arguments; this is a POSIX requirement, and I've never seen anyone use it.
c | Don't print a diagnostic message to stderr when archive is created.
d | Delete file(s) from archive.
p | Write the contents of the named file(s) to stdout. If no file(s) are specified, all of the files in archive are written in the order of the archive.
r | Replace or add file(s) to the archive. This will create archive if it doesn't already exist.
t | Write the table of contents of archive to stdout. If not file(s) are specified, list all of the files, otherwise only list the specified files.
u | Update older files. When used with the r option, files within the archive are only replaced if file has a modification date at least as new as the file already in the archive.
v | Give verbose output.
x | Extract file(s) from the archive. If no file(s) are specified, all of the files in archive are extracted.
archive | The pathname of an archive file.
file | One more more pathnames of object files; only the file name is used when comparing against the names of files in the archive.

## Description

The `ar` utility creates and maintains groups of files combined into a library. Once a library has been created, you can add new files, and extract, delete, or replace existing files.

## Exit status

`ar` exits with one of the following values:

0 | Successful completion.
> 0 | An error occurred.

## Bugs

No known bugs, but please read the comments in the code if you want to use it in another application.

## Comments

This is a POSIX 1003.2-1992 based `ar` command; it's not 100% POSIX 1003.2 because POSIX specifies a file format for `ar` archives. The BeOS `ar` produces library files compatible (at least in theory `:-)`) with Metrowerks CodeWarrior for PowerPC.

This `ar` and its source code were written as a service to the Be developer community, to make it easier for us to port UNIX applications and libraries. The code was written from scratch, after reverse-engineering the Metrowerks library and object file format (mostly because the library/object file format documentation was incorrect).

If you find this useful, please let me know, and tell me what you're working on. Be sure to include a URL for your homepage or your product homepages for my Be Community pages.

If you find any bugs, please try to fix them, and send me a context diff (use `diff -c original_file fixed_file`) so I can include your fixes in the next update. I have tested this, but these things have a way of slipping though.

If you'd like to know what other things I'm working on, take a look at my Be Software pages, and my Be Happy! pages.

## License

This program binary and its source code have been donated to the BeOS Developer Community by Arcane Dragon Software free of charge. You can do whatever you want with it.

If you really want to show your appreciation, you could always send me a gift of some sort; cool software you wrote, nice pictures for my desktop, ZIP drive disks, RAM, hard drives, post cards, a pointer to a really cool/useful/interesting web site, an MPEG audio file of an interesting band (make sure you can give me enough information to track down their CDs if I like it!), etc. Send me some email and I'll let you know where to send it.

But you don't have to do anything. Just write good BeOS software. But you're already doing that, right?

## Disclaimer

You use this at your own risk. I've tried to ensure that the code is correct, but software usually has bugs. If `ar` destroys your valuable data, formats your hard drive, kicks your cat, and lets the air out of your tires, I'm not responsible for it. The code is here, so you should feel fairly safe that there's nothing evil going on.

And, as I learned once again in December 1997, you really should keep backups of everything. I only lost a day's work, but it was still annoying, and it could've been much, much worse.

### A word about the code

This code isn't meant to be the ultimate in efficiency or speed, it's intended to be fairly easy to understand and maintain (hopefully). I was also quite keen on having something that was correct, without jumping through a lot of unnecessary hoops.

If you think this code sucks, don't use it. You're already applying this to your choice of operating system! `:-)`

## Versions

1.1 (April 18, 1998)
  Changes include:
  - Extract option (x) will preserve a file's mode bits when overwriting an existing file (this may go away if it's not POSIX behaviour).
  - Extracted files will now have the proper file type.
  - Removed attempt to use umask() to set newly created archive's mode bits; apparently, I'm not sure how it works and my POSIX manual isn't helping.
  - Should be 100% endian-neutral now; using this on BeOS for x86 is only useful if you're manipulating PowerPC objects though. The `ar` in GeekGadgets should work fine for x86 objects/libraries.
  - Updated the `README.txt` file; now it's got useful information about building/using the POSIX ar.
1.0 (January 13, 1998)
  Initial release.

Chris Herborth (chrish@qnx.com)

Last modified: $Date$