

AR                             10/11/79                             AR


NAME
       ar - archive file maintainer

SYNOPSIS
       ar {dpstux}[v/1] arcname [file] ...

DESCRIPTION
       Ar  collects  sets  of  arbitrary  files  into one big file and
       maintains that file as an 'archive'.  Files  can  be  extracted
       from  the  archive,  new  ones  can  be  added, old ones can be
       deleted or replaced by updated versions,  and  data  about  the
       contents can be listed.
       
       If  a  minus  sign  ('-') is given as a file name, further file
       names are read from the standard input, one file name per line.
       
       Files that are to be added to an archive must  exist  as  files
       with  the name given.  Files that are extracted from an archive
       will be put onto files with the  name  given.  Files  that  are
       added  to archives can, of course, be archive files themselves.
       There is no (theoretical) limit to the number of files that can
       be nested this way. Thus AR provides the utility  necessary  to
       maintain tree-structured file directories.
       
       AR is invoked by the command line
       
                 AR command archname [optional filenames]
       
       where 'command' is any one of 'uxtpds', optionally concatenated
       with  'v'  or  '1', specifying what operation to perform on the
       archive file named 'archname'. The possible commands are:
       
                 u - Update named archive by replacing existing  files
                 or adding new ones at end. If the 'v' option is used,
                 file  names will be printed on the standard output as
                 files are written to the new archived file.
                 
                 x - Extract named files from archive.  Put onto  file
                 of  the  same  name. If the 'v' option is added, file
                 names will be printed on the standard output as files
                 are extracted.
                 
                 d - Delete named  files  from  archive.  If  the  'v'
                 option  is  used,  file  names will be printed on the
                 standard output as they are deleted from the archive.
                 
                 p - Print named files on standard output.  Using  the
                 'v'  option  will  cause the file name to precede the
                 file.
                 
                 t - Print table of archive  contents.  Normally,  the


                                 -1-                                  


AR                             10/11/79                             AR


                 table  will  contain  only  the file name. If the 'v'
                 option is used,  the  table  will  also  contain  the
                 file's  length,  type,  and  date  and  time  of last
                 change. By default,  if  the  standard  output  is  a
                 terminal,  ar  will  pack  five names per line in the
                 non-verbose mode.  If  the  optional  '1'  option  is
                 used,  the output is force to single column, which is
                 the default is standard output  is  not  a  terminal.
                 For example,
                 
                 ar t archive
                 
                 might generate the following output:
                 
                 a               b               c               d
                 
                 whereas
                 
                 ar t1 archive
                 
                 would generate
                 
                 a
                 b
                 c
                 d
                 
                 
                 s  -  Salvage.  This command may be used to recover a
                 damaged  archive   whose  character  counts  do   not
                 reflect the correct number of characters in the file.
                 The  's' command extracts all files from the archive,
                 ignoring characters counts,  date  and  time  stamps,
                 etc.  on  the  archive  header  lines; it simply uses
                 '#-h-, which begins each archive member, and the file
                 name which follows it. The files are then replaced in
                 the archive, with corrected character  counts.  Thus,
                 the  's' flag is useful for salvaging the contents of
                 'alien'  archive  files  and   for   saving   damaged
                 archives.  It  does not work on nested archives (i.e.
                 archives within archives).
                 
                 v - Verbose.  This command may be concatenated to any
                 of the above commands, and will cause the archiver to
                 print additional information, generally  file  names,
                 on  the standard output. Its specific action for each
                 command has already been described.
       
       The optional filenames in the command line  specify  individual
       files  that  may  participate  in  the  action. If no files are
       named, the action is done on ALL files in the archive,  but  if


                                 -2-                                  


AR                             10/11/79                             AR


       any  files  are  explicitly  named, they are the ONLY ones that
       take  part  in   the   action.   (The   'd'   command   is   an
       exception--files  may  be  deleted  only  by  specifying  their
       names.)
       
       
       

FILES
       A file 'arctemp' is created and subsequently deleted  for  each
       run.

SEE ALSO
       The Unix commands 'ar' and 'ls' in the Unix manual
       `rar' - rearrange archive

DIAGNOSTICS
       archive not in proper format
                 The  basic  problem  is  that  archive  didn't find a
                 header line where one was expected.  Typical  reasons
                 include  misspelling the file name, using an existing
                 file (not in archive format) on a creation  run,  and
                 referencing  an  archive  file that has been modified
                 directly (say with the editor).
       
       delete by name only
                 For user protection, files are allowed to be  deleted
                 from an archive only by specifying each file name.
       
       duplicate file name
                 A  file  was  listed  more than once when calling the
                 archiver
       
       fatal errors-archive not altered
                 This message is generated whenever one or more of the
                 other errors have been detected.  An archive is never
                 altered unless EVERYTHING has run properly.
       
       too many file names
                 At the present the user may call the archiver with no
                 more than 25 files at a time.
       
       usage:  ar [dptuxsv] arcname [files]
                 The command line passed to the archiver is in  error.
                 Possibly  the  command  is wrong or the archived file
                 name has not been given.
       
       'filename': can't add
                 The file specified by  'filename'  doesn't  exist  or
                 can't be opened (e. g. is locked).
                 


                                 -3-                                  


AR                             10/11/79                             AR


       'filename': can't create
                 The  archiver  could not generate a local file by the
                 name of 'filename'.  Probably the archiver's internal
                 file buffer space has been exceeded.
                 
       'filename': not in archive
                 The archiver could not locate the file  specified  by
                 'filename' in the archived file.
                 

AUTHORS
       Original  code  from  Kernighan and Plauger's 'Software Tools',
       with modifications by Debbie Scherrer.

BUGS/DEFICIENCIES
       On some systems only text files can be archived.
       
       When the update and print commands  are  used,  the  files  are
       updated  or  printed  in  the order they appear on the archived
       file, NOT the order listed on the command line.
       
       The 's' salvage command works only on unnested archives.
       
       The Unix archiver allows files to be positioned in the archive,
       rather than simply added at the end as AR does. This is done by
       adding the following commands:
                 
                 m - Move specified files to end of archive
                 
                 ma posname - Move specified files to  position  after
                 file 'posname'
                 
                 mb  posname - Move specified files to position before
                 file 'posname'
                 
                 r - Replace specified  files  and  place  at  end  of
                 archive
                 
                 ra  posname  -  Replace  files  and  place after file
                 'posname'
                 
                 rb posname - Replace  files  and  place  before  file
                 'posname'
       
       There are some discrepancies between the Unix version of AR and
       this  version.   Unix uses 'r'--replace instead of 'u'--update.
       Unix also requires the user to specify  an  additional  command
       'n' when creating a new archive.





                                 -4-                                  

