FreeBSD Manual Pages
AR(1) FreeBSD General Commands Manual AR(1) NAME ar, ranlib -- manage archives SYNOPSIS ar -d [-T] [-f] [-j] [-v] [-z] archive file ... ar -m [-T] [-a position-after] [-b position-before] [-f] [-i position-before] [-j] [-s | -S] [-z] archive file ... ar -p [-T] [-f] [-v] archive [file ...] ar -q [-T] [-c] [-D] [-f] [-s | -S] [-U] [-v] [-z] archive file ... ar -r [-T] [-a position-after] [-b position-before] [-c] [-D] [-f] [-i position-before] [-j] [-s | -S] [-u] [-U] [-v] [-z] archive file ... ar -s [-j] [-z] archive ar -t [-f] [-T] [-v] archive [file ...] ar -x [-C] [-T] [-f] [-o] [-u] [-v] archive [file ...] ar -M ranlib [-D] [-U] archive ... DESCRIPTION The ar utility creates and maintains groups of files combined into an ar- chive. Once an archive has been created, new files can be added to it, and existing files can be extracted, deleted or replaced. Files are named in the archive by their last file name component, so if a file referenced by a path containing a "/" is archived, it will be named by the last component of the path. Similarly when matching paths listed on the command line against file names stored in the archive, only the last component of the path will be compared. The normal use of ar is for the creation and maintenance of libraries suitable for use with the link editor ld(1), although it is not re- stricted to this purpose. The ar utility can create and manage an ar- chive symbol table (see ar(5)) used to speed up link editing operations. If a symbol table is present in an archive, it will be kept up-to-date by subsequent operations on the archive. The ranlib utility is used to add an archive symbol table to an existing archive. OPTIONS The ar utility supports the following options: -a member-after When used with option -m this option specifies that the archive members specified by arguments file ... are moved to after the archive member named by argument member-after. When used with option -r this option specifies that the files specified by argu- ments file ... are added after the archive member named by argu- ment member-after. -b member-before When used with option -m this option specifies that the archive members specified by arguments file ... are moved to before the archive member named by argument member-before. When used with option -r this option specifies that the files specified by argu- ments file ... are added before the archive member named by argu- ment member-before. -c Suppress the informational message printed when a new archive is created using the -r and -q options. -C Prevent extracted files from replacing like-named files in the file system. -d Delete the members named by arguments file ... from the archive specified by argument archive. The archive's symbol table, if present, is updated to reflect the new contents of the archive. -D When used in combination with the -r or -q option, with the -s option without other options, or when invoked as ranlib, insert 0's instead of the real mtime, uid and gid values and 0644 in- stead of file mode from the members named by arguments file .... This ensures that checksums on the resulting archives are repro- ducible when member contents are identical. This option is en- abled by default. If multiple -D and -U options are specified on the command line, the final one takes precedence. -f Use only the first fifteen characters of the archive member name or command line file name argument when naming archive members. -i member-before Synonymous with option -b. -j This option is accepted but ignored. -l This option is accepted for compatibility with GNU ar(1), but is ignored. -m Move archive members specified by arguments file ... within the archive. If a position has been specified by one of the -a, -b or -i options, the members are moved to before or after the spec- ified position. If no position has been specified, the specified members are moved to the end of the archive. If the archive has a symbol table, it is updated to reflect the new contents of the archive. -M Read and execute MRI librarian commands from standard input. The commands understood by the ar utility are described in the sec- tion MRI Librarian Commands. -o Preserve the original modification times of members when extract- ing them. -p Write the contents of the specified archive members named by ar- guments file ... to standard output. If no members were speci- fied, the contents of all the files in the archive are written in the order they appear in the archive. -q Append the files specified by arguments file ... to the archive specified by argument archive without checking if the files al- ready exist in the archive. The archive symbol table will be up- dated as needed. If the file specified by the argument archive does not already exist, a new archive will be created. -r Replace (add) the files specified by arguments file ... in the archive specified by argument archive, creating the archive if necessary. Replacing existing members will not change the order of members within the archive. If a file named in arguments file ... does not exist, existing members in the archive that match that name are not changed. New files are added to the end of the archive unless one of the positioning options -a, -b or -i is specified. The archive symbol table, if it exists, is updated to reflect the new state of the archive. -s Add an archive symbol table (see ar(5)) to the archive specified by argument archive. Invoking ar with the -s option alone is equivalent to invoking ranlib. -S Do not generate an archive symbol table. -t List the files specified by arguments file ... in the order in which they appear in the archive, one per line. If no files are specified, all files in the archive are listed. -T Deprecated alias for -f. In other implementations of ar, -T cre- ates a "thin" archive. -u Conditionally update the archive or extract members. When used with the -r option, files named by arguments file ... will be re- placed in the archive if they are newer than their archived ver- sions. When used with the -x option, the members specified by arguments file ... will be extracted only if they are newer than the corresponding files in the file system. -U When used in combination with the -r or -q option, insert the real mtime, uid and gid, and file mode values from the members named by arguments file .... If multiple -D and -U options are specified on the command line, the final one takes precedence. -v Provide verbose output. When used with the -d, -m, -q or -x op- tions, ar gives a file-by-file description of the archive modifi- cation being performed, which consists of three white-space sepa- rated fields: the option letter, a dash "-", and the file name. When used with the -r option, ar displays the description as above, but the initial letter is an "a" if the file is added to the archive, or an "r" if the file replaces a file already in the archive. When used with the -p option, the name of the file en- closed in "<" and ">" characters is written to standard output preceded by a single newline character and followed by two new- line characters. The contents of the named file follow the file name. When used with the -t option, ar displays eight whitespace separated fields: the file permissions as displayed by strmode(3), decimal user and group IDs separated by a slash ( "/"), the file size in bytes, the file modification time in strftime(3) format "%b %e %H:%M %Y", and the name of the file. -V Print a version string and exit. -x Extract archive members specified by arguments file ... into the current directory. If no members have been specified, extract all members of the archive. If the file corresponding to an ex- tracted member does not exist it will be created. If the file corresponding to an extracted member does exist, its owner and group will not be changed while its contents will be overwritten and its permissions will set to that entered in the archive. The file's access and modification time would be that of the time of extraction unless the -o option was specified. -z This option is accepted but ignored. MRI Librarian Commands If the -M option is specified, the ar utility will read and execute com- mands from its standard input. If standard input is a terminal, the ar utility will display the prompt "AR >" before reading a line, and will continue operation even if errors are encountered. If standard input is not a terminal, the ar utility will not display a prompt and will termi- nate execution on encountering an error. Each input line contains a single command. Words in an input line are separated by whitespace characters. The first word of the line is the command, the remaining words are the arguments to the command. The com- mand word may be specified in either case. Arguments may be separated by commas or blanks. Empty lines are allowed and are ignored. Long lines are continued by ending them with the "+" character. The "*" and ";" characters start a comment. Comments extend till the end of the line. When executing an MRI librarian script the ar utility works on a tempo- rary copy of an archive. Changes to the copy are made permanent using the save command. Commands understood by the ar utility are: addlib archive | addlib archive (member [, member]...) Add the contents of the archive named by argument archive to the current archive. If specific members are named using the argu- ments member, then those members are added to the current ar- chive. If no members are specified, the entire contents of the archive are added to the current archive. addmod member [, member]... Add the files named by arguments member to the current archive. clear Discard all the contents of the current archive. create archive Create a new archive named by the argument archive, and makes it the current archive. If the named archive already exists, it will be overwritten when the save command is issued. delete module [, member]... Delete the modules named by the arguments member from the current archive. directory archive (member [, member]...) [outputfile] List each named module in the archive. The format of the output depends on the verbosity setting set using the verbose command. Output is sent to standard output, or to the file specified by argument outputfile. end Exit successfully from the ar utility. Any unsaved changes to the current archive will be discarded. extract member [, member]... Extract the members named by the arguments member from the cur- rent archive. list Display the contents of the current archive in verbose style. open archive Open the archive named by argument archive and make it the cur- rent archive. replace member [, member]... Replace named members in the current archive with the files spec- ified by arguments member. The files must be present in the cur- rent directory and the named modules must already exist in the current archive. save Commit all changes to the current archive. verbose Toggle the verbosity of the directory command. EXAMPLES To create a new archive ex.a containing three files ex1.o, ex2.o and ex3.o, use: ar -rc ex.a ex1.o ex2.o ex3.o To add an archive symbol table to an existing archive ex.a, use: ar -s ex.a To delete file ex1.o from archive ex.a, use: ar -d ex.a ex1.o To verbosely list the contents of archive ex.a, use: ar -tv ex.a To create a new archive ex.a containing the files ex1.o, and ex2.o, using MRI librarian commands, use the following script: create ex.a * specify the output archive addmod ex1.o ex2.o * add modules save * save pending changes end * exit the utility DIAGNOSTICS The ar utility exits 0 on success, and >0 if an error occurs. SEE ALSO ld(1), archive(3), elf(3), strftime(3), strmode(3), ar(5) STANDARDS COMPLIANCE The ar utility's support for the -a, -b, -c, -i, -m, -p, -q, -r, -s, -t, -u, -v, -C and -T options is believed to be compliant with IEEE Std 1003.2 ("POSIX.2"). HISTORY An ar command first appeared in AT&T UNIX Version 1. In FreeBSD 8.0, Kai Wang <kaiw@FreeBSD.org> reimplemented ar and ranlib using the Streaming Archive Library (libarchive, -larchive) and the ELF Parsing Library (libelf, -lelf). FreeBSD 13.0 December 29, 2021 FreeBSD 13.0
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | DIAGNOSTICS | SEE ALSO | STANDARDS COMPLIANCE | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ar&sektion=1&manpath=FreeBSD+13.2-RELEASE+and+Ports>