diff options
Diffstat (limited to 'usr.bin/clang/llvm-ar/llvm-ar.1')
| -rw-r--r-- | usr.bin/clang/llvm-ar/llvm-ar.1 | 484 |
1 files changed, 484 insertions, 0 deletions
diff --git a/usr.bin/clang/llvm-ar/llvm-ar.1 b/usr.bin/clang/llvm-ar/llvm-ar.1 new file mode 100644 index 0000000..84a978f --- /dev/null +++ b/usr.bin/clang/llvm-ar/llvm-ar.1 @@ -0,0 +1,484 @@ +.\" $FreeBSD$ +.TH "LLVM-AR" "1" "2012-08-16" "3.2" "LLVM" +.SH NAME +llvm-ar \- LLVM archiver +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.\" Man page generated from reStructuredText. +. +.SH SYNOPSIS +.sp +\fBllvm\-ar\fP [\-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [files...] +.SH DESCRIPTION +.sp +The \fBllvm\-ar\fP command is similar to the common Unix utility, \fBar\fP. It +archives several files together into a single file. The intent for this is +to produce archive libraries by LLVM bitcode that can be linked into an +LLVM program. However, the archive can contain any kind of file. By default, +\fBllvm\-ar\fP generates a symbol table that makes linking faster because +only the symbol table needs to be consulted, not each individual file member +of the archive. +.sp +The \fBllvm\-ar\fP command can be used to \fIread\fP both SVR4 and BSD style archive +files. However, it cannot be used to write them. While the \fBllvm\-ar\fP command +produces files that are \fIalmost\fP identical to the format used by other \fBar\fP +implementations, it has two significant departures in order to make the +archive appropriate for LLVM. The first departure is that \fBllvm\-ar\fP only +uses BSD4.4 style long path names (stored immediately after the header) and +never contains a string table for long names. The second departure is that the +symbol table is formated for efficient construction of an in\-memory data +structure that permits rapid (red\-black tree) lookups. Consequently, archives +produced with \fBllvm\-ar\fP usually won\(aqt be readable or editable with any +\fBar\fP implementation or useful for linking. Using the \fBf\fP modifier to flatten +file names will make the archive readable by other \fBar\fP implementations +but not for linking because the symbol table format for LLVM is unique. If an +SVR4 or BSD style archive is used with the \fBr\fP (replace) or \fBq\fP (quick +update) operations, the archive will be reconstructed in LLVM format. This +means that the string table will be dropped (in deference to BSD 4.4 long names) +and an LLVM symbol table will be added (by default). The system symbol table +will be retained. +.sp +Here\(aqs where \fBllvm\-ar\fP departs from previous \fBar\fP implementations: +.sp +\fISymbol Table\fP +.INDENT 0.0 +.INDENT 3.5 +Since \fBllvm\-ar\fP is intended to archive bitcode files, the symbol table +won\(aqt make much sense to anything but LLVM. Consequently, the symbol table\(aqs +format has been simplified. It consists simply of a sequence of pairs +of a file member index number as an LSB 4byte integer and a null\-terminated +string. +.UNINDENT +.UNINDENT +.sp +\fILong Paths\fP +.INDENT 0.0 +.INDENT 3.5 +Some \fBar\fP implementations (SVR4) use a separate file member to record long +path names (> 15 characters). \fBllvm\-ar\fP takes the BSD 4.4 and Mac OS X +approach which is to simply store the full path name immediately preceding +the data for the file. The path name is null terminated and may contain the +slash (/) character. +.UNINDENT +.UNINDENT +.sp +\fIDirectory Recursion\fP +.INDENT 0.0 +.INDENT 3.5 +Most \fBar\fP implementations do not recurse through directories but simply +ignore directories if they are presented to the program in the \fIfiles\fP +option. \fBllvm\-ar\fP, however, can recurse through directory structures and +add all the files under a directory, if requested. +.UNINDENT +.UNINDENT +.sp +\fITOC Verbose Output\fP +.INDENT 0.0 +.INDENT 3.5 +When \fBllvm\-ar\fP prints out the verbose table of contents (\fBtv\fP option), it +precedes the usual output with a character indicating the basic kind of +content in the file. A blank means the file is a regular file. A \(aqB\(aq means +the file is an LLVM bitcode file. An \(aqS\(aq means the file is the symbol table. +.UNINDENT +.UNINDENT +.SH OPTIONS +.sp +The options to \fBllvm\-ar\fP are compatible with other \fBar\fP implementations. +However, there are a few modifiers (\fIR\fP) that are not found in other \fBar\fP +implementations. The options to \fBllvm\-ar\fP specify a single basic operation to +perform on the archive, a variety of modifiers for that operation, the name of +the archive file, and an optional list of file names. These options are used to +determine how \fBllvm\-ar\fP should process the archive file. +.sp +The Operations and Modifiers are explained in the sections below. The minimal +set of options is at least one operator and the name of the archive. Typically +archive files end with a \fB.a\fP suffix, but this is not required. Following +the \fIarchive\-name\fP comes a list of \fIfiles\fP that indicate the specific members +of the archive to operate on. If the \fIfiles\fP option is not specified, it +generally means either "none" or "all" members, depending on the operation. +.SS Operations +.sp +d +.INDENT 0.0 +.INDENT 3.5 +Delete files from the archive. No modifiers are applicable to this operation. +The \fIfiles\fP options specify which members should be removed from the +archive. It is not an error if a specified file does not appear in the archive. +If no \fIfiles\fP are specified, the archive is not modified. +.UNINDENT +.UNINDENT +.sp +m[abi] +.INDENT 0.0 +.INDENT 3.5 +Move files from one location in the archive to another. The \fIa\fP, \fIb\fP, and +\fIi\fP modifiers apply to this operation. The \fIfiles\fP will all be moved +to the location given by the modifiers. If no modifiers are used, the files +will be moved to the end of the archive. If no \fIfiles\fP are specified, the +archive is not modified. +.UNINDENT +.UNINDENT +.sp +p[k] +.INDENT 0.0 +.INDENT 3.5 +Print files to the standard output. The \fIk\fP modifier applies to this +operation. This operation simply prints the \fIfiles\fP indicated to the +standard output. If no \fIfiles\fP are specified, the entire archive is printed. +Printing bitcode files is ill\-advised as they might confuse your terminal +settings. The \fIp\fP operation never modifies the archive. +.UNINDENT +.UNINDENT +.sp +q[Rf] +.INDENT 0.0 +.INDENT 3.5 +Quickly append files to the end of the archive. The \fIR\fP, and \fIf\fP +modifiers apply to this operation. This operation quickly adds the +\fIfiles\fP to the archive without checking for duplicates that should be +removed first. If no \fIfiles\fP are specified, the archive is not modified. +Because of the way that \fBllvm\-ar\fP constructs the archive file, its dubious +whether the \fIq\fP operation is any faster than the \fIr\fP operation. +.UNINDENT +.UNINDENT +.sp +r[Rabfu] +.INDENT 0.0 +.INDENT 3.5 +Replace or insert file members. The \fIR\fP, \fIa\fP, \fIb\fP, \fIf\fP, and \fIu\fP +modifiers apply to this operation. This operation will replace existing +\fIfiles\fP or insert them at the end of the archive if they do not exist. If no +\fIfiles\fP are specified, the archive is not modified. +.UNINDENT +.UNINDENT +.sp +t[v] +.INDENT 0.0 +.INDENT 3.5 +Print the table of contents. Without any modifiers, this operation just prints +the names of the members to the standard output. With the \fIv\fP modifier, +\fBllvm\-ar\fP also prints out the file type (B=bitcode, S=symbol +table, blank=regular file), the permission mode, the owner and group, the +size, and the date. If any \fIfiles\fP are specified, the listing is only for +those files. If no \fIfiles\fP are specified, the table of contents for the +whole archive is printed. +.UNINDENT +.UNINDENT +.sp +x[oP] +.INDENT 0.0 +.INDENT 3.5 +Extract archive members back to files. The \fIo\fP modifier applies to this +operation. This operation retrieves the indicated \fIfiles\fP from the archive +and writes them back to the operating system\(aqs file system. If no +\fIfiles\fP are specified, the entire archive is extract. +.UNINDENT +.UNINDENT +.SS Modifiers (operation specific) +.sp +The modifiers below are specific to certain operations. See the Operations +section (above) to determine which modifiers are applicable to which operations. +.sp +[a] +.INDENT 0.0 +.INDENT 3.5 +When inserting or moving member files, this option specifies the destination of +the new files as being after the \fIrelpos\fP member. If \fIrelpos\fP is not found, +the files are placed at the end of the archive. +.UNINDENT +.UNINDENT +.sp +[b] +.INDENT 0.0 +.INDENT 3.5 +When inserting or moving member files, this option specifies the destination of +the new files as being before the \fIrelpos\fP member. If \fIrelpos\fP is not +found, the files are placed at the end of the archive. This modifier is +identical to the \fIi\fP modifier. +.UNINDENT +.UNINDENT +.sp +[f] +.INDENT 0.0 +.INDENT 3.5 +Normally, \fBllvm\-ar\fP stores the full path name to a file as presented to it on +the command line. With this option, truncated (15 characters max) names are +used. This ensures name compatibility with older versions of \fBar\fP but may also +thwart correct extraction of the files (duplicates may overwrite). If used with +the \fIR\fP option, the directory recursion will be performed but the file names +will all be flattened to simple file names. +.UNINDENT +.UNINDENT +.sp +[i] +.INDENT 0.0 +.INDENT 3.5 +A synonym for the \fIb\fP option. +.UNINDENT +.UNINDENT +.sp +[k] +.INDENT 0.0 +.INDENT 3.5 +Normally, \fBllvm\-ar\fP will not print the contents of bitcode files when the +\fIp\fP operation is used. This modifier defeats the default and allows the +bitcode members to be printed. +.UNINDENT +.UNINDENT +.sp +[N] +.INDENT 0.0 +.INDENT 3.5 +This option is ignored by \fBllvm\-ar\fP but provided for compatibility. +.UNINDENT +.UNINDENT +.sp +[o] +.INDENT 0.0 +.INDENT 3.5 +When extracting files, this option will cause \fBllvm\-ar\fP to preserve the +original modification times of the files it writes. +.UNINDENT +.UNINDENT +.sp +[P] +.INDENT 0.0 +.INDENT 3.5 +use full path names when matching +.UNINDENT +.UNINDENT +.sp +[R] +.INDENT 0.0 +.INDENT 3.5 +This modifier instructions the \fIr\fP option to recursively process directories. +Without \fIR\fP, directories are ignored and only those \fIfiles\fP that refer to +files will be added to the archive. When \fIR\fP is used, any directories specified +with \fIfiles\fP will be scanned (recursively) to find files to be added to the +archive. Any file whose name begins with a dot will not be added. +.UNINDENT +.UNINDENT +.sp +[u] +.INDENT 0.0 +.INDENT 3.5 +When replacing existing files in the archive, only replace those files that have +a time stamp than the time stamp of the member in the archive. +.UNINDENT +.UNINDENT +.SS Modifiers (generic) +.sp +The modifiers below may be applied to any operation. +.sp +[c] +.INDENT 0.0 +.INDENT 3.5 +For all operations, \fBllvm\-ar\fP will always create the archive if it doesn\(aqt +exist. Normally, \fBllvm\-ar\fP will print a warning message indicating that the +archive is being created. Using this modifier turns off that warning. +.UNINDENT +.UNINDENT +.sp +[s] +.INDENT 0.0 +.INDENT 3.5 +This modifier requests that an archive index (or symbol table) be added to the +archive. This is the default mode of operation. The symbol table will contain +all the externally visible functions and global variables defined by all the +bitcode files in the archive. Using this modifier is more efficient that using +llvm\-ranlib|llvm\-ranlib which also creates the symbol table. +.UNINDENT +.UNINDENT +.sp +[S] +.INDENT 0.0 +.INDENT 3.5 +This modifier is the opposite of the \fIs\fP modifier. It instructs \fBllvm\-ar\fP to +not build the symbol table. If both \fIs\fP and \fIS\fP are used, the last modifier to +occur in the options will prevail. +.UNINDENT +.UNINDENT +.sp +[v] +.INDENT 0.0 +.INDENT 3.5 +This modifier instructs \fBllvm\-ar\fP to be verbose about what it is doing. Each +editing operation taken against the archive will produce a line of output saying +what is being done. +.UNINDENT +.UNINDENT +.SH STANDARDS +.sp +The \fBllvm\-ar\fP utility is intended to provide a superset of the IEEE Std 1003.2 +(POSIX.2) functionality for \fBar\fP. \fBllvm\-ar\fP can read both SVR4 and BSD4.4 (or +Mac OS X) archives. If the \fBf\fP modifier is given to the \fBx\fP or \fBr\fP operations +then \fBllvm\-ar\fP will write SVR4 compatible archives. Without this modifier, +\fBllvm\-ar\fP will write BSD4.4 compatible archives that have long names +immediately after the header and indicated using the "#1/ddd" notation for the +name in the header. +.SH FILE FORMAT +.sp +The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX +archive files. In fact, except for the symbol table, the \fBar\fP commands on those +operating systems should be able to read LLVM archive files. The details of the +file format follow. +.sp +Each archive begins with the archive magic number which is the eight printable +characters "!<arch>n" where n represents the newline character (0x0A). +Following the magic number, the file is composed of even length members that +begin with an archive header and end with a n padding character if necessary +(to make the length even). Each file member is composed of a header (defined +below), an optional newline\-terminated "long file name" and the contents of +the file. +.sp +The fields of the header are described in the items below. All fields of the +header contain only ASCII characters, are left justified and are right padded +with space characters. +.sp +name \- char[16] +.INDENT 0.0 +.INDENT 3.5 +This field of the header provides the name of the archive member. If the name is +longer than 15 characters or contains a slash (/) character, then this field +contains \fB#1/nnn\fP where \fBnnn\fP provides the length of the name and the \fB#1/\fP +is literal. In this case, the actual name of the file is provided in the \fBnnn\fP +bytes immediately following the header. If the name is 15 characters or less, it +is contained directly in this field and terminated with a slash (/) character. +.UNINDENT +.UNINDENT +.sp +date \- char[12] +.INDENT 0.0 +.INDENT 3.5 +This field provides the date of modification of the file in the form of a +decimal encoded number that provides the number of seconds since the epoch +(since 00:00:00 Jan 1, 1970) per Posix specifications. +.UNINDENT +.UNINDENT +.sp +uid \- char[6] +.INDENT 0.0 +.INDENT 3.5 +This field provides the user id of the file encoded as a decimal ASCII string. +This field might not make much sense on non\-Unix systems. On Unix, it is the +same value as the st_uid field of the stat structure returned by the stat(2) +operating system call. +.UNINDENT +.UNINDENT +.sp +gid \- char[6] +.INDENT 0.0 +.INDENT 3.5 +This field provides the group id of the file encoded as a decimal ASCII string. +This field might not make much sense on non\-Unix systems. On Unix, it is the +same value as the st_gid field of the stat structure returned by the stat(2) +operating system call. +.UNINDENT +.UNINDENT +.sp +mode \- char[8] +.INDENT 0.0 +.INDENT 3.5 +This field provides the access mode of the file encoded as an octal ASCII +string. This field might not make much sense on non\-Unix systems. On Unix, it +is the same value as the st_mode field of the stat structure returned by the +stat(2) operating system call. +.UNINDENT +.UNINDENT +.sp +size \- char[10] +.INDENT 0.0 +.INDENT 3.5 +This field provides the size of the file, in bytes, encoded as a decimal ASCII +string. +.UNINDENT +.UNINDENT +.sp +fmag \- char[2] +.INDENT 0.0 +.INDENT 3.5 +This field is the archive file member magic number. Its content is always the +two characters back tick (0x60) and newline (0x0A). This provides some measure +utility in identifying archive files that have been corrupted. +.UNINDENT +.UNINDENT +.sp +The LLVM symbol table has the special name "#_LLVM_SYM_TAB_#". It is presumed +that no regular archive member file will want this name. The LLVM symbol table +is simply composed of a sequence of triplets: byte offset, length of symbol, +and the symbol itself. Symbols are not null or newline terminated. Here are +the details on each of these items: +.sp +offset \- vbr encoded 32\-bit integer +.INDENT 0.0 +.INDENT 3.5 +The offset item provides the offset into the archive file where the bitcode +member is stored that is associated with the symbol. The offset value is 0 +based at the start of the first "normal" file member. To derive the actual +file offset of the member, you must add the number of bytes occupied by the file +signature (8 bytes) and the symbol tables. The value of this item is encoded +using variable bit rate encoding to reduce the size of the symbol table. +Variable bit rate encoding uses the high bit (0x80) of each byte to indicate +if there are more bytes to follow. The remaining 7 bits in each byte carry bits +from the value. The final byte does not have the high bit set. +.UNINDENT +.UNINDENT +.sp +length \- vbr encoded 32\-bit integer +.INDENT 0.0 +.INDENT 3.5 +The length item provides the length of the symbol that follows. Like this +\fIoffset\fP item, the length is variable bit rate encoded. +.UNINDENT +.UNINDENT +.sp +symbol \- character array +.INDENT 0.0 +.INDENT 3.5 +The symbol item provides the text of the symbol that is associated with the +\fIoffset\fP. The symbol is not terminated by any character. Its length is provided +by the \fIlength\fP field. Note that is allowed (but unwise) to use non\-printing +characters (even 0x00) in the symbol. This allows for multiple encodings of +symbol names. +.UNINDENT +.UNINDENT +.SH EXIT STATUS +.sp +If \fBllvm\-ar\fP succeeds, it will exit with 0. A usage error, results +in an exit code of 1. A hard (file system typically) error results in an +exit code of 2. Miscellaneous or unknown errors result in an +exit code of 3. +.SH SEE ALSO +.sp +llvm\-ranlib|llvm\-ranlib, ar(1) +.SH AUTHOR +Maintained by The LLVM Team (http://llvm.org/). +.SH COPYRIGHT +2012, LLVM Project +.\" Generated by docutils manpage writer. +. |
