1 .\" Copyright (c) 2007 Joseph Koshy. All rights reserved.
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\" notice, this list of conditions and the following disclaimer.
8 .\" 2. Redistributions in binary form must reproduce the above copyright
9 .\" notice, this list of conditions and the following disclaimer in the
10 .\" documentation and/or other materials provided with the distribution.
12 .\" This software is provided by Joseph Koshy ``as is'' and
13 .\" any express or implied warranties, including, but not limited to, the
14 .\" implied warranties of merchantability and fitness for a particular purpose
15 .\" are disclaimed. in no event shall Joseph Koshy be liable
16 .\" for any direct, indirect, incidental, special, exemplary, or consequential
17 .\" damages (including, but not limited to, procurement of substitute goods
18 .\" or services; loss of use, data, or profits; or business interruption)
19 .\" however caused and on any theory of liability, whether in contract, strict
20 .\" liability, or tort (including negligence or otherwise) arising in any way
21 .\" out of the use of this software, even if advised of the possibility of
46 .Op Fl a Ar position-after
47 .Op Fl b Ar position-before
49 .Op Fl i Ar position-before
77 .Op Fl a Ar position-after
78 .Op Fl b Ar position-before
82 .Op Fl i Ar position-before
122 utility creates and maintains groups of files combined into an
124 Once an archive has been created, new files can be added to it, and
125 existing files can be extracted, deleted or replaced.
127 Files are named in the archive by their last file name component,
128 so if a file referenced by a path containing a
130 is archived, it will be named by the last component of the path.
131 Similarly when matching paths listed on the command line against
132 file names stored in the archive, only the last component of the
133 path will be compared.
137 is for the creation and maintenance of libraries suitable for use
140 although it is not restricted to this purpose.
143 utility can create and manage an archive symbol table (see
145 used to speed up link editing operations.
146 If a symbol table is present in an archive, it will be
147 kept up-to-date by subsequent operations on the archive.
151 utility is used to add an archive symbol table
152 to an existing archive.
156 utility supports the following options:
157 .Bl -tag -width indent
158 .It Fl a Ar member-after
159 When used with option
161 this option specifies that the archive members specified by
164 are moved to after the archive member named by argument
166 When used with option
168 this option specifies that the files specified by arguments
170 are added after the archive member named by argument
172 .It Fl b Ar member-before
173 When used with option
175 this option specifies that the archive members specified by
178 are moved to before the archive member named by argument
180 When used with option
182 this option specifies that the files specified by arguments
184 are added before the archive member named by argument
187 Suppress the informational message printed when a new archive is
194 Prevent extracted files from replacing like-named files
197 Delete the members named by arguments
199 from the archive specified by argument
201 The archive's symbol table, if present, is updated to reflect
202 the new contents of the archive.
204 When used in combination with the
211 option without other options, or when invoked as
213 insert 0's instead of the real mtime, uid and gid values
214 and 0644 instead of file mode from the members named by arguments
216 This ensures that checksums on the resulting archives are reproducible
217 when member contents are identical.
218 This option is enabled by default.
223 options are specified on the command line, the final one takes precedence.
225 Synonymous with option
227 .It Fl i Ar member-before
228 Synonymous with option
231 This option is accepted but ignored.
233 This option is accepted for compatibility with GNU
237 Move archive members specified by arguments
240 If a position has been specified by one of the
245 options, the members are moved to before or after the specified
247 If no position has been specified, the specified members are moved
248 to the end of the archive.
249 If the archive has a symbol table, it is updated to reflect the
250 new contents of the archive.
252 Read and execute MRI librarian commands from standard input.
253 The commands understood by the
255 utility are described in the section
256 .Sx "MRI Librarian Commands" .
258 Preserve the original modification times of members when extracting
261 Write the contents of the specified archive members named by
265 If no members were specified, the contents of all the files in the
266 archive are written in the order they appear in the archive.
268 Append the files specified by arguments
270 to the archive specified by argument
272 without checking if the files already exist in the archive.
273 The archive symbol table will be updated as needed.
274 If the file specified by the argument
276 does not already exist, a new archive will be created.
278 Replace (add) the files specified by arguments
280 in the archive specified by argument
282 creating the archive if necessary.
283 Replacing existing members will not change the order of members within
285 If a file named in arguments
287 does not exist, existing members in the archive that match that
288 name are not changed.
289 New files are added to the end of the archive unless one of the
296 The archive symbol table, if it exists, is updated to reflect the
297 new state of the archive.
299 Add an archive symbol table (see
301 to the archive specified by argument
307 option alone is equivalent to invoking
310 Do not generate an archive symbol table.
312 List the files specified by arguments
314 in the order in which they appear in the archive, one per line.
315 If no files are specified, all files in the archive are listed.
317 Use only the first fifteen characters of the archive member name or
318 command line file name argument when naming archive members.
320 Conditionally update the archive or extract members.
323 option, files named by arguments
325 will be replaced in the archive if they are newer than their
329 option, the members specified by arguments
331 will be extracted only if they are newer than the corresponding
332 files in the file system.
334 When used in combination with the
338 option, insert the real mtime, uid and gid, and file mode values
339 from the members named by arguments
345 options are specified on the command line, the final one takes precedence.
347 Provide verbose output.
356 gives a file-by-file description of the archive modification being
357 performed, which consists of three white-space separated fields:
358 the option letter, a dash
365 displays the description as above, but the initial letter is an
367 if the file is added to the archive, or an
369 if the file replaces a file already in the archive.
372 option, the name of the file enclosed in
376 characters is written to standard output preceded by a single newline
377 character and followed by two newline characters.
378 The contents of the named file follow the file name.
383 displays eight whitespace separated fields:
384 the file permissions as displayed by
386 decimal user and group IDs separated by a slash (
388 the file size in bytes, the file modification time in
391 .Dq "%b %e %H:%M %Y" ,
392 and the name of the file.
394 Print a version string and exit.
396 Extract archive members specified by arguments
398 into the current directory.
399 If no members have been specified, extract all members of the archive.
400 If the file corresponding to an extracted member does not exist it
402 If the file corresponding to an extracted member does exist, its owner
403 and group will not be changed while its contents will be overwritten
404 and its permissions will set to that entered in the archive.
405 The file's access and modification time would be that of the time
406 of extraction unless the
408 option was specified.
410 This option is accepted but ignored.
412 .Ss "MRI Librarian Commands"
415 option is specified, the
417 utility will read and execute commands from its standard input.
418 If standard input is a terminal, the
420 utility will display the prompt
422 before reading a line, and will continue operation even if errors are
424 If standard input is not a terminal, the
426 utility will not display a prompt and will terminate execution on
427 encountering an error.
429 Each input line contains a single command.
430 Words in an input line are separated by whitespace characters.
431 The first word of the line is the command, the remaining words are
432 the arguments to the command.
433 The command word may be specified in either case.
434 Arguments may be separated by commas or blanks.
436 Empty lines are allowed and are ignored.
437 Long lines are continued by ending them with the
445 characters start a comment.
446 Comments extend till the end of the line.
448 When executing an MRI librarian script the
450 utility works on a temporary copy of an archive.
451 Changes to the copy are made permanent using the
455 Commands understood by the
458 .Bl -tag -width indent
459 .It Ic addlib Ar archive | Ic addlib Ar archive Pq Ar member Oo Li , Ar member Oc Ns ...
460 Add the contents of the archive named by argument
462 to the current archive.
463 If specific members are named using the arguments
465 then those members are added to the current archive.
466 If no members are specified, the entire contents of the archive
467 are added to the current archive.
468 .It Ic addmod Ar member Oo Li , Ar member Oc Ns ...
469 Add the files named by arguments
471 to the current archive.
473 Discard all the contents of the current archive.
474 .It Ic create Ar archive
475 Create a new archive named by the argument
477 and makes it the current archive.
478 If the named archive already exists, it will be overwritten
482 .It Ic delete Ar module Oo Li , Ar member Oc Ns ...
483 Delete the modules named by the arguments
485 from the current archive.
486 .It Ic directory Ar archive Po Ar member Oo Li , Ar member Oc Ns ... Pc Op Ar outputfile
487 List each named module in the archive.
488 The format of the output depends on the verbosity setting set using
492 Output is sent to standard output, or to the file specified by
496 Exit successfully from the
499 Any unsaved changes to the current archive will be discarded.
500 .It Ic extract Ar member Oo Li , Ar member Oc Ns ...
501 Extract the members named by the arguments
503 from the current archive.
505 Display the contents of the current archive in verbose style.
506 .It Ic open Ar archive
507 Open the archive named by argument
509 and make it the current archive.
510 .It Ic replace Ar member Oo Li , Ar member Oc Ns ...
511 Replace named members in the current archive with the files specified
514 The files must be present in the current directory and the named
515 modules must already exist in the current archive.
517 Commit all changes to the current archive.
519 Toggle the verbosity of the
524 To create a new archive
526 containing three files
532 .Dl "ar -rc ex.a ex1.o ex2.o ex3.o"
534 To add an archive symbol table to an existing archive
544 .D1 "ar -d ex.a ex1.o"
546 To verbosely list the contents of archive
551 To create a new archive
557 using MRI librarian commands, use the following script:
558 .Bd -literal -offset indent
559 create ex.a * specify the output archive
560 addmod ex1.o ex2.o * add modules
561 save * save pending changes
562 end * exit the utility
573 .Sh STANDARDS COMPLIANCE
576 utility's support for the
592 options is believed to be compliant with
597 command first appeared in AT&T UNIX Version 1.
600 .An Kai Wang Aq Mt kaiw@FreeBSD.org