

AR (1)                      09/16/80                       AR (1)


NAME
       ar - archive file maintainer

SYNOPSIS
       ar [-](d|p|t|u|x)[v] arcname [files]

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   'dptux',   optionally
       concatenated   with  'v',  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,


                               -1-




AR (1)                      09/16/80                       AR (1)


                 the 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. 
                 
                 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 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

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). 
       
       archive integrity in doubt - missing trailer
                 Each  file  in  an  archive  is  terminated by a
                 special line called a "trailer," which  must  be
                 present.   The  message is caused by the lack of
                 a trailer line when one was expected. 
       
       
       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
       


                               -2-




AR (1)                      09/16/80                       AR (1)


       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 [-](dptux)[v] arcname [files]
                 The  command  line  passed to the archiver is in
                 error.  Possibly the command  is  wrong  or  the
                 archive 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). 
                 
       '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 rewrites by Allen Akin (Georgia Institute of
       Technology) and minor changes suggested  by  David  Hanson
       (University of Arizona). 

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  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


                               -3-




AR (1)                      09/16/80                       AR (1)


                 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-


