scc-ar.man (8144B)
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 IMPLEMENTATION NOTES 219 The 220 .B scc-ar 221 utility in the SCC toolchain is designed to be POSIX-compliant and 222 portable across different systems. It has the following characteristics: 223 .TP 224 \(bu 225 Archive member names are limited to 16 characters and cannot contain spaces. 226 .TP 227 \(bu 228 Member names are stored in a fixed 16-character field, space-padded. 229 .TP 230 \(bu 231 Archive members are aligned on even byte boundaries; if a member has an 232 odd size, a newline character is appended as padding. 233 .TP 234 \(bu 235 The archive format uses the standard UNIX archive magic number. 236 .TP 237 \(bu 238 File attributes (permissions, owner, group, modification time) are preserved 239 when extracting files. 240 .TP 241 \(bu 242 When adding files, the utility stores the canonical (base) name only, 243 stripping any directory path components. 244 .TP 245 \(bu 246 If any specified 247 .I file 248 is not found in the archive during an operation that requires it 249 (such as 250 .BR \-d , 251 .BR \-m , 252 or 253 .BR \-r ), 254 an error is reported after all other operations complete. 255 .TP 256 \(bu 257 Signal handling: The utility registers handlers for SIGINT, SIGQUIT 258 (on systems that support it), and SIGTERM to ensure temporary files 259 are cleaned up on abnormal termination. 260 .SH EXAMPLES 261 .PP 262 Create (or update) an archive containing object files: 263 .IP 264 .EX 265 scc-ar \-r libfoo.a foo.o bar.o baz.o 266 .EE 267 .PP 268 List the contents of an archive: 269 .IP 270 .EX 271 scc-ar \-t libfoo.a 272 .EN 273 .PP 274 List the contents verbosely, showing file details: 275 .IP 276 .EX 277 scc-ar \-tv libfoo.a 278 .EE 279 .PP 280 Extract all files from an archive: 281 .IP 282 .EX 283 scc-ar \-x libfoo.a 284 .EE 285 .PP 286 Extract a specific file: 287 .IP 288 .EX 289 scc-ar \-x libfoo.a foo.o 290 .EE 291 .PP 292 Delete a file from an archive: 293 .IP 294 .EX 295 scc-ar \-d libfoo.a foo.o 296 .EE 297 .PP 298 Replace a file only if it has been modified: 299 .IP 300 .EX 301 scc-ar \-ru libfoo.a foo.o 302 .EE 303 .PP 304 Insert a file before another member: 305 .IP 306 .EX 307 scc-ar \-r \-b bar.o libfoo.a newfile.o 308 .EE 309 .PP 310 Move a member to the end of the archive: 311 .IP 312 .EX 313 scc-ar \-m libfoo.a foo.o 314 .EE 315 .SH DIAGNOSTICS 316 If the 317 .B \-c 318 modifier is not specified and a new archive is created, 319 .B scc-ar 320 writes the following message to standard error: 321 .IP 322 .EX 323 ar: creating archive 324 .EE 325 .PP 326 Error messages are written to standard error and have the format: 327 .IP 328 .EX 329 ar: archive: message 330 .EE 331 .SH STANDARDS 332 The 333 .B scc-ar 334 utility is designed to conform to IEEE Std 1003.1-2008 (POSIX.1). 335 .SH SEE ALSO 336 .BR scc-ranlib (1), 337 .BR scc-ld (1), 338 .BR scc-nm (1), 339 .BR scc-strip (1) 340 .SH BUGS 341 The 342 .B scc-ar 343 utility does not create a symbol table by default. Use 344 .BR scc-ranlib (1) 345 to add a symbol table to an archive. 346 The option \-s is not implemented.