usr.bin/clang/llvm-ar/llvm-ar.1

   1 .\" $FreeBSD$
   2 .\" Man page generated from reStructuredText.
   3 .
   4 .TH "LLVM-AR" "1" "2020-06-26" "10" "LLVM"
   5 .SH NAME
   6 llvm-ar \- LLVM archiver
   7 .
   8 .nr rst2man-indent-level 0
   9 .
  10 .de1 rstReportMargin
  11 \\$1 \\n[an-margin]
  12 level \\n[rst2man-indent-level]
  13 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  14 -
  15 \\n[rst2man-indent0]
  16 \\n[rst2man-indent1]
  17 \\n[rst2man-indent2]
  18 ..
  19 .de1 INDENT
  20 .\" .rstReportMargin pre:
  21 . RS \\$1
  22 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  23 . nr rst2man-indent-level +1
  24 .\" .rstReportMargin post:
  25 ..
  26 .de UNINDENT
  27 . RE
  28 .\" indent \\n[an-margin]
  29 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  30 .nr rst2man-indent-level -1
  31 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  32 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  33 ..
  34 .SH SYNOPSIS
  35 .sp
  36 \fBllvm\-ar\fP [\-]{dmpqrstx}[abcDilLNoOPsSTuUvV] [relpos] [count] archive [files...]
  37 .SH DESCRIPTION
  38 .sp
  39 The \fBllvm\-ar\fP command is similar to the common Unix utility,
  40 \fBar\fP\&. It archives several files, such as objects and LLVM bitcode
  41 files into a single archive library that can be linked into a program. However,
  42 the archive can contain any kind of file. By default, \fBllvm\-ar\fP
  43 generates a symbol table that makes linking faster because only the symbol
  44 table needs to be consulted, not each individual file member of the archive.
  45 .sp
  46 The \fBllvm\-ar\fP command can be used to \fIread\fP archive files in SVR4,
  47 GNU, BSD and Darwin format, and \fIwrite\fP in the GNU, BSD, and Darwin style
  48 archive files. If an SVR4 format archive is used with the \fI\%r\fP
  49 (replace), \fI\%d\fP (delete), \fI\%m\fP (move) or \fI\%q\fP
  50 (quick update) operations, the archive will be reconstructed in the format
  51 defined by \fI\%\-\-format\fP\&.
  52 .sp
  53 Here\(aqs where \fBllvm\-ar\fP departs from previous \fBar\fP
  54 implementations:
  55 .sp
  56 \fIThe following option is not supported\fP
  57 .INDENT 0.0
  58 .INDENT 3.5
  59 [f] \- truncate inserted filenames
  60 .UNINDENT
  61 .UNINDENT
  62 .sp
  63 \fIThe following options are ignored for compatibility\fP
  64 .INDENT 0.0
  65 .INDENT 3.5
  66 \-\-plugin=<string> \- load a plugin which adds support for other file formats
  67 .sp
  68 [l] \- ignored in \fBar\fP
  69 .UNINDENT
  70 .UNINDENT
  71 .sp
  72 \fISymbol Table\fP
  73 .INDENT 0.0
  74 .INDENT 3.5
  75 Since \fBllvm\-ar\fP supports bitcode files, the symbol table it creates
  76 includes both native and bitcode symbols.
  77 .UNINDENT
  78 .UNINDENT
  79 .sp
  80 \fIDeterministic Archives\fP
  81 .INDENT 0.0
  82 .INDENT 3.5
  83 By default, \fBllvm\-ar\fP always uses zero for timestamps and UIDs/GIDs
  84 to write archives in a deterministic mode. This is equivalent to the
  85 \fI\%D\fP modifier being enabled by default. If you wish to maintain
  86 compatibility with other \fBar\fP implementations, you can pass the
  87 \fI\%U\fP modifier to write actual timestamps and UIDs/GIDs.
  88 .UNINDENT
  89 .UNINDENT
  90 .sp
  91 \fIWindows Paths\fP
  92 .INDENT 0.0
  93 .INDENT 3.5
  94 When on Windows \fBllvm\-ar\fP treats the names of archived \fIfiles\fP in the same
  95 case sensitive manner as the operating system. When on a non\-Windows machine
  96 \fBllvm\-ar\fP does not consider character case.
  97 .UNINDENT
  98 .UNINDENT
  99 .SH OPTIONS
 100 .sp
 101 \fBllvm\-ar\fP operations are compatible with other \fBar\fP
 102 implementations. However, there are a few modifiers (\fI\%L\fP) that are not
 103 found in other \fBar\fP implementations. The options for
 104 \fBllvm\-ar\fP specify a single basic Operation to perform on the archive,
 105 a variety of Modifiers for that Operation, the name of the archive file, and an
 106 optional list of file names. If the \fIfiles\fP option is not specified, it
 107 generally means either "none" or "all" members, depending on the operation. The
 108 Options, Operations and Modifiers are explained in the sections below.
 109 .sp
 110 The minimal set of options is at least one operator and the name of the
 111 archive.
 112 .SS Operations
 113 .INDENT 0.0
 114 .TP
 115 .B d [NT]
 116 Delete files from the \fBarchive\fP\&. The \fI\%N\fP and \fI\%T\fP modifiers
 117 apply to this operation. The \fIfiles\fP options specify which members should be
 118 removed from the archive. It is not an error if a specified file does not
 119 appear in the archive. If no \fIfiles\fP are specified, the archive is not
 120 modified.
 121 .UNINDENT
 122 .INDENT 0.0
 123 .TP
 124 .B m [abi]
 125 Move files from one location in the \fBarchive\fP to another. The \fI\%a\fP,
 126 \fI\%b\fP, and \fI\%i\fP modifiers apply to this operation. The \fIfiles\fP
 127 will all be moved to the location given by the modifiers. If no modifiers are
 128 used, the files will be moved to the end of the archive. If no \fIfiles\fP are
 129 specified, the archive is not modified.
 130 .UNINDENT
 131 .INDENT 0.0
 132 .TP
 133 .B p [v]
 134 Print \fIfiles\fP to the standard output stream. If no \fIfiles\fP are specified, the
 135 entire \fBarchive\fP is printed. With the \fI\%v\fP modifier,
 136 \fBllvm\-ar\fP also prints out the name of the file being output. Printing
 137 binary files is  ill\-advised as they might confuse your terminal settings. The
 138 \fI\%p\fP operation never modifies the archive.
 139 .UNINDENT
 140 .INDENT 0.0
 141 .TP
 142 .B q [LT]
 143 Quickly append files to the end of the \fBarchive\fP without removing
 144 duplicates. If no \fIfiles\fP are specified, the archive is not modified. The
 145 behavior when appending one archive to another depends upon whether the
 146 \fI\%L\fP and \fI\%T\fP modifiers are used:
 147 .INDENT 7.0
 148 .IP \(bu 2
 149 Appending a regular archive to a regular archive will append the archive
 150 file. If the \fI\%L\fP modifier is specified the members will be appended
 151 instead.
 152 .IP \(bu 2
 153 Appending a regular archive to a thin archive requires the \fI\%T\fP
 154 modifier and will append the archive file. The \fI\%L\fP modifier is not
 155 supported.
 156 .IP \(bu 2
 157 Appending a thin archive to a regular archive will append the archive file.
 158 If the \fI\%L\fP modifier is specified the members will be appended
 159 instead.
 160 .IP \(bu 2
 161 Appending a thin archive to a thin archive will always quick append its
 162 members.
 163 .UNINDENT
 164 .UNINDENT
 165 .INDENT 0.0
 166 .TP
 167 .B r [abTu]
 168 Replace existing \fIfiles\fP or insert them at the end of the \fBarchive\fP if
 169 they do not exist. The \fI\%a\fP, \fI\%b\fP, \fI\%T\fP and \fI\%u\fP
 170 modifiers apply to this operation. If no \fIfiles\fP are specified, the archive
 171 is not modified.
 172 .UNINDENT
 173 .sp
 174 t[v]
 175 .. option:: t [vO]
 176 .INDENT 0.0
 177 .INDENT 3.5
 178 Print the table of contents. Without any modifiers, this operation just prints
 179 the names of the members to the standard output stream. With the \fI\%v\fP
 180 modifier, \fBllvm\-ar\fP also prints out the file type (B=bitcode,
 181 S=symbol table, blank=regular file), the permission mode, the owner and group,
 182 are ignored when extracting \fIfiles\fP and set to placeholder values when adding
 183 size, and the date. With the \fI\%O\fP modifier, display member offsets. If
 184 any \fIfiles\fP are specified, the listing is only for those files. If no \fIfiles\fP
 185 are specified, the table of contents for the whole archive is printed.
 186 .UNINDENT
 187 .UNINDENT
 188 .INDENT 0.0
 189 .TP
 190 .B V
 191 A synonym for the \fI\%\-\-version\fP option.
 192 .UNINDENT
 193 .INDENT 0.0
 194 .TP
 195 .B x [oP]
 196 Extract \fBarchive\fP members back to files. The \fI\%o\fP modifier applies
 197 to this operation. This operation retrieves the indicated \fIfiles\fP from the
 198 archive and writes them back to the operating system\(aqs file system. If no
 199 \fIfiles\fP are specified, the entire archive is extracted.
 200 .UNINDENT
 201 .SS Modifiers (operation specific)
 202 .sp
 203 The modifiers below are specific to certain operations. See the Operations
 204 section to determine which modifiers are applicable to which operations.
 205 .INDENT 0.0
 206 .TP
 207 .B a
 208 When inserting or moving member files, this option specifies the destination
 209 of the new files as being after the \fIrelpos\fP member. If \fIrelpos\fP is not found,
 210 the files are placed at the end of the \fBarchive\fP\&. \fIrelpos\fP cannot be
 211 consumed without either \fI\%a\fP, \fI\%b\fP or \fI\%i\fP\&.
 212 .UNINDENT
 213 .INDENT 0.0
 214 .TP
 215 .B b
 216 When inserting or moving member files, this option specifies the destination
 217 of the new files as being before the \fIrelpos\fP member. If \fIrelpos\fP is not
 218 found, the files are placed at the end of the \fBarchive\fP\&. \fIrelpos\fP cannot
 219 be consumed without either \fI\%a\fP, \fI\%b\fP or \fI\%i\fP\&. This
 220 modifier is identical to the \fI\%i\fP modifier.
 221 .UNINDENT
 222 .INDENT 0.0
 223 .TP
 224 .B i
 225 A synonym for the \fI\%b\fP option.
 226 .UNINDENT
 227 .INDENT 0.0
 228 .TP
 229 .B L
 230 When quick appending an \fBarchive\fP, instead quick append its members. This
 231 is a feature for \fBllvm\-ar\fP that is not found in gnu\-ar.
 232 .UNINDENT
 233 .INDENT 0.0
 234 .TP
 235 .B N
 236 When extracting or deleting a member that shares its name with another member,
 237 the \fIcount\fP parameter allows you to supply a positive whole number that
 238 selects the instance of the given name, with "1" indicating the first
 239 instance. If \fI\%N\fP is not specified the first member of that name will
 240 be selected. If \fIcount\fP is not supplied, the operation fails.*count* cannot be
 241 .UNINDENT
 242 .INDENT 0.0
 243 .TP
 244 .B o
 245 When extracting files, use the modification times of any \fIfiles\fP as they
 246 appear in the \fBarchive\fP\&. By default \fIfiles\fP extracted from the archive
 247 use the time of extraction.
 248 .UNINDENT
 249 .INDENT 0.0
 250 .TP
 251 .B O
 252 Display member offsets inside the archive.
 253 .UNINDENT
 254 .INDENT 0.0
 255 .TP
 256 .B T
 257 When creating or modifying an archive, this option specifies that the
 258 \fBarchive\fP will be thin. By default, archives are not created as thin
 259 archives and when modifying a thin archive, it will be converted to a regular
 260 archive.
 261 .UNINDENT
 262 .INDENT 0.0
 263 .TP
 264 .B v
 265 When printing \fIfiles\fP or the \fBarchive\fP table of contents, this modifier
 266 instructs \fBllvm\-ar\fP to include additional information in the output.
 267 .UNINDENT
 268 .SS Modifiers (generic)
 269 .sp
 270 The modifiers below may be applied to any operation.
 271 .INDENT 0.0
 272 .TP
 273 .B c
 274 For the \fI\%r\fP (replace)and \fI\%q\fP (quick update) operations,
 275 \fBllvm\-ar\fP will always create the archive if it doesn\(aqt exist.
 276 Normally, \fBllvm\-ar\fP will print a warning message indicating that the
 277 \fBarchive\fP is being created. Using this modifier turns off
 278 that warning.
 279 .UNINDENT
 280 .INDENT 0.0
 281 .TP
 282 .B D
 283 Use zero for timestamps and UIDs/GIDs. This is set by default.
 284 .UNINDENT
 285 .INDENT 0.0
 286 .TP
 287 .B P
 288 Use full paths when matching member names rather than just the file name.
 289 This can be useful when manipulating an \fBarchive\fP generated by another
 290 archiver, as some allow paths as member names. This is the default behavior
 291 for thin archives.
 292 .UNINDENT
 293 .INDENT 0.0
 294 .TP
 295 .B s
 296 This modifier requests that an archive index (or symbol table) be added to the
 297 \fBarchive\fP, as if using ranlib. The symbol table will contain all the
 298 externally visible functions and global variables defined by all the bitcode
 299 files in the archive. By default \fBllvm\-ar\fP generates symbol tables in
 300 archives. This can also be used as an operation.
 301 .UNINDENT
 302 .INDENT 0.0
 303 .TP
 304 .B S
 305 This modifier is the opposite of the \fI\%s\fP modifier. It instructs
 306 \fBllvm\-ar\fP to not build the symbol table. If both \fI\%s\fP and
 307 \fI\%S\fP are used, the last modifier to occur in the options will prevail.
 308 .UNINDENT
 309 .INDENT 0.0
 310 .TP
 311 .B u
 312 Only update \fBarchive\fP members with \fIfiles\fP that have more recent
 313 timestamps.
 314 .UNINDENT
 315 .INDENT 0.0
 316 .TP
 317 .B U
 318 Use actual timestamps and UIDs/GIDs.
 319 .UNINDENT
 320 .SS Other
 321 .INDENT 0.0
 322 .TP
 323 .B \-\-format=<type>
 324 This option allows for default, gnu, darwin or bsd \fB<type>\fP to be selected.
 325 When creating an \fBarchive\fP, \fB<type>\fP will default to that of the host
 326 machine.
 327 .UNINDENT
 328 .INDENT 0.0
 329 .TP
 330 .B \-h, \-\-help
 331 Print a summary of command\-line options and their meanings.
 332 .UNINDENT
 333 .INDENT 0.0
 334 .TP
 335 .B \-M
 336 This option allows for MRI scripts to be read through the standard input
 337 stream. No other options are compatible with this option.
 338 .UNINDENT
 339 .INDENT 0.0
 340 .TP
 341 .B \-\-version
 342 Display the version of the \fBllvm\-ar\fP executable.
 343 .UNINDENT
 344 .INDENT 0.0
 345 .TP
 346 .B @<FILE>
 347 Read command\-line options and commands from response file \fB<FILE>\fP\&.
 348 .UNINDENT
 349 .SH MRI SCRIPTS
 350 .sp
 351 \fBllvm\-ar\fP understands a subset of the MRI scripting interface commonly
 352 supported by archivers following in the ar tradition. An MRI script contains a
 353 sequence of commands to be executed by the archiver. The \fI\%\-M\fP option
 354 allows for an MRI script to be passed to \fBllvm\-ar\fP through the
 355 standard input stream.
 356 .sp
 357 Note that \fBllvm\-ar\fP has known limitations regarding the use of MRI
 358 scripts:
 359 .INDENT 0.0
 360 .IP \(bu 2
 361 Each script can only create one archive.
 362 .IP \(bu 2
 363 Existing archives can not be modified.
 364 .UNINDENT
 365 .SS MRI Script Commands
 366 .sp
 367 Each command begins with the command\(aqs name and must appear on its own line.
 368 Some commands have arguments, which must be separated from the name by
 369 whitespace. An MRI script should begin with either a \fI\%CREATE\fP or
 370 \fI\%CREATETHIN\fP command and will typically end with a \fI\%SAVE\fP
 371 command. Any text after either \(aq*\(aq or \(aq;\(aq is treated as a comment.
 372 .INDENT 0.0
 373 .TP
 374 .B CREATE archive
 375 Begin creation of a regular archive with the specified name. Subsequent
 376 commands act upon this \fBarchive\fP\&.
 377 .UNINDENT
 378 .INDENT 0.0
 379 .TP
 380 .B CREATETHIN archive
 381 Begin creation of a thin archive with the specified name. Subsequent
 382 commands act upon this \fBarchive\fP\&.
 383 .UNINDENT
 384 .INDENT 0.0
 385 .TP
 386 .B ADDLIB archive
 387 Append the contents of \fBarchive\fP to the current archive.
 388 .UNINDENT
 389 .INDENT 0.0
 390 .TP
 391 .B ADDMOD <file>
 392 Append \fB<file>\fP to the current archive.
 393 .UNINDENT
 394 .INDENT 0.0
 395 .TP
 396 .B DELETE <file>
 397 Delete the member of the current archive whose file name, excluding directory
 398 components, matches \fB<file>\fP\&.
 399 .UNINDENT
 400 .INDENT 0.0
 401 .TP
 402 .B SAVE
 403 Write the current archive to the path specified in the previous
 404 \fI\%CREATE\fP/\fI\%CREATETHIN\fP command.
 405 .UNINDENT
 406 .INDENT 0.0
 407 .TP
 408 .B END
 409 Ends the MRI script (optional).
 410 .UNINDENT
 411 .SH EXIT STATUS
 412 .sp
 413 If \fBllvm\-ar\fP succeeds, it will exit with 0.  Otherwise, if an error occurs, it
 414 will exit with a non\-zero value.
 415 .SH AUTHOR
 416 Maintained by the LLVM Team (https://llvm.org/).
 417 .SH COPYRIGHT
 418 2003-2020, LLVM Project
 419 .\" Generated by docutils manpage writer.
 420 .