| 1 | .\" Copyright (c) 1990 The Regents of the University of California. |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" This code is derived from software contributed to Berkeley by |
| 5 | .\" Hugh Smith at The University of Guelph. |
| 6 | .\" |
| 7 | .\" %sccs.include.redist.man% |
| 8 | .\" |
| 9 | .\" @(#)ar.1 6.8 (Berkeley) %G% |
| 10 | .\" |
| 11 | .TH AR 1 "" |
| 12 | .AT 3 |
| 13 | .SH NAME |
| 14 | ar \- create and maintain library archives |
| 15 | .SH SYNOPSIS |
| 16 | .nf |
| 17 | .ft B |
| 18 | ar -d [-sv] archive file ... |
| 19 | ar -m [-sv] archive file ... |
| 20 | ar -m [-abisv] position archive file ... |
| 21 | ar -p [-sv] archive [file ...] |
| 22 | ar -q [-csv] archive file ... |
| 23 | ar -r [-cusv] archive file ... |
| 24 | ar -r [-abciusv] position archive file ... |
| 25 | ar -t [-sv] archive [file ...] |
| 26 | ar -x [-ousv] archive [file ...] |
| 27 | .fi |
| 28 | .ft R |
| 29 | .SH DESCRIPTION |
| 30 | The |
| 31 | .I ar |
| 32 | utility creates and maintains groups of files combined into an archive. |
| 33 | Once an archive has been created, new files can be added and existing |
| 34 | files can be extracted, deleted, or replaced. |
| 35 | .PP |
| 36 | Files are named in the archive by a single component, i.e., if a file |
| 37 | referenced by a path containing a slash (``/'') is archived it will be |
| 38 | named by the last component of that path. |
| 39 | When matching paths listed on the command line against file names stored |
| 40 | in the archive, only the last component of the path will be compared. |
| 41 | .PP |
| 42 | All informational and error messages use the path listed on the command |
| 43 | archive, not the name entered in the archive unless no name was supplied |
| 44 | on the command line. |
| 45 | If multiple files in the archive have the same name, and paths are listed |
| 46 | on the command line to ``select'' archive files for an operation, only the |
| 47 | .B first |
| 48 | file with a matching name will be selected. |
| 49 | .PP |
| 50 | The normal use of |
| 51 | .I ar |
| 52 | is for the creation and maintenance of libraries suitable for use with |
| 53 | the loader (see |
| 54 | .IR ld (1)) |
| 55 | although it is not restricted to this purpose. |
| 56 | The options are as follows: |
| 57 | .TP |
| 58 | \-a |
| 59 | A positioning modifier used with the options \-r and \-m. |
| 60 | The files are entered or moved |
| 61 | .B after |
| 62 | the archive member |
| 63 | .IR position , |
| 64 | which must be specified. |
| 65 | .TP |
| 66 | \-b |
| 67 | A positioning modifier used with the options \-r and \-m. |
| 68 | The files are entered or moved |
| 69 | .B before |
| 70 | the archive member |
| 71 | .IR position , |
| 72 | which must be specified. |
| 73 | .TP |
| 74 | \-c |
| 75 | Whenever an archive is created, an informational message to that effect |
| 76 | is written to standard error. |
| 77 | If the \-c option is specified, |
| 78 | .I ar |
| 79 | creates the archive silently. |
| 80 | .TP |
| 81 | \-d |
| 82 | Delete the specified archive files. |
| 83 | .TP |
| 84 | \-i |
| 85 | Identical to the \-b option. |
| 86 | .TP |
| 87 | \-m |
| 88 | Move the specified archive files within the archive. |
| 89 | If one of the options \-a, \-b or \-i are specified, the files are moved |
| 90 | before or after the |
| 91 | .I position |
| 92 | file in the archive. |
| 93 | If none of those options are specified, the files are moved |
| 94 | to the end of the archive. |
| 95 | .TP |
| 96 | \-o |
| 97 | Set the access and modification times of extracted files to the |
| 98 | modification time of the file when it was entered into the archive. |
| 99 | This will fail if the user is not the owner of the extracted file |
| 100 | or the super-user. |
| 101 | .TP |
| 102 | \-p |
| 103 | Write the contents of the specified archive files to the standard output. |
| 104 | If no files are specified, the contents of all the files in the archive |
| 105 | are written in the order they appear in the archive. |
| 106 | .TP |
| 107 | \-q |
| 108 | (Quickly) append the specified files to the archive. |
| 109 | If the archive does not exist a new archive file is created. |
| 110 | Much faster than the \-r option, when creating a large archive |
| 111 | piece-by-piece, as no checking is done to see if the files already |
| 112 | exist in the archive. |
| 113 | .TP |
| 114 | \-r |
| 115 | Replace or add the specified files to the archive. |
| 116 | If the archive does not exist a new archive file is created. |
| 117 | Files that replace existing files do not change the order of the files |
| 118 | within the archive. |
| 119 | New files are appended to the archive unless one of the options \-a, \-b |
| 120 | or \-i is specified. |
| 121 | .TP |
| 122 | \-s |
| 123 | Select and/or name archive members using only the first fifteen characters |
| 124 | of the archive member or command line file name. |
| 125 | The historic archive format had sixteen bytes for the name, but some |
| 126 | historic archiver and loader implementations were unable to handle names |
| 127 | that used the entire space. |
| 128 | This means that file names that are not unique in their first fifteen |
| 129 | characters can subsequently be confused. |
| 130 | A warning message is printed to the standard error output if any file |
| 131 | names are truncated. |
| 132 | (See |
| 133 | .IR ar (5) |
| 134 | for more information.) |
| 135 | .TP |
| 136 | \-t |
| 137 | List the specified files in the order in which they appear in the archive, |
| 138 | each on a separate line. |
| 139 | If no files are specified, all files in the archive are listed. |
| 140 | .TP |
| 141 | \-u |
| 142 | Update files. |
| 143 | When used with the \-r option, files in the archive will be replaced |
| 144 | only if the disk file has a newer modification time than the file in |
| 145 | the archive. |
| 146 | When used with the \-x option, files in the archive will be extracted |
| 147 | only if the archive file has a newer modification time than the file |
| 148 | on disk. |
| 149 | .TP |
| 150 | \-v |
| 151 | Provide verbose output. |
| 152 | When used with the \-d, \-m, \-q or \-x options, |
| 153 | .I ar |
| 154 | gives a file-by-file description of the archive modification. |
| 155 | This description consists of three, white-space separated fields: the |
| 156 | option letter, a dash (``-'') and the file name. |
| 157 | When used with the \-r option, |
| 158 | .I ar |
| 159 | displays the description as above, but the initial letter is an ``a'' if |
| 160 | the file is added to the archive and an ``r'' if the file replaces a file |
| 161 | already in the archive. |
| 162 | .IP |
| 163 | When used with the \-p option, |
| 164 | the name of each printed file is written to the standard output before |
| 165 | the contents of the file, on a line by itself, enclosed in less-than |
| 166 | (``<'') and greater-than (``>'') characters. |
| 167 | .IP |
| 168 | When used with the \-t option, |
| 169 | .I ar |
| 170 | displays an ``ls -l'' style listing of information about the files in |
| 171 | the archive. |
| 172 | This listing consists of eight, white-space separated fields: |
| 173 | the file permissions (see |
| 174 | .IR strmode (3)), |
| 175 | the decimal user and group ID's, separated by a single slash (``/''), |
| 176 | the file size (in bytes), the file modification time (in the |
| 177 | .IR date (1) |
| 178 | format ``%b %e %H:%M %Y''), and the name of the file. |
| 179 | .TP |
| 180 | \-x |
| 181 | Extract the specified files into the files named by the command line |
| 182 | arguments. |
| 183 | If no files are specified, all the files in the archive are extracted into |
| 184 | the current directory. |
| 185 | .IP |
| 186 | If the file does not exist, it is created; if it does exist, the owner |
| 187 | and group will be unchanged. |
| 188 | The file access and modification times are the time of the extraction |
| 189 | (but see the \-o option). |
| 190 | The file permissions will be set to those of the file when it was entered |
| 191 | into the archive; this will fail if the user is not the owner of the |
| 192 | extracted file or the super-user. |
| 193 | .PP |
| 194 | The |
| 195 | .I ar |
| 196 | utility exits 0 on success, and >0 if an error occurs. |
| 197 | .SH ENVIRONMENT |
| 198 | .TP |
| 199 | TMPDIR |
| 200 | The pathname of the directory to use when creating temporary files. |
| 201 | .SH FILES |
| 202 | .TP 14 |
| 203 | /tmp |
| 204 | default temporary file directory |
| 205 | .TP 14 |
| 206 | ar.XXXXXX |
| 207 | temporary file names |
| 208 | .SH COMPATIBILITY |
| 209 | By default, |
| 210 | .I ar |
| 211 | writes archives that may be incompatible with historic archives, as |
| 212 | the format used for storing archive members with names longer than |
| 213 | fifteen characters has changed. |
| 214 | This implementation of |
| 215 | .I ar |
| 216 | is backward compatible with previous versions of |
| 217 | .I ar |
| 218 | in that it can read and write (using the \-s option) historic archives. |
| 219 | The \-s option is provided for compatibility only, and will be deleted |
| 220 | in a future release. |
| 221 | See |
| 222 | .IR ar (5) |
| 223 | for more information. |
| 224 | .SH STANDARDS |
| 225 | The |
| 226 | .I ar |
| 227 | utility is expected to offer a superset of the POSIX 1003.2 functionality. |
| 228 | .SH "SEE ALSO" |
| 229 | ld(1), ranlib(1), ar(5) |