| 1 | \input texinfo @c -*- Texinfo -*- |
| 2 | @setfilename binutils.info |
| 3 | |
| 4 | @ifinfo |
| 5 | @format |
| 6 | START-INFO-DIR-ENTRY |
| 7 | |
| 8 | * Binutils: (binutils). |
| 9 | The GNU binary utilities "ar", "ld", "objdump", "nm", |
| 10 | "size", "strip", and "ranlib". |
| 11 | |
| 12 | END-INFO-DIR-ENTRY |
| 13 | @end format |
| 14 | @end ifinfo |
| 15 | |
| 16 | @synindex ky cp |
| 17 | @c |
| 18 | @c This file documents the GNU binary utilities "ar", "ld", "objdump", "nm", |
| 19 | @c "size", "strip", and "ranlib". |
| 20 | @c |
| 21 | @c Copyright (C) 1991 Free Software Foundation, Inc. |
| 22 | @c |
| 23 | @c This text may be freely distributed under the terms of the GNU |
| 24 | @c General Public License. |
| 25 | @c |
| 26 | @c $Id$ |
| 27 | |
| 28 | @setchapternewpage odd |
| 29 | @settitle GNU Binary Utilities |
| 30 | @titlepage |
| 31 | @finalout |
| 32 | @c @smallbook |
| 33 | @c @cropmarks |
| 34 | @title The GNU Binary Utilities |
| 35 | @subtitle Version 1.97 |
| 36 | @sp 1 |
| 37 | @subtitle October 1991 |
| 38 | @author Roland H. Pesch |
| 39 | @author Cygnus Support |
| 40 | @page |
| 41 | |
| 42 | @tex |
| 43 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ |
| 44 | \xdef\manvers{\$Revision$} % For use in headers, footers too |
| 45 | {\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par \hfill |
| 46 | \TeX{}info \texinfoversion\par } |
| 47 | @end tex |
| 48 | |
| 49 | @vskip 0pt plus 1filll |
| 50 | Copyright @copyright{} 1991 Free Software Foundation, Inc. |
| 51 | |
| 52 | Permission is granted to make and distribute verbatim copies of |
| 53 | this manual provided the copyright notice and this permission notice |
| 54 | are preserved on all copies. |
| 55 | |
| 56 | Permission is granted to copy and distribute modified versions of this |
| 57 | manual under the conditions for verbatim copying, provided also that |
| 58 | the entire resulting derived work is distributed under the terms of a |
| 59 | permission notice identical to this one. |
| 60 | |
| 61 | Permission is granted to copy and distribute translations of this manual |
| 62 | into another language, under the above conditions for modified versions. |
| 63 | @end titlepage |
| 64 | |
| 65 | @node Top, ar, (dir), (dir) |
| 66 | @chapter Introduction |
| 67 | |
| 68 | @cindex version |
| 69 | This brief manual contains preliminary documentation for the GNU binary |
| 70 | utilities (collectively version 1.97): |
| 71 | @table @code |
| 72 | @item ar |
| 73 | Create, modify, and extract from archives |
| 74 | |
| 75 | @item nm |
| 76 | List symbols from object files |
| 77 | |
| 78 | @item objdump |
| 79 | Display information from object files |
| 80 | |
| 81 | @item ranlib |
| 82 | Generate index to archive contents |
| 83 | |
| 84 | @item size |
| 85 | List section sizes and total size |
| 86 | |
| 87 | @item strip |
| 88 | Discard symbols |
| 89 | @end table |
| 90 | |
| 91 | @ifinfo |
| 92 | Copyright @copyright{} 1991 Free Software Foundation, Inc. |
| 93 | |
| 94 | Permission is granted to make and distribute verbatim copies of |
| 95 | this manual provided the copyright notice and this permission notice |
| 96 | are preserved on all copies. |
| 97 | |
| 98 | @ignore |
| 99 | Permission is granted to process this file through TeX and print the |
| 100 | results, provided the printed document carries a copying permission |
| 101 | notice identical to this one except for the removal of this paragraph |
| 102 | (this paragraph not being relevant to the printed manual). |
| 103 | |
| 104 | @end ignore |
| 105 | |
| 106 | Permission is granted to copy and distribute modified versions of this |
| 107 | manual under the conditions for verbatim copying, provided also that |
| 108 | the entire resulting derived work is distributed under the terms of a |
| 109 | permission notice identical to this one. |
| 110 | |
| 111 | Permission is granted to copy and distribute translations of this manual |
| 112 | into another language, under the above conditions for modified versions. |
| 113 | @end ifinfo |
| 114 | |
| 115 | @menu |
| 116 | * ar:: ar |
| 117 | * ld:: ld |
| 118 | * nm:: nm |
| 119 | * objdump:: objdump |
| 120 | * ranlib:: ranlib |
| 121 | * size:: size |
| 122 | * strip:: strip |
| 123 | * Index:: Index |
| 124 | |
| 125 | --- The Detailed Node Listing --- |
| 126 | |
| 127 | ar |
| 128 | |
| 129 | * ar-cmdline:: Controlling @code{ar} on the command line |
| 130 | * ar-scripts:: Controlling @code{ar} with a script |
| 131 | @end menu |
| 132 | |
| 133 | @node ar, ld, Top, Top |
| 134 | @chapter ar |
| 135 | |
| 136 | @kindex ar |
| 137 | @cindex archives |
| 138 | @cindex collections of files |
| 139 | @smallexample |
| 140 | ar [-]@var{p}@var{mod} [ @var{membername} ] @var{archive} @var{files}@dots{} |
| 141 | ar -M [ <mri-script ] |
| 142 | @end smallexample |
| 143 | |
| 144 | The GNU @code{ar} program creates, modifies, and extracts from |
| 145 | archives. An @dfn{archive} is a single file holding a collection of |
| 146 | other files in a structure that makes it possible to retrieve |
| 147 | the original individual files (called @dfn{members} of the archive). |
| 148 | |
| 149 | The original files' contents, mode (permissions), timestamp, owner, and |
| 150 | group are preserved in the archive, and may be reconstituted on |
| 151 | extraction. |
| 152 | |
| 153 | @cindex name length |
| 154 | GNU @code{ar} can maintain archives whose members have names of any |
| 155 | length; however, depending on how @code{ar} is configured on your |
| 156 | system, a limit on member-name length may be imposed (for compatibility |
| 157 | with archive formats maintained with other tools). If it exists, the |
| 158 | limit is often 15 characters (typical of formats related to a.out) or 16 |
| 159 | characters (typical of formats related to coff). |
| 160 | |
| 161 | @cindex libraries |
| 162 | @code{ar} is considered a binary utility because archives of this sort |
| 163 | are most often used as @dfn{libraries} holding commonly needed |
| 164 | subroutines. |
| 165 | |
| 166 | @cindex symbol index |
| 167 | @code{ar} will create an index to the symbols defined in relocatable |
| 168 | object modules in the archive when you specify the modifier @samp{s}. |
| 169 | Once created, this index is updated in the archive whenever @code{ar} |
| 170 | makes a change to its contents (save for the @samp{q} update operation). |
| 171 | An archive with such an index speeds up linking to the library, and |
| 172 | allows routines in the library to call each other without regard to |
| 173 | their placement in the archive. |
| 174 | |
| 175 | You may use @samp{nm -s} or @samp{nm +print-armap} to list this index |
| 176 | table. If an archive lacks the table, another form of @code{ar} called |
| 177 | @code{ranlib} can be used to add just the table. |
| 178 | |
| 179 | @cindex compatibility, @code{ar} |
| 180 | @cindex @code{ar} compatibility |
| 181 | GNU @code{ar} is designed to be compatible with two different |
| 182 | facilities. You can control its activity using command-line options, |
| 183 | like the different varieties of @code{ar} on Unix systems; or, if you |
| 184 | specify the single command-line option @samp{-M}, you can control it |
| 185 | with a script supplied via standard input, like the MRI ``librarian'' |
| 186 | program. |
| 187 | |
| 188 | @menu |
| 189 | * ar-cmdline:: Controlling @code{ar} on the command line |
| 190 | * ar-scripts:: Controlling @code{ar} with a script |
| 191 | @end menu |
| 192 | |
| 193 | @page |
| 194 | @node ar-cmdline, ar-scripts, ar, ar |
| 195 | @section Controlling @code{ar} on the command line |
| 196 | |
| 197 | @smallexample |
| 198 | ar [-]@var{p}@var{mod} [ @var{membername} ] @var{archive} @var{files}@dots{} |
| 199 | @end smallexample |
| 200 | |
| 201 | @cindex Unix compatibility, @code{ar} |
| 202 | When you use @code{ar} in the Unix style, @code{ar} insists on at least two |
| 203 | arguments to execute: one keyletter specifying the @emph{operation} |
| 204 | (optionally accompanied by other keyletters specifying |
| 205 | @emph{modifiers}), and the archive name to act on. |
| 206 | |
| 207 | Most operations can also accept further @var{files} arguments, |
| 208 | specifying particular files to operate on. |
| 209 | |
| 210 | GNU @code{ar} allows you to mix the operation code @var{p} and modifier |
| 211 | flags @var{mod} in any order, within the first command-line argument. |
| 212 | |
| 213 | If you wish, you may begin the first command-line argument with a |
| 214 | dash. |
| 215 | |
| 216 | @cindex operations on archive |
| 217 | The @var{p} keyletter specifies what operation to execute; it may be |
| 218 | any of the following, but you must specify only one of them: |
| 219 | |
| 220 | @table @code |
| 221 | @item d |
| 222 | @cindex deleting from archive |
| 223 | @emph{Delete} modules from the archive. Specify the names of modules to |
| 224 | be deleted as @var{files}; the archive is untouched if you |
| 225 | specify no files to delete. |
| 226 | |
| 227 | If you specify the @samp{v} modifier, @code{ar} will list each module |
| 228 | as it is deleted. |
| 229 | |
| 230 | @item m |
| 231 | @cindex moving in archive |
| 232 | Use this operation to @emph{move} members in an archive. |
| 233 | |
| 234 | The ordering of members in an archive can make a difference in how |
| 235 | programs are linked using the library, if a symbol is defined in more |
| 236 | than one member. |
| 237 | |
| 238 | If no modifiers are used with @code{m}, any members you name in the |
| 239 | @var{files} arguments are moved to the @emph{end} of the archive; |
| 240 | you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a |
| 241 | specified place instead. |
| 242 | |
| 243 | @item p |
| 244 | @cindex printing from archive |
| 245 | @emph{Print} the specified members of the archive, to the standard |
| 246 | output file. If the @samp{v} modifier is specified, show the member |
| 247 | name before copying its contents to standard output. |
| 248 | |
| 249 | If you specify no @var{files}, all the files in the archive are printed. |
| 250 | |
| 251 | @item q |
| 252 | @cindex quick append to archive |
| 253 | @emph{Quick append}; add @var{files} to the end of @var{archive}, |
| 254 | without checking for replacement. |
| 255 | |
| 256 | The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this |
| 257 | operation; new members are always placed at the end of the archive. |
| 258 | |
| 259 | The modifier @samp{v} makes @code{ar} list each file as it is appended. |
| 260 | |
| 261 | Since the point of this operation is speed, the archive's symbol table |
| 262 | index is not updated, even if it already existed; you can use @samp{ar s} or |
| 263 | @code{ranlib} explicitly to update the symbol table index. |
| 264 | |
| 265 | @item r |
| 266 | @cindex replacement in archive |
| 267 | Insert @var{files} into @var{archive} (with @emph{replacement}). This |
| 268 | operation differs from @samp{q} in that any previously existing members |
| 269 | are deleted if their names match those being added. |
| 270 | |
| 271 | If one of the files named in @var{files} doesn't exist, @code{ar} |
| 272 | displays an error message, and leaves undisturbed any existing members |
| 273 | of the archive matching that name. |
| 274 | |
| 275 | By default, new members are added at the end of the file; but you may |
| 276 | use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request |
| 277 | placement relative to some existing member. |
| 278 | |
| 279 | The modifier @samp{v} used with this operation elicits a line of |
| 280 | output for each file inserted, along with one of the letters @samp{a} or |
| 281 | @samp{r} to indicate whether the file was appended (no old member |
| 282 | deleted) or replaced. |
| 283 | |
| 284 | @item t |
| 285 | @cindex contents of archive |
| 286 | Display a @emph{table} listing the contents of @var{archive}, or those |
| 287 | of the files listed in @var{files} that are present in the |
| 288 | archive. Normally only the member name is shown; if you also want to |
| 289 | see the modes (permissions), timestamp, owner, group, and size, you can |
| 290 | request that by also specifying the @samp{v} modifier. |
| 291 | |
| 292 | If you do not specify any @var{files}, all files in the archive |
| 293 | are listed. |
| 294 | |
| 295 | @cindex repeated names in archive |
| 296 | @cindex name duplication in archive |
| 297 | If there is more than one file with the same name (say, @samp{fie}) in |
| 298 | an archive (say @samp{b.a}), @samp{ar t b.a fie} will list only the |
| 299 | first instance; to see them all, you must ask for a complete |
| 300 | listing---in our example, @samp{ar t b.a}. |
| 301 | @c WRS only; per Gumby, this is implementation-dependent, and in a more |
| 302 | @c recent case in fact works the other way. |
| 303 | |
| 304 | @item x |
| 305 | @cindex extract from archive |
| 306 | @emph{Extract} members (named @var{files}) from the archive. You can |
| 307 | use the @samp{v} modifier with this operation, to request that |
| 308 | @code{ar} list each name as it extracts it. |
| 309 | |
| 310 | If you do not specify any @var{files}, all files in the archive |
| 311 | are extracted. |
| 312 | |
| 313 | @end table |
| 314 | |
| 315 | A number of modifiers (@var{mod}) may immediately follow the @var{p} |
| 316 | keyletter, to specify variations on an operation's behavior: |
| 317 | |
| 318 | @table @code |
| 319 | @item a |
| 320 | @cindex relative placement in archive |
| 321 | Add new files @emph{after} an existing member of the |
| 322 | archive. If you use the modifier @code{a}, the name of an existing archive |
| 323 | member must be present as the @var{membername} argument, before the |
| 324 | @var{archive} specification. |
| 325 | |
| 326 | @item b |
| 327 | Add new files @emph{before} an existing member of the |
| 328 | archive. If you use the modifier @code{b}, the name of an existing archive |
| 329 | member must be present as the @var{membername} argument, before the |
| 330 | @var{archive} specification. (same as @samp{i}). |
| 331 | |
| 332 | @item c |
| 333 | @cindex creating archives |
| 334 | @emph{Create} the archive. The specified @var{archive} is always |
| 335 | created if it didn't exist, when you request an update. But a warning is |
| 336 | issued unless you specify in advance that you expect to create it, by |
| 337 | using this modifier. |
| 338 | |
| 339 | @item i |
| 340 | Insert new files @emph{before} an existing member of the |
| 341 | archive. If you use the modifier @code{i}, the name of an existing archive |
| 342 | member must be present as the @var{membername} argument, before the |
| 343 | @var{archive} specification. (same as @samp{b}). |
| 344 | |
| 345 | @item l |
| 346 | This modifier is accepted but not used. |
| 347 | @c whaffor ar l modifier??? presumably compat; with |
| 348 | @c what???---pesch@@cygnus.com, 25jan91 |
| 349 | |
| 350 | @item o |
| 351 | @cindex dates in archive |
| 352 | Preserve the @emph{original} dates of members when extracting them. If |
| 353 | you do not specify this modifier, files extracted from the archive |
| 354 | will be stamped with the time of extraction. |
| 355 | |
| 356 | @item s |
| 357 | @cindex writing archive index |
| 358 | Write an object-file index into the archive, or update an existing one, |
| 359 | even if no other change is made to the archive. You may use this modifier |
| 360 | flag either with any operation, or alone. Running @samp{ar s} on an |
| 361 | archive is equivalent to running @samp{ranlib} on it. |
| 362 | |
| 363 | @item u |
| 364 | @cindex updating an archive |
| 365 | Normally, @code{ar r}@dots{} inserts all files |
| 366 | listed into the archive. If you would like to insert @emph{only} those |
| 367 | of the files you list that are newer than existing members of the same |
| 368 | names, use this modifier. The @samp{u} modifier is allowed only for the |
| 369 | operation @samp{r} (replace). In particular, the combination @samp{qu} is |
| 370 | not allowed, since checking the timestamps would lose any speed |
| 371 | advantage from the operation @samp{q}. |
| 372 | |
| 373 | @item v |
| 374 | This modifier requests the @emph{verbose} version of an operation. Many |
| 375 | operations display additional information, such as filenames processed, |
| 376 | when the modifier @samp{v} is appended. |
| 377 | @end table |
| 378 | |
| 379 | @node ar-scripts, , ar-cmdline, ar |
| 380 | @section Controlling @code{ar} with a script |
| 381 | |
| 382 | @smallexample |
| 383 | ar -M [ <@var{script} ] |
| 384 | @end smallexample |
| 385 | |
| 386 | @cindex MRI compatibility, @code{ar} |
| 387 | @cindex scripts, @code{ar} |
| 388 | If you use the single command-line option @samp{-M} with @code{ar}, you |
| 389 | can control its operation with a rudimentary command language. This |
| 390 | form of @code{ar} will operate interactively if standard input is coming |
| 391 | directly from a terminal. During interactive use, @code{ar} prompts for |
| 392 | input (the prompt is @samp{AR >}), and continues executing even after |
| 393 | errors. If you redirect standard input to a script file, no prompts are |
| 394 | issued, and @code{ar} will abandon execution (with a nonzero exit code) |
| 395 | on any error. |
| 396 | |
| 397 | The @code{ar} command language is @emph{not} designed to be equivalent |
| 398 | to the command-line options; in fact, it provides somewhat less control |
| 399 | over archives. The only purpose of the command language is to ease the |
| 400 | transition to GNU @code{ar} for developers who already have scripts |
| 401 | written for the MRI ``librarian'' program. |
| 402 | |
| 403 | The syntax for the @code{ar} command language is straightforward: |
| 404 | @itemize @bullet |
| 405 | @item |
| 406 | commands are recognized in upper or lower case; for example, @code{LIST} |
| 407 | is the same as @code{list}. In the following descriptions, commands are |
| 408 | shown in upper case for clarity. |
| 409 | |
| 410 | @item |
| 411 | a single command may appear on each line; it is the first word on the |
| 412 | line. |
| 413 | |
| 414 | @item |
| 415 | empty lines are allowed, and have no effect. |
| 416 | |
| 417 | @item |
| 418 | comments are allowed; text after either of the characters @samp{*} |
| 419 | or @samp{;} is ignored. |
| 420 | |
| 421 | @item |
| 422 | Whenever you use a list of names as part of the argument to an @code{ar} |
| 423 | command, you can separate the individual names with either commas or |
| 424 | blanks. Commas are shown in the explanations below, for clarity. |
| 425 | |
| 426 | @item |
| 427 | @samp{+} is used as a line continuation character; if @samp{+} appears |
| 428 | at the end of a line, the text on the following line is considered part |
| 429 | of the current command. |
| 430 | @end itemize |
| 431 | |
| 432 | Here are the commands you can use in @code{ar} scripts, or when using |
| 433 | @code{ar} interactively. Three of them have special significance: |
| 434 | |
| 435 | @code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is |
| 436 | a temporary file required for most of the other commands. |
| 437 | |
| 438 | @code{SAVE} commits the changes so far specified by the script. Prior |
| 439 | to @code{SAVE}, commands affect only the temporary copy of the current |
| 440 | archive. |
| 441 | |
| 442 | @table @code |
| 443 | @item ADDLIB @var{archive} |
| 444 | @itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module}) |
| 445 | Add all the contents of @var{archive} (or, if specified, each named |
| 446 | @var{module} from @var{archive}) to the current archive. |
| 447 | |
| 448 | Requires prior use of @code{OPEN} or @code{CREATE}. |
| 449 | |
| 450 | @item ADDMOD @var{file}, @var{file}, @dots{} @var{file} |
| 451 | @c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}" |
| 452 | @c else like "ar q..." |
| 453 | Add each named @var{file} as a module in the current archive. |
| 454 | |
| 455 | Requires prior use of @code{OPEN} or @code{CREATE}. |
| 456 | |
| 457 | @item CLEAR |
| 458 | Discard the contents of the current archive, cancelling the effect of |
| 459 | any operations since the last @code{SAVE}. May be executed (with no |
| 460 | effect) even if no current archive is specified. |
| 461 | |
| 462 | @item CREATE @var{archive} |
| 463 | Creates an archive, and makes it the current archive (required for many |
| 464 | other commands). The new archive is created with a temporary name; it |
| 465 | is not actually saved as @var{archive} until you use @code{SAVE}. |
| 466 | You can overwrite existing archives; similarly, the contents of any |
| 467 | existing file named @var{archive} will not be destroyed until @code{SAVE}. |
| 468 | |
| 469 | @item DELETE @var{module}, @var{module}, @dots{} @var{module} |
| 470 | Delete each listed @var{module} from the current archive; equivalent to |
| 471 | @samp{ar -d @var{archive} @var{module} @dots{} @var{module}}. |
| 472 | |
| 473 | Requires prior use of @code{OPEN} or @code{CREATE}. |
| 474 | |
| 475 | @item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) |
| 476 | @itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile} |
| 477 | List each named @var{module} present in @var{archive}. The separate |
| 478 | command @code{VERBOSE} specifies the form of the output: when verbose |
| 479 | output is off, output is like that of @samp{ar -t @var{archive} |
| 480 | @var{module}@dots{}}. When verbose output is on, the listing is like |
| 481 | @samp{ar -tv @var{archive} @var{module}@dots{}}. |
| 482 | |
| 483 | Output normally goes to the standard output stream; however, if you |
| 484 | specify @var{outputfile} as a final argument, @code{ar} directs the |
| 485 | output to that file. |
| 486 | |
| 487 | @item END |
| 488 | Exit from @code{ar}, with a @code{0} exit code to indicate successful |
| 489 | completion. This command does not save the output file; if you have |
| 490 | changed the current archive since the last @code{SAVE} command, those |
| 491 | changes are lost. |
| 492 | |
| 493 | @item EXTRACT @var{module}, @var{module}, @dots{} @var{module} |
| 494 | Extract each named @var{module} from the current archive, writing them |
| 495 | into the current directory as separate files. Equivalent to @samp{ar -x |
| 496 | @var{archive} @var{module}@dots{}}. |
| 497 | |
| 498 | Requires prior use of @code{OPEN} or @code{CREATE}. |
| 499 | |
| 500 | @ignore |
| 501 | @c FIXME Tokens but no commands??? |
| 502 | @item FULLDIR |
| 503 | |
| 504 | @item HELP |
| 505 | @end ignore |
| 506 | |
| 507 | @item LIST |
| 508 | Display full contents of the current archive, in ``verbose'' style |
| 509 | regardless of the state of @code{VERBOSE}. The effect is like @samp{ar |
| 510 | tv @var{archive}}). (This single command is a GNU @code{ld} |
| 511 | enhancement, rather than present for MRI compatibility.) |
| 512 | |
| 513 | Requires prior use of @code{OPEN} or @code{CREATE}. |
| 514 | |
| 515 | @item OPEN @var{archive} |
| 516 | Opens an existing archive for use as the current archive (required for |
| 517 | many other commands). Any changes as the result of subsequent commands |
| 518 | will not actually affect @var{archive} until you next use @code{SAVE}. |
| 519 | |
| 520 | @item REPLACE @var{module}, @var{module}, @dots{} @var{module} |
| 521 | In the current archive, replace each existing @var{module} (named in |
| 522 | the @code{REPLACE} arguments) from files in the current working directory. |
| 523 | To execute this command without errors, both the file, and the module in |
| 524 | the current archive, must exist. |
| 525 | |
| 526 | Requires prior use of @code{OPEN} or @code{CREATE}. |
| 527 | |
| 528 | @item VERBOSE |
| 529 | Toggle an internal flag governing the output from @code{DIRECTORY}. |
| 530 | When the flag is on, @code{DIRECTORY} output matches output from |
| 531 | @samp{ar -tv @dots{}}. |
| 532 | |
| 533 | @item SAVE |
| 534 | Commit your changes to the current archive, and actually save it as a |
| 535 | file with the name specified in the last @code{CREATE} or @code{OPEN} |
| 536 | command. |
| 537 | |
| 538 | Requires prior use of @code{OPEN} or @code{CREATE}. |
| 539 | |
| 540 | @end table |
| 541 | |
| 542 | |
| 543 | @node ld, nm, ar, Top |
| 544 | @chapter ld |
| 545 | @cindex linker |
| 546 | @kindex ld |
| 547 | The GNU linker @code{ld} is now described in a separate manual. |
| 548 | @xref{Top,, Overview,, Using LD: the GNU linker}. |
| 549 | |
| 550 | @node nm, objdump, ld, Top |
| 551 | @chapter nm |
| 552 | @cindex symbols |
| 553 | @kindex nm |
| 554 | |
| 555 | @smallexample |
| 556 | nm [ -a | +debug-syms ] [ -g | +extern-only ] |
| 557 | [ -s | +print-armap ] [ -o | +print-file-name ] |
| 558 | [ -n | +numeric-sort ] [ -p | +no-sort ] |
| 559 | [ -r | +reverse-sort ] [ -u | +undefined-only ] |
| 560 | [ +target @var{bfdname} ] |
| 561 | [ @var{objfiles}@dots{} ] |
| 562 | @end smallexample |
| 563 | |
| 564 | GNU @code{nm} will list the symbols from object files @var{objfiles}. |
| 565 | |
| 566 | The long and short forms of options, shown here as alternatives, are |
| 567 | equivalent. |
| 568 | |
| 569 | @table @code |
| 570 | @item @var{objfiles}@dots{} |
| 571 | @kindex a.out |
| 572 | Object files whose symbols are to be listed. If no object files are |
| 573 | listed as arguments, @code{nm} assumes @samp{a.out}. |
| 574 | |
| 575 | @item -a |
| 576 | @itemx +debug-syms |
| 577 | @cindex debugging symbols |
| 578 | Display debugger-only symbols; normally these are not listed. |
| 579 | |
| 580 | @item -g |
| 581 | @itemx +extern-only |
| 582 | @cindex external symbols |
| 583 | Display only external symbols. |
| 584 | |
| 585 | @item -p |
| 586 | @itemx +no-sort |
| 587 | @cindex sorting symbols |
| 588 | Don't bother to sort the symbols in any order; just print them in the |
| 589 | order encountered. |
| 590 | |
| 591 | @item -n |
| 592 | @itemx +numeric-sort |
| 593 | Sort symbols numerically by their addresses, not alphabetically by their |
| 594 | names. |
| 595 | |
| 596 | @item -s |
| 597 | @itemx +print-armap |
| 598 | @cindex symbol index, listing |
| 599 | When listing symbols from archive members, include the index: a mapping |
| 600 | (stored in the archive by @code{ar} or @code{ranlib}) of what modules |
| 601 | contain definitions for what names. |
| 602 | |
| 603 | @item -o |
| 604 | @itemx +print-file-name |
| 605 | @cindex input file name |
| 606 | @cindex file name |
| 607 | @cindex source file name |
| 608 | Precede each symbol by the name of the input file where it was found, |
| 609 | rather than identifying the input file once only before all of its |
| 610 | symbols. |
| 611 | |
| 612 | @item -r |
| 613 | @itemx +reverse-sort |
| 614 | Reverse the sense of the sort (whether numeric or alphabetic); let the |
| 615 | last come first. |
| 616 | |
| 617 | @item +target @var{bfdname} |
| 618 | @c @item +target |
| 619 | @cindex object code format |
| 620 | Specify an object code format other than your system's default format. |
| 621 | @xref{objdump}, for information on listing available formats. |
| 622 | @c FIXME what *does* +target/no arg do? |
| 623 | |
| 624 | @item -u |
| 625 | @itemx +undefined-only |
| 626 | @cindex external symbols |
| 627 | @cindex undefined symbols |
| 628 | Display only undefined symbols (those external to each object file). |
| 629 | |
| 630 | @end table |
| 631 | |
| 632 | @node objdump, ranlib, nm, Top |
| 633 | @chapter objdump |
| 634 | |
| 635 | @cindex object file information |
| 636 | @kindex objdump |
| 637 | |
| 638 | @smallexample |
| 639 | objdump [ -a ] [ -b @var{bfdname} ] [ -d ] [ -f ] |
| 640 | [ -h | --header ] [ -i ] [ -j @var{section} ] [ -l ] |
| 641 | [ -m @var{machine} ] [ -r | --reloc ] [ -s ] |
| 642 | [ --stabs ] [ -t | --syms ] [ -x ] |
| 643 | @var{objfiles}@dots{} |
| 644 | @end smallexample |
| 645 | |
| 646 | @code{objdump} displays information about one or more object files. |
| 647 | The options control what particular information to display. This |
| 648 | information is mostly useful to programmers who are working on the |
| 649 | compilation tools, as opposed to programmers who just want their |
| 650 | program to compile and work. |
| 651 | |
| 652 | The long and short forms of options, shown here as alternatives, are |
| 653 | equivalent. |
| 654 | |
| 655 | @table @code |
| 656 | @item @var{objfiles}@dots{} |
| 657 | The object files to be examined. When you specify archives, |
| 658 | @code{objdump} shows information on each of the member object files. |
| 659 | |
| 660 | @item -a |
| 661 | @c print_arelt_descr |
| 662 | @cindex archive headers |
| 663 | If any files from @var{objfiles} are archives, display the archive |
| 664 | header information (in a format similar to @samp{ls -l}). Besides the |
| 665 | information you could list with @samp{ar tv}, @samp{objdump -a} shows |
| 666 | the object file format of each archive member. |
| 667 | |
| 668 | @c suggest longname --target or --format or --bfd |
| 669 | @item -b @var{bfdname} |
| 670 | @cindex object code format |
| 671 | You can specify a particular object-code format for your object files as |
| 672 | @var{bfdname}. This may not be necessary; @var{objdump} can |
| 673 | automatically recognize many formats. For example, |
| 674 | @example |
| 675 | objdump -b oasys -m vax -h fu.o |
| 676 | @end example |
| 677 | @noindent |
| 678 | Displays summary information from the section headers (@samp{-h}) of |
| 679 | @file{fu.o}, which is explicitly identified (@samp{-m}) as a Vax object |
| 680 | file in the format produced by Oasys compilers. You can list the |
| 681 | formats available with the @samp{-i} option. |
| 682 | |
| 683 | @item -d |
| 684 | @cindex disassembling object code |
| 685 | @cindex machine instructions |
| 686 | Disassemble. Display the assembler mnemonics for the machine |
| 687 | instructions from @var{objfiles}. |
| 688 | |
| 689 | @item -f |
| 690 | @cindex object file header |
| 691 | File header. Display summary information from the overall header of |
| 692 | each file in @var{objfiles}. |
| 693 | |
| 694 | @item -h |
| 695 | @itemx --header |
| 696 | @cindex section headers |
| 697 | Header. Display summary information from the section headers of the |
| 698 | object file. |
| 699 | |
| 700 | @item -i |
| 701 | @cindex architectures available |
| 702 | @cindex object formats available |
| 703 | Display a list showing all architectures and object formats available |
| 704 | for specification with @code{-b} or @code{-m}. |
| 705 | |
| 706 | @c suggest longname --section |
| 707 | @item -j @var{name} |
| 708 | @cindex section information |
| 709 | Display information only for section @var{name} |
| 710 | |
| 711 | @c suggest longname --label or --linespec |
| 712 | @item -l |
| 713 | @cindex source filenames for object files |
| 714 | Label the display (using debugging information) with the source filename |
| 715 | and line numbers corresponding to the object code shown. |
| 716 | |
| 717 | @c suggest longname --architecture |
| 718 | @item -m @var{machine} |
| 719 | @cindex architecture |
| 720 | Specify the object files @var{objfiles} are for architecture |
| 721 | @var{machine}. You can list available architectures using the @samp{-i} |
| 722 | option. |
| 723 | |
| 724 | @item -r |
| 725 | @itemx --reloc |
| 726 | @cindex relocation entries, in object file |
| 727 | Relocation. Print the relocation entries of the file. |
| 728 | |
| 729 | @item -s |
| 730 | @cindex sections, full contents |
| 731 | @cindex object file sections |
| 732 | Display the full contents of any sections requested. |
| 733 | |
| 734 | @item --stabs |
| 735 | @cindex stab |
| 736 | @cindex .stab |
| 737 | @cindex debug symbols |
| 738 | @cindex ELF object file format |
| 739 | Display the full contents of any sections requested. |
| 740 | Display the contents of the .stab section from an ELF file. |
| 741 | This is only useful on systems (such as Solaris 2.0) in which |
| 742 | @code{.stab} debugging symbol-table entries are carried in an ELF section. |
| 743 | In most other file formats, debugging symbol-table entries are |
| 744 | interleaved with linkage symbols, and are visible in the @samp{--syms} |
| 745 | output. |
| 746 | |
| 747 | @item -t |
| 748 | @itemx --syms |
| 749 | @cindex symbol table entries, printing |
| 750 | Symbol Table. Print the symbol table entries of the file. |
| 751 | This is similar to the information provided by the @samp{nm} program. |
| 752 | |
| 753 | @item -x |
| 754 | @cindex all header information, object file |
| 755 | @cindex header information, all |
| 756 | Display all available header information, including the symbol table and |
| 757 | relocation entries. Using @samp{-x} is equivalent to specifying all of |
| 758 | @samp{-a -f -h -r -t}. |
| 759 | |
| 760 | @end table |
| 761 | |
| 762 | @node ranlib, size, objdump, Top |
| 763 | @chapter ranlib |
| 764 | |
| 765 | @kindex ranlib |
| 766 | @cindex archive contents |
| 767 | @cindex symbol index |
| 768 | |
| 769 | @smallexample |
| 770 | ranlib @var{archive} |
| 771 | @end smallexample |
| 772 | |
| 773 | @code{ranlib} generates an index to the contents of an archive, and |
| 774 | stores it in the archive. The index lists each symbol defined by a |
| 775 | member of an archive that is a relocatable object file. |
| 776 | |
| 777 | You may use @samp{nm -s} or @samp{nm +print-armap} to list this index. |
| 778 | |
| 779 | An archive with such an index speeds up linking to the library, and |
| 780 | allows routines in the library to call each other without regard to |
| 781 | their placement in the archive. |
| 782 | |
| 783 | The GNU @code{ranlib} program is another form of GNU @code{ar}; running |
| 784 | @code{ranlib} is completely equivalent to executing @samp{ar -s}. |
| 785 | @xref{ar}. |
| 786 | |
| 787 | @node size, strip, ranlib, Top |
| 788 | @chapter size |
| 789 | |
| 790 | @kindex size |
| 791 | @cindex section sizes |
| 792 | |
| 793 | @smallexample |
| 794 | size [ -A | -B | +format @var{compatibility} ] |
| 795 | [ +help ] [ -d | -o | -x | +radix @var{number} ] |
| 796 | [ +target @var{bfdname} ] [ -V | +version ] |
| 797 | @var{objfiles}@dots{} |
| 798 | @end smallexample |
| 799 | |
| 800 | The GNU @code{size} utility lists the section sizes---and the total |
| 801 | size---for each of the object files @var{objfiles} in its argument list. |
| 802 | By default, one line of output is generated for each object file or each |
| 803 | module in an archive. |
| 804 | |
| 805 | The command line options have the following meanings: |
| 806 | @table @code |
| 807 | @item @var{objfiles}@dots{} |
| 808 | The object files to be examined. |
| 809 | |
| 810 | @item -A |
| 811 | @itemx -B |
| 812 | @itemx +format @var{compatibility} |
| 813 | @cindex size display format |
| 814 | Using one of these options, you can choose whether the output from GNU |
| 815 | @code{size} resembles output from System V @code{size} (using @samp{-A}, |
| 816 | or @samp{+format sysv}), or Berkeley @code{size} (using @samp{-B}, or |
| 817 | @samp{+format berkeley}). The default is the one-line format similar to |
| 818 | Berkeley's. |
| 819 | @c Bonus for doc-source readers: you can also say +format=strange (or |
| 820 | @c anything else that starts with 's') for sysv, and +format=boring (or |
| 821 | @c anything else that starts with 'b') for Berkeley. |
| 822 | |
| 823 | Here is an example of the Berkeley (default) format of output from |
| 824 | @code{size}: |
| 825 | @smallexample |
| 826 | eg$ size +format Berkeley ranlib size |
| 827 | text data bss dec hex filename |
| 828 | 294880 81920 11592 388392 5ed28 ranlib |
| 829 | 294880 81920 11888 388688 5ee50 size |
| 830 | @end smallexample |
| 831 | |
| 832 | @noindent |
| 833 | This is the same data, but displayed closer to System V conventions: |
| 834 | |
| 835 | @smallexample |
| 836 | eg$ size +format SysV ranlib size |
| 837 | ranlib : |
| 838 | section size addr |
| 839 | .text 294880 8192 |
| 840 | .data 81920 303104 |
| 841 | .bss 11592 385024 |
| 842 | Total 388392 |
| 843 | |
| 844 | |
| 845 | size : |
| 846 | section size addr |
| 847 | .text 294880 8192 |
| 848 | .data 81920 303104 |
| 849 | .bss 11888 385024 |
| 850 | Total 388688 |
| 851 | @end smallexample |
| 852 | |
| 853 | @item +help |
| 854 | Show a summary of acceptable arguments and options. |
| 855 | |
| 856 | @item -d |
| 857 | @itemx -o |
| 858 | @itemx -x |
| 859 | @itemx +radix @var{number} |
| 860 | @cindex size number format |
| 861 | @cindex radix for section sizes |
| 862 | Using one of these options, you can control whether the size of each |
| 863 | section is given in decimal (@samp{-d}, or @samp{+radix 10}); octal |
| 864 | (@samp{-o}, or @samp{+radix 8}); or hexadecimal (@samp{-x}, or |
| 865 | @samp{+radix 16}). In @samp{+radix @var{number}}, only the three |
| 866 | values (8, 10, 16) are supported. The total size is always given in two |
| 867 | radices; decimal and hexadecimal for @samp{-d} or @samp{-x} output, or |
| 868 | octal and hexadecimal if you're using @samp{-o}. |
| 869 | |
| 870 | @item +target @var{bfdname} |
| 871 | @cindex object code format |
| 872 | You can specify a particular object-code format for @var{objfiles} as |
| 873 | @var{bfdname}. This may not be necessary; @var{size} can |
| 874 | automatically recognize many formats. @xref{objdump}, for information |
| 875 | on listing available formats. |
| 876 | |
| 877 | @item -V |
| 878 | @itemx +version |
| 879 | Display version number information on @code{size} itself. |
| 880 | |
| 881 | @end table |
| 882 | |
| 883 | @node strip, Index, size, Top |
| 884 | @chapter strip |
| 885 | |
| 886 | @kindex strip |
| 887 | @cindex removing symbols |
| 888 | @cindex discarding symbols |
| 889 | |
| 890 | @smallexample |
| 891 | strip [ -s | +strip-all ] [ -g | -S | +strip-debug ] |
| 892 | [ -x | +discard-all ] [ -X | +discard-locals ] |
| 893 | [ -T @var{bfdname} ] |
| 894 | @var{objfiles}@dots{} |
| 895 | @end smallexample |
| 896 | |
| 897 | GNU @code{strip} will discard all symbols from object files |
| 898 | @var{objfiles}, if no options are specified; or only certain symbols, |
| 899 | depending on its command-line options. |
| 900 | |
| 901 | @code{strip} will not execute unless at least one object file is listed. |
| 902 | |
| 903 | @quotation |
| 904 | @emph{WARNING:} @code{strip} modifies the files named in its argument, |
| 905 | rather than writing modified copies under different names. |
| 906 | @end quotation |
| 907 | |
| 908 | The long and short forms of options, shown here as alternatives, are |
| 909 | equivalent. |
| 910 | |
| 911 | @table @code |
| 912 | @item -s |
| 913 | @itemx +strip-all |
| 914 | @cindex all symbols, discarding |
| 915 | This is the default case: strip all symbol entries from @var{objfiles}. |
| 916 | |
| 917 | @item -g |
| 918 | @itemx -S |
| 919 | @itemx +strip-debug |
| 920 | @cindex debugging symbols, discarding |
| 921 | Discard only debugging symbol information from @var{objfiles}. |
| 922 | |
| 923 | @item -x |
| 924 | @itemx +discard-all |
| 925 | @cindex local symbols, discarding |
| 926 | Discard all symbols local to each file in @var{objfiles}. |
| 927 | @emph{WARNING:} Note that @code{+discard-all} discards only @emph{local} |
| 928 | symbols, in spite of its name. |
| 929 | |
| 930 | @item -X |
| 931 | @itemx +discard-locals |
| 932 | Discard local symbols starting with @samp{L} from each file in |
| 933 | @var{objfiles}. (Some compilers produce internally-used symbols that |
| 934 | begin with @samp{L}.) |
| 935 | |
| 936 | @item -T @var{bfdname} |
| 937 | @cindex object code format |
| 938 | You can specify a particular object-code format @var{bfdname} for |
| 939 | @var{objfiles}. This may not be necessary; @var{strip} can automatically |
| 940 | recognize many formats. @xref{objdump}, for information on listing |
| 941 | available formats. |
| 942 | @end table |
| 943 | |
| 944 | @node Index, , strip, Top |
| 945 | @unnumbered Index |
| 946 | |
| 947 | @printindex cp |
| 948 | |
| 949 | @contents |
| 950 | @bye |