home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / cpm / cug / softt-5.lbr / AR_VER1.DQC / AR_VER1.DOC
Encoding:
Text File  |  1984-07-05  |  6.1 KB  |  240 lines
  1. .bp 1
  2. .in 0
  3. .he 'AR (1)'09/16/80'AR (1)'
  4. .fo ''-#-'
  5. .fi
  6. .in 7
  7. .ti -7
  8. NAME
  9. .br
  10. ar - archive file maintainer
  11. .sp 1
  12. .ti -7
  13. SYNOPSIS
  14. .br
  15. ar [-](d|p|t|u|x)[v] arcname [files]
  16. .sp 1
  17. .ti -7
  18. DESCRIPTION
  19. .br
  20. Ar collects sets of arbitrary files into one big file and
  21. maintains that file as an 'archive'.
  22. Files can be extracted from the archive, new ones can be added,
  23. old ones can be deleted or replaced by updated versions, and
  24. data about the contents can be listed.
  25.  
  26. If a minus sign ('-') is given as a file name, further file names
  27. are read from the standard input, one file name per line.
  28.  
  29. Files that are to be added to an archive must exist as
  30. files with the name given.  Files that are extracted from
  31. an archive will be put onto files with the name given.
  32. Files that are added to archives can, of course, be archive files
  33. themselves.  There is no (theoretical) limit to the number
  34. of files that can be nested this way.
  35. Thus AR provides the utility necessary to maintain tree-structured
  36. file directories.
  37.  
  38. AR is invoked by the command line
  39. .br
  40.  
  41. .ti +10
  42. AR command archname [optional filenames]
  43.  
  44. where 'command' is any one of 'dptux', optionally concatenated
  45. with 'v', specifying what operation to perform on the
  46. archive file named 'archname'.
  47. The possible commands are:
  48. .br
  49.  
  50. .in +10
  51. u - Update named archive by replacing existing files or adding new
  52. ones at end.
  53. If the 'v' option is used, file names will be printed on the
  54. standard output as files are written to the new archived file.
  55.  
  56. x - Extract named files from archive.  Put onto file of the
  57. same name.
  58. If the 'v' option is added, file names will be printed on the
  59. standard output as files are extracted.
  60.  
  61. d - Delete named files from archive.
  62. If the 'v' option is used, file names will be printed on
  63. the standard output as they are deleted from the archive.
  64.  
  65. p - Print named files on standard output.
  66. Using the 'v' option will cause the file name to precede the file.
  67.  
  68. t - Print table of archive contents.
  69. Normally, the table will contain only the file name.
  70. If the 'v' option is used, the table will also contain
  71. the file's length, type, and date and time of last change.
  72.  
  73. v - Verbose.  This command may be concatenated to any of the above
  74. commands,
  75. and will cause the archiver to print additional information,
  76. generally file names, on the standard output.
  77. Its specific action for each command has already been described.
  78. .br
  79. .in -10
  80.  
  81. The optional filenames in the command line specify individual
  82. files that may participate in the action.
  83. If no files are named, the action is done on ALL files in the archive,
  84. but if any files are explicitly named, they are the ONLY ones that
  85. take part in the action.
  86. (The 'd' command is an exception--files may be deleted only by
  87. specifying their names.)
  88.  
  89.  
  90. .br
  91.  
  92. .sp 1
  93. .ti -7
  94. FILES
  95. .br
  96. A file 'arctemp' is created and subsequently deleted for each run.
  97. .sp 1
  98. .ti -7
  99. SEE ALSO
  100. .br
  101. The Unix commands 'ar' and 'ls' in the Unix manual
  102. .sp 1
  103. .ti -7
  104. DIAGNOSTICS
  105. .br
  106. archive not in proper format
  107. .br
  108. .in +10
  109. The basic problem is that archive didn't find a header
  110. line where one was expected.
  111. Typical reasons include misspelling the file name,
  112. using an existing file (not in archive format)
  113. on a creation run, and
  114. referencing an archive file that has been modified
  115. directly (say with the editor).
  116. .br
  117. .in -10
  118.  
  119. archive integrity in doubt - missing trailer
  120. .br
  121. .in +10
  122. Each file in an archive is terminated by a special line called a
  123. "trailer," which must be present.
  124. The message is caused by the lack of a trailer line when one was
  125. expected.
  126. .br
  127. .in -10
  128.  
  129.  
  130. delete by name only
  131. .br
  132. .in +10
  133. For user protection, files are allowed to be deleted from an archive
  134. only by specifying each file name.
  135. .br
  136. .in -10
  137.  
  138. duplicate file name
  139. .br
  140. .in +10
  141. A file was listed more than once when calling the archiver
  142. .br
  143. .in -10
  144.  
  145. fatal errors-archive not altered
  146. .br
  147. .in +10
  148. This message is generated whenever one or more of the other
  149. errors have been detected.  An archive is never altered unless
  150. EVERYTHING has run properly.
  151. .br
  152. .in -10
  153.  
  154. too many file names
  155. .br
  156. .in +10
  157. At the present the user may call the archiver with no more than
  158. 25 files at a time.
  159. .br
  160. .in -10
  161.  
  162. usage:  ar [-](dptux)[v] arcname [files]
  163. .br
  164. .in +10
  165. The command line passed to the archiver is in error.
  166. Possibly the command is wrong or the archive file name
  167. has not been given.
  168. .br
  169. .in -10
  170.  
  171. 'filename': can't add
  172. .br
  173. .in +10
  174. The file specified by 'filename' doesn't exist or can't be
  175. opened (e. g. is locked).
  176. .br
  177.  
  178. .in -10
  179. 'filename': can't create
  180. .br
  181. .in +10
  182. The archiver could not generate a local file by the name
  183. of 'filename'.  Probably the archiver's internal file
  184. buffer space has been exceeded.
  185. .br
  186.  
  187. .in -10
  188. 'filename': not in archive
  189. .br
  190. .in +10
  191. The archiver could not locate the file specified by 'filename' in
  192. the archived file.
  193. .br
  194.  
  195. .in -10
  196. .sp 1
  197. .ti -7
  198. AUTHORS
  199. .br
  200. Original code from Kernighan and Plauger's 'Software Tools',
  201. with rewrites by Allen Akin (Georgia Institute of Technology)
  202. and minor changes suggested by David Hanson (University
  203. of Arizona).
  204. .sp 1
  205. .ti -7
  206. BUGS/DEFICIENCIES
  207. .br
  208. On some systems only text files can be archived.
  209.  
  210. When the update and print commands are used, the files are
  211. updated or printed
  212. in the order they appear on the
  213. archived file, NOT the order listed on
  214. the command line.
  215.  
  216. The Unix archiver allows files to be positioned in the
  217. archive, rather than simply added at the end as AR does.
  218. This is done by adding the following commands:
  219. .br
  220. .in +10
  221.  
  222. m - Move specified files to end of archive
  223.  
  224. ma posname - Move specified files to position after file 'posname'
  225.  
  226. mb posname - Move specified files to position before file 'posname'
  227.  
  228. r - Replace specified files and place at end of archive
  229.  
  230. ra posname - Replace files and place after file 'posname'
  231.  
  232. rb posname - Replace files and place before file 'posname'
  233. .br
  234. .in -10
  235.  
  236. There are some discrepancies between the Unix version of AR and
  237. this version.  Unix uses 'r'--replace instead of 'u'--update.
  238. Unix also requires the user to specify an additional command 'n'
  239. when creating a new archive.
  240.