scc

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