scc-ar.1 (8326B)
1 .TH SCC-AR 1 scc\-VERSION 2 .SH NAME 3 scc-ar \- create and maintain library archives 4 .SH SYNOPSIS 5 .B scc-ar 6 .RB [ \-cluv ] 7 .RB [ \-d | \-m | \-p | \-q | \-r | \-t | \-x ] 8 .RB [ \-a | \-b | \-i 9 .IR posname ] 10 .I archive 11 .RI [ file ...] 12 .SH DESCRIPTION 13 .B scc-ar 14 creates and maintains groups of files combined into an archive. 15 Once an archive has been created, new files can be added and existing 16 files can be updated, replaced, or deleted. 17 .PP 18 The archive is created with a special header that identifies it as an 19 archive file, followed by the archived files. Each archived member includes 20 a header containing the file name, modification time, owner, group, file mode, 21 and size. 22 .PP 23 Archives are commonly used to create libraries of object files for use 24 with the linker. The 25 .B scc-ar 26 utility, in combination with a symbol table created by 27 .BR scc-ranlib (1), 28 allows the linker to selectively extract only those object files needed 29 to resolve external references. 30 .SH OPTIONS 31 Exactly one of the following key options must be specified: 32 .TP 33 .B \-d 34 Delete the specified 35 .I files 36 from the 37 .IR archive . 38 If the verbose modifier 39 .B \-v 40 is specified, 41 .B scc-ar 42 writes a line to standard output for each file deleted, consisting of 43 the single character 'd' followed by a space and the name of the file. 44 If one or more 45 .I files 46 are specified but not found in the archive, an error is reported. 47 .TP 48 .B \-m 49 Move the specified 50 .I files 51 within the 52 .IR archive . 53 By default, members are moved to the end of the archive. The 54 .BR \-a , 55 .BR \-b , 56 or 57 .B \-i 58 modifiers can be used to specify a position relative to another member. 59 If the verbose modifier 60 .B \-v 61 is specified, 62 .B scc-ar 63 writes a line to standard output for each file moved, consisting of 64 the single character 'm' followed by a space and the name of the file. 65 .TP 66 .B \-p 67 Print the contents of the specified 68 .I files 69 from the 70 .I archive 71 to standard output. If no 72 .I files 73 are specified, the contents of all files in the archive are printed. 74 If the verbose modifier 75 .B \-v 76 is specified, a header is printed before each file consisting of 77 a newline, '<', the file name, '>', and two newlines. 78 .TP 79 .B \-q 80 Quickly append the specified 81 .I files 82 to the end of the 83 .IR archive . 84 This is faster than 85 .B \-r 86 because it does not check whether the files already exist in the archive. 87 The 88 .B \-a 89 and 90 .B \-b 91 modifiers are not supported with this operation. 92 .TP 93 .B \-r 94 Replace or add the specified 95 .I files 96 to the 97 .IR archive . 98 If the archive does not exist, it is created. If a specified file is 99 already a member of the archive, it is replaced. New files are added 100 at the end of the archive by default, or at a position specified by 101 the 102 .BR \-a , 103 .BR \-b , 104 or 105 .B \-i 106 modifiers. If the verbose modifier 107 .B \-v 108 is specified, 109 .B scc-ar 110 writes a line to standard output for each file added or replaced, 111 consisting of the single character 'a' or 'r' followed by a space 112 and the name of the file. 113 .TP 114 .B \-t 115 List the table of contents of the 116 .IR archive . 117 If 118 .I files 119 are specified, only those files are listed. If the verbose modifier 120 .B \-v 121 is specified, the listing includes file permissions, owner/group IDs, 122 modification time, and file name in a format similar to 123 .BR ls (1). 124 Otherwise, only file names are printed, one per line. 125 .TP 126 .B \-x 127 Extract the specified 128 .I files 129 from the 130 .IR archive . 131 If no 132 .I files 133 are specified, all files in the archive are extracted. The extracted 134 files are created with the same permissions, modification time, owner, 135 and group as they had when archived. If the verbose modifier 136 .B \-v 137 is specified, 138 .B scc-ar 139 writes a line to standard output for each file extracted, consisting of 140 the single character 'x' followed by a space and the name of the file. 141 .PP 142 The following modifiers are available: 143 .TP 144 .BI \-a " posname" 145 Position new or moved files after the existing member 146 .IR posname . 147 This modifier is only valid with the 148 .B \-m 149 and 150 .B \-r 151 operations. 152 .TP 153 .BI \-b " posname" 154 Position new or moved files before the existing member 155 .IR posname . 156 This modifier is only valid with the 157 .B \-m 158 and 159 .B \-r 160 operations. The 161 .B \-i 162 modifier is a synonym for 163 .BR \-b . 164 .TP 165 .BI \-i " posname" 166 Identical to 167 .BR \-b . 168 Position new or moved files before the existing member 169 .IR posname . 170 This modifier is only valid with the 171 .B \-m 172 and 173 .B \-r 174 operations. 175 .TP 176 .B \-c 177 Suppress the diagnostic message that is written to standard error when 178 the 179 .I archive 180 is created. Without this modifier, 181 .B scc-ar 182 writes a message to standard error when creating a new archive. 183 .TP 184 .B \-l 185 Use local temporary files instead of 186 .BR tmpfile (3). 187 When specified, temporary files are created in the current directory 188 with the names 189 .IR ar.tmp1 , 190 .IR ar.tmp2 , 191 and 192 .IR ar.tmp3 . 193 This can be useful when the system temporary directory is on a different 194 filesystem or has insufficient space. 195 .TP 196 .B \-u 197 Update members conditionally. When used with the 198 .B \-r 199 option, a file is only replaced in the archive if the file on disk 200 has been modified more recently than the version in the archive. 201 This modifier is only valid with the 202 .B \-r 203 operation. 204 .TP 205 .B \-v 206 Verbose mode. Provide detailed output showing which files are being 207 processed. The format of the output depends on the operation being 208 performed (see individual operation descriptions above). 209 .SH OPERANDS 210 .TP 211 .I archive 212 The pathname of the archive file to be created, modified, or examined. 213 .TP 214 .I file 215 A pathname of a file to be added to, extracted from, or listed in the archive. 216 When adding files to an archive, the canonical name (basename) of the file 217 is stored in the archive, stripped of any directory components. 218 .SH EXIT STATUS 219 .TP 220 .B 0 221 Successful completion. 222 .TP 223 .B >0 224 An error occurred. 225 .SH IMPLEMENTATION NOTES 226 The 227 .B scc-ar 228 utility in the SCC toolchain is designed to be POSIX-compliant and 229 portable across different systems. It has the following characteristics: 230 .TP 231 \(bu 232 Archive member names are limited to 16 characters and cannot contain spaces. 233 .TP 234 \(bu 235 Member names are stored in a fixed 16-character field, space-padded. 236 .TP 237 \(bu 238 Archive members are aligned on even byte boundaries; if a member has an 239 odd size, a newline character is appended as padding. 240 .TP 241 \(bu 242 The archive format uses the standard UNIX archive magic number. 243 .TP 244 \(bu 245 File attributes (permissions, owner, group, modification time) are preserved 246 when extracting files. 247 .TP 248 \(bu 249 When adding files, the utility stores the canonical (base) name only, 250 stripping any directory path components. 251 .TP 252 \(bu 253 If any specified 254 .I file 255 is not found in the archive during an operation that requires it 256 (such as 257 .BR \-d , 258 .BR \-m , 259 or 260 .BR \-r ), 261 an error is reported after all other operations complete. 262 .TP 263 \(bu 264 Signal handling: The utility registers handlers for SIGINT, SIGQUIT 265 (on systems that support it), and SIGTERM to ensure temporary files 266 are cleaned up on abnormal termination. 267 .SH EXAMPLES 268 .PP 269 Create (or update) an archive containing object files: 270 .IP 271 .EX 272 scc-ar \-r libfoo.a foo.o bar.o baz.o 273 .EE 274 .PP 275 List the contents of an archive: 276 .IP 277 .EX 278 scc-ar \-t libfoo.a 279 .EN 280 .PP 281 List the contents verbosely, showing file details: 282 .IP 283 .EX 284 scc-ar \-tv libfoo.a 285 .EE 286 .PP 287 Extract all files from an archive: 288 .IP 289 .EX 290 scc-ar \-x libfoo.a 291 .EE 292 .PP 293 Extract a specific file: 294 .IP 295 .EX 296 scc-ar \-x libfoo.a foo.o 297 .EE 298 .PP 299 Delete a file from an archive: 300 .IP 301 .EX 302 scc-ar \-d libfoo.a foo.o 303 .EE 304 .PP 305 Replace a file only if it has been modified: 306 .IP 307 .EX 308 scc-ar \-ru libfoo.a foo.o 309 .EE 310 .PP 311 Insert a file before another member: 312 .IP 313 .EX 314 scc-ar \-r \-b bar.o libfoo.a newfile.o 315 .EE 316 .PP 317 Move a member to the end of the archive: 318 .IP 319 .EX 320 scc-ar \-m libfoo.a foo.o 321 .EE 322 .SH DIAGNOSTICS 323 If the 324 .B \-c 325 modifier is not specified and a new archive is created, 326 .B scc-ar 327 writes the following message to standard error: 328 .PP 329 .in +4n 330 .EX 331 ar: creating archive 332 .EE 333 .in 334 .PP 335 Error messages are written to standard error and have the format: 336 .PP 337 .in +4n 338 .EX 339 ar: archive: message 340 .EE 341 .in 342 .SH STANDARDS 343 The 344 .B scc-ar 345 utility is designed to conform to IEEE Std 1003.1-2008 (POSIX.1). 346 .SH AUTHORS 347 See the LICENSE file for the authors. 348 .SH LICENSE 349 See the LICENSE file for the terms of redistribution. 350 .SH SEE ALSO 351 .BR scc-ranlib (1), 352 .BR scc-ld (1), 353 .BR scc-nm (1), 354 .BR scc-strip (1) 355 .SH BUGS 356 The 357 .B scc-ar 358 utility does not create a symbol table by default. Use 359 .BR scc-ranlib (1) 360 to add a symbol table to an archive.