1279528Sbapt.Dd 2015-03-02 2279528Sbapt.Dt BINUTILS 7 3279528Sbapt.Os 4279528Sbapt.Sh NAME 5279528Sbapt.Nm binutils 6279528Sbapt.Nd GNU Binary Utilities 7279528Sbapt.Sh Introduction 8279528SbaptThis brief manual contains documentation for the GNU binary utilities version "2.17.50 9279528Sbapt[FreeBSD] 2007-07-03": 10279528Sbapt.Pp 11279528SbaptThis document is distributed under the terms of the GNU Free Documentation 12279528SbaptLicense. A copy of the license is included in the section entitled "GNU Free 13279528SbaptDocumentation License". 14279528Sbapt.Pp 15279528Sbapt.Sh ar 16279528Sbapt.Bd -literal -offset indent 17279528Sbaptar [-]p[mod [relpos] [count]] archive [member...] 18279528Sbaptar -M [ <mri-script ] 19279528Sbapt.Ed 20279528Sbapt.Pp 21279528SbaptThe GNU 22279528Sbapt.Xr ar 23279528Sbaptprogram creates, modifies, and extracts from archives. An 24279528Sbapt.Em archive 25279528Sbaptis a single file holding a collection of other files in a structure that makes 26279528Sbaptit possible to retrieve the original individual files (called 27279528Sbapt.Em members 28279528Sbaptof the archive). 29279528Sbapt.Pp 30279528SbaptThe original files' contents, mode (permissions), timestamp, owner, and group 31279528Sbaptare preserved in the archive, and can be restored on extraction. 32279528Sbapt.Pp 33279528SbaptGNU 34279528Sbapt.Xr ar 35279528Sbaptcan maintain archives whose members have names of any length; however, depending 36279528Sbapton how 37279528Sbapt.Xr ar 38279528Sbaptis configured on your system, a limit on member-name length may be imposed 39279528Sbaptfor compatibility with archive formats maintained with other tools. If it 40279528Sbaptexists, the limit is often 15 characters (typical of formats related to a.out) 41279528Sbaptor 16 characters (typical of formats related to coff). 42279528Sbapt.Pp 43279528Sbapt.Xr ar 44279528Sbaptis considered a binary utility because archives of this sort are most often 45279528Sbaptused as 46279528Sbapt.Em libraries 47279528Sbaptholding commonly needed subroutines. 48279528Sbapt.Pp 49279528Sbapt.Xr ar 50279528Sbaptcreates an index to the symbols defined in relocatable object modules in the 51279528Sbaptarchive when you specify the modifier 52279528Sbapt.Li s . 53279528SbaptOnce created, this index is updated in the archive whenever 54279528Sbapt.Xr ar 55279528Sbaptmakes a change to its contents (save for the 56279528Sbapt.Li q 57279528Sbaptupdate operation). An archive with such an index speeds up linking to the 58279528Sbaptlibrary, and allows routines in the library to call each other without regard 59279528Sbaptto their placement in the archive. 60279528Sbapt.Pp 61279528SbaptYou may use 62279528Sbapt.Li nm -s 63279528Sbaptor 64279528Sbapt.Li nm --print-armap 65279528Sbaptto list this index table. If an archive lacks the table, another form of 66279528Sbapt.Xr ar 67279528Sbaptcalled 68279528Sbapt.Xr ranlib 69279528Sbaptcan be used to add just the table. 70279528Sbapt.Pp 71279528SbaptGNU 72279528Sbapt.Xr ar 73279528Sbaptis designed to be compatible with two different facilities. You can control 74279528Sbaptits activity using command-line options, like the different varieties of 75279528Sbapt.Xr ar 76279528Sbapton Unix systems; or, if you specify the single command-line option 77279528Sbapt.Op -M , 78279528Sbaptyou can control it with a script supplied via standard input, like the MRI 79279528Sbapt\(lqlibrarian\(rq program. 80279528Sbapt.Pp 81279528Sbapt.Ss Controlling Xr ar on the Command Line 82279528Sbapt.Bd -literal -offset indent 83279528Sbaptar [-X32_64] [-]p[mod [relpos] [count]] archive [member...] 84279528Sbapt.Ed 85279528Sbapt.Pp 86279528SbaptWhen you use 87279528Sbapt.Xr ar 88279528Sbaptin the Unix style, 89279528Sbapt.Xr ar 90279528Sbaptinsists on at least two arguments to execute: one keyletter specifying the 91279528Sbapt.Em operation 92279528Sbapt(optionally accompanied by other keyletters specifying 93279528Sbapt.Em modifiers ) , 94279528Sbaptand the archive name to act on. 95279528Sbapt.Pp 96279528SbaptMost operations can also accept further 97279528Sbapt.Va member 98279528Sbaptarguments, specifying particular files to operate on. 99279528Sbapt.Pp 100279528SbaptGNU 101279528Sbapt.Xr ar 102279528Sbaptallows you to mix the operation code 103279528Sbapt.Va p 104279528Sbaptand modifier flags 105279528Sbapt.Va mod 106279528Sbaptin any order, within the first command-line argument. 107279528Sbapt.Pp 108279528SbaptIf you wish, you may begin the first command-line argument with a dash. 109279528Sbapt.Pp 110279528SbaptThe 111279528Sbapt.Va p 112279528Sbaptkeyletter specifies what operation to execute; it may be any of the following, 113279528Sbaptbut you must specify only one of them: 114279528Sbapt.Pp 115279528Sbapt.Bl -tag -width Ds 116279528Sbapt.It d 117279528Sbapt.Em Delete 118279528Sbaptmodules from the archive. Specify the names of modules to be deleted as 119279528Sbapt.Va member 120279528Sbapt\&...; the archive is untouched if you specify no files to delete. 121279528Sbapt.Pp 122279528SbaptIf you specify the 123279528Sbapt.Li v 124279528Sbaptmodifier, 125279528Sbapt.Xr ar 126279528Sbaptlists each module as it is deleted. 127279528Sbapt.Pp 128279528Sbapt.It m 129279528SbaptUse this operation to 130279528Sbapt.Em move 131279528Sbaptmembers in an archive. 132279528Sbapt.Pp 133279528SbaptThe ordering of members in an archive can make a difference in how programs 134279528Sbaptare linked using the library, if a symbol is defined in more than one member. 135279528Sbapt.Pp 136279528SbaptIf no modifiers are used with 137279528Sbapt.Li m , 138279528Sbaptany members you name in the 139279528Sbapt.Va member 140279528Sbaptarguments are moved to the 141279528Sbapt.Em end 142279528Sbaptof the archive; you can use the 143279528Sbapt.Li a , 144279528Sbapt.Li b , 145279528Sbaptor 146279528Sbapt.Li i 147279528Sbaptmodifiers to move them to a specified place instead. 148279528Sbapt.Pp 149279528Sbapt.It p 150279528Sbapt.Em Print 151279528Sbaptthe specified members of the archive, to the standard output file. If the 152279528Sbapt.Li v 153279528Sbaptmodifier is specified, show the member name before copying its contents to 154279528Sbaptstandard output. 155279528Sbapt.Pp 156279528SbaptIf you specify no 157279528Sbapt.Va member 158279528Sbaptarguments, all the files in the archive are printed. 159279528Sbapt.Pp 160279528Sbapt.It q 161279528Sbapt.Em Quick append ; 162279528SbaptHistorically, add the files 163279528Sbapt.Va member 164279528Sbapt\&...to the end of 165279528Sbapt.Va archive , 166279528Sbaptwithout checking for replacement. 167279528Sbapt.Pp 168279528SbaptThe modifiers 169279528Sbapt.Li a , 170279528Sbapt.Li b , 171279528Sbaptand 172279528Sbapt.Li i 173279528Sbaptdo 174279528Sbapt.Em not 175279528Sbaptaffect this operation; new members are always placed at the end of the archive. 176279528Sbapt.Pp 177279528SbaptThe modifier 178279528Sbapt.Li v 179279528Sbaptmakes 180279528Sbapt.Xr ar 181279528Sbaptlist each file as it is appended. 182279528Sbapt.Pp 183279528SbaptSince the point of this operation is speed, the archive's symbol table index 184279528Sbaptis not updated, even if it already existed; you can use 185279528Sbapt.Li ar s 186279528Sbaptor 187279528Sbapt.Xr ranlib 188279528Sbaptexplicitly to update the symbol table index. 189279528Sbapt.Pp 190279528SbaptHowever, too many different systems assume quick append rebuilds the index, 191279528Sbaptso GNU 192279528Sbapt.Xr ar 193279528Sbaptimplements 194279528Sbapt.Li q 195279528Sbaptas a synonym for 196279528Sbapt.Li r . 197279528Sbapt.Pp 198279528Sbapt.It r 199279528SbaptInsert the files 200279528Sbapt.Va member 201279528Sbapt\&...into 202279528Sbapt.Va archive 203279528Sbapt(with 204279528Sbapt.Em replacement ) . 205279528SbaptThis operation differs from 206279528Sbapt.Li q 207279528Sbaptin that any previously existing members are deleted if their names match those 208279528Sbaptbeing added. 209279528Sbapt.Pp 210279528SbaptIf one of the files named in 211279528Sbapt.Va member 212279528Sbapt\&...does not exist, 213279528Sbapt.Xr ar 214279528Sbaptdisplays an error message, and leaves undisturbed any existing members of 215279528Sbaptthe archive matching that name. 216279528Sbapt.Pp 217279528SbaptBy default, new members are added at the end of the file; but you may use 218279528Sbaptone of the modifiers 219279528Sbapt.Li a , 220279528Sbapt.Li b , 221279528Sbaptor 222279528Sbapt.Li i 223279528Sbaptto request placement relative to some existing member. 224279528Sbapt.Pp 225279528SbaptThe modifier 226279528Sbapt.Li v 227279528Sbaptused with this operation elicits a line of output for each file inserted, 228279528Sbaptalong with one of the letters 229279528Sbapt.Li a 230279528Sbaptor 231279528Sbapt.Li r 232279528Sbaptto indicate whether the file was appended (no old member deleted) or replaced. 233279528Sbapt.Pp 234279528Sbapt.It t 235279528SbaptDisplay a 236279528Sbapt.Em table 237279528Sbaptlisting the contents of 238279528Sbapt.Va archive , 239279528Sbaptor those of the files listed in 240279528Sbapt.Va member 241279528Sbapt\&...that are present in the archive. Normally only the member name is shown; if 242279528Sbaptyou also want to see the modes (permissions), timestamp, owner, group, and 243279528Sbaptsize, you can request that by also specifying the 244279528Sbapt.Li v 245279528Sbaptmodifier. 246279528Sbapt.Pp 247279528SbaptIf you do not specify a 248279528Sbapt.Va member , 249279528Sbaptall files in the archive are listed. 250279528Sbapt.Pp 251279528SbaptIf there is more than one file with the same name (say, 252279528Sbapt.Li fie ) 253279528Sbaptin an archive (say 254279528Sbapt.Li b.a ) , 255279528Sbapt.Li ar t b.a fie 256279528Sbaptlists only the first instance; to see them all, you must ask for a complete 257279528Sbaptlisting---in our example, 258279528Sbapt.Li ar t b.a . 259279528Sbapt.Pp 260279528Sbapt.It x 261279528Sbapt.Em Extract 262279528Sbaptmembers (named 263279528Sbapt.Va member ) 264279528Sbaptfrom the archive. You can use the 265279528Sbapt.Li v 266279528Sbaptmodifier with this operation, to request that 267279528Sbapt.Xr ar 268279528Sbaptlist each name as it extracts it. 269279528Sbapt.Pp 270279528SbaptIf you do not specify a 271279528Sbapt.Va member , 272279528Sbaptall files in the archive are extracted. 273279528Sbapt.Pp 274279528Sbapt.El 275279528SbaptA number of modifiers ( 276279528Sbapt.Va mod ) 277279528Sbaptmay immediately follow the 278279528Sbapt.Va p 279279528Sbaptkeyletter, to specify variations on an operation's behavior: 280279528Sbapt.Pp 281279528Sbapt.Bl -tag -width Ds 282279528Sbapt.It a 283279528SbaptAdd new files 284279528Sbapt.Em after 285279528Sbaptan existing member of the archive. If you use the modifier 286279528Sbapt.Li a , 287279528Sbaptthe name of an existing archive member must be present as the 288279528Sbapt.Va relpos 289279528Sbaptargument, before the 290279528Sbapt.Va archive 291279528Sbaptspecification. 292279528Sbapt.Pp 293279528Sbapt.It b 294279528SbaptAdd new files 295279528Sbapt.Em before 296279528Sbaptan existing member of the archive. If you use the modifier 297279528Sbapt.Li b , 298279528Sbaptthe name of an existing archive member must be present as the 299279528Sbapt.Va relpos 300279528Sbaptargument, before the 301279528Sbapt.Va archive 302279528Sbaptspecification. (same as 303279528Sbapt.Li i ) . 304279528Sbapt.Pp 305279528Sbapt.It c 306279528Sbapt.Em Create 307279528Sbaptthe archive. The specified 308279528Sbapt.Va archive 309279528Sbaptis always created if it did not exist, when you request an update. But a warning 310279528Sbaptis issued unless you specify in advance that you expect to create it, by using 311279528Sbaptthis modifier. 312279528Sbapt.Pp 313279528Sbapt.It f 314279528SbaptTruncate names in the archive. GNU 315279528Sbapt.Xr ar 316279528Sbaptwill normally permit file names of any length. This will cause it to create 317279528Sbaptarchives which are not compatible with the native 318279528Sbapt.Xr ar 319279528Sbaptprogram on some systems. If this is a concern, the 320279528Sbapt.Li f 321279528Sbaptmodifier may be used to truncate file names when putting them in the archive. 322279528Sbapt.Pp 323279528Sbapt.It i 324279528SbaptInsert new files 325279528Sbapt.Em before 326279528Sbaptan existing member of the archive. If you use the modifier 327279528Sbapt.Li i , 328279528Sbaptthe name of an existing archive member must be present as the 329279528Sbapt.Va relpos 330279528Sbaptargument, before the 331279528Sbapt.Va archive 332279528Sbaptspecification. (same as 333279528Sbapt.Li b ) . 334279528Sbapt.Pp 335279528Sbapt.It l 336279528SbaptThis modifier is accepted but not used. 337279528Sbapt.Pp 338279528Sbapt.It N 339279528SbaptUses the 340279528Sbapt.Va count 341279528Sbaptparameter. This is used if there are multiple entries in the archive with 342279528Sbaptthe same name. Extract or delete instance 343279528Sbapt.Va count 344279528Sbaptof the given name from the archive. 345279528Sbapt.Pp 346279528Sbapt.It o 347279528SbaptPreserve the 348279528Sbapt.Em original 349279528Sbaptdates of members when extracting them. If you do not specify this modifier, 350279528Sbaptfiles extracted from the archive are stamped with the time of extraction. 351279528Sbapt.Pp 352279528Sbapt.It P 353279528SbaptUse the full path name when matching names in the archive. GNU 354279528Sbapt.Xr ar 355279528Sbaptcan not create an archive with a full path name (such archives are not POSIX 356279528Sbaptcomplaint), but other archive creators can. This option will cause GNU 357279528Sbapt.Xr ar 358279528Sbaptto match file names using a complete path name, which can be convenient when 359279528Sbaptextracting a single file from an archive created by another tool. 360279528Sbapt.Pp 361279528Sbapt.It s 362279528SbaptWrite an object-file index into the archive, or update an existing one, even 363279528Sbaptif no other change is made to the archive. You may use this modifier flag 364279528Sbapteither with any operation, or alone. Running 365279528Sbapt.Li ar s 366279528Sbapton an archive is equivalent to running 367279528Sbapt.Li ranlib 368279528Sbapton it. 369279528Sbapt.Pp 370279528Sbapt.It S 371279528SbaptDo not generate an archive symbol table. This can speed up building a large 372279528Sbaptlibrary in several steps. The resulting archive can not be used with the linker. 373279528SbaptIn order to build a symbol table, you must omit the 374279528Sbapt.Li S 375279528Sbaptmodifier on the last execution of 376279528Sbapt.Li ar , 377279528Sbaptor you must run 378279528Sbapt.Li ranlib 379279528Sbapton the archive. 380279528Sbapt.Pp 381279528Sbapt.It u 382279528SbaptNormally, 383279528Sbapt.Li ar r 384279528Sbapt\&...inserts all files listed into the archive. If you would like to insert 385279528Sbapt.Em only 386279528Sbaptthose of the files you list that are newer than existing members of the same 387279528Sbaptnames, use this modifier. The 388279528Sbapt.Li u 389279528Sbaptmodifier is allowed only for the operation 390279528Sbapt.Li r 391279528Sbapt(replace). In particular, the combination 392279528Sbapt.Li qu 393279528Sbaptis not allowed, since checking the timestamps would lose any speed advantage 394279528Sbaptfrom the operation 395279528Sbapt.Li q . 396279528Sbapt.Pp 397279528Sbapt.It v 398279528SbaptThis modifier requests the 399279528Sbapt.Em verbose 400279528Sbaptversion of an operation. Many operations display additional information, such 401279528Sbaptas filenames processed, when the modifier 402279528Sbapt.Li v 403279528Sbaptis appended. 404279528Sbapt.Pp 405279528Sbapt.It V 406279528SbaptThis modifier shows the version number of 407279528Sbapt.Xr ar . 408279528Sbapt.El 409279528Sbapt.Pp 410279528Sbapt.Xr ar 411279528Sbaptignores an initial option spelt 412279528Sbapt.Li -X32_64 , 413279528Sbaptfor compatibility with AIX. The behaviour produced by this option is the default 414279528Sbaptfor GNU 415279528Sbapt.Xr ar . 416279528Sbapt.Xr ar 417279528Sbaptdoes not support any of the other 418279528Sbapt.Li -X 419279528Sbaptoptions; in particular, it does not support 420279528Sbapt.Op -X32 421279528Sbaptwhich is the default for AIX 422279528Sbapt.Xr ar . 423279528Sbapt.Pp 424279528Sbapt.Ss Controlling Xr ar with a Script 425279528Sbapt.Bd -literal -offset indent 426279528Sbaptar -M [ <script ] 427279528Sbapt.Ed 428279528Sbapt.Pp 429279528SbaptIf you use the single command-line option 430279528Sbapt.Li -M 431279528Sbaptwith 432279528Sbapt.Xr ar , 433279528Sbaptyou can control its operation with a rudimentary command language. This form 434279528Sbaptof 435279528Sbapt.Xr ar 436279528Sbaptoperates interactively if standard input is coming directly from a terminal. 437279528SbaptDuring interactive use, 438279528Sbapt.Xr ar 439279528Sbaptprompts for input (the prompt is 440279528Sbapt.Li AR > ) , 441279528Sbaptand continues executing even after errors. If you redirect standard input 442279528Sbaptto a script file, no prompts are issued, and 443279528Sbapt.Xr ar 444279528Sbaptabandons execution (with a nonzero exit code) on any error. 445279528Sbapt.Pp 446279528SbaptThe 447279528Sbapt.Xr ar 448279528Sbaptcommand language is 449279528Sbapt.Em not 450279528Sbaptdesigned to be equivalent to the command-line options; in fact, it provides 451279528Sbaptsomewhat less control over archives. The only purpose of the command language 452279528Sbaptis to ease the transition to GNU 453279528Sbapt.Xr ar 454279528Sbaptfor developers who already have scripts written for the MRI \(lqlibrarian\(rq program. 455279528Sbapt.Pp 456279528SbaptThe syntax for the 457279528Sbapt.Xr ar 458279528Sbaptcommand language is straightforward: 459279528Sbapt.Bl -bullet 460279528Sbapt.It 461279528Sbaptcommands are recognized in upper or lower case; for example, 462279528Sbapt.Li LIST 463279528Sbaptis the same as 464279528Sbapt.Li list . 465279528SbaptIn the following descriptions, commands are shown in upper case for clarity. 466279528Sbapt.Pp 467279528Sbapt.It 468279528Sbapta single command may appear on each line; it is the first word on the line. 469279528Sbapt.Pp 470279528Sbapt.It 471279528Sbaptempty lines are allowed, and have no effect. 472279528Sbapt.Pp 473279528Sbapt.It 474279528Sbaptcomments are allowed; text after either of the characters 475279528Sbapt.Li * 476279528Sbaptor 477279528Sbapt.Li ; 478279528Sbaptis ignored. 479279528Sbapt.Pp 480279528Sbapt.It 481279528SbaptWhenever you use a list of names as part of the argument to an 482279528Sbapt.Xr ar 483279528Sbaptcommand, you can separate the individual names with either commas or blanks. 484279528SbaptCommas are shown in the explanations below, for clarity. 485279528Sbapt.Pp 486279528Sbapt.It 487279528Sbapt.Li + 488279528Sbaptis used as a line continuation character; if 489279528Sbapt.Li + 490279528Sbaptappears at the end of a line, the text on the following line is considered 491279528Sbaptpart of the current command. 492279528Sbapt.El 493279528Sbapt.Pp 494279528SbaptHere are the commands you can use in 495279528Sbapt.Xr ar 496279528Sbaptscripts, or when using 497279528Sbapt.Xr ar 498279528Sbaptinteractively. Three of them have special significance: 499279528Sbapt.Pp 500279528Sbapt.Li OPEN 501279528Sbaptor 502279528Sbapt.Li CREATE 503279528Sbaptspecify a 504279528Sbapt.Em current archive , 505279528Sbaptwhich is a temporary file required for most of the other commands. 506279528Sbapt.Pp 507279528Sbapt.Li SAVE 508279528Sbaptcommits the changes so far specified by the script. Prior to 509279528Sbapt.Li SAVE , 510279528Sbaptcommands affect only the temporary copy of the current archive. 511279528Sbapt.Pp 512279528Sbapt.Bl -tag -width Ds 513279528Sbapt.It ADDLIB Va archive 514279528Sbapt.It ADDLIB Va archive ( Va module, Va module, ... Va module) 515279528SbaptAdd all the contents of 516279528Sbapt.Va archive 517279528Sbapt(or, if specified, each named 518279528Sbapt.Va module 519279528Sbaptfrom 520279528Sbapt.Va archive ) 521279528Sbaptto the current archive. 522279528Sbapt.Pp 523279528SbaptRequires prior use of 524279528Sbapt.Li OPEN 525279528Sbaptor 526279528Sbapt.Li CREATE . 527279528Sbapt.Pp 528279528Sbapt.It ADDMOD Va member, Va member, ... Va member 529279528SbaptAdd each named 530279528Sbapt.Va member 531279528Sbaptas a module in the current archive. 532279528Sbapt.Pp 533279528SbaptRequires prior use of 534279528Sbapt.Li OPEN 535279528Sbaptor 536279528Sbapt.Li CREATE . 537279528Sbapt.Pp 538279528Sbapt.It CLEAR 539279528SbaptDiscard the contents of the current archive, canceling the effect of any operations 540279528Sbaptsince the last 541279528Sbapt.Li SAVE . 542279528SbaptMay be executed (with no effect) even if no current archive is specified. 543279528Sbapt.Pp 544279528Sbapt.It CREATE Va archive 545279528SbaptCreates an archive, and makes it the current archive (required for many other 546279528Sbaptcommands). The new archive is created with a temporary name; it is not actually 547279528Sbaptsaved as 548279528Sbapt.Va archive 549279528Sbaptuntil you use 550279528Sbapt.Li SAVE . 551279528SbaptYou can overwrite existing archives; similarly, the contents of any existing 552279528Sbaptfile named 553279528Sbapt.Va archive 554279528Sbaptwill not be destroyed until 555279528Sbapt.Li SAVE . 556279528Sbapt.Pp 557279528Sbapt.It DELETE Va module, Va module, ... Va module 558279528SbaptDelete each listed 559279528Sbapt.Va module 560279528Sbaptfrom the current archive; equivalent to 561279528Sbapt.Li ar -d Va archive Va module ... Va module . 562279528Sbapt.Pp 563279528SbaptRequires prior use of 564279528Sbapt.Li OPEN 565279528Sbaptor 566279528Sbapt.Li CREATE . 567279528Sbapt.Pp 568279528Sbapt.It DIRECTORY Va archive ( Va module, ... Va module) 569279528Sbapt.It DIRECTORY Va archive ( Va module, ... Va module) Va outputfile 570279528SbaptList each named 571279528Sbapt.Va module 572279528Sbaptpresent in 573279528Sbapt.Va archive . 574279528SbaptThe separate command 575279528Sbapt.Li VERBOSE 576279528Sbaptspecifies the form of the output: when verbose output is off, output is like 577279528Sbaptthat of 578279528Sbapt.Li ar -t Va archive Va module... . 579279528SbaptWhen verbose output is on, the listing is like 580279528Sbapt.Li ar -tv Va archive Va module... . 581279528Sbapt.Pp 582279528SbaptOutput normally goes to the standard output stream; however, if you specify 583279528Sbapt.Va outputfile 584279528Sbaptas a final argument, 585279528Sbapt.Xr ar 586279528Sbaptdirects the output to that file. 587279528Sbapt.Pp 588279528Sbapt.It END 589279528SbaptExit from 590279528Sbapt.Xr ar , 591279528Sbaptwith a 592279528Sbapt.Li 0 593279528Sbaptexit code to indicate successful completion. This command does not save the 594279528Sbaptoutput file; if you have changed the current archive since the last 595279528Sbapt.Li SAVE 596279528Sbaptcommand, those changes are lost. 597279528Sbapt.Pp 598279528Sbapt.It EXTRACT Va module, Va module, ... Va module 599279528SbaptExtract each named 600279528Sbapt.Va module 601279528Sbaptfrom the current archive, writing them into the current directory as separate 602279528Sbaptfiles. Equivalent to 603279528Sbapt.Li ar -x Va archive Va module... . 604279528Sbapt.Pp 605279528SbaptRequires prior use of 606279528Sbapt.Li OPEN 607279528Sbaptor 608279528Sbapt.Li CREATE . 609279528Sbapt.Pp 610279528Sbapt.It LIST 611279528SbaptDisplay full contents of the current archive, in \(lqverbose\(rq style regardless 612279528Sbaptof the state of 613279528Sbapt.Li VERBOSE . 614279528SbaptThe effect is like 615279528Sbapt.Li ar tv Va archive . 616279528Sbapt(This single command is a GNU 617279528Sbapt.Xr ar 618279528Sbaptenhancement, rather than present for MRI compatibility.) 619279528Sbapt.Pp 620279528SbaptRequires prior use of 621279528Sbapt.Li OPEN 622279528Sbaptor 623279528Sbapt.Li CREATE . 624279528Sbapt.Pp 625279528Sbapt.It OPEN Va archive 626279528SbaptOpens an existing archive for use as the current archive (required for many 627279528Sbaptother commands). Any changes as the result of subsequent commands will not 628279528Sbaptactually affect 629279528Sbapt.Va archive 630279528Sbaptuntil you next use 631279528Sbapt.Li SAVE . 632279528Sbapt.Pp 633279528Sbapt.It REPLACE Va module, Va module, ... Va module 634279528SbaptIn the current archive, replace each existing 635279528Sbapt.Va module 636279528Sbapt(named in the 637279528Sbapt.Li REPLACE 638279528Sbaptarguments) from files in the current working directory. To execute this command 639279528Sbaptwithout errors, both the file, and the module in the current archive, must 640279528Sbaptexist. 641279528Sbapt.Pp 642279528SbaptRequires prior use of 643279528Sbapt.Li OPEN 644279528Sbaptor 645279528Sbapt.Li CREATE . 646279528Sbapt.Pp 647279528Sbapt.It VERBOSE 648279528SbaptToggle an internal flag governing the output from 649279528Sbapt.Li DIRECTORY . 650279528SbaptWhen the flag is on, 651279528Sbapt.Li DIRECTORY 652279528Sbaptoutput matches output from 653279528Sbapt.Li ar -tv 654279528Sbapt\&...\&. 655279528Sbapt.Pp 656279528Sbapt.It SAVE 657279528SbaptCommit your changes to the current archive, and actually save it as a file 658279528Sbaptwith the name specified in the last 659279528Sbapt.Li CREATE 660279528Sbaptor 661279528Sbapt.Li OPEN 662279528Sbaptcommand. 663279528Sbapt.Pp 664279528SbaptRequires prior use of 665279528Sbapt.Li OPEN 666279528Sbaptor 667279528Sbapt.Li CREATE . 668279528Sbapt.Pp 669279528Sbapt.El 670279528Sbapt.Sh nm 671279528Sbapt.Bd -literal -offset indent 672279528Sbaptnm [-a|--debug-syms] [-g|--extern-only] 673279528Sbapt [-B] [-C|--demangle[=style]] [-D|--dynamic] 674279528Sbapt [-S|--print-size] [-s|--print-armap] 675279528Sbapt [-A|-o|--print-file-name][--special-syms] 676279528Sbapt [-n|-v|--numeric-sort] [-p|--no-sort] 677279528Sbapt [-r|--reverse-sort] [--size-sort] [-u|--undefined-only] 678279528Sbapt [-t radix|--radix=radix] [-P|--portability] 679279528Sbapt [--target=bfdname] [-fformat|--format=format] 680279528Sbapt [--defined-only] [-l|--line-numbers] [--no-demangle] 681279528Sbapt [-V|--version] [-X 32_64] [--help] [objfile...] 682279528Sbapt.Ed 683279528Sbapt.Pp 684279528SbaptGNU 685279528Sbapt.Xr nm 686279528Sbaptlists the symbols from object files 687279528Sbapt.Va objfile 688279528Sbapt\&...\&. If no object files are listed as arguments, 689279528Sbapt.Xr nm 690279528Sbaptassumes the file 691279528Sbapt.Pa a.out . 692279528Sbapt.Pp 693279528SbaptFor each symbol, 694279528Sbapt.Xr nm 695279528Sbaptshows: 696279528Sbapt.Pp 697279528Sbapt.Bl -bullet 698279528Sbapt.It 699279528SbaptThe symbol value, in the radix selected by options (see below), or hexadecimal 700279528Sbaptby default. 701279528Sbapt.Pp 702279528Sbapt.It 703279528SbaptThe symbol type. At least the following types are used; others are, as well, 704279528Sbaptdepending on the object file format. If lowercase, the symbol is local; if 705279528Sbaptuppercase, the symbol is global (external). 706279528Sbapt.Pp 707279528Sbapt.Bl -tag -width Ds 708279528Sbapt.It A 709279528SbaptThe symbol's value is absolute, and will not be changed by further linking. 710279528Sbapt.Pp 711279528Sbapt.It B 712279528SbaptThe symbol is in the uninitialized data section (known as BSS). 713279528Sbapt.Pp 714279528Sbapt.It C 715279528SbaptThe symbol is common. Common symbols are uninitialized data. When linking, 716279528Sbaptmultiple common symbols may appear with the same name. If the symbol is defined 717279528Sbaptanywhere, the common symbols are treated as undefined references. For more 718279528Sbaptdetails on common symbols, see the discussion of --warn-common in Options,,Linker 719279528Sbaptoptions,ld.info,The GNU linker. 720279528Sbapt.Pp 721279528Sbapt.It D 722279528SbaptThe symbol is in the initialized data section. 723279528Sbapt.Pp 724279528Sbapt.It G 725279528SbaptThe symbol is in an initialized data section for small objects. Some object 726279528Sbaptfile formats permit more efficient access to small data objects, such as a 727279528Sbaptglobal int variable as opposed to a large global array. 728279528Sbapt.Pp 729279528Sbapt.It I 730279528SbaptThe symbol is an indirect reference to another symbol. This is a GNU extension 731279528Sbaptto the a.out object file format which is rarely used. 732279528Sbapt.Pp 733279528Sbapt.It N 734279528SbaptThe symbol is a debugging symbol. 735279528Sbapt.Pp 736279528Sbapt.It R 737279528SbaptThe symbol is in a read only data section. 738279528Sbapt.Pp 739279528Sbapt.It S 740279528SbaptThe symbol is in an uninitialized data section for small objects. 741279528Sbapt.Pp 742279528Sbapt.It T 743279528SbaptThe symbol is in the text (code) section. 744279528Sbapt.Pp 745279528Sbapt.It U 746279528SbaptThe symbol is undefined. 747279528Sbapt.Pp 748279528Sbapt.It V 749279528SbaptThe symbol is a weak object. When a weak defined symbol is linked with a normal 750279528Sbaptdefined symbol, the normal defined symbol is used with no error. When a weak 751279528Sbaptundefined symbol is linked and the symbol is not defined, the value of the 752279528Sbaptweak symbol becomes zero with no error. 753279528Sbapt.Pp 754279528Sbapt.It W 755279528SbaptThe symbol is a weak symbol that has not been specifically tagged as a weak 756279528Sbaptobject symbol. When a weak defined symbol is linked with a normal defined 757279528Sbaptsymbol, the normal defined symbol is used with no error. When a weak undefined 758279528Sbaptsymbol is linked and the symbol is not defined, the value of the symbol is 759279528Sbaptdetermined in a system-specific manner without error. On some systems, uppercase 760279528Sbaptindicates that a default value has been specified. 761279528Sbapt.Pp 762279528Sbapt.It - 763279528SbaptThe symbol is a stabs symbol in an a.out object file. In this case, the next 764279528Sbaptvalues printed are the stabs other field, the stabs desc field, and the stab 765279528Sbapttype. Stabs symbols are used to hold debugging information. For more information, 766279528Sbaptsee Top,Stabs,Stabs Overview,stabs.info, The \(lqstabs\(rq debug format. 767279528Sbapt.Pp 768279528Sbapt.It ? 769279528SbaptThe symbol type is unknown, or object file format specific. 770279528Sbapt.El 771279528Sbapt.Pp 772279528Sbapt.It 773279528SbaptThe symbol name. 774279528Sbapt.El 775279528Sbapt.Pp 776279528SbaptThe long and short forms of options, shown here as alternatives, are equivalent. 777279528Sbapt.Pp 778279528Sbapt.Bl -tag -width Ds 779279528Sbapt.It -A 780279528Sbapt.It -o 781279528Sbapt.It --print-file-name 782279528SbaptPrecede each symbol by the name of the input file (or archive member) in which 783279528Sbaptit was found, rather than identifying the input file once only, before all 784279528Sbaptof its symbols. 785279528Sbapt.Pp 786279528Sbapt.It -a 787279528Sbapt.It --debug-syms 788279528SbaptDisplay all symbols, even debugger-only symbols; normally these are not listed. 789279528Sbapt.Pp 790279528Sbapt.It -B 791279528SbaptThe same as 792279528Sbapt.Op --format=bsd 793279528Sbapt(for compatibility with the MIPS 794279528Sbapt.Xr nm ) . 795279528Sbapt.Pp 796279528Sbapt.It -C 797279528Sbapt.It --demangle[= Va style] 798279528SbaptDecode ( 799279528Sbapt.Em demangle ) 800279528Sbaptlow-level symbol names into user-level names. Besides removing any initial 801279528Sbaptunderscore prepended by the system, this makes C++ function names readable. 802279528SbaptDifferent compilers have different mangling styles. The optional demangling 803279528Sbaptstyle argument can be used to choose an appropriate demangling style for your 804279528Sbaptcompiler.See Section 805279528Sbapt.Dq c++filt , 806279528Sbaptfor more information on demangling. 807279528Sbapt.Pp 808279528Sbapt.It --no-demangle 809279528SbaptDo not demangle low-level symbol names. This is the default. 810279528Sbapt.Pp 811279528Sbapt.It -D 812279528Sbapt.It --dynamic 813279528SbaptDisplay the dynamic symbols rather than the normal symbols. This is only meaningful 814279528Sbaptfor dynamic objects, such as certain types of shared libraries. 815279528Sbapt.Pp 816279528Sbapt.It -f Va format 817279528Sbapt.It --format= Va format 818279528SbaptUse the output format 819279528Sbapt.Va format , 820279528Sbaptwhich can be 821279528Sbapt.Li bsd , 822279528Sbapt.Li sysv , 823279528Sbaptor 824279528Sbapt.Li posix . 825279528SbaptThe default is 826279528Sbapt.Li bsd . 827279528SbaptOnly the first character of 828279528Sbapt.Va format 829279528Sbaptis significant; it can be either upper or lower case. 830279528Sbapt.Pp 831279528Sbapt.It -g 832279528Sbapt.It --extern-only 833279528SbaptDisplay only external symbols. 834279528Sbapt.Pp 835279528Sbapt.It -l 836279528Sbapt.It --line-numbers 837279528SbaptFor each symbol, use debugging information to try to find a filename and line 838279528Sbaptnumber. For a defined symbol, look for the line number of the address of the 839279528Sbaptsymbol. For an undefined symbol, look for the line number of a relocation 840279528Sbaptentry which refers to the symbol. If line number information can be found, 841279528Sbaptprint it after the other symbol information. 842279528Sbapt.Pp 843279528Sbapt.It -n 844279528Sbapt.It -v 845279528Sbapt.It --numeric-sort 846279528SbaptSort symbols numerically by their addresses, rather than alphabetically by 847279528Sbapttheir names. 848279528Sbapt.Pp 849279528Sbapt.It -p 850279528Sbapt.It --no-sort 851279528SbaptDo not bother to sort the symbols in any order; print them in the order encountered. 852279528Sbapt.Pp 853279528Sbapt.It -P 854279528Sbapt.It --portability 855279528SbaptUse the POSIX.2 standard output format instead of the default format. Equivalent 856279528Sbaptto 857279528Sbapt.Li -f posix . 858279528Sbapt.Pp 859279528Sbapt.It -S 860279528Sbapt.It --print-size 861279528SbaptPrint size, not the value, of defined symbols for the 862279528Sbapt.Li bsd 863279528Sbaptoutput format. 864279528Sbapt.Pp 865279528Sbapt.It -s 866279528Sbapt.It --print-armap 867279528SbaptWhen listing symbols from archive members, include the index: a mapping (stored 868279528Sbaptin the archive by 869279528Sbapt.Xr ar 870279528Sbaptor 871279528Sbapt.Xr ranlib ) 872279528Sbaptof which modules contain definitions for which names. 873279528Sbapt.Pp 874279528Sbapt.It -r 875279528Sbapt.It --reverse-sort 876279528SbaptReverse the order of the sort (whether numeric or alphabetic); let the last 877279528Sbaptcome first. 878279528Sbapt.Pp 879279528Sbapt.It --size-sort 880279528SbaptSort symbols by size. The size is computed as the difference between the value 881279528Sbaptof the symbol and the value of the symbol with the next higher value. If the 882279528Sbapt.Li bsd 883279528Sbaptoutput format is used the size of the symbol is printed, rather than the value, 884279528Sbaptand 885279528Sbapt.Li -S 886279528Sbaptmust be used in order both size and value to be printed. 887279528Sbapt.Pp 888279528Sbapt.It --special-syms 889279528SbaptDisplay symbols which have a target-specific special meaning. These symbols 890279528Sbaptare usually used by the target for some special processing and are not normally 891279528Sbapthelpful when included included in the normal symbol lists. For example for 892279528SbaptARM targets this option would skip the mapping symbols used to mark transitions 893279528Sbaptbetween ARM code, THUMB code and data. 894279528Sbapt.Pp 895279528Sbapt.It -t Va radix 896279528Sbapt.It --radix= Va radix 897279528SbaptUse 898279528Sbapt.Va radix 899279528Sbaptas the radix for printing the symbol values. It must be 900279528Sbapt.Li d 901279528Sbaptfor decimal, 902279528Sbapt.Li o 903279528Sbaptfor octal, or 904279528Sbapt.Li x 905279528Sbaptfor hexadecimal. 906279528Sbapt.Pp 907279528Sbapt.It --target= Va bfdname 908279528SbaptSpecify an object code format other than your system's default format.See Section 909279528Sbapt.Dq Target Selection , 910279528Sbaptfor more information. 911279528Sbapt.Pp 912279528Sbapt.It -u 913279528Sbapt.It --undefined-only 914279528SbaptDisplay only undefined symbols (those external to each object file). 915279528Sbapt.Pp 916279528Sbapt.It --defined-only 917279528SbaptDisplay only defined symbols for each object file. 918279528Sbapt.Pp 919279528Sbapt.It -V 920279528Sbapt.It --version 921279528SbaptShow the version number of 922279528Sbapt.Xr nm 923279528Sbaptand exit. 924279528Sbapt.Pp 925279528Sbapt.It -X 926279528SbaptThis option is ignored for compatibility with the AIX version of 927279528Sbapt.Xr nm . 928279528SbaptIt takes one parameter which must be the string 929279528Sbapt.Op 32_64 . 930279528SbaptThe default mode of AIX 931279528Sbapt.Xr nm 932279528Sbaptcorresponds to 933279528Sbapt.Op -X 32 , 934279528Sbaptwhich is not supported by GNU 935279528Sbapt.Xr nm . 936279528Sbapt.Pp 937279528Sbapt.It --help 938279528SbaptShow a summary of the options to 939279528Sbapt.Xr nm 940279528Sbaptand exit. 941279528Sbapt.El 942279528Sbapt.Pp 943279528Sbapt.Sh objcopy 944279528Sbapt.Bd -literal -offset indent 945279528Sbaptobjcopy [-F bfdname|--target=bfdname] 946279528Sbapt [-I bfdname|--input-target=bfdname] 947279528Sbapt [-O bfdname|--output-target=bfdname] 948279528Sbapt [-B bfdarch|--binary-architecture=bfdarch] 949279528Sbapt [-S|--strip-all] 950279528Sbapt [-g|--strip-debug] 951279528Sbapt [-K symbolname|--keep-symbol=symbolname] 952279528Sbapt [-N symbolname|--strip-symbol=symbolname] 953279528Sbapt [--strip-unneeded-symbol=symbolname] 954279528Sbapt [-G symbolname|--keep-global-symbol=symbolname] 955279528Sbapt [--localize-hidden] 956279528Sbapt [-L symbolname|--localize-symbol=symbolname] 957279528Sbapt [--globalize-symbol=symbolname] 958279528Sbapt [-W symbolname|--weaken-symbol=symbolname] 959279528Sbapt [-w|--wildcard] 960279528Sbapt [-x|--discard-all] 961279528Sbapt [-X|--discard-locals] 962279528Sbapt [-b byte|--byte=byte] 963279528Sbapt [-i interleave|--interleave=interleave] 964279528Sbapt [-j sectionname|--only-section=sectionname] 965279528Sbapt [-R sectionname|--remove-section=sectionname] 966279528Sbapt [-p|--preserve-dates] 967279528Sbapt [--debugging] 968279528Sbapt [--gap-fill=val] 969279528Sbapt [--pad-to=address] 970279528Sbapt [--set-start=val] 971279528Sbapt [--adjust-start=incr] 972279528Sbapt [--change-addresses=incr] 973279528Sbapt [--change-section-address section{=,+,-}val] 974279528Sbapt [--change-section-lma section{=,+,-}val] 975279528Sbapt [--change-section-vma section{=,+,-}val] 976279528Sbapt [--change-warnings] [--no-change-warnings] 977279528Sbapt [--set-section-flags section=flags] 978279528Sbapt [--add-section sectionname=filename] 979279528Sbapt [--rename-section oldname=newname[,flags]] 980279528Sbapt [--change-leading-char] [--remove-leading-char] 981279528Sbapt [--reverse-bytes=num] 982279528Sbapt [--srec-len=ival] [--srec-forceS3] 983279528Sbapt [--redefine-sym old=new] 984279528Sbapt [--redefine-syms=filename] 985279528Sbapt [--weaken] 986279528Sbapt [--keep-symbols=filename] 987279528Sbapt [--strip-symbols=filename] 988279528Sbapt [--strip-unneeded-symbols=filename] 989279528Sbapt [--keep-global-symbols=filename] 990279528Sbapt [--localize-symbols=filename] 991279528Sbapt [--globalize-symbols=filename] 992279528Sbapt [--weaken-symbols=filename] 993279528Sbapt [--alt-machine-code=index] 994279528Sbapt [--prefix-symbols=string] 995279528Sbapt [--prefix-sections=string] 996279528Sbapt [--prefix-alloc-sections=string] 997279528Sbapt [--add-GNU-debuglink=path-to-file] 998279528Sbapt [--keep-file-symbols] 999279528Sbapt [--only-keep-debug] 1000279528Sbapt [--extract-symbol] 1001279528Sbapt [--writable-text] 1002279528Sbapt [--readonly-text] 1003279528Sbapt [--pure] 1004279528Sbapt [--impure] 1005279528Sbapt [-v|--verbose] 1006279528Sbapt [-V|--version] 1007279528Sbapt [--help] [--info] 1008279528Sbapt infile [outfile] 1009279528Sbapt.Ed 1010279528Sbapt.Pp 1011279528SbaptThe GNU 1012279528Sbapt.Xr objcopy 1013279528Sbaptutility copies the contents of an object file to another. 1014279528Sbapt.Xr objcopy 1015279528Sbaptuses the GNU bfd Library to read and write the object files. It can write 1016279528Sbaptthe destination object file in a format different from that of the source 1017279528Sbaptobject file. The exact behavior of 1018279528Sbapt.Xr objcopy 1019279528Sbaptis controlled by command-line options. Note that 1020279528Sbapt.Xr objcopy 1021279528Sbaptshould be able to copy a fully linked file between any two formats. However, 1022279528Sbaptcopying a relocatable object file between any two formats may not work as 1023279528Sbaptexpected. 1024279528Sbapt.Pp 1025279528Sbapt.Xr objcopy 1026279528Sbaptcreates temporary files to do its translations and deletes them afterward. 1027279528Sbapt.Xr objcopy 1028279528Sbaptuses bfd to do all its translation work; it has access to all the formats 1029279528Sbaptdescribed in bfd and thus is able to recognize most formats without being 1030279528Sbapttold explicitly.See Section 1031279528Sbapt.Dq BFD . 1032279528Sbapt.Pp 1033279528Sbapt.Xr objcopy 1034279528Sbaptcan be used to generate S-records by using an output target of 1035279528Sbapt.Li srec 1036279528Sbapt(e.g., use 1037279528Sbapt.Li -O srec ) . 1038279528Sbapt.Pp 1039279528Sbapt.Xr objcopy 1040279528Sbaptcan be used to generate a raw binary file by using an output target of 1041279528Sbapt.Li binary 1042279528Sbapt(e.g., use 1043279528Sbapt.Op -O binary ) . 1044279528SbaptWhen 1045279528Sbapt.Xr objcopy 1046279528Sbaptgenerates a raw binary file, it will essentially produce a memory dump of 1047279528Sbaptthe contents of the input object file. All symbols and relocation information 1048279528Sbaptwill be discarded. The memory dump will start at the load address of the lowest 1049279528Sbaptsection copied into the output file. 1050279528Sbapt.Pp 1051279528SbaptWhen generating an S-record or a raw binary file, it may be helpful to use 1052279528Sbapt.Op -S 1053279528Sbaptto remove sections containing debugging information. In some cases 1054279528Sbapt.Op -R 1055279528Sbaptwill be useful to remove sections which contain information that is not needed 1056279528Sbaptby the binary file. 1057279528Sbapt.Pp 1058279528SbaptNote--- 1059279528Sbapt.Xr objcopy 1060279528Sbaptis not able to change the endianness of its input files. If the input format 1061279528Sbapthas an endianness (some formats do not), 1062279528Sbapt.Xr objcopy 1063279528Sbaptcan only copy the inputs into file formats that have the same endianness or 1064279528Sbaptwhich have no endianness (e.g., 1065279528Sbapt.Li srec ) . 1066279528Sbapt(However, see the 1067279528Sbapt.Op --reverse-bytes 1068279528Sbaptoption.) 1069279528Sbapt.Pp 1070279528Sbapt.Bl -tag -width Ds 1071279528Sbapt.It Va infile 1072279528Sbapt.It Va outfile 1073279528SbaptThe input and output files, respectively. If you do not specify 1074279528Sbapt.Va outfile , 1075279528Sbapt.Xr objcopy 1076279528Sbaptcreates a temporary file and destructively renames the result with the name 1077279528Sbaptof 1078279528Sbapt.Va infile . 1079279528Sbapt.Pp 1080279528Sbapt.It -I Va bfdname 1081279528Sbapt.It --input-target= Va bfdname 1082279528SbaptConsider the source file's object format to be 1083279528Sbapt.Va bfdname , 1084279528Sbaptrather than attempting to deduce it.See Section 1085279528Sbapt.Dq Target Selection , 1086279528Sbaptfor more information. 1087279528Sbapt.Pp 1088279528Sbapt.It -O Va bfdname 1089279528Sbapt.It --output-target= Va bfdname 1090279528SbaptWrite the output file using the object format 1091279528Sbapt.Va bfdname . 1092279528SbaptSee Section.Dq Target Selection , 1093279528Sbaptfor more information. 1094279528Sbapt.Pp 1095279528Sbapt.It -F Va bfdname 1096279528Sbapt.It --target= Va bfdname 1097279528SbaptUse 1098279528Sbapt.Va bfdname 1099279528Sbaptas the object format for both the input and the output file; i.e., simply 1100279528Sbapttransfer data from source to destination with no translation.See Section 1101279528Sbapt.Dq Target Selection , 1102279528Sbaptfor more information. 1103279528Sbapt.Pp 1104279528Sbapt.It -B Va bfdarch 1105279528Sbapt.It --binary-architecture= Va bfdarch 1106279528SbaptUseful when transforming a raw binary input file into an object file. In this 1107279528Sbaptcase the output architecture can be set to 1108279528Sbapt.Va bfdarch . 1109279528SbaptThis option will be ignored if the input file has a known 1110279528Sbapt.Va bfdarch . 1111279528SbaptYou can access this binary data inside a program by referencing the special 1112279528Sbaptsymbols that are created by the conversion process. These symbols are called 1113279528Sbapt_binary_ 1114279528Sbapt.Va objfile 1115279528Sbapt_start, _binary_ 1116279528Sbapt.Va objfile 1117279528Sbapt_end and _binary_ 1118279528Sbapt.Va objfile 1119279528Sbapt_size. e.g. you can transform a picture file into an object file and then 1120279528Sbaptaccess it in your code using these symbols. 1121279528Sbapt.Pp 1122279528Sbapt.It -j Va sectionname 1123279528Sbapt.It --only-section= Va sectionname 1124279528SbaptCopy only the named section from the input file to the output file. This option 1125279528Sbaptmay be given more than once. Note that using this option inappropriately may 1126279528Sbaptmake the output file unusable. 1127279528Sbapt.Pp 1128279528Sbapt.It -R Va sectionname 1129279528Sbapt.It --remove-section= Va sectionname 1130279528SbaptRemove any section named 1131279528Sbapt.Va sectionname 1132279528Sbaptfrom the output file. This option may be given more than once. Note that using 1133279528Sbaptthis option inappropriately may make the output file unusable. 1134279528Sbapt.Pp 1135279528Sbapt.It -S 1136279528Sbapt.It --strip-all 1137279528SbaptDo not copy relocation and symbol information from the source file. 1138279528Sbapt.Pp 1139279528Sbapt.It -g 1140279528Sbapt.It --strip-debug 1141279528SbaptDo not copy debugging symbols or sections from the source file. 1142279528Sbapt.Pp 1143279528Sbapt.It --strip-unneeded 1144279528SbaptStrip all symbols that are not needed for relocation processing. 1145279528Sbapt.Pp 1146279528Sbapt.It -K Va symbolname 1147279528Sbapt.It --keep-symbol= Va symbolname 1148279528SbaptWhen stripping symbols, keep symbol 1149279528Sbapt.Va symbolname 1150279528Sbapteven if it would normally be stripped. This option may be given more than 1151279528Sbaptonce. 1152279528Sbapt.Pp 1153279528Sbapt.It -N Va symbolname 1154279528Sbapt.It --strip-symbol= Va symbolname 1155279528SbaptDo not copy symbol 1156279528Sbapt.Va symbolname 1157279528Sbaptfrom the source file. This option may be given more than once. 1158279528Sbapt.Pp 1159279528Sbapt.It --strip-unneeded-symbol= Va symbolname 1160279528SbaptDo not copy symbol 1161279528Sbapt.Va symbolname 1162279528Sbaptfrom the source file unless it is needed by a relocation. This option may 1163279528Sbaptbe given more than once. 1164279528Sbapt.Pp 1165279528Sbapt.It -G Va symbolname 1166279528Sbapt.It --keep-global-symbol= Va symbolname 1167279528SbaptKeep only symbol 1168279528Sbapt.Va symbolname 1169279528Sbaptglobal. Make all other symbols local to the file, so that they are not visible 1170279528Sbaptexternally. This option may be given more than once. 1171279528Sbapt.Pp 1172279528Sbapt.It --localize-hidden 1173279528SbaptIn an ELF object, mark all symbols that have hidden or internal visibility 1174279528Sbaptas local. This option applies on top of symbol-specific localization options 1175279528Sbaptsuch as 1176279528Sbapt.Op -L . 1177279528Sbapt.Pp 1178279528Sbapt.It -L Va symbolname 1179279528Sbapt.It --localize-symbol= Va symbolname 1180279528SbaptMake symbol 1181279528Sbapt.Va symbolname 1182279528Sbaptlocal to the file, so that it is not visible externally. This option may be 1183279528Sbaptgiven more than once. 1184279528Sbapt.Pp 1185279528Sbapt.It -W Va symbolname 1186279528Sbapt.It --weaken-symbol= Va symbolname 1187279528SbaptMake symbol 1188279528Sbapt.Va symbolname 1189279528Sbaptweak. This option may be given more than once. 1190279528Sbapt.Pp 1191279528Sbapt.It --globalize-symbol= Va symbolname 1192279528SbaptGive symbol 1193279528Sbapt.Va symbolname 1194279528Sbaptglobal scoping so that it is visible outside of the file in which it is defined. 1195279528SbaptThis option may be given more than once. 1196279528Sbapt.Pp 1197279528Sbapt.It -w 1198279528Sbapt.It --wildcard 1199279528SbaptPermit regular expressions in 1200279528Sbapt.Va symbolname 1201279528Sbapts used in other command line options. The question mark (?), asterisk (*), 1202279528Sbaptbackslash (\e) and square brackets ([]) operators can be used anywhere in the 1203279528Sbaptsymbol name. If the first character of the symbol name is the exclamation 1204279528Sbaptpoint (!) then the sense of the switch is reversed for that symbol. For example: 1205279528Sbapt.Pp 1206279528Sbapt.Bd -literal -offset indent 1207279528Sbapt -w -W !foo -W fo* 1208279528Sbapt.Ed 1209279528Sbapt.Pp 1210279528Sbaptwould cause objcopy to weaken all symbols that start with \(lqfo\(rq except for the 1211279528Sbaptsymbol \(lqfoo\(rq. 1212279528Sbapt.Pp 1213279528Sbapt.It -x 1214279528Sbapt.It --discard-all 1215279528SbaptDo not copy non-global symbols from the source file. 1216279528Sbapt.Pp 1217279528Sbapt.It -X 1218279528Sbapt.It --discard-locals 1219279528SbaptDo not copy compiler-generated local symbols. (These usually start with 1220279528Sbapt.Li L 1221279528Sbaptor 1222279528Sbapt.Li . . ) 1223279528Sbapt.Pp 1224279528Sbapt.It -b Va byte 1225279528Sbapt.It --byte= Va byte 1226279528SbaptKeep only every 1227279528Sbapt.Va byte 1228279528Sbaptth byte of the input file (header data is not affected). 1229279528Sbapt.Va byte 1230279528Sbaptcan be in the range from 0 to 1231279528Sbapt.Va interleave 1232279528Sbapt-1, where 1233279528Sbapt.Va interleave 1234279528Sbaptis given by the 1235279528Sbapt.Op -i 1236279528Sbaptor 1237279528Sbapt.Op --interleave 1238279528Sbaptoption, or the default of 4. This option is useful for creating files to program 1239279528Sbaptrom. It is typically used with an 1240279528Sbapt.Li srec 1241279528Sbaptoutput target. 1242279528Sbapt.Pp 1243279528Sbapt.It -i Va interleave 1244279528Sbapt.It --interleave= Va interleave 1245279528SbaptOnly copy one out of every 1246279528Sbapt.Va interleave 1247279528Sbaptbytes. Select which byte to copy with the 1248279528Sbapt.Op -b 1249279528Sbaptor 1250279528Sbapt.Op --byte 1251279528Sbaptoption. The default is 4. 1252279528Sbapt.Xr objcopy 1253279528Sbaptignores this option if you do not specify either 1254279528Sbapt.Op -b 1255279528Sbaptor 1256279528Sbapt.Op --byte . 1257279528Sbapt.Pp 1258279528Sbapt.It -p 1259279528Sbapt.It --preserve-dates 1260279528SbaptSet the access and modification dates of the output file to be the same as 1261279528Sbaptthose of the input file. 1262279528Sbapt.Pp 1263279528Sbapt.It --debugging 1264279528SbaptConvert debugging information, if possible. This is not the default because 1265279528Sbaptonly certain debugging formats are supported, and the conversion process can 1266279528Sbaptbe time consuming. 1267279528Sbapt.Pp 1268279528Sbapt.It --gap-fill Va val 1269279528SbaptFill gaps between sections with 1270279528Sbapt.Va val . 1271279528SbaptThis operation applies to the 1272279528Sbapt.Em load address 1273279528Sbapt(LMA) of the sections. It is done by increasing the size of the section with 1274279528Sbaptthe lower address, and filling in the extra space created with 1275279528Sbapt.Va val . 1276279528Sbapt.Pp 1277279528Sbapt.It --pad-to Va address 1278279528SbaptPad the output file up to the load address 1279279528Sbapt.Va address . 1280279528SbaptThis is done by increasing the size of the last section. The extra space is 1281279528Sbaptfilled in with the value specified by 1282279528Sbapt.Op --gap-fill 1283279528Sbapt(default zero). 1284279528Sbapt.Pp 1285279528Sbapt.It --set-start Va val 1286279528SbaptSet the start address of the new file to 1287279528Sbapt.Va val . 1288279528SbaptNot all object file formats support setting the start address. 1289279528Sbapt.Pp 1290279528Sbapt.It --change-start Va incr 1291279528Sbapt.It --adjust-start Va incr 1292279528SbaptChange the start address by adding 1293279528Sbapt.Va incr . 1294279528SbaptNot all object file formats support setting the start address. 1295279528Sbapt.Pp 1296279528Sbapt.It --change-addresses Va incr 1297279528Sbapt.It --adjust-vma Va incr 1298279528SbaptChange the VMA and LMA addresses of all sections, as well as the start address, 1299279528Sbaptby adding 1300279528Sbapt.Va incr . 1301279528SbaptSome object file formats do not permit section addresses to be changed arbitrarily. 1302279528SbaptNote that this does not relocate the sections; if the program expects sections 1303279528Sbaptto be loaded at a certain address, and this option is used to change the sections 1304279528Sbaptsuch that they are loaded at a different address, the program may fail. 1305279528Sbapt.Pp 1306279528Sbapt.It --change-section-address Va section{=,+,-} Va val 1307279528Sbapt.It --adjust-section-vma Va section{=,+,-} Va val 1308279528SbaptSet or change both the VMA address and the LMA address of the named 1309279528Sbapt.Va section . 1310279528SbaptIf 1311279528Sbapt.Li = 1312279528Sbaptis used, the section address is set to 1313279528Sbapt.Va val . 1314279528SbaptOtherwise, 1315279528Sbapt.Va val 1316279528Sbaptis added to or subtracted from the section address. See the comments under 1317279528Sbapt.Op --change-addresses , 1318279528Sbaptabove. If 1319279528Sbapt.Va section 1320279528Sbaptdoes not exist in the input file, a warning will be issued, unless 1321279528Sbapt.Op --no-change-warnings 1322279528Sbaptis used. 1323279528Sbapt.Pp 1324279528Sbapt.It --change-section-lma Va section{=,+,-} Va val 1325279528SbaptSet or change the LMA address of the named 1326279528Sbapt.Va section . 1327279528SbaptThe LMA address is the address where the section will be loaded into memory 1328279528Sbaptat program load time. Normally this is the same as the VMA address, which 1329279528Sbaptis the address of the section at program run time, but on some systems, especially 1330279528Sbaptthose where a program is held in ROM, the two can be different. If 1331279528Sbapt.Li = 1332279528Sbaptis used, the section address is set to 1333279528Sbapt.Va val . 1334279528SbaptOtherwise, 1335279528Sbapt.Va val 1336279528Sbaptis added to or subtracted from the section address. See the comments under 1337279528Sbapt.Op --change-addresses , 1338279528Sbaptabove. If 1339279528Sbapt.Va section 1340279528Sbaptdoes not exist in the input file, a warning will be issued, unless 1341279528Sbapt.Op --no-change-warnings 1342279528Sbaptis used. 1343279528Sbapt.Pp 1344279528Sbapt.It --change-section-vma Va section{=,+,-} Va val 1345279528SbaptSet or change the VMA address of the named 1346279528Sbapt.Va section . 1347279528SbaptThe VMA address is the address where the section will be located once the 1348279528Sbaptprogram has started executing. Normally this is the same as the LMA address, 1349279528Sbaptwhich is the address where the section will be loaded into memory, but on 1350279528Sbaptsome systems, especially those where a program is held in ROM, the two can 1351279528Sbaptbe different. If 1352279528Sbapt.Li = 1353279528Sbaptis used, the section address is set to 1354279528Sbapt.Va val . 1355279528SbaptOtherwise, 1356279528Sbapt.Va val 1357279528Sbaptis added to or subtracted from the section address. See the comments under 1358279528Sbapt.Op --change-addresses , 1359279528Sbaptabove. If 1360279528Sbapt.Va section 1361279528Sbaptdoes not exist in the input file, a warning will be issued, unless 1362279528Sbapt.Op --no-change-warnings 1363279528Sbaptis used. 1364279528Sbapt.Pp 1365279528Sbapt.It --change-warnings 1366279528Sbapt.It --adjust-warnings 1367279528SbaptIf 1368279528Sbapt.Op --change-section-address 1369279528Sbaptor 1370279528Sbapt.Op --change-section-lma 1371279528Sbaptor 1372279528Sbapt.Op --change-section-vma 1373279528Sbaptis used, and the named section does not exist, issue a warning. This is the 1374279528Sbaptdefault. 1375279528Sbapt.Pp 1376279528Sbapt.It --no-change-warnings 1377279528Sbapt.It --no-adjust-warnings 1378279528SbaptDo not issue a warning if 1379279528Sbapt.Op --change-section-address 1380279528Sbaptor 1381279528Sbapt.Op --adjust-section-lma 1382279528Sbaptor 1383279528Sbapt.Op --adjust-section-vma 1384279528Sbaptis used, even if the named section does not exist. 1385279528Sbapt.Pp 1386279528Sbapt.It --set-section-flags Va section= Va flags 1387279528SbaptSet the flags for the named section. The 1388279528Sbapt.Va flags 1389279528Sbaptargument is a comma separated string of flag names. The recognized names are 1390279528Sbapt.Li alloc , 1391279528Sbapt.Li contents , 1392279528Sbapt.Li load , 1393279528Sbapt.Li noload , 1394279528Sbapt.Li readonly , 1395279528Sbapt.Li code , 1396279528Sbapt.Li data , 1397279528Sbapt.Li rom , 1398279528Sbapt.Li share , 1399279528Sbaptand 1400279528Sbapt.Li debug . 1401279528SbaptYou can set the 1402279528Sbapt.Li contents 1403279528Sbaptflag for a section which does not have contents, but it is not meaningful 1404279528Sbaptto clear the 1405279528Sbapt.Li contents 1406279528Sbaptflag of a section which does have contents--just remove the section instead. 1407279528SbaptNot all flags are meaningful for all object file formats. 1408279528Sbapt.Pp 1409279528Sbapt.It --add-section Va sectionname= Va filename 1410279528SbaptAdd a new section named 1411279528Sbapt.Va sectionname 1412279528Sbaptwhile copying the file. The contents of the new section are taken from the 1413279528Sbaptfile 1414279528Sbapt.Va filename . 1415279528SbaptThe size of the section will be the size of the file. This option only works 1416279528Sbapton file formats which can support sections with arbitrary names. 1417279528Sbapt.Pp 1418279528Sbapt.It --rename-section Va oldname= Va newname[, Va flags] 1419279528SbaptRename a section from 1420279528Sbapt.Va oldname 1421279528Sbaptto 1422279528Sbapt.Va newname , 1423279528Sbaptoptionally changing the section's flags to 1424279528Sbapt.Va flags 1425279528Sbaptin the process. This has the advantage over usng a linker script to perform 1426279528Sbaptthe rename in that the output stays as an object file and does not become 1427279528Sbapta linked executable. 1428279528Sbapt.Pp 1429279528SbaptThis option is particularly helpful when the input format is binary, since 1430279528Sbaptthis will always create a section called .data. If for example, you wanted 1431279528Sbaptinstead to create a section called .rodata containing binary data you could 1432279528Sbaptuse the following command line to achieve it: 1433279528Sbapt.Pp 1434279528Sbapt.Bd -literal -offset indent 1435279528Sbapt objcopy -I binary -O <output_format> -B <architecture> \e 1436279528Sbapt --rename-section .data=.rodata,alloc,load,readonly,data,contents \e 1437279528Sbapt <input_binary_file> <output_object_file> 1438279528Sbapt.Ed 1439279528Sbapt.Pp 1440279528Sbapt.It --change-leading-char 1441279528SbaptSome object file formats use special characters at the start of symbols. The 1442279528Sbaptmost common such character is underscore, which compilers often add before 1443279528Sbaptevery symbol. This option tells 1444279528Sbapt.Xr objcopy 1445279528Sbaptto change the leading character of every symbol when it converts between object 1446279528Sbaptfile formats. If the object file formats use the same leading character, this 1447279528Sbaptoption has no effect. Otherwise, it will add a character, or remove a character, 1448279528Sbaptor change a character, as appropriate. 1449279528Sbapt.Pp 1450279528Sbapt.It --remove-leading-char 1451279528SbaptIf the first character of a global symbol is a special symbol leading character 1452279528Sbaptused by the object file format, remove the character. The most common symbol 1453279528Sbaptleading character is underscore. This option will remove a leading underscore 1454279528Sbaptfrom all global symbols. This can be useful if you want to link together objects 1455279528Sbaptof different file formats with different conventions for symbol names. This 1456279528Sbaptis different from 1457279528Sbapt.Op --change-leading-char 1458279528Sbaptbecause it always changes the symbol name when appropriate, regardless of 1459279528Sbaptthe object file format of the output file. 1460279528Sbapt.Pp 1461279528Sbapt.It --reverse-bytes= Va num 1462279528SbaptReverse the bytes in a section with output contents. A section length must 1463279528Sbaptbe evenly divisible by the value given in order for the swap to be able to 1464279528Sbapttake place. Reversing takes place before the interleaving is performed. 1465279528Sbapt.Pp 1466279528SbaptThis option is used typically in generating ROM images for problematic target 1467279528Sbaptsystems. For example, on some target boards, the 32-bit words fetched from 1468279528Sbapt8-bit ROMs are re-assembled in little-endian byte order regardless of the 1469279528SbaptCPU byte order. Depending on the programming model, the endianness of the 1470279528SbaptROM may need to be modified. 1471279528Sbapt.Pp 1472279528SbaptConsider a simple file with a section containing the following eight bytes: 1473279528Sbapt.Li 12345678 . 1474279528Sbapt.Pp 1475279528SbaptUsing 1476279528Sbapt.Li --reverse-bytes=2 1477279528Sbaptfor the above example, the bytes in the output file would be ordered 1478279528Sbapt.Li 21436587 . 1479279528Sbapt.Pp 1480279528SbaptUsing 1481279528Sbapt.Li --reverse-bytes=4 1482279528Sbaptfor the above example, the bytes in the output file would be ordered 1483279528Sbapt.Li 43218765 . 1484279528Sbapt.Pp 1485279528SbaptBy using 1486279528Sbapt.Li --reverse-bytes=2 1487279528Sbaptfor the above example, followed by 1488279528Sbapt.Li --reverse-bytes=4 1489279528Sbapton the output file, the bytes in the second output file would be ordered 1490279528Sbapt.Li 34127856 . 1491279528Sbapt.Pp 1492279528Sbapt.It --srec-len= Va ival 1493279528SbaptMeaningful only for srec output. Set the maximum length of the Srecords being 1494279528Sbaptproduced to 1495279528Sbapt.Va ival . 1496279528SbaptThis length covers both address, data and crc fields. 1497279528Sbapt.Pp 1498279528Sbapt.It --srec-forceS3 1499279528SbaptMeaningful only for srec output. Avoid generation of S1/S2 records, creating 1500279528SbaptS3-only record format. 1501279528Sbapt.Pp 1502279528Sbapt.It --redefine-sym Va old= Va new 1503279528SbaptChange the name of a symbol 1504279528Sbapt.Va old , 1505279528Sbaptto 1506279528Sbapt.Va new . 1507279528SbaptThis can be useful when one is trying link two things together for which you 1508279528Sbapthave no source, and there are name collisions. 1509279528Sbapt.Pp 1510279528Sbapt.It --redefine-syms= Va filename 1511279528SbaptApply 1512279528Sbapt.Op --redefine-sym 1513279528Sbaptto each symbol pair " 1514279528Sbapt.Va old 1515279528Sbapt.Va new " 1516279528Sbaptlisted in the file 1517279528Sbapt.Va filename . 1518279528Sbapt.Va filename 1519279528Sbaptis simply a flat file, with one symbol pair per line. Line comments may be 1520279528Sbaptintroduced by the hash character. This option may be given more than once. 1521279528Sbapt.Pp 1522279528Sbapt.It --weaken 1523279528SbaptChange all global symbols in the file to be weak. This can be useful when 1524279528Sbaptbuilding an object which will be linked against other objects using the 1525279528Sbapt.Op -R 1526279528Sbaptoption to the linker. This option is only effective when using an object file 1527279528Sbaptformat which supports weak symbols. 1528279528Sbapt.Pp 1529279528Sbapt.It --keep-symbols= Va filename 1530279528SbaptApply 1531279528Sbapt.Op --keep-symbol 1532279528Sbaptoption to each symbol listed in the file 1533279528Sbapt.Va filename . 1534279528Sbapt.Va filename 1535279528Sbaptis simply a flat file, with one symbol name per line. Line comments may be 1536279528Sbaptintroduced by the hash character. This option may be given more than once. 1537279528Sbapt.Pp 1538279528Sbapt.It --strip-symbols= Va filename 1539279528SbaptApply 1540279528Sbapt.Op --strip-symbol 1541279528Sbaptoption to each symbol listed in the file 1542279528Sbapt.Va filename . 1543279528Sbapt.Va filename 1544279528Sbaptis simply a flat file, with one symbol name per line. Line comments may be 1545279528Sbaptintroduced by the hash character. This option may be given more than once. 1546279528Sbapt.Pp 1547279528Sbapt.It --strip-unneeded-symbols= Va filename 1548279528SbaptApply 1549279528Sbapt.Op --strip-unneeded-symbol 1550279528Sbaptoption to each symbol listed in the file 1551279528Sbapt.Va filename . 1552279528Sbapt.Va filename 1553279528Sbaptis simply a flat file, with one symbol name per line. Line comments may be 1554279528Sbaptintroduced by the hash character. This option may be given more than once. 1555279528Sbapt.Pp 1556279528Sbapt.It --keep-global-symbols= Va filename 1557279528SbaptApply 1558279528Sbapt.Op --keep-global-symbol 1559279528Sbaptoption to each symbol listed in the file 1560279528Sbapt.Va filename . 1561279528Sbapt.Va filename 1562279528Sbaptis simply a flat file, with one symbol name per line. Line comments may be 1563279528Sbaptintroduced by the hash character. This option may be given more than once. 1564279528Sbapt.Pp 1565279528Sbapt.It --localize-symbols= Va filename 1566279528SbaptApply 1567279528Sbapt.Op --localize-symbol 1568279528Sbaptoption to each symbol listed in the file 1569279528Sbapt.Va filename . 1570279528Sbapt.Va filename 1571279528Sbaptis simply a flat file, with one symbol name per line. Line comments may be 1572279528Sbaptintroduced by the hash character. This option may be given more than once. 1573279528Sbapt.Pp 1574279528Sbapt.It --globalize-symbols= Va filename 1575279528SbaptApply 1576279528Sbapt.Op --globalize-symbol 1577279528Sbaptoption to each symbol listed in the file 1578279528Sbapt.Va filename . 1579279528Sbapt.Va filename 1580279528Sbaptis simply a flat file, with one symbol name per line. Line comments may be 1581279528Sbaptintroduced by the hash character. This option may be given more than once. 1582279528Sbapt.Pp 1583279528Sbapt.It --weaken-symbols= Va filename 1584279528SbaptApply 1585279528Sbapt.Op --weaken-symbol 1586279528Sbaptoption to each symbol listed in the file 1587279528Sbapt.Va filename . 1588279528Sbapt.Va filename 1589279528Sbaptis simply a flat file, with one symbol name per line. Line comments may be 1590279528Sbaptintroduced by the hash character. This option may be given more than once. 1591279528Sbapt.Pp 1592279528Sbapt.It --alt-machine-code= Va index 1593279528SbaptIf the output architecture has alternate machine codes, use the 1594279528Sbapt.Va index 1595279528Sbaptth code instead of the default one. This is useful in case a machine is assigned 1596279528Sbaptan official code and the tool-chain adopts the new code, but other applications 1597279528Sbaptstill depend on the original code being used. For ELF based architectures 1598279528Sbaptif the 1599279528Sbapt.Va index 1600279528Sbaptalternative does not exist then the value is treated as an absolute number 1601279528Sbaptto be stored in the e_machine field of the ELF header. 1602279528Sbapt.Pp 1603279528Sbapt.It --writable-text 1604279528SbaptMark the output text as writable. This option isn't meaningful for all object 1605279528Sbaptfile formats. 1606279528Sbapt.Pp 1607279528Sbapt.It --readonly-text 1608279528SbaptMake the output text write protected. This option isn't meaningful for all 1609279528Sbaptobject file formats. 1610279528Sbapt.Pp 1611279528Sbapt.It --pure 1612279528SbaptMark the output file as demand paged. This option isn't meaningful for all 1613279528Sbaptobject file formats. 1614279528Sbapt.Pp 1615279528Sbapt.It --impure 1616279528SbaptMark the output file as impure. This option isn't meaningful for all object 1617279528Sbaptfile formats. 1618279528Sbapt.Pp 1619279528Sbapt.It --prefix-symbols= Va string 1620279528SbaptPrefix all symbols in the output file with 1621279528Sbapt.Va string . 1622279528Sbapt.Pp 1623279528Sbapt.It --prefix-sections= Va string 1624279528SbaptPrefix all section names in the output file with 1625279528Sbapt.Va string . 1626279528Sbapt.Pp 1627279528Sbapt.It --prefix-alloc-sections= Va string 1628279528SbaptPrefix all the names of all allocated sections in the output file with 1629279528Sbapt.Va string . 1630279528Sbapt.Pp 1631279528Sbapt.It --add-GNU-debuglink= Va path-to-file 1632279528SbaptCreates a .GNU_debuglink section which contains a reference to 1633279528Sbapt.Va path-to-file 1634279528Sbaptand adds it to the output file. 1635279528Sbapt.Pp 1636279528Sbapt.It --keep-file-symbols 1637279528SbaptWhen stripping a file, perhaps with 1638279528Sbapt.Op --strip-debug 1639279528Sbaptor 1640279528Sbapt.Op --strip-unneeded , 1641279528Sbaptretain any symbols specifying source file names, which would otherwise get 1642279528Sbaptstripped. 1643279528Sbapt.Pp 1644279528Sbapt.It --only-keep-debug 1645279528SbaptStrip a file, removing contents of any sections that would not be stripped 1646279528Sbaptby 1647279528Sbapt.Op --strip-debug 1648279528Sbaptand leaving the debugging sections intact. In ELF files, this preserves all 1649279528Sbaptnote sections in the output. 1650279528Sbapt.Pp 1651279528SbaptThe intention is that this option will be used in conjunction with 1652279528Sbapt.Op --add-GNU-debuglink 1653279528Sbaptto create a two part executable. One a stripped binary which will occupy less 1654279528Sbaptspace in RAM and in a distribution and the second a debugging information 1655279528Sbaptfile which is only needed if debugging abilities are required. The suggested 1656279528Sbaptprocedure to create these files is as follows: 1657279528Sbapt.Pp 1658279528Sbapt.Bl -enum 1659279528Sbapt.It 1660279528SbaptLink the executable as normal. Assuming that is is called 1661279528Sbapt.Li foo 1662279528Sbaptthen... 1663279528Sbapt.It 1664279528SbaptRun 1665279528Sbapt.Li objcopy --only-keep-debug foo foo.dbg 1666279528Sbaptto 1667279528Sbaptcreate a file containing the debugging info. 1668279528Sbapt.It 1669279528SbaptRun 1670279528Sbapt.Li objcopy --strip-debug foo 1671279528Sbaptto create a 1672279528Sbaptstripped executable. 1673279528Sbapt.It 1674279528SbaptRun 1675279528Sbapt.Li objcopy --add-GNU-debuglink=foo.dbg foo 1676279528Sbaptto add a link to the debugging info into the stripped executable. 1677279528Sbapt.El 1678279528Sbapt.Pp 1679279528SbaptNote - the choice of 1680279528Sbapt.Li .dbg 1681279528Sbaptas an extension for the debug info file is arbitrary. Also the 1682279528Sbapt.Li --only-keep-debug 1683279528Sbaptstep is optional. You could instead do this: 1684279528Sbapt.Pp 1685279528Sbapt.Bl -enum 1686279528Sbapt.It 1687279528SbaptLink the executable as normal. 1688279528Sbapt.It 1689279528SbaptCopy 1690279528Sbapt.Li foo 1691279528Sbaptto 1692279528Sbapt.Li foo.full 1693279528Sbapt.It 1694279528SbaptRun 1695279528Sbapt.Li objcopy --strip-debug foo 1696279528Sbapt.It 1697279528SbaptRun 1698279528Sbapt.Li objcopy --add-GNU-debuglink=foo.full foo 1699279528Sbapt.El 1700279528Sbapt.Pp 1701279528Sbapti.e., the file pointed to by the 1702279528Sbapt.Op --add-GNU-debuglink 1703279528Sbaptcan be the full executable. It does not have to be a file created by the 1704279528Sbapt.Op --only-keep-debug 1705279528Sbaptswitch. 1706279528Sbapt.Pp 1707279528SbaptNote - this switch is only intended for use on fully linked files. It does 1708279528Sbaptnot make sense to use it on object files where the debugging information may 1709279528Sbaptbe incomplete. Besides the GNU_debuglink feature currently only supports the 1710279528Sbaptpresence of one filename containing debugging information, not multiple filenames 1711279528Sbapton a one-per-object-file basis. 1712279528Sbapt.Pp 1713279528Sbapt.It --extract-symbol 1714279528SbaptKeep the file's section flags and symbols but remove all section data. Specifically, 1715279528Sbaptthe option: 1716279528Sbapt.Pp 1717279528Sbapt.Bl -bullet 1718279528Sbapt.It 1719279528Sbaptsets the virtual and load addresses of every section to zero; 1720279528Sbapt.It 1721279528Sbaptremoves the contents of all sections; 1722279528Sbapt.It 1723279528Sbaptsets the size of every section to zero; and 1724279528Sbapt.It 1725279528Sbaptsets the file's start address to zero. 1726279528Sbapt.El 1727279528Sbapt.Pp 1728279528SbaptThis option is used to build a 1729279528Sbapt.Pa .sym 1730279528Sbaptfile for a VxWorks kernel. It can also be a useful way of reducing the size 1731279528Sbaptof a 1732279528Sbapt.Op --just-symbols 1733279528Sbaptlinker input file. 1734279528Sbapt.Pp 1735279528Sbapt.It -V 1736279528Sbapt.It --version 1737279528SbaptShow the version number of 1738279528Sbapt.Xr objcopy . 1739279528Sbapt.Pp 1740279528Sbapt.It -v 1741279528Sbapt.It --verbose 1742279528SbaptVerbose output: list all object files modified. In the case of archives, 1743279528Sbapt.Li objcopy -V 1744279528Sbaptlists all members of the archive. 1745279528Sbapt.Pp 1746279528Sbapt.It --help 1747279528SbaptShow a summary of the options to 1748279528Sbapt.Xr objcopy . 1749279528Sbapt.Pp 1750279528Sbapt.It --info 1751279528SbaptDisplay a list showing all architectures and object formats available. 1752279528Sbapt.El 1753279528Sbapt.Pp 1754279528Sbapt.Sh objdump 1755279528Sbapt.Bd -literal -offset indent 1756279528Sbaptobjdump [-a|--archive-headers] 1757279528Sbapt [-b bfdname|--target=bfdname] 1758279528Sbapt [-C|--demangle[=style] ] 1759279528Sbapt [-d|--disassemble] 1760279528Sbapt [-D|--disassemble-all] 1761279528Sbapt [-z|--disassemble-zeroes] 1762279528Sbapt [-EB|-EL|--endian={big | little }] 1763279528Sbapt [-f|--file-headers] 1764279528Sbapt [--file-start-context] 1765279528Sbapt [-g|--debugging] 1766279528Sbapt [-e|--debugging-tags] 1767279528Sbapt [-h|--section-headers|--headers] 1768279528Sbapt [-i|--info] 1769279528Sbapt [-j section|--section=section] 1770279528Sbapt [-l|--line-numbers] 1771279528Sbapt [-S|--source] 1772279528Sbapt [-m machine|--architecture=machine] 1773279528Sbapt [-M options|--disassembler-options=options] 1774279528Sbapt [-p|--private-headers] 1775279528Sbapt [-r|--reloc] 1776279528Sbapt [-R|--dynamic-reloc] 1777279528Sbapt [-s|--full-contents] 1778279528Sbapt [-W|--dwarf] 1779279528Sbapt [-G|--stabs] 1780279528Sbapt [-t|--syms] 1781279528Sbapt [-T|--dynamic-syms] 1782279528Sbapt [-x|--all-headers] 1783279528Sbapt [-w|--wide] 1784279528Sbapt [--start-address=address] 1785279528Sbapt [--stop-address=address] 1786279528Sbapt [--prefix-addresses] 1787279528Sbapt [--[no-]show-raw-insn] 1788279528Sbapt [--adjust-vma=offset] 1789279528Sbapt [--special-syms] 1790279528Sbapt [-V|--version] 1791279528Sbapt [-H|--help] 1792279528Sbapt objfile... 1793279528Sbapt.Ed 1794279528Sbapt.Pp 1795279528Sbapt.Xr objdump 1796279528Sbaptdisplays information about one or more object files. The options control what 1797279528Sbaptparticular information to display. This information is mostly useful to programmers 1798279528Sbaptwho are working on the compilation tools, as opposed to programmers who just 1799279528Sbaptwant their program to compile and work. 1800279528Sbapt.Pp 1801279528Sbapt.Va objfile 1802279528Sbapt\&...are the object files to be examined. When you specify archives, 1803279528Sbapt.Xr objdump 1804279528Sbaptshows information on each of the member object files. 1805279528Sbapt.Pp 1806279528SbaptThe long and short forms of options, shown here as alternatives, are equivalent. 1807279528SbaptAt least one option from the list 1808279528Sbapt.Op -a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x 1809279528Sbaptmust be given. 1810279528Sbapt.Pp 1811279528Sbapt.Bl -tag -width Ds 1812279528Sbapt.It -a 1813279528Sbapt.It --archive-header 1814279528SbaptIf any of the 1815279528Sbapt.Va objfile 1816279528Sbaptfiles are archives, display the archive header information (in a format similar 1817279528Sbaptto 1818279528Sbapt.Li ls -l ) . 1819279528SbaptBesides the information you could list with 1820279528Sbapt.Li ar tv , 1821279528Sbapt.Li objdump -a 1822279528Sbaptshows the object file format of each archive member. 1823279528Sbapt.Pp 1824279528Sbapt.It --adjust-vma= Va offset 1825279528SbaptWhen dumping information, first add 1826279528Sbapt.Va offset 1827279528Sbaptto all the section addresses. This is useful if the section addresses do not 1828279528Sbaptcorrespond to the symbol table, which can happen when putting sections at 1829279528Sbaptparticular addresses when using a format which can not represent section addresses, 1830279528Sbaptsuch as a.out. 1831279528Sbapt.Pp 1832279528Sbapt.It -b Va bfdname 1833279528Sbapt.It --target= Va bfdname 1834279528SbaptSpecify that the object-code format for the object files is 1835279528Sbapt.Va bfdname . 1836279528SbaptThis option may not be necessary; 1837279528Sbapt.Va objdump 1838279528Sbaptcan automatically recognize many formats. 1839279528Sbapt.Pp 1840279528SbaptFor example, 1841279528Sbapt.Bd -literal -offset indent 1842279528Sbaptobjdump -b oasys -m vax -h fu.o 1843279528Sbapt.Ed 1844279528Sbaptdisplays summary information from the section headers ( 1845279528Sbapt.Op -h ) 1846279528Sbaptof 1847279528Sbapt.Pa fu.o , 1848279528Sbaptwhich is explicitly identified ( 1849279528Sbapt.Op -m ) 1850279528Sbaptas a VAX object file in the format produced by Oasys compilers. You can list 1851279528Sbaptthe formats available with the 1852279528Sbapt.Op -i 1853279528Sbaptoption.See Section 1854279528Sbapt.Dq Target Selection , 1855279528Sbaptfor more information. 1856279528Sbapt.Pp 1857279528Sbapt.It -C 1858279528Sbapt.It --demangle[= Va style] 1859279528SbaptDecode ( 1860279528Sbapt.Em demangle ) 1861279528Sbaptlow-level symbol names into user-level names. Besides removing any initial 1862279528Sbaptunderscore prepended by the system, this makes C++ function names readable. 1863279528SbaptDifferent compilers have different mangling styles. The optional demangling 1864279528Sbaptstyle argument can be used to choose an appropriate demangling style for your 1865279528Sbaptcompiler.See Section 1866279528Sbapt.Dq c++filt , 1867279528Sbaptfor more information on demangling. 1868279528Sbapt.Pp 1869279528Sbapt.It -g 1870279528Sbapt.It --debugging 1871279528SbaptDisplay debugging information. This attempts to parse debugging information 1872279528Sbaptstored in the file and print it out using a C like syntax. Only certain types 1873279528Sbaptof debugging information have been implemented. Some other types are supported 1874279528Sbaptby 1875279528Sbapt.Xr readelf -w . 1876279528SbaptSee Section.Dq readelf . 1877279528Sbapt.Pp 1878279528Sbapt.It -e 1879279528Sbapt.It --debugging-tags 1880279528SbaptLike 1881279528Sbapt.Op -g , 1882279528Sbaptbut the information is generated in a format compatible with ctags tool. 1883279528Sbapt.Pp 1884279528Sbapt.It -d 1885279528Sbapt.It --disassemble 1886279528SbaptDisplay the assembler mnemonics for the machine instructions from 1887279528Sbapt.Va objfile . 1888279528SbaptThis option only disassembles those sections which are expected to contain 1889279528Sbaptinstructions. 1890279528Sbapt.Pp 1891279528Sbapt.It -D 1892279528Sbapt.It --disassemble-all 1893279528SbaptLike 1894279528Sbapt.Op -d , 1895279528Sbaptbut disassemble the contents of all sections, not just those expected to contain 1896279528Sbaptinstructions. 1897279528Sbapt.Pp 1898279528Sbapt.It --prefix-addresses 1899279528SbaptWhen disassembling, print the complete address on each line. This is the older 1900279528Sbaptdisassembly format. 1901279528Sbapt.Pp 1902279528Sbapt.It -EB 1903279528Sbapt.It -EL 1904279528Sbapt.It --endian={big|little} 1905279528SbaptSpecify the endianness of the object files. This only affects disassembly. 1906279528SbaptThis can be useful when disassembling a file format which does not describe 1907279528Sbaptendianness information, such as S-records. 1908279528Sbapt.Pp 1909279528Sbapt.It -f 1910279528Sbapt.It --file-headers 1911279528SbaptDisplay summary information from the overall header of each of the 1912279528Sbapt.Va objfile 1913279528Sbaptfiles. 1914279528Sbapt.Pp 1915279528Sbapt.It --file-start-context 1916279528SbaptSpecify that when displaying interlisted source code/disassembly (assumes 1917279528Sbapt.Op -S ) 1918279528Sbaptfrom a file that has not yet been displayed, extend the context to the start 1919279528Sbaptof the file. 1920279528Sbapt.Pp 1921279528Sbapt.It -h 1922279528Sbapt.It --section-headers 1923279528Sbapt.It --headers 1924279528SbaptDisplay summary information from the section headers of the object file. 1925279528Sbapt.Pp 1926279528SbaptFile segments may be relocated to nonstandard addresses, for example by using 1927279528Sbaptthe 1928279528Sbapt.Op -Ttext , 1929279528Sbapt.Op -Tdata , 1930279528Sbaptor 1931279528Sbapt.Op -Tbss 1932279528Sbaptoptions to 1933279528Sbapt.Xr ld . 1934279528SbaptHowever, some object file formats, such as a.out, do not store the starting 1935279528Sbaptaddress of the file segments. In those situations, although 1936279528Sbapt.Xr ld 1937279528Sbaptrelocates the sections correctly, using 1938279528Sbapt.Li objdump -h 1939279528Sbaptto list the file section headers cannot show the correct addresses. Instead, 1940279528Sbaptit shows the usual addresses, which are implicit for the target. 1941279528Sbapt.Pp 1942279528Sbapt.It -H 1943279528Sbapt.It --help 1944279528SbaptPrint a summary of the options to 1945279528Sbapt.Xr objdump 1946279528Sbaptand exit. 1947279528Sbapt.Pp 1948279528Sbapt.It -i 1949279528Sbapt.It --info 1950279528SbaptDisplay a list showing all architectures and object formats available for 1951279528Sbaptspecification with 1952279528Sbapt.Op -b 1953279528Sbaptor 1954279528Sbapt.Op -m . 1955279528Sbapt.Pp 1956279528Sbapt.It -j Va name 1957279528Sbapt.It --section= Va name 1958279528SbaptDisplay information only for section 1959279528Sbapt.Va name . 1960279528Sbapt.Pp 1961279528Sbapt.It -l 1962279528Sbapt.It --line-numbers 1963279528SbaptLabel the display (using debugging information) with the filename and source 1964279528Sbaptline numbers corresponding to the object code or relocs shown. Only useful 1965279528Sbaptwith 1966279528Sbapt.Op -d , 1967279528Sbapt.Op -D , 1968279528Sbaptor 1969279528Sbapt.Op -r . 1970279528Sbapt.Pp 1971279528Sbapt.It -m Va machine 1972279528Sbapt.It --architecture= Va machine 1973279528SbaptSpecify the architecture to use when disassembling object files. This can 1974279528Sbaptbe useful when disassembling object files which do not describe architecture 1975279528Sbaptinformation, such as S-records. You can list the available architectures with 1976279528Sbaptthe 1977279528Sbapt.Op -i 1978279528Sbaptoption. 1979279528Sbapt.Pp 1980279528Sbapt.It -M Va options 1981279528Sbapt.It --disassembler-options= Va options 1982279528SbaptPass target specific information to the disassembler. Only supported on some 1983279528Sbapttargets. If it is necessary to specify more than one disassembler option then 1984279528Sbaptmultiple 1985279528Sbapt.Op -M 1986279528Sbaptoptions can be used or can be placed together into a comma separated list. 1987279528Sbapt.Pp 1988279528SbaptIf the target is an ARM architecture then this switch can be used to select 1989279528Sbaptwhich register name set is used during disassembler. Specifying 1990279528Sbapt.Op -M reg-names-std 1991279528Sbapt(the default) will select the register names as used in ARM's instruction 1992279528Sbaptset documentation, but with register 13 called 'sp', register 14 called 'lr' 1993279528Sbaptand register 15 called 'pc'. Specifying 1994279528Sbapt.Op -M reg-names-apcs 1995279528Sbaptwill select the name set used by the ARM Procedure Call Standard, whilst specifying 1996279528Sbapt.Op -M reg-names-raw 1997279528Sbaptwill just use 1998279528Sbapt.Li r 1999279528Sbaptfollowed by the register number. 2000279528Sbapt.Pp 2001279528SbaptThere are also two variants on the APCS register naming scheme enabled by 2002279528Sbapt.Op -M reg-names-atpcs 2003279528Sbaptand 2004279528Sbapt.Op -M reg-names-special-atpcs 2005279528Sbaptwhich use the ARM/Thumb Procedure Call Standard naming conventions. (Either 2006279528Sbaptwith the normal register names or the special register names). 2007279528Sbapt.Pp 2008279528SbaptThis option can also be used for ARM architectures to force the disassembler 2009279528Sbaptto interpret all instructions as Thumb instructions by using the switch 2010279528Sbapt.Op --disassembler-options=force-thumb . 2011279528SbaptThis can be useful when attempting to disassemble thumb code produced by other 2012279528Sbaptcompilers. 2013279528Sbapt.Pp 2014279528SbaptFor the x86, some of the options duplicate functions of the 2015279528Sbapt.Op -m 2016279528Sbaptswitch, but allow finer grained control. Multiple selections from the following 2017279528Sbaptmay be specified as a comma separated string. 2018279528Sbapt.Op x86-64 , 2019279528Sbapt.Op i386 2020279528Sbaptand 2021279528Sbapt.Op i8086 2022279528Sbaptselect disassembly for the given architecture. 2023279528Sbapt.Op intel 2024279528Sbaptand 2025279528Sbapt.Op att 2026279528Sbaptselect between intel syntax mode and AT&T syntax mode. 2027279528Sbapt.Op addr64 , 2028279528Sbapt.Op addr32 , 2029279528Sbapt.Op addr16 , 2030279528Sbapt.Op data32 2031279528Sbaptand 2032279528Sbapt.Op data16 2033279528Sbaptspecify the default address size and operand size. These four options will 2034279528Sbaptbe overridden if 2035279528Sbapt.Op x86-64 , 2036279528Sbapt.Op i386 2037279528Sbaptor 2038279528Sbapt.Op i8086 2039279528Sbaptappear later in the option string. Lastly, 2040279528Sbapt.Op suffix , 2041279528Sbaptwhen in AT&T mode, instructs the disassembler to print a mnemonic suffix even 2042279528Sbaptwhen the suffix could be inferred by the operands. 2043279528Sbapt.Pp 2044279528SbaptFor PPC, 2045279528Sbapt.Op booke , 2046279528Sbapt.Op booke32 2047279528Sbaptand 2048279528Sbapt.Op booke64 2049279528Sbaptselect disassembly of BookE instructions. 2050279528Sbapt.Op 32 2051279528Sbaptand 2052279528Sbapt.Op 64 2053279528Sbaptselect PowerPC and PowerPC64 disassembly, respectively. 2054279528Sbapt.Op e300 2055279528Sbaptselects disassembly for the e300 family. 2056279528Sbapt.Op 440 2057279528Sbaptselects disassembly for the PowerPC 440. 2058279528Sbapt.Pp 2059279528SbaptFor MIPS, this option controls the printing of instruction mnemonic names 2060279528Sbaptand register names in disassembled instructions. Multiple selections from 2061279528Sbaptthe following may be specified as a comma separated string, and invalid options 2062279528Sbaptare ignored: 2063279528Sbapt.Pp 2064279528Sbapt.Bl -tag -width Ds 2065279528Sbapt.It no-aliases 2066279528SbaptPrint the 'raw' instruction mnemonic instead of some pseudo instruction mnemonic. 2067279528SbaptI.e., print 'daddu' or 'or' instead of 'move', 'sll' instead of 'nop', etc. 2068279528Sbapt.Pp 2069279528Sbapt.It gpr-names= Va ABI 2070279528SbaptPrint GPR (general-purpose register) names as appropriate for the specified 2071279528SbaptABI. By default, GPR names are selected according to the ABI of the binary 2072279528Sbaptbeing disassembled. 2073279528Sbapt.Pp 2074279528Sbapt.It fpr-names= Va ABI 2075279528SbaptPrint FPR (floating-point register) names as appropriate for the specified 2076279528SbaptABI. By default, FPR numbers are printed rather than names. 2077279528Sbapt.Pp 2078279528Sbapt.It cp0-names= Va ARCH 2079279528SbaptPrint CP0 (system control coprocessor; coprocessor 0) register names as appropriate 2080279528Sbaptfor the CPU or architecture specified by 2081279528Sbapt.Va ARCH . 2082279528SbaptBy default, CP0 register names are selected according to the architecture 2083279528Sbaptand CPU of the binary being disassembled. 2084279528Sbapt.Pp 2085279528Sbapt.It hwr-names= Va ARCH 2086279528SbaptPrint HWR (hardware register, used by the 2087279528Sbapt.Li rdhwr 2088279528Sbaptinstruction) names as appropriate for the CPU or architecture specified by 2089279528Sbapt.Va ARCH . 2090279528SbaptBy default, HWR names are selected according to the architecture and CPU of 2091279528Sbaptthe binary being disassembled. 2092279528Sbapt.Pp 2093279528Sbapt.It reg-names= Va ABI 2094279528SbaptPrint GPR and FPR names as appropriate for the selected ABI. 2095279528Sbapt.Pp 2096279528Sbapt.It reg-names= Va ARCH 2097279528SbaptPrint CPU-specific register names (CP0 register and HWR names) as appropriate 2098279528Sbaptfor the selected CPU or architecture. 2099279528Sbapt.El 2100279528Sbapt.Pp 2101279528SbaptFor any of the options listed above, 2102279528Sbapt.Va ABI 2103279528Sbaptor 2104279528Sbapt.Va ARCH 2105279528Sbaptmay be specified as 2106279528Sbapt.Li numeric 2107279528Sbaptto have numbers printed rather than names, for the selected types of registers. 2108279528SbaptYou can list the available values of 2109279528Sbapt.Va ABI 2110279528Sbaptand 2111279528Sbapt.Va ARCH 2112279528Sbaptusing the 2113279528Sbapt.Op --help 2114279528Sbaptoption. 2115279528Sbapt.Pp 2116279528SbaptFor VAX, you can specify function entry addresses with 2117279528Sbapt.Op -M entry:0xf00ba . 2118279528SbaptYou can use this multiple times to properly disassemble VAX binary files that 2119279528Sbaptdon't contain symbol tables (like ROM dumps). In these cases, the function 2120279528Sbaptentry mask would otherwise be decoded as VAX instructions, which would probably 2121279528Sbaptlead the rest of the function being wrongly disassembled. 2122279528Sbapt.Pp 2123279528Sbapt.It -p 2124279528Sbapt.It --private-headers 2125279528SbaptPrint information that is specific to the object file format. The exact information 2126279528Sbaptprinted depends upon the object file format. For some object file formats, 2127279528Sbaptno additional information is printed. 2128279528Sbapt.Pp 2129279528Sbapt.It -r 2130279528Sbapt.It --reloc 2131279528SbaptPrint the relocation entries of the file. If used with 2132279528Sbapt.Op -d 2133279528Sbaptor 2134279528Sbapt.Op -D , 2135279528Sbaptthe relocations are printed interspersed with the disassembly. 2136279528Sbapt.Pp 2137279528Sbapt.It -R 2138279528Sbapt.It --dynamic-reloc 2139279528SbaptPrint the dynamic relocation entries of the file. This is only meaningful 2140279528Sbaptfor dynamic objects, such as certain types of shared libraries. 2141279528Sbapt.Pp 2142279528Sbapt.It -s 2143279528Sbapt.It --full-contents 2144279528SbaptDisplay the full contents of any sections requested. By default all non-empty 2145279528Sbaptsections are displayed. 2146279528Sbapt.Pp 2147279528Sbapt.It -S 2148279528Sbapt.It --source 2149279528SbaptDisplay source code intermixed with disassembly, if possible. Implies 2150279528Sbapt.Op -d . 2151279528Sbapt.Pp 2152279528Sbapt.It --show-raw-insn 2153279528SbaptWhen disassembling instructions, print the instruction in hex as well as in 2154279528Sbaptsymbolic form. This is the default except when 2155279528Sbapt.Op --prefix-addresses 2156279528Sbaptis used. 2157279528Sbapt.Pp 2158279528Sbapt.It --no-show-raw-insn 2159279528SbaptWhen disassembling instructions, do not print the instruction bytes. This 2160279528Sbaptis the default when 2161279528Sbapt.Op --prefix-addresses 2162279528Sbaptis used. 2163279528Sbapt.Pp 2164279528Sbapt.It -W 2165279528Sbapt.It --dwarf 2166279528SbaptDisplays the contents of the DWARF debug sections in the file, if any are 2167279528Sbaptpresent. 2168279528Sbapt.Pp 2169279528Sbapt.It -G 2170279528Sbapt.It --stabs 2171279528SbaptDisplay the full contents of any sections requested. Display the contents 2172279528Sbaptof the .stab and .stab.index and .stab.excl sections from an ELF file. This 2173279528Sbaptis only useful on systems (such as Solaris 2.0) in which 2174279528Sbapt.Li .stab 2175279528Sbaptdebugging symbol-table entries are carried in an ELF section. In most other 2176279528Sbaptfile formats, debugging symbol-table entries are interleaved with linkage 2177279528Sbaptsymbols, and are visible in the 2178279528Sbapt.Op --syms 2179279528Sbaptoutput. For more information on stabs symbols, see Top,Stabs,Stabs Overview,stabs.info, 2180279528SbaptThe \(lqstabs\(rq debug format. 2181279528Sbapt.Pp 2182279528Sbapt.It --start-address= Va address 2183279528SbaptStart displaying data at the specified address. This affects the output of 2184279528Sbaptthe 2185279528Sbapt.Op -d , 2186279528Sbapt.Op -r 2187279528Sbaptand 2188279528Sbapt.Op -s 2189279528Sbaptoptions. 2190279528Sbapt.Pp 2191279528Sbapt.It --stop-address= Va address 2192279528SbaptStop displaying data at the specified address. This affects the output of 2193279528Sbaptthe 2194279528Sbapt.Op -d , 2195279528Sbapt.Op -r 2196279528Sbaptand 2197279528Sbapt.Op -s 2198279528Sbaptoptions. 2199279528Sbapt.Pp 2200279528Sbapt.It -t 2201279528Sbapt.It --syms 2202279528SbaptPrint the symbol table entries of the file. This is similar to the information 2203279528Sbaptprovided by the 2204279528Sbapt.Li nm 2205279528Sbaptprogram. 2206279528Sbapt.Pp 2207279528Sbapt.It -T 2208279528Sbapt.It --dynamic-syms 2209279528SbaptPrint the dynamic symbol table entries of the file. This is only meaningful 2210279528Sbaptfor dynamic objects, such as certain types of shared libraries. This is similar 2211279528Sbaptto the information provided by the 2212279528Sbapt.Li nm 2213279528Sbaptprogram when given the 2214279528Sbapt.Op -D 2215279528Sbapt( 2216279528Sbapt.Op --dynamic ) 2217279528Sbaptoption. 2218279528Sbapt.Pp 2219279528Sbapt.It --special-syms 2220279528SbaptWhen displaying symbols include those which the target considers to be special 2221279528Sbaptin some way and which would not normally be of interest to the user. 2222279528Sbapt.Pp 2223279528Sbapt.It -V 2224279528Sbapt.It --version 2225279528SbaptPrint the version number of 2226279528Sbapt.Xr objdump 2227279528Sbaptand exit. 2228279528Sbapt.Pp 2229279528Sbapt.It -x 2230279528Sbapt.It --all-headers 2231279528SbaptDisplay all available header information, including the symbol table and relocation 2232279528Sbaptentries. Using 2233279528Sbapt.Op -x 2234279528Sbaptis equivalent to specifying all of 2235279528Sbapt.Op -a -f -h -p -r -t . 2236279528Sbapt.Pp 2237279528Sbapt.It -w 2238279528Sbapt.It --wide 2239279528SbaptFormat some lines for output devices that have more than 80 columns. Also 2240279528Sbaptdo not truncate symbol names when they are displayed. 2241279528Sbapt.Pp 2242279528Sbapt.It -z 2243279528Sbapt.It --disassemble-zeroes 2244279528SbaptNormally the disassembly output will skip blocks of zeroes. This option directs 2245279528Sbaptthe disassembler to disassemble those blocks, just like any other data. 2246279528Sbapt.El 2247279528Sbapt.Pp 2248279528Sbapt.Sh ranlib 2249279528Sbapt.Bd -literal -offset indent 2250279528Sbaptranlib [-vV] archive 2251279528Sbapt.Ed 2252279528Sbapt.Pp 2253279528Sbapt.Xr ranlib 2254279528Sbaptgenerates an index to the contents of an archive and stores it in the archive. 2255279528SbaptThe index lists each symbol defined by a member of an archive that is a relocatable 2256279528Sbaptobject file. 2257279528Sbapt.Pp 2258279528SbaptYou may use 2259279528Sbapt.Li nm -s 2260279528Sbaptor 2261279528Sbapt.Li nm --print-armap 2262279528Sbaptto list this index. 2263279528Sbapt.Pp 2264279528SbaptAn archive with such an index speeds up linking to the library and allows 2265279528Sbaptroutines in the library to call each other without regard to their placement 2266279528Sbaptin the archive. 2267279528Sbapt.Pp 2268279528SbaptThe GNU 2269279528Sbapt.Xr ranlib 2270279528Sbaptprogram is another form of GNU 2271279528Sbapt.Xr ar ; 2272279528Sbaptrunning 2273279528Sbapt.Xr ranlib 2274279528Sbaptis completely equivalent to executing 2275279528Sbapt.Li ar -s . 2276279528SbaptSee Section.Dq ar . 2277279528Sbapt.Pp 2278279528Sbapt.Bl -tag -width Ds 2279279528Sbapt.It -v 2280279528Sbapt.It -V 2281279528Sbapt.It --version 2282279528SbaptShow the version number of 2283279528Sbapt.Xr ranlib . 2284279528Sbapt.El 2285279528Sbapt.Pp 2286279528Sbapt.Sh size 2287279528Sbapt.Bd -literal -offset indent 2288279528Sbaptsize [-A|-B|--format=compatibility] 2289279528Sbapt [--help] 2290279528Sbapt [-d|-o|-x|--radix=number] 2291279528Sbapt [-t|--totals] 2292279528Sbapt [--target=bfdname] [-V|--version] 2293279528Sbapt [objfile...] 2294279528Sbapt.Ed 2295279528Sbapt.Pp 2296279528SbaptThe GNU 2297279528Sbapt.Xr size 2298279528Sbaptutility lists the section sizes---and the total size---for each of the object 2299279528Sbaptor archive files 2300279528Sbapt.Va objfile 2301279528Sbaptin its argument list. By default, one line of output is generated for each 2302279528Sbaptobject file or each module in an archive. 2303279528Sbapt.Pp 2304279528Sbapt.Va objfile 2305279528Sbapt\&...are the object files to be examined. If none are specified, the file 2306279528Sbapt.Li a.out 2307279528Sbaptwill be used. 2308279528Sbapt.Pp 2309279528SbaptThe command line options have the following meanings: 2310279528Sbapt.Pp 2311279528Sbapt.Bl -tag -width Ds 2312279528Sbapt.It -A 2313279528Sbapt.It -B 2314279528Sbapt.It --format= Va compatibility 2315279528SbaptUsing one of these options, you can choose whether the output from GNU 2316279528Sbapt.Xr size 2317279528Sbaptresembles output from System V 2318279528Sbapt.Xr size 2319279528Sbapt(using 2320279528Sbapt.Op -A , 2321279528Sbaptor 2322279528Sbapt.Op --format=sysv ) , 2323279528Sbaptor Berkeley 2324279528Sbapt.Xr size 2325279528Sbapt(using 2326279528Sbapt.Op -B , 2327279528Sbaptor 2328279528Sbapt.Op --format=berkeley ) . 2329279528SbaptThe default is the one-line format similar to Berkeley's. 2330279528Sbapt.Pp 2331279528SbaptHere is an example of the Berkeley (default) format of output from 2332279528Sbapt.Xr size : 2333279528Sbapt.Bd -literal -offset indent 2334279528Sbapt$ size --format=Berkeley ranlib size 2335279528Sbapttext data bss dec hex filename 2336279528Sbapt294880 81920 11592 388392 5ed28 ranlib 2337279528Sbapt294880 81920 11888 388688 5ee50 size 2338279528Sbapt.Ed 2339279528Sbapt.Pp 2340279528SbaptThis is the same data, but displayed closer to System V conventions: 2341279528Sbapt.Pp 2342279528Sbapt.Bd -literal -offset indent 2343279528Sbapt$ size --format=SysV ranlib size 2344279528Sbaptranlib : 2345279528Sbaptsection size addr 2346279528Sbapt\&.text 294880 8192 2347279528Sbapt\&.data 81920 303104 2348279528Sbapt\&.bss 11592 385024 2349279528SbaptTotal 388392 2350279528Sbapt 2351279528Sbapt 2352279528Sbaptsize : 2353279528Sbaptsection size addr 2354279528Sbapt\&.text 294880 8192 2355279528Sbapt\&.data 81920 303104 2356279528Sbapt\&.bss 11888 385024 2357279528SbaptTotal 388688 2358279528Sbapt.Ed 2359279528Sbapt.Pp 2360279528Sbapt.It --help 2361279528SbaptShow a summary of acceptable arguments and options. 2362279528Sbapt.Pp 2363279528Sbapt.It -d 2364279528Sbapt.It -o 2365279528Sbapt.It -x 2366279528Sbapt.It --radix= Va number 2367279528SbaptUsing one of these options, you can control whether the size of each section 2368279528Sbaptis given in decimal ( 2369279528Sbapt.Op -d , 2370279528Sbaptor 2371279528Sbapt.Op --radix=10 ) ; 2372279528Sbaptoctal ( 2373279528Sbapt.Op -o , 2374279528Sbaptor 2375279528Sbapt.Op --radix=8 ) ; 2376279528Sbaptor hexadecimal ( 2377279528Sbapt.Op -x , 2378279528Sbaptor 2379279528Sbapt.Op --radix=16 ) . 2380279528SbaptIn 2381279528Sbapt.Op --radix= Va number , 2382279528Sbaptonly the three values (8, 10, 16) are supported. The total size is always 2383279528Sbaptgiven in two radices; decimal and hexadecimal for 2384279528Sbapt.Op -d 2385279528Sbaptor 2386279528Sbapt.Op -x 2387279528Sbaptoutput, or octal and hexadecimal if you're using 2388279528Sbapt.Op -o . 2389279528Sbapt.Pp 2390279528Sbapt.It -t 2391279528Sbapt.It --totals 2392279528SbaptShow totals of all objects listed (Berkeley format listing mode only). 2393279528Sbapt.Pp 2394279528Sbapt.It --target= Va bfdname 2395279528SbaptSpecify that the object-code format for 2396279528Sbapt.Va objfile 2397279528Sbaptis 2398279528Sbapt.Va bfdname . 2399279528SbaptThis option may not be necessary; 2400279528Sbapt.Xr size 2401279528Sbaptcan automatically recognize many formats.See Section 2402279528Sbapt.Dq Target Selection , 2403279528Sbaptfor more information. 2404279528Sbapt.Pp 2405279528Sbapt.It -V 2406279528Sbapt.It --version 2407279528SbaptDisplay the version number of 2408279528Sbapt.Xr size . 2409279528Sbapt.El 2410279528Sbapt.Pp 2411279528Sbapt.Sh strings 2412279528Sbapt.Bd -literal -offset indent 2413279528Sbaptstrings [-afov] [-min-len] 2414279528Sbapt [-n min-len] [--bytes=min-len] 2415279528Sbapt [-t radix] [--radix=radix] 2416279528Sbapt [-e encoding] [--encoding=encoding] 2417279528Sbapt [-] [--all] [--print-file-name] 2418279528Sbapt [-T bfdname] [--target=bfdname] 2419279528Sbapt [--help] [--version] file... 2420279528Sbapt.Ed 2421279528Sbapt.Pp 2422279528SbaptFor each 2423279528Sbapt.Va file 2424279528Sbaptgiven, GNU 2425279528Sbapt.Xr strings 2426279528Sbaptprints the printable character sequences that are at least 4 characters long 2427279528Sbapt(or the number given with the options below) and are followed by an unprintable 2428279528Sbaptcharacter. By default, it only prints the strings from the initialized and 2429279528Sbaptloaded sections of object files; for other types of files, it prints the strings 2430279528Sbaptfrom the whole file. 2431279528Sbapt.Pp 2432279528Sbapt.Xr strings 2433279528Sbaptis mainly useful for determining the contents of non-text files. 2434279528Sbapt.Pp 2435279528Sbapt.Bl -tag -width Ds 2436279528Sbapt.It -a 2437279528Sbapt.It --all 2438279528Sbapt.It - 2439279528SbaptDo not scan only the initialized and loaded sections of object files; scan 2440279528Sbaptthe whole files. 2441279528Sbapt.Pp 2442279528Sbapt.It -f 2443279528Sbapt.It --print-file-name 2444279528SbaptPrint the name of the file before each string. 2445279528Sbapt.Pp 2446279528Sbapt.It --help 2447279528SbaptPrint a summary of the program usage on the standard output and exit. 2448279528Sbapt.Pp 2449279528Sbapt.It - Va min-len 2450279528Sbapt.It -n Va min-len 2451279528Sbapt.It --bytes= Va min-len 2452279528SbaptPrint sequences of characters that are at least 2453279528Sbapt.Va min-len 2454279528Sbaptcharacters long, instead of the default 4. 2455279528Sbapt.Pp 2456279528Sbapt.It -o 2457279528SbaptLike 2458279528Sbapt.Li -t o . 2459279528SbaptSome other versions of 2460279528Sbapt.Xr strings 2461279528Sbapthave 2462279528Sbapt.Op -o 2463279528Sbaptact like 2464279528Sbapt.Li -t d 2465279528Sbaptinstead. Since we can not be compatible with both ways, we simply chose one. 2466279528Sbapt.Pp 2467279528Sbapt.It -t Va radix 2468279528Sbapt.It --radix= Va radix 2469279528SbaptPrint the offset within the file before each string. The single character 2470279528Sbaptargument specifies the radix of the offset--- 2471279528Sbapt.Li o 2472279528Sbaptfor octal, 2473279528Sbapt.Li x 2474279528Sbaptfor hexadecimal, or 2475279528Sbapt.Li d 2476279528Sbaptfor decimal. 2477279528Sbapt.Pp 2478279528Sbapt.It -e Va encoding 2479279528Sbapt.It --encoding= Va encoding 2480279528SbaptSelect the character encoding of the strings that are to be found. Possible 2481279528Sbaptvalues for 2482279528Sbapt.Va encoding 2483279528Sbaptare: 2484279528Sbapt.Li s 2485279528Sbapt= single-7-bit-byte characters (ASCII, ISO 8859, etc., default), 2486279528Sbapt.Li S 2487279528Sbapt= single-8-bit-byte characters, 2488279528Sbapt.Li b 2489279528Sbapt= 16-bit bigendian, 2490279528Sbapt.Li l 2491279528Sbapt= 16-bit littleendian, 2492279528Sbapt.Li B 2493279528Sbapt= 32-bit bigendian, 2494279528Sbapt.Li L 2495279528Sbapt= 32-bit littleendian. Useful for finding wide character strings. 2496279528Sbapt.Pp 2497279528Sbapt.It -T Va bfdname 2498279528Sbapt.It --target= Va bfdname 2499279528SbaptSpecify an object code format other than your system's default format.See Section 2500279528Sbapt.Dq Target Selection , 2501279528Sbaptfor more information. 2502279528Sbapt.Pp 2503279528Sbapt.It -v 2504279528Sbapt.It --version 2505279528SbaptPrint the program version number on the standard output and exit. 2506279528Sbapt.El 2507279528Sbapt.Pp 2508279528Sbapt.Sh strip 2509279528Sbapt.Bd -literal -offset indent 2510279528Sbaptstrip [-F bfdname |--target=bfdname] 2511279528Sbapt [-I bfdname |--input-target=bfdname] 2512279528Sbapt [-O bfdname |--output-target=bfdname] 2513279528Sbapt [-s|--strip-all] 2514279528Sbapt [-S|-g|-d|--strip-debug] 2515279528Sbapt [-K symbolname |--keep-symbol=symbolname] 2516279528Sbapt [-N symbolname |--strip-symbol=symbolname] 2517279528Sbapt [-w|--wildcard] 2518279528Sbapt [-x|--discard-all] [-X |--discard-locals] 2519279528Sbapt [-R sectionname |--remove-section=sectionname] 2520279528Sbapt [-o file] [-p|--preserve-dates] 2521279528Sbapt [--keep-file-symbols] 2522279528Sbapt [--only-keep-debug] 2523279528Sbapt [-v |--verbose] [-V|--version] 2524279528Sbapt [--help] [--info] 2525279528Sbapt objfile... 2526279528Sbapt.Ed 2527279528Sbapt.Pp 2528279528SbaptGNU 2529279528Sbapt.Xr strip 2530279528Sbaptdiscards all symbols from object files 2531279528Sbapt.Va objfile . 2532279528SbaptThe list of object files may include archives. At least one object file must 2533279528Sbaptbe given. 2534279528Sbapt.Pp 2535279528Sbapt.Xr strip 2536279528Sbaptmodifies the files named in its argument, rather than writing modified copies 2537279528Sbaptunder different names. 2538279528Sbapt.Pp 2539279528Sbapt.Bl -tag -width Ds 2540279528Sbapt.It -F Va bfdname 2541279528Sbapt.It --target= Va bfdname 2542279528SbaptTreat the original 2543279528Sbapt.Va objfile 2544279528Sbaptas a file with the object code format 2545279528Sbapt.Va bfdname , 2546279528Sbaptand rewrite it in the same format.See Section 2547279528Sbapt.Dq Target Selection , 2548279528Sbaptfor more information. 2549279528Sbapt.Pp 2550279528Sbapt.It --help 2551279528SbaptShow a summary of the options to 2552279528Sbapt.Xr strip 2553279528Sbaptand exit. 2554279528Sbapt.Pp 2555279528Sbapt.It --info 2556279528SbaptDisplay a list showing all architectures and object formats available. 2557279528Sbapt.Pp 2558279528Sbapt.It -I Va bfdname 2559279528Sbapt.It --input-target= Va bfdname 2560279528SbaptTreat the original 2561279528Sbapt.Va objfile 2562279528Sbaptas a file with the object code format 2563279528Sbapt.Va bfdname . 2564279528SbaptSee Section.Dq Target Selection , 2565279528Sbaptfor more information. 2566279528Sbapt.Pp 2567279528Sbapt.It -O Va bfdname 2568279528Sbapt.It --output-target= Va bfdname 2569279528SbaptReplace 2570279528Sbapt.Va objfile 2571279528Sbaptwith a file in the output format 2572279528Sbapt.Va bfdname . 2573279528SbaptSee Section.Dq Target Selection , 2574279528Sbaptfor more information. 2575279528Sbapt.Pp 2576279528Sbapt.It -R Va sectionname 2577279528Sbapt.It --remove-section= Va sectionname 2578279528SbaptRemove any section named 2579279528Sbapt.Va sectionname 2580279528Sbaptfrom the output file. This option may be given more than once. Note that using 2581279528Sbaptthis option inappropriately may make the output file unusable. 2582279528Sbapt.Pp 2583279528Sbapt.It -s 2584279528Sbapt.It --strip-all 2585279528SbaptRemove all symbols. 2586279528Sbapt.Pp 2587279528Sbapt.It -g 2588279528Sbapt.It -S 2589279528Sbapt.It -d 2590279528Sbapt.It --strip-debug 2591279528SbaptRemove debugging symbols only. 2592279528Sbapt.Pp 2593279528Sbapt.It --strip-unneeded 2594279528SbaptRemove all symbols that are not needed for relocation processing. 2595279528Sbapt.Pp 2596279528Sbapt.It -K Va symbolname 2597279528Sbapt.It --keep-symbol= Va symbolname 2598279528SbaptWhen stripping symbols, keep symbol 2599279528Sbapt.Va symbolname 2600279528Sbapteven if it would normally be stripped. This option may be given more than 2601279528Sbaptonce. 2602279528Sbapt.Pp 2603279528Sbapt.It -N Va symbolname 2604279528Sbapt.It --strip-symbol= Va symbolname 2605279528SbaptRemove symbol 2606279528Sbapt.Va symbolname 2607279528Sbaptfrom the source file. This option may be given more than once, and may be 2608279528Sbaptcombined with strip options other than 2609279528Sbapt.Op -K . 2610279528Sbapt.Pp 2611279528Sbapt.It -o Va file 2612279528SbaptPut the stripped output in 2613279528Sbapt.Va file , 2614279528Sbaptrather than replacing the existing file. When this argument is used, only 2615279528Sbaptone 2616279528Sbapt.Va objfile 2617279528Sbaptargument may be specified. 2618279528Sbapt.Pp 2619279528Sbapt.It -p 2620279528Sbapt.It --preserve-dates 2621279528SbaptPreserve the access and modification dates of the file. 2622279528Sbapt.Pp 2623279528Sbapt.It -w 2624279528Sbapt.It --wildcard 2625279528SbaptPermit regular expressions in 2626279528Sbapt.Va symbolname 2627279528Sbapts used in other command line options. The question mark (?), asterisk (*), 2628279528Sbaptbackslash (\e) and square brackets ([]) operators can be used anywhere in the 2629279528Sbaptsymbol name. If the first character of the symbol name is the exclamation 2630279528Sbaptpoint (!) then the sense of the switch is reversed for that symbol. For example: 2631279528Sbapt.Pp 2632279528Sbapt.Bd -literal -offset indent 2633279528Sbapt -w -K !foo -K fo* 2634279528Sbapt.Ed 2635279528Sbapt.Pp 2636279528Sbaptwould cause strip to only keep symbols that start with the letters \(lqfo\(rq, but 2637279528Sbaptto discard the symbol \(lqfoo\(rq. 2638279528Sbapt.Pp 2639279528Sbapt.It -x 2640279528Sbapt.It --discard-all 2641279528SbaptRemove non-global symbols. 2642279528Sbapt.Pp 2643279528Sbapt.It -X 2644279528Sbapt.It --discard-locals 2645279528SbaptRemove compiler-generated local symbols. (These usually start with 2646279528Sbapt.Li L 2647279528Sbaptor 2648279528Sbapt.Li . . ) 2649279528Sbapt.Pp 2650279528Sbapt.It --keep-file-symbols 2651279528SbaptWhen stripping a file, perhaps with 2652279528Sbapt.Op --strip-debug 2653279528Sbaptor 2654279528Sbapt.Op --strip-unneeded , 2655279528Sbaptretain any symbols specifying source file names, which would otherwise get 2656279528Sbaptstripped. 2657279528Sbapt.Pp 2658279528Sbapt.It --only-keep-debug 2659279528SbaptStrip a file, removing contents of any sections that would not be stripped 2660279528Sbaptby 2661279528Sbapt.Op --strip-debug 2662279528Sbaptand leaving the debugging sections intact. In ELF files, this preserves all 2663279528Sbaptnote sections in the output. 2664279528Sbapt.Pp 2665279528SbaptThe intention is that this option will be used in conjunction with 2666279528Sbapt.Op --add-GNU-debuglink 2667279528Sbaptto create a two part executable. One a stripped binary which will occupy less 2668279528Sbaptspace in RAM and in a distribution and the second a debugging information 2669279528Sbaptfile which is only needed if debugging abilities are required. The suggested 2670279528Sbaptprocedure to create these files is as follows: 2671279528Sbapt.Pp 2672279528Sbapt.Bl -enum 2673279528Sbapt.It 2674279528SbaptLink the executable as normal. Assuming that is is called 2675279528Sbapt.Li foo 2676279528Sbaptthen... 2677279528Sbapt.It 2678279528SbaptRun 2679279528Sbapt.Li objcopy --only-keep-debug foo foo.dbg 2680279528Sbaptto 2681279528Sbaptcreate a file containing the debugging info. 2682279528Sbapt.It 2683279528SbaptRun 2684279528Sbapt.Li objcopy --strip-debug foo 2685279528Sbaptto create a 2686279528Sbaptstripped executable. 2687279528Sbapt.It 2688279528SbaptRun 2689279528Sbapt.Li objcopy --add-GNU-debuglink=foo.dbg foo 2690279528Sbaptto add a link to the debugging info into the stripped executable. 2691279528Sbapt.El 2692279528Sbapt.Pp 2693279528SbaptNote - the choice of 2694279528Sbapt.Li .dbg 2695279528Sbaptas an extension for the debug info file is arbitrary. Also the 2696279528Sbapt.Li --only-keep-debug 2697279528Sbaptstep is optional. You could instead do this: 2698279528Sbapt.Pp 2699279528Sbapt.Bl -enum 2700279528Sbapt.It 2701279528SbaptLink the executable as normal. 2702279528Sbapt.It 2703279528SbaptCopy 2704279528Sbapt.Li foo 2705279528Sbaptto 2706279528Sbapt.Li foo.full 2707279528Sbapt.It 2708279528SbaptRun 2709279528Sbapt.Li strip --strip-debug foo 2710279528Sbapt.It 2711279528SbaptRun 2712279528Sbapt.Li objcopy --add-GNU-debuglink=foo.full foo 2713279528Sbapt.El 2714279528Sbapt.Pp 2715279528Sbaptie the file pointed to by the 2716279528Sbapt.Op --add-GNU-debuglink 2717279528Sbaptcan be the full executable. It does not have to be a file created by the 2718279528Sbapt.Op --only-keep-debug 2719279528Sbaptswitch. 2720279528Sbapt.Pp 2721279528SbaptNote - this switch is only intended for use on fully linked files. It does 2722279528Sbaptnot make sense to use it on object files where the debugging information may 2723279528Sbaptbe incomplete. Besides the GNU_debuglink feature currently only supports the 2724279528Sbaptpresence of one filename containing debugging information, not multiple filenames 2725279528Sbapton a one-per-object-file basis. 2726279528Sbapt.Pp 2727279528Sbapt.It -V 2728279528Sbapt.It --version 2729279528SbaptShow the version number for 2730279528Sbapt.Xr strip . 2731279528Sbapt.Pp 2732279528Sbapt.It -v 2733279528Sbapt.It --verbose 2734279528SbaptVerbose output: list all object files modified. In the case of archives, 2735279528Sbapt.Li strip -v 2736279528Sbaptlists all members of the archive. 2737279528Sbapt.El 2738279528Sbapt.Pp 2739279528Sbapt.Sh c++filt 2740279528Sbapt.Bd -literal -offset indent 2741279528Sbaptc++filt [-_|--strip-underscores] 2742279528Sbapt [-n|--no-strip-underscores] 2743279528Sbapt [-p|--no-params] 2744279528Sbapt [-t|--types] 2745279528Sbapt [-i|--no-verbose] 2746279528Sbapt [-s format|--format=format] 2747279528Sbapt [--help] [--version] [symbol...] 2748279528Sbapt.Ed 2749279528Sbapt.Pp 2750279528SbaptThe C++ and Java languages provide function overloading, which means that 2751279528Sbaptyou can write many functions with the same name, providing that each function 2752279528Sbapttakes parameters of different types. In order to be able to distinguish these 2753279528Sbaptsimilarly named functions C++ and Java encode them into a low-level assembler 2754279528Sbaptname which uniquely identifies each different version. This process is known 2755279528Sbaptas 2756279528Sbapt.Em mangling . 2757279528SbaptThe 2758279528Sbapt.Xr c++filt 2759279528Sbaptprogram does the inverse mapping: it decodes ( 2760279528Sbapt.Em demangles ) 2761279528Sbaptlow-level names into user-level names so that they can be read. 2762279528Sbapt.Pp 2763279528SbaptEvery alphanumeric word (consisting of letters, digits, underscores, dollars, 2764279528Sbaptor periods) seen in the input is a potential mangled name. If the name decodes 2765279528Sbaptinto a C++ name, the C++ name replaces the low-level name in the output, otherwise 2766279528Sbaptthe original word is output. In this way you can pass an entire assembler 2767279528Sbaptsource file, containing mangled names, through 2768279528Sbapt.Xr c++filt 2769279528Sbaptand see the same source file containing demangled names. 2770279528Sbapt.Pp 2771279528SbaptYou can also use 2772279528Sbapt.Xr c++filt 2773279528Sbaptto decipher individual symbols by passing them on the command line: 2774279528Sbapt.Pp 2775279528Sbapt.Bd -literal -offset indent 2776279528Sbaptc++filt symbol 2777279528Sbapt.Ed 2778279528Sbapt.Pp 2779279528SbaptIf no 2780279528Sbapt.Va symbol 2781279528Sbaptarguments are given, 2782279528Sbapt.Xr c++filt 2783279528Sbaptreads symbol names from the standard input instead. All the results are printed 2784279528Sbapton the standard output. The difference between reading names from the command 2785279528Sbaptline versus reading names from the standard input is that command line arguments 2786279528Sbaptare expected to be just mangled names and no checking is performed to separate 2787279528Sbaptthem from surrounding text. Thus for example: 2788279528Sbapt.Pp 2789279528Sbapt.Bd -literal -offset indent 2790279528Sbaptc++filt -n _Z1fv 2791279528Sbapt.Ed 2792279528Sbapt.Pp 2793279528Sbaptwill work and demangle the name to \(lqf()\(rq whereas: 2794279528Sbapt.Pp 2795279528Sbapt.Bd -literal -offset indent 2796279528Sbaptc++filt -n _Z1fv, 2797279528Sbapt.Ed 2798279528Sbapt.Pp 2799279528Sbaptwill not work. (Note the extra comma at the end of the mangled name which 2800279528Sbaptmakes it invalid). This command however will work: 2801279528Sbapt.Pp 2802279528Sbapt.Bd -literal -offset indent 2803279528Sbaptecho _Z1fv, | c++filt -n 2804279528Sbapt.Ed 2805279528Sbapt.Pp 2806279528Sbaptand will display \(lqf(),\(rq ie the demangled name followed by a trailing comma. 2807279528SbaptThis behaviour is because when the names are read from the standard input 2808279528Sbaptit is expected that they might be part of an assembler source file where there 2809279528Sbaptmight be extra, extraneous characters trailing after a mangled name. eg: 2810279528Sbapt.Pp 2811279528Sbapt.Bd -literal -offset indent 2812279528Sbapt .type _Z1fv, @function 2813279528Sbapt.Ed 2814279528Sbapt.Pp 2815279528Sbapt.Bl -tag -width Ds 2816279528Sbapt.It -_ 2817279528Sbapt.It --strip-underscores 2818279528SbaptOn some systems, both the C and C++ compilers put an underscore in front of 2819279528Sbaptevery name. For example, the C name 2820279528Sbapt.Li foo 2821279528Sbaptgets the low-level name 2822279528Sbapt.Li _foo . 2823279528SbaptThis option removes the initial underscore. Whether 2824279528Sbapt.Xr c++filt 2825279528Sbaptremoves the underscore by default is target dependent. 2826279528Sbapt.Pp 2827279528Sbapt.It -j 2828279528Sbapt.It --java 2829279528SbaptPrints demangled names using Java syntax. The default is to use C++ syntax. 2830279528Sbapt.Pp 2831279528Sbapt.It -n 2832279528Sbapt.It --no-strip-underscores 2833279528SbaptDo not remove the initial underscore. 2834279528Sbapt.Pp 2835279528Sbapt.It -p 2836279528Sbapt.It --no-params 2837279528SbaptWhen demangling the name of a function, do not display the types of the function's 2838279528Sbaptparameters. 2839279528Sbapt.Pp 2840279528Sbapt.It -t 2841279528Sbapt.It --types 2842279528SbaptAttempt to demangle types as well as function names. This is disabled by default 2843279528Sbaptsince mangled types are normally only used internally in the compiler, and 2844279528Sbaptthey can be confused with non-mangled names. eg a function called \(lqa\(rq treated 2845279528Sbaptas a mangled type name would be demangled to \(lqsigned char\(rq. 2846279528Sbapt.Pp 2847279528Sbapt.It -i 2848279528Sbapt.It --no-verbose 2849279528SbaptDo not include implementation details (if any) in the demangled output. 2850279528Sbapt.Pp 2851279528Sbapt.It -s Va format 2852279528Sbapt.It --format= Va format 2853279528Sbapt.Xr c++filt 2854279528Sbaptcan decode various methods of mangling, used by different compilers. The argument 2855279528Sbaptto this option selects which method it uses: 2856279528Sbapt.Pp 2857279528Sbapt.Bl -tag -width Ds 2858279528Sbapt.It auto 2859279528SbaptAutomatic selection based on executable (the default method) 2860279528Sbapt.It GNU 2861279528Sbaptthe one used by the GNU C++ compiler (g++) 2862279528Sbapt.It lucid 2863279528Sbaptthe one used by the Lucid compiler (lcc) 2864279528Sbapt.It arm 2865279528Sbaptthe one specified by the C++ Annotated Reference Manual 2866279528Sbapt.It hp 2867279528Sbaptthe one used by the HP compiler (aCC) 2868279528Sbapt.It edg 2869279528Sbaptthe one used by the EDG compiler 2870279528Sbapt.It GNU-v3 2871279528Sbaptthe one used by the GNU C++ compiler (g++) with the V3 ABI. 2872279528Sbapt.It java 2873279528Sbaptthe one used by the GNU Java compiler (gcj) 2874279528Sbapt.It gnat 2875279528Sbaptthe one used by the GNU Ada compiler (GNAT). 2876279528Sbapt.El 2877279528Sbapt.Pp 2878279528Sbapt.It --help 2879279528SbaptPrint a summary of the options to 2880279528Sbapt.Xr c++filt 2881279528Sbaptand exit. 2882279528Sbapt.Pp 2883279528Sbapt.It --version 2884279528SbaptPrint the version number of 2885279528Sbapt.Xr c++filt 2886279528Sbaptand exit. 2887279528Sbapt.El 2888279528Sbapt.Pp 2889279528Sbapt.Qo 2890279528Sbapt.Em Warning: 2891279528Sbapt.Xr c++filt 2892279528Sbaptis a new utility, and the details of its user interface are subject to change 2893279528Sbaptin future releases. In particular, a command-line option may be required in 2894279528Sbaptthe future to decode a name passed as an argument on the command line; in 2895279528Sbaptother words, 2896279528Sbapt.Pp 2897279528Sbapt.Bd -literal -offset indent 2898279528Sbaptc++filt symbol 2899279528Sbapt.Ed 2900279528Sbapt.Pp 2901279528Sbaptmay in a future release become 2902279528Sbapt.Pp 2903279528Sbapt.Bd -literal -offset indent 2904279528Sbaptc++filt option symbol 2905279528Sbapt.Ed 2906279528Sbapt.Qc 2907279528Sbapt.Pp 2908279528Sbapt.Sh addr2line 2909279528Sbapt.Bd -literal -offset indent 2910279528Sbaptaddr2line [-b bfdname|--target=bfdname] 2911279528Sbapt [-C|--demangle[=style]] 2912279528Sbapt [-e filename|--exe=filename] 2913279528Sbapt [-f|--functions] [-s|--basename] 2914279528Sbapt [-i|--inlines] 2915279528Sbapt [-j|--section=name] 2916279528Sbapt [-H|--help] [-V|--version] 2917279528Sbapt [addr addr ...] 2918279528Sbapt.Ed 2919279528Sbapt.Pp 2920279528Sbapt.Xr addr2line 2921279528Sbapttranslates addresses into file names and line numbers. Given an address in 2922279528Sbaptan executable or an offset in a section of a relocatable object, it uses the 2923279528Sbaptdebugging information to figure out which file name and line number are associated 2924279528Sbaptwith it. 2925279528Sbapt.Pp 2926279528SbaptThe executable or relocatable object to use is specified with the 2927279528Sbapt.Op -e 2928279528Sbaptoption. The default is the file 2929279528Sbapt.Pa a.out . 2930279528SbaptThe section in the relocatable object to use is specified with the 2931279528Sbapt.Op -j 2932279528Sbaptoption. 2933279528Sbapt.Pp 2934279528Sbapt.Xr addr2line 2935279528Sbapthas two modes of operation. 2936279528Sbapt.Pp 2937279528SbaptIn the first, hexadecimal addresses are specified on the command line, and 2938279528Sbapt.Xr addr2line 2939279528Sbaptdisplays the file name and line number for each address. 2940279528Sbapt.Pp 2941279528SbaptIn the second, 2942279528Sbapt.Xr addr2line 2943279528Sbaptreads hexadecimal addresses from standard input, and prints the file name 2944279528Sbaptand line number for each address on standard output. In this mode, 2945279528Sbapt.Xr addr2line 2946279528Sbaptmay be used in a pipe to convert dynamically chosen addresses. 2947279528Sbapt.Pp 2948279528SbaptThe format of the output is 2949279528Sbapt.Li FILENAME:LINENO . 2950279528SbaptThe file name and line number for each address is printed on a separate line. 2951279528SbaptIf the 2952279528Sbapt.Xr -f 2953279528Sbaptoption is used, then each 2954279528Sbapt.Li FILENAME:LINENO 2955279528Sbaptline is preceded by a 2956279528Sbapt.Li FUNCTIONNAME 2957279528Sbaptline which is the name of the function containing the address. 2958279528Sbapt.Pp 2959279528SbaptIf the file name or function name can not be determined, 2960279528Sbapt.Xr addr2line 2961279528Sbaptwill print two question marks in their place. If the line number can not be 2962279528Sbaptdetermined, 2963279528Sbapt.Xr addr2line 2964279528Sbaptwill print 0. 2965279528Sbapt.Pp 2966279528SbaptThe long and short forms of options, shown here as alternatives, are equivalent. 2967279528Sbapt.Pp 2968279528Sbapt.Bl -tag -width Ds 2969279528Sbapt.It -b Va bfdname 2970279528Sbapt.It --target= Va bfdname 2971279528SbaptSpecify that the object-code format for the object files is 2972279528Sbapt.Va bfdname . 2973279528Sbapt.Pp 2974279528Sbapt.It -C 2975279528Sbapt.It --demangle[= Va style] 2976279528SbaptDecode ( 2977279528Sbapt.Em demangle ) 2978279528Sbaptlow-level symbol names into user-level names. Besides removing any initial 2979279528Sbaptunderscore prepended by the system, this makes C++ function names readable. 2980279528SbaptDifferent compilers have different mangling styles. The optional demangling 2981279528Sbaptstyle argument can be used to choose an appropriate demangling style for your 2982279528Sbaptcompiler.See Section 2983279528Sbapt.Dq c++filt , 2984279528Sbaptfor more information on demangling. 2985279528Sbapt.Pp 2986279528Sbapt.It -e Va filename 2987279528Sbapt.It --exe= Va filename 2988279528SbaptSpecify the name of the executable for which addresses should be translated. 2989279528SbaptThe default file is 2990279528Sbapt.Pa a.out . 2991279528Sbapt.Pp 2992279528Sbapt.It -f 2993279528Sbapt.It --functions 2994279528SbaptDisplay function names as well as file and line number information. 2995279528Sbapt.Pp 2996279528Sbapt.It -s 2997279528Sbapt.It --basenames 2998279528SbaptDisplay only the base of each file name. 2999279528Sbapt.Pp 3000279528Sbapt.It -i 3001279528Sbapt.It --inlines 3002279528SbaptIf the address belongs to a function that was inlined, the source information 3003279528Sbaptfor all enclosing scopes back to the first non-inlined function will also 3004279528Sbaptbe printed. For example, if 3005279528Sbapt.Li main 3006279528Sbaptinlines 3007279528Sbapt.Li callee1 3008279528Sbaptwhich inlines 3009279528Sbapt.Li callee2 , 3010279528Sbaptand address is from 3011279528Sbapt.Li callee2 , 3012279528Sbaptthe source information for 3013279528Sbapt.Li callee1 3014279528Sbaptand 3015279528Sbapt.Li main 3016279528Sbaptwill also be printed. 3017279528Sbapt.Pp 3018279528Sbapt.It -j 3019279528Sbapt.It --section 3020279528SbaptRead offsets relative to the specified section instead of absolute addresses. 3021279528Sbapt.El 3022279528Sbapt.Pp 3023279528Sbapt.Sh nlmconv 3024279528Sbapt.Xr nlmconv 3025279528Sbaptconverts a relocatable object file into a NetWare Loadable Module. 3026279528Sbapt.Pp 3027279528Sbapt.Qo 3028279528Sbapt.Em Warning: 3029279528Sbapt.Xr nlmconv 3030279528Sbaptis not always built as part of the binary utilities, since it is only useful 3031279528Sbaptfor NLM targets. 3032279528Sbapt.Qc 3033279528Sbapt.Pp 3034279528Sbapt.Bd -literal -offset indent 3035279528Sbaptnlmconv [-I bfdname|--input-target=bfdname] 3036279528Sbapt [-O bfdname|--output-target=bfdname] 3037279528Sbapt [-T headerfile|--header-file=headerfile] 3038279528Sbapt [-d|--debug] [-l linker|--linker=linker] 3039279528Sbapt [-h|--help] [-V|--version] 3040279528Sbapt infile outfile 3041279528Sbapt.Ed 3042279528Sbapt.Pp 3043279528Sbapt.Xr nlmconv 3044279528Sbaptconverts the relocatable 3045279528Sbapt.Li i386 3046279528Sbaptobject file 3047279528Sbapt.Va infile 3048279528Sbaptinto the NetWare Loadable Module 3049279528Sbapt.Va outfile , 3050279528Sbaptoptionally reading 3051279528Sbapt.Va headerfile 3052279528Sbaptfor NLM header information. For instructions on writing the NLM command file 3053279528Sbaptlanguage used in header files, see the 3054279528Sbapt.Li linkers 3055279528Sbaptsection, 3056279528Sbapt.Li NLMLINK 3057279528Sbaptin particular, of the 3058279528Sbapt.Em NLM Development and Tools Overview , 3059279528Sbaptwhich is part of the NLM Software Developer's Kit (\(lqNLM SDK\(rq), available from 3060279528SbaptNovell, Inc. 3061279528Sbapt.Xr nlmconv 3062279528Sbaptuses the GNU Binary File Descriptor library to read 3063279528Sbapt.Va infile ; 3064279528Sbaptsee BFD,,BFD,ld.info,Using LD, for more information. 3065279528Sbapt.Pp 3066279528Sbapt.Xr nlmconv 3067279528Sbaptcan perform a link step. In other words, you can list more than one object 3068279528Sbaptfile for input if you list them in the definitions file (rather than simply 3069279528Sbaptspecifying one input file on the command line). In this case, 3070279528Sbapt.Xr nlmconv 3071279528Sbaptcalls the linker for you. 3072279528Sbapt.Pp 3073279528Sbapt.Bl -tag -width Ds 3074279528Sbapt.It -I Va bfdname 3075279528Sbapt.It --input-target= Va bfdname 3076279528SbaptObject format of the input file. 3077279528Sbapt.Xr nlmconv 3078279528Sbaptcan usually determine the format of a given file (so no default is necessary).See Section 3079279528Sbapt.Dq Target Selection , 3080279528Sbaptfor more information. 3081279528Sbapt.Pp 3082279528Sbapt.It -O Va bfdname 3083279528Sbapt.It --output-target= Va bfdname 3084279528SbaptObject format of the output file. 3085279528Sbapt.Xr nlmconv 3086279528Sbaptinfers the output format based on the input format, e.g. for a 3087279528Sbapt.Li i386 3088279528Sbaptinput file the output format is 3089279528Sbapt.Li nlm32-i386 . 3090279528SbaptSee Section.Dq Target Selection , 3091279528Sbaptfor more information. 3092279528Sbapt.Pp 3093279528Sbapt.It -T Va headerfile 3094279528Sbapt.It --header-file= Va headerfile 3095279528SbaptReads 3096279528Sbapt.Va headerfile 3097279528Sbaptfor NLM header information. For instructions on writing the NLM command file 3098279528Sbaptlanguage used in header files, see see the 3099279528Sbapt.Li linkers 3100279528Sbaptsection, of the 3101279528Sbapt.Em NLM Development and Tools Overview , 3102279528Sbaptwhich is part of the NLM Software Developer's Kit, available from Novell, 3103279528SbaptInc. 3104279528Sbapt.Pp 3105279528Sbapt.It -d 3106279528Sbapt.It --debug 3107279528SbaptDisplays (on standard error) the linker command line used by 3108279528Sbapt.Xr nlmconv . 3109279528Sbapt.Pp 3110279528Sbapt.It -l Va linker 3111279528Sbapt.It --linker= Va linker 3112279528SbaptUse 3113279528Sbapt.Va linker 3114279528Sbaptfor any linking. 3115279528Sbapt.Va linker 3116279528Sbaptcan be an absolute or a relative pathname. 3117279528Sbapt.Pp 3118279528Sbapt.It -h 3119279528Sbapt.It --help 3120279528SbaptPrints a usage summary. 3121279528Sbapt.Pp 3122279528Sbapt.It -V 3123279528Sbapt.It --version 3124279528SbaptPrints the version number for 3125279528Sbapt.Xr nlmconv . 3126279528Sbapt.El 3127279528Sbapt.Pp 3128279528Sbapt.Sh windmc 3129279528Sbapt.Xr windmc 3130279528Sbaptmay be used to generator Windows message resources. 3131279528Sbapt.Pp 3132279528Sbapt.Qo 3133279528Sbapt.Em Warning: 3134279528Sbapt.Xr windmc 3135279528Sbaptis not always built as part of the binary utilities, since it is only useful 3136279528Sbaptfor Windows targets. 3137279528Sbapt.Qc 3138279528Sbapt.Pp 3139279528Sbapt.Bd -literal -offset indent 3140279528Sbaptwindmc [options] input-file 3141279528Sbapt.Ed 3142279528Sbapt.Pp 3143279528Sbapt.Xr windmc 3144279528Sbaptreads message definitions from an input file (.mc) and translate them into 3145279528Sbapta set of output files. The output files may be of four kinds: 3146279528Sbapt.Pp 3147279528Sbapt.Bl -tag -width Ds 3148279528Sbapt.It h 3149279528SbaptA C header file containing the message definitions. 3150279528Sbapt.Pp 3151279528Sbapt.It rc 3152279528SbaptA resource file compilable by the 3153279528Sbapt.Xr windres 3154279528Sbapttool. 3155279528Sbapt.Pp 3156279528Sbapt.It bin 3157279528SbaptOne or more binary files containing the resource data for a specific message 3158279528Sbaptlanguage. 3159279528Sbapt.Pp 3160279528Sbapt.It dbg 3161279528SbaptA C include file that maps message id's to their symbolic name. 3162279528Sbapt.El 3163279528Sbapt.Pp 3164279528SbaptThe exact description of these different formats is available in documentation 3165279528Sbaptfrom Microsoft. 3166279528Sbapt.Pp 3167279528SbaptWhen 3168279528Sbapt.Xr windmc 3169279528Sbaptconverts from the 3170279528Sbapt.Li mc 3171279528Sbaptformat to the 3172279528Sbapt.Li bin 3173279528Sbaptformat, 3174279528Sbapt.Li rc , 3175279528Sbapt.Li h , 3176279528Sbaptand optional 3177279528Sbapt.Li dbg 3178279528Sbaptit is acting like the Windows Message Compiler. 3179279528Sbapt.Pp 3180279528Sbapt.Bl -tag -width Ds 3181279528Sbapt.It -a 3182279528Sbapt.It --ascii_in 3183279528SbaptSpecifies that the input file specified is ANSI. This is the default behaviour. 3184279528Sbapt.Pp 3185279528Sbapt.It -A 3186279528Sbapt.It --ascii_out 3187279528SbaptSpecifies that messages in the output 3188279528Sbapt.Li bin 3189279528Sbaptfiles should be in ANSI format. 3190279528Sbapt.Pp 3191279528Sbapt.It -b 3192279528Sbapt.It --binprefix 3193279528SbaptSpecifies that 3194279528Sbapt.Li bin 3195279528Sbaptfilenames should have to be prefixed by the basename of the source file. 3196279528Sbapt.Pp 3197279528Sbapt.It -c 3198279528Sbapt.It --customflag 3199279528SbaptSets the customer bit in all message id's. 3200279528Sbapt.Pp 3201279528Sbapt.It -C Va codepage 3202279528Sbapt.It --codepage_in Va codepage 3203279528SbaptSets the default codepage to be used to convert input file to UTF16. The default 3204279528Sbaptis ocdepage 1252. 3205279528Sbapt.Pp 3206279528Sbapt.It -d 3207279528Sbapt.It --decimal_values 3208279528SbaptOutputs the constants in the header file in decimal. Default is using hexadecimal 3209279528Sbaptoutput. 3210279528Sbapt.Pp 3211279528Sbapt.It -e Va ext 3212279528Sbapt.It --extension Va ext 3213279528SbaptThe extension for the header file. The default is .h extension. 3214279528Sbapt.Pp 3215279528Sbapt.It -F Va target 3216279528Sbapt.It --target Va target 3217279528SbaptSpecify the BFD format to use for a bin file as output. This is a BFD target 3218279528Sbaptname; you can use the 3219279528Sbapt.Op --help 3220279528Sbaptoption to see a list of supported targets. Normally 3221279528Sbapt.Xr windmc 3222279528Sbaptwill use the default format, which is the first one listed by the 3223279528Sbapt.Op --help 3224279528Sbaptoption. Target Selection. 3225279528Sbapt.Pp 3226279528Sbapt.It -h Va path 3227279528Sbapt.It --headerdir Va path 3228279528SbaptThe target directory of the generated header file. The default is the current 3229279528Sbaptdirectory. 3230279528Sbapt.Pp 3231279528Sbapt.It -H 3232279528Sbapt.It --help 3233279528SbaptDisplays a list of command line options and then exits. 3234279528Sbapt.Pp 3235279528Sbapt.It -m Va characters 3236279528Sbapt.It --maxlength Va characters 3237279528SbaptInstructs 3238279528Sbapt.Xr windmc 3239279528Sbaptto generate a warning if the length of any message exceeds the number specified. 3240279528Sbapt.Pp 3241279528Sbapt.It -n 3242279528Sbapt.It --nullterminate 3243279528SbaptTerminate message text in 3244279528Sbapt.Li bin 3245279528Sbaptfiles by zero. By default they are terminated by CR/LF. 3246279528Sbapt.Pp 3247279528Sbapt.It -o 3248279528Sbapt.It --hresult_use 3249279528SbaptNot yet implemented. Instructs 3250279528Sbapt.Li windmc 3251279528Sbaptto generate an OLE2 header file, using HRESULT definitions. Status codes are 3252279528Sbaptused if the flag is not specified. 3253279528Sbapt.Pp 3254279528Sbapt.It -O Va codepage 3255279528Sbapt.It --codepage_out Va codepage 3256279528SbaptSets the default codepage to be used to output text files. The default is 3257279528Sbaptocdepage 1252. 3258279528Sbapt.Pp 3259279528Sbapt.It -r Va path 3260279528Sbapt.It --rcdir Va path 3261279528SbaptThe target directory for the generated 3262279528Sbapt.Li rc 3263279528Sbaptscript and the generated 3264279528Sbapt.Li bin 3265279528Sbaptfiles that the resource compiler script includes. The default is the current 3266279528Sbaptdirectory. 3267279528Sbapt.Pp 3268279528Sbapt.It -u 3269279528Sbapt.It --unicode_in 3270279528SbaptSpecifies that the input file is UTF16. 3271279528Sbapt.Pp 3272279528Sbapt.It -U 3273279528Sbapt.It --unicode_out 3274279528SbaptSpecifies that messages in the output 3275279528Sbapt.Li bin 3276279528Sbaptfile should be in UTF16 format. This is the default behaviour. 3277279528Sbapt.Pp 3278279528Sbapt.It -v 3279279528Sbapt.It --verbose 3280279528SbaptEnable verbose mode. This tells you what the preprocessor is if you didn't 3281279528Sbaptspecify one. 3282279528Sbapt.Pp 3283279528Sbapt.It -V 3284279528Sbapt.It --version 3285279528SbaptPrints the version number for 3286279528Sbapt.Xr windres . 3287279528Sbapt.Pp 3288279528Sbapt.It -x Va path 3289279528Sbapt.It --xdgb Va path 3290279528SbaptThe path of the 3291279528Sbapt.Li dbg 3292279528SbaptC include file that maps message id's to the symbolic name. No such file is 3293279528Sbaptgenerated without specifying the switch. 3294279528Sbapt.El 3295279528Sbapt.Pp 3296279528Sbapt.Sh windres 3297279528Sbapt.Xr windres 3298279528Sbaptmay be used to manipulate Windows resources. 3299279528Sbapt.Pp 3300279528Sbapt.Qo 3301279528Sbapt.Em Warning: 3302279528Sbapt.Xr windres 3303279528Sbaptis not always built as part of the binary utilities, since it is only useful 3304279528Sbaptfor Windows targets. 3305279528Sbapt.Qc 3306279528Sbapt.Pp 3307279528Sbapt.Bd -literal -offset indent 3308279528Sbaptwindres [options] [input-file] [output-file] 3309279528Sbapt.Ed 3310279528Sbapt.Pp 3311279528Sbapt.Xr windres 3312279528Sbaptreads resources from an input file and copies them into an output file. Either 3313279528Sbaptfile may be in one of three formats: 3314279528Sbapt.Pp 3315279528Sbapt.Bl -tag -width Ds 3316279528Sbapt.It rc 3317279528SbaptA text format read by the Resource Compiler. 3318279528Sbapt.Pp 3319279528Sbapt.It res 3320279528SbaptA binary format generated by the Resource Compiler. 3321279528Sbapt.Pp 3322279528Sbapt.It coff 3323279528SbaptA COFF object or executable. 3324279528Sbapt.El 3325279528Sbapt.Pp 3326279528SbaptThe exact description of these different formats is available in documentation 3327279528Sbaptfrom Microsoft. 3328279528Sbapt.Pp 3329279528SbaptWhen 3330279528Sbapt.Xr windres 3331279528Sbaptconverts from the 3332279528Sbapt.Li rc 3333279528Sbaptformat to the 3334279528Sbapt.Li res 3335279528Sbaptformat, it is acting like the Windows Resource Compiler. When 3336279528Sbapt.Xr windres 3337279528Sbaptconverts from the 3338279528Sbapt.Li res 3339279528Sbaptformat to the 3340279528Sbapt.Li coff 3341279528Sbaptformat, it is acting like the Windows 3342279528Sbapt.Li CVTRES 3343279528Sbaptprogram. 3344279528Sbapt.Pp 3345279528SbaptWhen 3346279528Sbapt.Xr windres 3347279528Sbaptgenerates an 3348279528Sbapt.Li rc 3349279528Sbaptfile, the output is similar but not identical to the format expected for the 3350279528Sbaptinput. When an input 3351279528Sbapt.Li rc 3352279528Sbaptfile refers to an external filename, an output 3353279528Sbapt.Li rc 3354279528Sbaptfile will instead include the file contents. 3355279528Sbapt.Pp 3356279528SbaptIf the input or output format is not specified, 3357279528Sbapt.Xr windres 3358279528Sbaptwill guess based on the file name, or, for the input file, the file contents. 3359279528SbaptA file with an extension of 3360279528Sbapt.Pa .rc 3361279528Sbaptwill be treated as an 3362279528Sbapt.Li rc 3363279528Sbaptfile, a file with an extension of 3364279528Sbapt.Pa .res 3365279528Sbaptwill be treated as a 3366279528Sbapt.Li res 3367279528Sbaptfile, and a file with an extension of 3368279528Sbapt.Pa .o 3369279528Sbaptor 3370279528Sbapt.Pa .exe 3371279528Sbaptwill be treated as a 3372279528Sbapt.Li coff 3373279528Sbaptfile. 3374279528Sbapt.Pp 3375279528SbaptIf no output file is specified, 3376279528Sbapt.Xr windres 3377279528Sbaptwill print the resources in 3378279528Sbapt.Li rc 3379279528Sbaptformat to standard output. 3380279528Sbapt.Pp 3381279528SbaptThe normal use is for you to write an 3382279528Sbapt.Li rc 3383279528Sbaptfile, use 3384279528Sbapt.Xr windres 3385279528Sbaptto convert it to a COFF object file, and then link the COFF file into your 3386279528Sbaptapplication. This will make the resources described in the 3387279528Sbapt.Li rc 3388279528Sbaptfile available to Windows. 3389279528Sbapt.Pp 3390279528Sbapt.Bl -tag -width Ds 3391279528Sbapt.It -i Va filename 3392279528Sbapt.It --input Va filename 3393279528SbaptThe name of the input file. If this option is not used, then 3394279528Sbapt.Xr windres 3395279528Sbaptwill use the first non-option argument as the input file name. If there are 3396279528Sbaptno non-option arguments, then 3397279528Sbapt.Xr windres 3398279528Sbaptwill read from standard input. 3399279528Sbapt.Xr windres 3400279528Sbaptcan not read a COFF file from standard input. 3401279528Sbapt.Pp 3402279528Sbapt.It -o Va filename 3403279528Sbapt.It --output Va filename 3404279528SbaptThe name of the output file. If this option is not used, then 3405279528Sbapt.Xr windres 3406279528Sbaptwill use the first non-option argument, after any used for the input file 3407279528Sbaptname, as the output file name. If there is no non-option argument, then 3408279528Sbapt.Xr windres 3409279528Sbaptwill write to standard output. 3410279528Sbapt.Xr windres 3411279528Sbaptcan not write a COFF file to standard output. Note, for compatibility with 3412279528Sbapt.Xr rc 3413279528Sbaptthe option 3414279528Sbapt.Op -fo 3415279528Sbaptis also accepted, but its use is not recommended. 3416279528Sbapt.Pp 3417279528Sbapt.It -J Va format 3418279528Sbapt.It --input-format Va format 3419279528SbaptThe input format to read. 3420279528Sbapt.Va format 3421279528Sbaptmay be 3422279528Sbapt.Li res , 3423279528Sbapt.Li rc , 3424279528Sbaptor 3425279528Sbapt.Li coff . 3426279528SbaptIf no input format is specified, 3427279528Sbapt.Xr windres 3428279528Sbaptwill guess, as described above. 3429279528Sbapt.Pp 3430279528Sbapt.It -O Va format 3431279528Sbapt.It --output-format Va format 3432279528SbaptThe output format to generate. 3433279528Sbapt.Va format 3434279528Sbaptmay be 3435279528Sbapt.Li res , 3436279528Sbapt.Li rc , 3437279528Sbaptor 3438279528Sbapt.Li coff . 3439279528SbaptIf no output format is specified, 3440279528Sbapt.Xr windres 3441279528Sbaptwill guess, as described above. 3442279528Sbapt.Pp 3443279528Sbapt.It -F Va target 3444279528Sbapt.It --target Va target 3445279528SbaptSpecify the BFD format to use for a COFF file as input or output. This is 3446279528Sbapta BFD target name; you can use the 3447279528Sbapt.Op --help 3448279528Sbaptoption to see a list of supported targets. Normally 3449279528Sbapt.Xr windres 3450279528Sbaptwill use the default format, which is the first one listed by the 3451279528Sbapt.Op --help 3452279528Sbaptoption. Target Selection. 3453279528Sbapt.Pp 3454279528Sbapt.It --preprocessor Va program 3455279528SbaptWhen 3456279528Sbapt.Xr windres 3457279528Sbaptreads an 3458279528Sbapt.Li rc 3459279528Sbaptfile, it runs it through the C preprocessor first. This option may be used 3460279528Sbaptto specify the preprocessor to use, including any leading arguments. The default 3461279528Sbaptpreprocessor argument is 3462279528Sbapt.Li gcc -E -xc-header -DRC_INVOKED . 3463279528Sbapt.Pp 3464279528Sbapt.It -I Va directory 3465279528Sbapt.It --include-dir Va directory 3466279528SbaptSpecify an include directory to use when reading an 3467279528Sbapt.Li rc 3468279528Sbaptfile. 3469279528Sbapt.Xr windres 3470279528Sbaptwill pass this to the preprocessor as an 3471279528Sbapt.Op -I 3472279528Sbaptoption. 3473279528Sbapt.Xr windres 3474279528Sbaptwill also search this directory when looking for files named in the 3475279528Sbapt.Li rc 3476279528Sbaptfile. If the argument passed to this command matches any of the supported 3477279528Sbapt.Va formats 3478279528Sbapt(as described in the 3479279528Sbapt.Op -J 3480279528Sbaptoption), it will issue a deprecation warning, and behave just like the 3481279528Sbapt.Op -J 3482279528Sbaptoption. New programs should not use this behaviour. If a directory happens 3483279528Sbaptto match a 3484279528Sbapt.Va format , 3485279528Sbaptsimple prefix it with 3486279528Sbapt.Li ./ 3487279528Sbaptto disable the backward compatibility. 3488279528Sbapt.Pp 3489279528Sbapt.It -D Va target 3490279528Sbapt.It --define Va sym[= Va val] 3491279528SbaptSpecify a 3492279528Sbapt.Op -D 3493279528Sbaptoption to pass to the preprocessor when reading an 3494279528Sbapt.Li rc 3495279528Sbaptfile. 3496279528Sbapt.Pp 3497279528Sbapt.It -U Va target 3498279528Sbapt.It --undefine Va sym 3499279528SbaptSpecify a 3500279528Sbapt.Op -U 3501279528Sbaptoption to pass to the preprocessor when reading an 3502279528Sbapt.Li rc 3503279528Sbaptfile. 3504279528Sbapt.Pp 3505279528Sbapt.It -r 3506279528SbaptIgnored for compatibility with rc. 3507279528Sbapt.Pp 3508279528Sbapt.It -v 3509279528SbaptEnable verbose mode. This tells you what the preprocessor is if you didn't 3510279528Sbaptspecify one. 3511279528Sbapt.Pp 3512279528Sbapt.It -c Va val 3513279528Sbapt.It --codepage Va val 3514279528SbaptSpecify the default codepage to use when reading an 3515279528Sbapt.Li rc 3516279528Sbaptfile. 3517279528Sbapt.Va val 3518279528Sbaptshould be a hexadecimal prefixed by 3519279528Sbapt.Li 0x 3520279528Sbaptor decimal codepage code. The valid range is from zero up to 0xffff, but the 3521279528Sbaptvalidity of the codepage is host and configuration dependent. 3522279528Sbapt.Pp 3523279528Sbapt.It -l Va val 3524279528Sbapt.It --language Va val 3525279528SbaptSpecify the default language to use when reading an 3526279528Sbapt.Li rc 3527279528Sbaptfile. 3528279528Sbapt.Va val 3529279528Sbaptshould be a hexadecimal language code. The low eight bits are the language, 3530279528Sbaptand the high eight bits are the sublanguage. 3531279528Sbapt.Pp 3532279528Sbapt.It --use-temp-file 3533279528SbaptUse a temporary file to instead of using popen to read the output of the preprocessor. 3534279528SbaptUse this option if the popen implementation is buggy on the host (eg., certain 3535279528Sbaptnon-English language versions of Windows 95 and Windows 98 are known to have 3536279528Sbaptbuggy popen where the output will instead go the console). 3537279528Sbapt.Pp 3538279528Sbapt.It --no-use-temp-file 3539279528SbaptUse popen, not a temporary file, to read the output of the preprocessor. This 3540279528Sbaptis the default behaviour. 3541279528Sbapt.Pp 3542279528Sbapt.It -h 3543279528Sbapt.It --help 3544279528SbaptPrints a usage summary. 3545279528Sbapt.Pp 3546279528Sbapt.It -V 3547279528Sbapt.It --version 3548279528SbaptPrints the version number for 3549279528Sbapt.Xr windres . 3550279528Sbapt.Pp 3551279528Sbapt.It --yydebug 3552279528SbaptIf 3553279528Sbapt.Xr windres 3554279528Sbaptis compiled with 3555279528Sbapt.Li YYDEBUG 3556279528Sbaptdefined as 3557279528Sbapt.Li 1 , 3558279528Sbaptthis will turn on parser debugging. 3559279528Sbapt.El 3560279528Sbapt.Pp 3561279528Sbapt.Sh dlltool 3562279528Sbapt.Xr dlltool 3563279528Sbaptis used to create the files needed to create dynamic link libraries (DLLs) 3564279528Sbapton systems which understand PE format image files such as Windows. A DLL contains 3565279528Sbaptan export table which contains information that the runtime loader needs to 3566279528Sbaptresolve references from a referencing program. 3567279528Sbapt.Pp 3568279528SbaptThe export table is generated by this program by reading in a 3569279528Sbapt.Pa .def 3570279528Sbaptfile or scanning the 3571279528Sbapt.Pa .a 3572279528Sbaptand 3573279528Sbapt.Pa .o 3574279528Sbaptfiles which will be in the DLL. A 3575279528Sbapt.Pa .o 3576279528Sbaptfile can contain information in special 3577279528Sbapt.Li .drectve 3578279528Sbaptsections with export information. 3579279528Sbapt.Pp 3580279528Sbapt.Qo 3581279528Sbapt.Em Note: 3582279528Sbapt.Xr dlltool 3583279528Sbaptis not always built as part of the binary utilities, since it is only useful 3584279528Sbaptfor those targets which support DLLs. 3585279528Sbapt.Qc 3586279528Sbapt.Pp 3587279528Sbapt.Bd -literal -offset indent 3588279528Sbaptdlltool [-d|--input-def def-file-name] 3589279528Sbapt [-b|--base-file base-file-name] 3590279528Sbapt [-e|--output-exp exports-file-name] 3591279528Sbapt [-z|--output-def def-file-name] 3592279528Sbapt [-l|--output-lib library-file-name] 3593279528Sbapt [--export-all-symbols] [--no-export-all-symbols] 3594279528Sbapt [--exclude-symbols list] 3595279528Sbapt [--no-default-excludes] 3596279528Sbapt [-S|--as path-to-assembler] [-f|--as-flags options] 3597279528Sbapt [-D|--dllname name] [-m|--machine machine] 3598279528Sbapt [-a|--add-indirect] 3599279528Sbapt [-U|--add-underscore] [--add-stdcall-underscore] 3600279528Sbapt [-k|--kill-at] [-A|--add-stdcall-alias] 3601279528Sbapt [-p|--ext-prefix-alias prefix] 3602279528Sbapt [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork] 3603279528Sbapt [-n|--nodelete] [-t|--temp-prefix prefix] 3604279528Sbapt [-v|--verbose] 3605279528Sbapt [-h|--help] [-V|--version] 3606279528Sbapt [object-file ...] 3607279528Sbapt.Ed 3608279528Sbapt.Pp 3609279528Sbapt.Xr dlltool 3610279528Sbaptreads its inputs, which can come from the 3611279528Sbapt.Op -d 3612279528Sbaptand 3613279528Sbapt.Op -b 3614279528Sbaptoptions as well as object files specified on the command line. It then processes 3615279528Sbaptthese inputs and if the 3616279528Sbapt.Op -e 3617279528Sbaptoption has been specified it creates a exports file. If the 3618279528Sbapt.Op -l 3619279528Sbaptoption has been specified it creates a library file and if the 3620279528Sbapt.Op -z 3621279528Sbaptoption has been specified it creates a def file. Any or all of the 3622279528Sbapt.Op -e , 3623279528Sbapt.Op -l 3624279528Sbaptand 3625279528Sbapt.Op -z 3626279528Sbaptoptions can be present in one invocation of dlltool. 3627279528Sbapt.Pp 3628279528SbaptWhen creating a DLL, along with the source for the DLL, it is necessary to 3629279528Sbapthave three other files. 3630279528Sbapt.Xr dlltool 3631279528Sbaptcan help with the creation of these files. 3632279528Sbapt.Pp 3633279528SbaptThe first file is a 3634279528Sbapt.Pa .def 3635279528Sbaptfile which specifies which functions are exported from the DLL, which functions 3636279528Sbaptthe DLL imports, and so on. This is a text file and can be created by hand, 3637279528Sbaptor 3638279528Sbapt.Xr dlltool 3639279528Sbaptcan be used to create it using the 3640279528Sbapt.Op -z 3641279528Sbaptoption. In this case 3642279528Sbapt.Xr dlltool 3643279528Sbaptwill scan the object files specified on its command line looking for those 3644279528Sbaptfunctions which have been specially marked as being exported and put entries 3645279528Sbaptfor them in the 3646279528Sbapt.Pa .def 3647279528Sbaptfile it creates. 3648279528Sbapt.Pp 3649279528SbaptIn order to mark a function as being exported from a DLL, it needs to have 3650279528Sbaptan 3651279528Sbapt.Op -export:<name_of_function> 3652279528Sbaptentry in the 3653279528Sbapt.Li .drectve 3654279528Sbaptsection of the object file. This can be done in C by using the asm() operator: 3655279528Sbapt.Pp 3656279528Sbapt.Bd -literal -offset indent 3657279528Sbapt asm (".section .drectve"); 3658279528Sbapt asm (".ascii \e"-export:my_func\e""); 3659279528Sbapt 3660279528Sbapt int my_func (void) { ... } 3661279528Sbapt.Ed 3662279528Sbapt.Pp 3663279528SbaptThe second file needed for DLL creation is an exports file. This file is linked 3664279528Sbaptwith the object files that make up the body of the DLL and it handles the 3665279528Sbaptinterface between the DLL and the outside world. This is a binary file and 3666279528Sbaptit can be created by giving the 3667279528Sbapt.Op -e 3668279528Sbaptoption to 3669279528Sbapt.Xr dlltool 3670279528Sbaptwhen it is creating or reading in a 3671279528Sbapt.Pa .def 3672279528Sbaptfile. 3673279528Sbapt.Pp 3674279528SbaptThe third file needed for DLL creation is the library file that programs will 3675279528Sbaptlink with in order to access the functions in the DLL. This file can be created 3676279528Sbaptby giving the 3677279528Sbapt.Op -l 3678279528Sbaptoption to dlltool when it is creating or reading in a 3679279528Sbapt.Pa .def 3680279528Sbaptfile. 3681279528Sbapt.Pp 3682279528Sbapt.Xr dlltool 3683279528Sbaptbuilds the library file by hand, but it builds the exports file by creating 3684279528Sbapttemporary files containing assembler statements and then assembling these. 3685279528SbaptThe 3686279528Sbapt.Op -S 3687279528Sbaptcommand line option can be used to specify the path to the assembler that 3688279528Sbaptdlltool will use, and the 3689279528Sbapt.Op -f 3690279528Sbaptoption can be used to pass specific flags to that assembler. The 3691279528Sbapt.Op -n 3692279528Sbaptcan be used to prevent dlltool from deleting these temporary assembler files 3693279528Sbaptwhen it is done, and if 3694279528Sbapt.Op -n 3695279528Sbaptis specified twice then this will prevent dlltool from deleting the temporary 3696279528Sbaptobject files it used to build the library. 3697279528Sbapt.Pp 3698279528SbaptHere is an example of creating a DLL from a source file 3699279528Sbapt.Li dll.c 3700279528Sbaptand also creating a program (from an object file called 3701279528Sbapt.Li program.o ) 3702279528Sbaptthat uses that DLL: 3703279528Sbapt.Pp 3704279528Sbapt.Bd -literal -offset indent 3705279528Sbapt gcc -c dll.c 3706279528Sbapt dlltool -e exports.o -l dll.lib dll.o 3707279528Sbapt gcc dll.o exports.o -o dll.dll 3708279528Sbapt gcc program.o dll.lib -o program 3709279528Sbapt.Ed 3710279528Sbapt.Pp 3711279528SbaptThe command line options have the following meanings: 3712279528Sbapt.Pp 3713279528Sbapt.Bl -tag -width Ds 3714279528Sbapt.It -d Va filename 3715279528Sbapt.It --input-def Va filename 3716279528SbaptSpecifies the name of a 3717279528Sbapt.Pa .def 3718279528Sbaptfile to be read in and processed. 3719279528Sbapt.Pp 3720279528Sbapt.It -b Va filename 3721279528Sbapt.It --base-file Va filename 3722279528SbaptSpecifies the name of a base file to be read in and processed. The contents 3723279528Sbaptof this file will be added to the relocation section in the exports file generated 3724279528Sbaptby dlltool. 3725279528Sbapt.Pp 3726279528Sbapt.It -e Va filename 3727279528Sbapt.It --output-exp Va filename 3728279528SbaptSpecifies the name of the export file to be created by dlltool. 3729279528Sbapt.Pp 3730279528Sbapt.It -z Va filename 3731279528Sbapt.It --output-def Va filename 3732279528SbaptSpecifies the name of the 3733279528Sbapt.Pa .def 3734279528Sbaptfile to be created by dlltool. 3735279528Sbapt.Pp 3736279528Sbapt.It -l Va filename 3737279528Sbapt.It --output-lib Va filename 3738279528SbaptSpecifies the name of the library file to be created by dlltool. 3739279528Sbapt.Pp 3740279528Sbapt.It --export-all-symbols 3741279528SbaptTreat all global and weak defined symbols found in the input object files 3742279528Sbaptas symbols to be exported. There is a small list of symbols which are not 3743279528Sbaptexported by default; see the 3744279528Sbapt.Op --no-default-excludes 3745279528Sbaptoption. You may add to the list of symbols to not export by using the 3746279528Sbapt.Op --exclude-symbols 3747279528Sbaptoption. 3748279528Sbapt.Pp 3749279528Sbapt.It --no-export-all-symbols 3750279528SbaptOnly export symbols explicitly listed in an input 3751279528Sbapt.Pa .def 3752279528Sbaptfile or in 3753279528Sbapt.Li .drectve 3754279528Sbaptsections in the input object files. This is the default behaviour. The 3755279528Sbapt.Li .drectve 3756279528Sbaptsections are created by 3757279528Sbapt.Li dllexport 3758279528Sbaptattributes in the source code. 3759279528Sbapt.Pp 3760279528Sbapt.It --exclude-symbols Va list 3761279528SbaptDo not export the symbols in 3762279528Sbapt.Va list . 3763279528SbaptThis is a list of symbol names separated by comma or colon characters. The 3764279528Sbaptsymbol names should not contain a leading underscore. This is only meaningful 3765279528Sbaptwhen 3766279528Sbapt.Op --export-all-symbols 3767279528Sbaptis used. 3768279528Sbapt.Pp 3769279528Sbapt.It --no-default-excludes 3770279528SbaptWhen 3771279528Sbapt.Op --export-all-symbols 3772279528Sbaptis used, it will by default avoid exporting certain special symbols. The current 3773279528Sbaptlist of symbols to avoid exporting is 3774279528Sbapt.Li DllMain@12 , 3775279528Sbapt.Li DllEntryPoint@0 , 3776279528Sbapt.Li impure_ptr . 3777279528SbaptYou may use the 3778279528Sbapt.Op --no-default-excludes 3779279528Sbaptoption to go ahead and export these special symbols. This is only meaningful 3780279528Sbaptwhen 3781279528Sbapt.Op --export-all-symbols 3782279528Sbaptis used. 3783279528Sbapt.Pp 3784279528Sbapt.It -S Va path 3785279528Sbapt.It --as Va path 3786279528SbaptSpecifies the path, including the filename, of the assembler to be used to 3787279528Sbaptcreate the exports file. 3788279528Sbapt.Pp 3789279528Sbapt.It -f Va options 3790279528Sbapt.It --as-flags Va options 3791279528SbaptSpecifies any specific command line options to be passed to the assembler 3792279528Sbaptwhen building the exports file. This option will work even if the 3793279528Sbapt.Op -S 3794279528Sbaptoption is not used. This option only takes one argument, and if it occurs 3795279528Sbaptmore than once on the command line, then later occurrences will override earlier 3796279528Sbaptoccurrences. So if it is necessary to pass multiple options to the assembler 3797279528Sbaptthey should be enclosed in double quotes. 3798279528Sbapt.Pp 3799279528Sbapt.It -D Va name 3800279528Sbapt.It --dll-name Va name 3801279528SbaptSpecifies the name to be stored in the 3802279528Sbapt.Pa .def 3803279528Sbaptfile as the name of the DLL when the 3804279528Sbapt.Op -e 3805279528Sbaptoption is used. If this option is not present, then the filename given to 3806279528Sbaptthe 3807279528Sbapt.Op -e 3808279528Sbaptoption will be used as the name of the DLL. 3809279528Sbapt.Pp 3810279528Sbapt.It -m Va machine 3811279528Sbapt.It -machine Va machine 3812279528SbaptSpecifies the type of machine for which the library file should be built. 3813279528Sbapt.Xr dlltool 3814279528Sbapthas a built in default type, depending upon how it was created, but this option 3815279528Sbaptcan be used to override that. This is normally only useful when creating DLLs 3816279528Sbaptfor an ARM processor, when the contents of the DLL are actually encode using 3817279528SbaptThumb instructions. 3818279528Sbapt.Pp 3819279528Sbapt.It -a 3820279528Sbapt.It --add-indirect 3821279528SbaptSpecifies that when 3822279528Sbapt.Xr dlltool 3823279528Sbaptis creating the exports file it should add a section which allows the exported 3824279528Sbaptfunctions to be referenced without using the import library. Whatever the 3825279528Sbapthell that means! 3826279528Sbapt.Pp 3827279528Sbapt.It -U 3828279528Sbapt.It --add-underscore 3829279528SbaptSpecifies that when 3830279528Sbapt.Xr dlltool 3831279528Sbaptis creating the exports file it should prepend an underscore to the names 3832279528Sbaptof 3833279528Sbapt.Em all 3834279528Sbaptexported symbols. 3835279528Sbapt.Pp 3836279528Sbapt.It --add-stdcall-underscore 3837279528SbaptSpecifies that when 3838279528Sbapt.Xr dlltool 3839279528Sbaptis creating the exports file it should prepend an underscore to the names 3840279528Sbaptof exported 3841279528Sbapt.Em stdcall 3842279528Sbaptfunctions. Variable names and non-stdcall function names are not modified. 3843279528SbaptThis option is useful when creating GNU-compatible import libs for third party 3844279528SbaptDLLs that were built with MS-Windows tools. 3845279528Sbapt.Pp 3846279528Sbapt.It -k 3847279528Sbapt.It --kill-at 3848279528SbaptSpecifies that when 3849279528Sbapt.Xr dlltool 3850279528Sbaptis creating the exports file it should not append the string 3851279528Sbapt.Li @ <number> . 3852279528SbaptThese numbers are called ordinal numbers and they represent another way of 3853279528Sbaptaccessing the function in a DLL, other than by name. 3854279528Sbapt.Pp 3855279528Sbapt.It -A 3856279528Sbapt.It --add-stdcall-alias 3857279528SbaptSpecifies that when 3858279528Sbapt.Xr dlltool 3859279528Sbaptis creating the exports file it should add aliases for stdcall symbols without 3860279528Sbapt.Li @ <number> 3861279528Sbaptin addition to the symbols with 3862279528Sbapt.Li @ <number> . 3863279528Sbapt.Pp 3864279528Sbapt.It -p 3865279528Sbapt.It --ext-prefix-alias Va prefix 3866279528SbaptCauses 3867279528Sbapt.Xr dlltool 3868279528Sbaptto create external aliases for all DLL imports with the specified prefix. 3869279528SbaptThe aliases are created for both external and import symbols with no leading 3870279528Sbaptunderscore. 3871279528Sbapt.Pp 3872279528Sbapt.It -x 3873279528Sbapt.It --no-idata4 3874279528SbaptSpecifies that when 3875279528Sbapt.Xr dlltool 3876279528Sbaptis creating the exports and library files it should omit the 3877279528Sbapt.Li .idata4 3878279528Sbaptsection. This is for compatibility with certain operating systems. 3879279528Sbapt.Pp 3880279528Sbapt.It -c 3881279528Sbapt.It --no-idata5 3882279528SbaptSpecifies that when 3883279528Sbapt.Xr dlltool 3884279528Sbaptis creating the exports and library files it should omit the 3885279528Sbapt.Li .idata5 3886279528Sbaptsection. This is for compatibility with certain operating systems. 3887279528Sbapt.Pp 3888279528Sbapt.It -i 3889279528Sbapt.It --interwork 3890279528SbaptSpecifies that 3891279528Sbapt.Xr dlltool 3892279528Sbaptshould mark the objects in the library file and exports file that it produces 3893279528Sbaptas supporting interworking between ARM and Thumb code. 3894279528Sbapt.Pp 3895279528Sbapt.It -n 3896279528Sbapt.It --nodelete 3897279528SbaptMakes 3898279528Sbapt.Xr dlltool 3899279528Sbaptpreserve the temporary assembler files it used to create the exports file. 3900279528SbaptIf this option is repeated then dlltool will also preserve the temporary object 3901279528Sbaptfiles it uses to create the library file. 3902279528Sbapt.Pp 3903279528Sbapt.It -t Va prefix 3904279528Sbapt.It --temp-prefix Va prefix 3905279528SbaptMakes 3906279528Sbapt.Xr dlltool 3907279528Sbaptuse 3908279528Sbapt.Va prefix 3909279528Sbaptwhen constructing the names of temporary assembler and object files. By default, 3910279528Sbaptthe temp file prefix is generated from the pid. 3911279528Sbapt.Pp 3912279528Sbapt.It -v 3913279528Sbapt.It --verbose 3914279528SbaptMake dlltool describe what it is doing. 3915279528Sbapt.Pp 3916279528Sbapt.It -h 3917279528Sbapt.It --help 3918279528SbaptDisplays a list of command line options and then exits. 3919279528Sbapt.Pp 3920279528Sbapt.It -V 3921279528Sbapt.It --version 3922279528SbaptDisplays dlltool's version number and then exits. 3923279528Sbapt.Pp 3924279528Sbapt.El 3925279528Sbapt.Ss The format of the Xr dlltool Pa .def file 3926279528SbaptA 3927279528Sbapt.Pa .def 3928279528Sbaptfile contains any number of the following commands: 3929279528Sbapt.Pp 3930279528Sbapt.Bl -tag -width Ds 3931279528Sbapt.It Li NAME Va name Li [ , Va base Li ] 3932279528SbaptThe result is going to be named 3933279528Sbapt.Va name 3934279528Sbapt.Li .exe . 3935279528Sbapt.Pp 3936279528Sbapt.It Li LIBRARY Va name Li [ , Va base Li ] 3937279528SbaptThe result is going to be named 3938279528Sbapt.Va name 3939279528Sbapt.Li .dll . 3940279528Sbapt.Pp 3941279528Sbapt.It Li EXPORTS ( ( ( Va name1 Li [ = Va name2 Li ] ) | ( Va name1 Li = Va module-name Li . Va external-name Li ) ) 3942279528Sbapt.It Li [ Va integer Li ] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) * 3943279528SbaptDeclares 3944279528Sbapt.Va name1 3945279528Sbaptas an exported symbol from the DLL, with optional ordinal number 3946279528Sbapt.Va integer , 3947279528Sbaptor declares 3948279528Sbapt.Va name1 3949279528Sbaptas an alias (forward) of the function 3950279528Sbapt.Va external-name 3951279528Sbaptin the DLL 3952279528Sbapt.Va module-name . 3953279528Sbapt.Pp 3954279528Sbapt.It Li IMPORTS ( ( Va internal-name Li = Va module-name Li . Va integer Li ) | [ Va internal-name Li = ] Va module-name Li . Va external-name Li ) ) * 3955279528SbaptDeclares that 3956279528Sbapt.Va external-name 3957279528Sbaptor the exported function whose ordinal number is 3958279528Sbapt.Va integer 3959279528Sbaptis to be imported from the file 3960279528Sbapt.Va module-name . 3961279528SbaptIf 3962279528Sbapt.Va internal-name 3963279528Sbaptis specified then this is the name that the imported function will be referred 3964279528Sbaptto in the body of the DLL. 3965279528Sbapt.Pp 3966279528Sbapt.It Li DESCRIPTION Va string 3967279528SbaptPuts 3968279528Sbapt.Va string 3969279528Sbaptinto the output 3970279528Sbapt.Pa .exp 3971279528Sbaptfile in the 3972279528Sbapt.Li .rdata 3973279528Sbaptsection. 3974279528Sbapt.Pp 3975279528Sbapt.It Li STACKSIZE Va number-reserve Li [, Va number-commit Li ] 3976279528Sbapt.It Li HEAPSIZE Va number-reserve Li [, Va number-commit Li ] 3977279528SbaptGenerates 3978279528Sbapt.Li --stack 3979279528Sbaptor 3980279528Sbapt.Li --heap 3981279528Sbapt.Va number-reserve 3982279528Sbapt, 3983279528Sbapt.Va number-commit 3984279528Sbaptin the output 3985279528Sbapt.Li .drectve 3986279528Sbaptsection. The linker will see this and act upon it. 3987279528Sbapt.Pp 3988279528Sbapt.It Li CODE Va attr Li + 3989279528Sbapt.It Li DATA Va attr Li + 3990279528Sbapt.It Li SECTIONS ( Va section-name Va attr Li + ) * 3991279528SbaptGenerates 3992279528Sbapt.Li --attr 3993279528Sbapt.Va section-name 3994279528Sbapt.Va attr 3995279528Sbaptin the output 3996279528Sbapt.Li .drectve 3997279528Sbaptsection, where 3998279528Sbapt.Va attr 3999279528Sbaptis one of 4000279528Sbapt.Li READ , 4001279528Sbapt.Li WRITE , 4002279528Sbapt.Li EXECUTE 4003279528Sbaptor 4004279528Sbapt.Li SHARED . 4005279528SbaptThe linker will see this and act upon it. 4006279528Sbapt.Pp 4007279528Sbapt.El 4008279528Sbapt.Sh readelf 4009279528Sbapt.Bd -literal -offset indent 4010279528Sbaptreadelf [-a|--all] 4011279528Sbapt [-h|--file-header] 4012279528Sbapt [-l|--program-headers|--segments] 4013279528Sbapt [-S|--section-headers|--sections] 4014279528Sbapt [-g|--section-groups] 4015279528Sbapt [-t|--section-details] 4016279528Sbapt [-e|--headers] 4017279528Sbapt [-s|--syms|--symbols] 4018279528Sbapt [-n|--notes] 4019279528Sbapt [-r|--relocs] 4020279528Sbapt [-u|--unwind] 4021279528Sbapt [-d|--dynamic] 4022279528Sbapt [-V|--version-info] 4023279528Sbapt [-A|--arch-specific] 4024279528Sbapt [-D|--use-dynamic] 4025279528Sbapt [-x <number or name>|--hex-dump=<number or name>] 4026279528Sbapt [-w[liaprmfFsoR]| 4027279528Sbapt --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]] 4028279528Sbapt [-I|-histogram] 4029279528Sbapt [-v|--version] 4030279528Sbapt [-W|--wide] 4031279528Sbapt [-H|--help] 4032279528Sbapt elffile... 4033279528Sbapt.Ed 4034279528Sbapt.Pp 4035279528Sbapt.Xr readelf 4036279528Sbaptdisplays information about one or more ELF format object files. The options 4037279528Sbaptcontrol what particular information to display. 4038279528Sbapt.Pp 4039279528Sbapt.Va elffile 4040279528Sbapt\&...are the object files to be examined. 32-bit and 64-bit ELF files are supported, 4041279528Sbaptas are archives containing ELF files. 4042279528Sbapt.Pp 4043279528SbaptThis program performs a similar function to 4044279528Sbapt.Xr objdump 4045279528Sbaptbut it goes into more detail and it exists independently of the bfd library, 4046279528Sbaptso if there is a bug in bfd then readelf will not be affected. 4047279528Sbapt.Pp 4048279528SbaptThe long and short forms of options, shown here as alternatives, are equivalent. 4049279528SbaptAt least one option besides 4050279528Sbapt.Li -v 4051279528Sbaptor 4052279528Sbapt.Li -H 4053279528Sbaptmust be given. 4054279528Sbapt.Pp 4055279528Sbapt.Bl -tag -width Ds 4056279528Sbapt.It -a 4057279528Sbapt.It --all 4058279528SbaptEquivalent to specifying 4059279528Sbapt.Op --file-header , 4060279528Sbapt.Op --program-headers , 4061279528Sbapt.Op --sections , 4062279528Sbapt.Op --symbols , 4063279528Sbapt.Op --relocs , 4064279528Sbapt.Op --dynamic , 4065279528Sbapt.Op --notes 4066279528Sbaptand 4067279528Sbapt.Op --version-info . 4068279528Sbapt.Pp 4069279528Sbapt.It -h 4070279528Sbapt.It --file-header 4071279528SbaptDisplays the information contained in the ELF header at the start of the file. 4072279528Sbapt.Pp 4073279528Sbapt.It -l 4074279528Sbapt.It --program-headers 4075279528Sbapt.It --segments 4076279528SbaptDisplays the information contained in the file's segment headers, if it has 4077279528Sbaptany. 4078279528Sbapt.Pp 4079279528Sbapt.It -S 4080279528Sbapt.It --sections 4081279528Sbapt.It --section-headers 4082279528SbaptDisplays the information contained in the file's section headers, if it has 4083279528Sbaptany. 4084279528Sbapt.Pp 4085279528Sbapt.It -g 4086279528Sbapt.It --section-groups 4087279528SbaptDisplays the information contained in the file's section groups, if it has 4088279528Sbaptany. 4089279528Sbapt.Pp 4090279528Sbapt.It -t 4091279528Sbapt.It --section-details 4092279528SbaptDisplays the detailed section information. Implies 4093279528Sbapt.Op -S . 4094279528Sbapt.Pp 4095279528Sbapt.It -s 4096279528Sbapt.It --symbols 4097279528Sbapt.It --syms 4098279528SbaptDisplays the entries in symbol table section of the file, if it has one. 4099279528Sbapt.Pp 4100279528Sbapt.It -e 4101279528Sbapt.It --headers 4102279528SbaptDisplay all the headers in the file. Equivalent to 4103279528Sbapt.Op -h -l -S . 4104279528Sbapt.Pp 4105279528Sbapt.It -n 4106279528Sbapt.It --notes 4107279528SbaptDisplays the contents of the NOTE segments and/or sections, if any. 4108279528Sbapt.Pp 4109279528Sbapt.It -r 4110279528Sbapt.It --relocs 4111279528SbaptDisplays the contents of the file's relocation section, if it has one. 4112279528Sbapt.Pp 4113279528Sbapt.It -u 4114279528Sbapt.It --unwind 4115279528SbaptDisplays the contents of the file's unwind section, if it has one. Only the 4116279528Sbaptunwind sections for IA64 ELF files are currently supported. 4117279528Sbapt.Pp 4118279528Sbapt.It -d 4119279528Sbapt.It --dynamic 4120279528SbaptDisplays the contents of the file's dynamic section, if it has one. 4121279528Sbapt.Pp 4122279528Sbapt.It -V 4123279528Sbapt.It --version-info 4124279528SbaptDisplays the contents of the version sections in the file, it they exist. 4125279528Sbapt.Pp 4126279528Sbapt.It -A 4127279528Sbapt.It --arch-specific 4128279528SbaptDisplays architecture-specific information in the file, if there is any. 4129279528Sbapt.Pp 4130279528Sbapt.It -D 4131279528Sbapt.It --use-dynamic 4132279528SbaptWhen displaying symbols, this option makes 4133279528Sbapt.Xr readelf 4134279528Sbaptuse the symbol table in the file's dynamic section, rather than the one in 4135279528Sbaptthe symbols section. 4136279528Sbapt.Pp 4137279528Sbapt.It -x <number or name> 4138279528Sbapt.It --hex-dump=<number or name> 4139279528SbaptDisplays the contents of the indicated section as a hexadecimal dump. A number 4140279528Sbaptidentifies a particular section by index in the section table; any other string 4141279528Sbaptidentifies all sections with that name in the object file. 4142279528Sbapt.Pp 4143279528Sbapt.It -w[liaprmfFsoR] 4144279528Sbapt.It --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges] 4145279528SbaptDisplays the contents of the debug sections in the file, if any are present. 4146279528SbaptIf one of the optional letters or words follows the switch then only data 4147279528Sbaptfound in those specific sections will be dumped. 4148279528Sbapt.Pp 4149279528Sbapt.It -I 4150279528Sbapt.It --histogram 4151279528SbaptDisplay a histogram of bucket list lengths when displaying the contents of 4152279528Sbaptthe symbol tables. 4153279528Sbapt.Pp 4154279528Sbapt.It -v 4155279528Sbapt.It --version 4156279528SbaptDisplay the version number of readelf. 4157279528Sbapt.Pp 4158279528Sbapt.It -W 4159279528Sbapt.It --wide 4160279528SbaptDon't break output lines to fit into 80 columns. By default 4161279528Sbapt.Xr readelf 4162279528Sbaptbreaks section header and segment listing lines for 64-bit ELF files, so that 4163279528Sbaptthey fit into 80 columns. This option causes 4164279528Sbapt.Xr readelf 4165279528Sbaptto print each section header resp. each segment one a single line, which is 4166279528Sbaptfar more readable on terminals wider than 80 columns. 4167279528Sbapt.Pp 4168279528Sbapt.It -H 4169279528Sbapt.It --help 4170279528SbaptDisplay the command line options understood by 4171279528Sbapt.Xr readelf . 4172279528Sbapt.Pp 4173279528Sbapt.El 4174279528Sbapt.Sh Common Options 4175279528SbaptThe following command-line options are supported by all of the programs described 4176279528Sbaptin this manual. 4177279528Sbapt.Pp 4178279528Sbapt.Bl -tag -width Ds 4179279528Sbapt.It @ Va file 4180279528SbaptRead command-line options from 4181279528Sbapt.Va file . 4182279528SbaptThe options read are inserted in place of the original @ 4183279528Sbapt.Va file 4184279528Sbaptoption. If 4185279528Sbapt.Va file 4186279528Sbaptdoes not exist, or cannot be read, then the option will be treated literally, 4187279528Sbaptand not removed. 4188279528Sbapt.Pp 4189279528SbaptOptions in 4190279528Sbapt.Va file 4191279528Sbaptare separated by whitespace. A whitespace character may be included in an 4192279528Sbaptoption by surrounding the entire option in either single or double quotes. 4193279528SbaptAny character (including a backslash) may be included by prefixing the character 4194279528Sbaptto be included with a backslash. The 4195279528Sbapt.Va file 4196279528Sbaptmay itself contain additional @ 4197279528Sbapt.Va file 4198279528Sbaptoptions; any such options will be processed recursively. 4199279528Sbapt.Pp 4200279528Sbapt.It --help 4201279528SbaptDisplay the command-line options supported by the program. 4202279528Sbapt.Pp 4203279528Sbapt.It --version 4204279528SbaptDisplay the version number of the program. 4205279528Sbapt.Pp 4206279528Sbapt.El 4207279528Sbapt.Sh Selecting the Target System 4208279528SbaptYou can specify two aspects of the target system to the GNU binary file utilities, 4209279528Sbapteach in several ways: 4210279528Sbapt.Pp 4211279528Sbapt.Bl -bullet 4212279528Sbapt.It 4213279528Sbaptthe target 4214279528Sbapt.Pp 4215279528Sbapt.It 4216279528Sbaptthe architecture 4217279528Sbapt.El 4218279528Sbapt.Pp 4219279528SbaptIn the following summaries, the lists of ways to specify values are in order 4220279528Sbaptof decreasing precedence. The ways listed first override those listed later. 4221279528Sbapt.Pp 4222279528SbaptThe commands to list valid values only list the values for which the programs 4223279528Sbaptyou are running were configured. If they were configured with 4224279528Sbapt.Op --enable-targets=all , 4225279528Sbaptthe commands list most of the available values, but a few are left out; not 4226279528Sbaptall targets can be configured in at once because some of them can only be 4227279528Sbaptconfigured 4228279528Sbapt.Em native 4229279528Sbapt(on hosts with the same type as the target system). 4230279528Sbapt.Pp 4231279528Sbapt.Ss Target Selection 4232279528SbaptA 4233279528Sbapt.Em target 4234279528Sbaptis an object file format. A given target may be supported for multiple architectures 4235279528Sbapt(see Section 4236279528Sbapt.Dq Architecture Selection ) . 4237279528SbaptA target selection may also have variations for different operating systems 4238279528Sbaptor architectures. 4239279528Sbapt.Pp 4240279528SbaptThe command to list valid target values is 4241279528Sbapt.Li objdump -i 4242279528Sbapt(the first column of output contains the relevant information). 4243279528Sbapt.Pp 4244279528SbaptSome sample values are: 4245279528Sbapt.Li a.out-hp300bsd , 4246279528Sbapt.Li ecoff-littlemips , 4247279528Sbapt.Li a.out-sunos-big . 4248279528Sbapt.Pp 4249279528SbaptYou can also specify a target using a configuration triplet. This is the same 4250279528Sbaptsort of name that is passed to 4251279528Sbapt.Pa configure 4252279528Sbaptto specify a target. When you use a configuration triplet as an argument, 4253279528Sbaptit must be fully canonicalized. You can see the canonical version of a triplet 4254279528Sbaptby running the shell script 4255279528Sbapt.Pa config.sub 4256279528Sbaptwhich is included with the sources. 4257279528Sbapt.Pp 4258279528SbaptSome sample configuration triplets are: 4259279528Sbapt.Li m68k-hp-bsd , 4260279528Sbapt.Li mips-dec-ultrix , 4261279528Sbapt.Li sparc-sun-sunos . 4262279528Sbapt.Pp 4263279528Sbapt.Em Xr objdump Target 4264279528Sbapt.Pp 4265279528SbaptWays to specify: 4266279528Sbapt.Pp 4267279528Sbapt.Bl -enum 4268279528Sbapt.It 4269279528Sbaptcommand line option: 4270279528Sbapt.Op -b 4271279528Sbaptor 4272279528Sbapt.Op --target 4273279528Sbapt.Pp 4274279528Sbapt.It 4275279528Sbaptenvironment variable 4276279528Sbapt.Li GNUTARGET 4277279528Sbapt.Pp 4278279528Sbapt.It 4279279528Sbaptdeduced from the input file 4280279528Sbapt.El 4281279528Sbapt.Pp 4282279528Sbapt.Em Xr objcopy and Xr strip Input Target 4283279528Sbapt.Pp 4284279528SbaptWays to specify: 4285279528Sbapt.Pp 4286279528Sbapt.Bl -enum 4287279528Sbapt.It 4288279528Sbaptcommand line options: 4289279528Sbapt.Op -I 4290279528Sbaptor 4291279528Sbapt.Op --input-target , 4292279528Sbaptor 4293279528Sbapt.Op -F 4294279528Sbaptor 4295279528Sbapt.Op --target 4296279528Sbapt.Pp 4297279528Sbapt.It 4298279528Sbaptenvironment variable 4299279528Sbapt.Li GNUTARGET 4300279528Sbapt.Pp 4301279528Sbapt.It 4302279528Sbaptdeduced from the input file 4303279528Sbapt.El 4304279528Sbapt.Pp 4305279528Sbapt.Em Xr objcopy and Xr strip Output Target 4306279528Sbapt.Pp 4307279528SbaptWays to specify: 4308279528Sbapt.Pp 4309279528Sbapt.Bl -enum 4310279528Sbapt.It 4311279528Sbaptcommand line options: 4312279528Sbapt.Op -O 4313279528Sbaptor 4314279528Sbapt.Op --output-target , 4315279528Sbaptor 4316279528Sbapt.Op -F 4317279528Sbaptor 4318279528Sbapt.Op --target 4319279528Sbapt.Pp 4320279528Sbapt.It 4321279528Sbaptthe input target (see \(lq 4322279528Sbapt.Xr objcopy 4323279528Sbaptand 4324279528Sbapt.Xr strip 4325279528SbaptInput Target\(rq above) 4326279528Sbapt.Pp 4327279528Sbapt.It 4328279528Sbaptenvironment variable 4329279528Sbapt.Li GNUTARGET 4330279528Sbapt.Pp 4331279528Sbapt.It 4332279528Sbaptdeduced from the input file 4333279528Sbapt.El 4334279528Sbapt.Pp 4335279528Sbapt.Em Xr nm, Xr size, and Xr strings Target 4336279528Sbapt.Pp 4337279528SbaptWays to specify: 4338279528Sbapt.Pp 4339279528Sbapt.Bl -enum 4340279528Sbapt.It 4341279528Sbaptcommand line option: 4342279528Sbapt.Op --target 4343279528Sbapt.Pp 4344279528Sbapt.It 4345279528Sbaptenvironment variable 4346279528Sbapt.Li GNUTARGET 4347279528Sbapt.Pp 4348279528Sbapt.It 4349279528Sbaptdeduced from the input file 4350279528Sbapt.El 4351279528Sbapt.Pp 4352279528Sbapt.Ss Architecture Selection 4353279528SbaptAn 4354279528Sbapt.Em architecture 4355279528Sbaptis a type of cpu on which an object file is to run. Its name may contain a 4356279528Sbaptcolon, separating the name of the processor family from the name of the particular 4357279528Sbaptcpu. 4358279528Sbapt.Pp 4359279528SbaptThe command to list valid architecture values is 4360279528Sbapt.Li objdump -i 4361279528Sbapt(the second column contains the relevant information). 4362279528Sbapt.Pp 4363279528SbaptSample values: 4364279528Sbapt.Li m68k:68020 , 4365279528Sbapt.Li mips:3000 , 4366279528Sbapt.Li sparc . 4367279528Sbapt.Pp 4368279528Sbapt.Em Xr objdump Architecture 4369279528Sbapt.Pp 4370279528SbaptWays to specify: 4371279528Sbapt.Pp 4372279528Sbapt.Bl -enum 4373279528Sbapt.It 4374279528Sbaptcommand line option: 4375279528Sbapt.Op -m 4376279528Sbaptor 4377279528Sbapt.Op --architecture 4378279528Sbapt.Pp 4379279528Sbapt.It 4380279528Sbaptdeduced from the input file 4381279528Sbapt.El 4382279528Sbapt.Pp 4383279528Sbapt.Em Xr objcopy, Xr nm, Xr size, Xr strings Architecture 4384279528Sbapt.Pp 4385279528SbaptWays to specify: 4386279528Sbapt.Pp 4387279528Sbapt.Bl -enum 4388279528Sbapt.It 4389279528Sbaptdeduced from the input file 4390279528Sbapt.El 4391279528Sbapt.Pp 4392279528Sbapt.Sh Reporting Bugs 4393279528SbaptYour bug reports play an essential role in making the binary utilities reliable. 4394279528Sbapt.Pp 4395279528SbaptReporting a bug may help you by bringing a solution to your problem, or it 4396279528Sbaptmay not. But in any case the principal function of a bug report is to help 4397279528Sbaptthe entire community by making the next version of the binary utilities work 4398279528Sbaptbetter. Bug reports are your contribution to their maintenance. 4399279528Sbapt.Pp 4400279528SbaptIn order for a bug report to serve its purpose, you must include the information 4401279528Sbaptthat enables us to fix the bug. 4402279528Sbapt.Pp 4403279528Sbapt.Ss Have You Found a Bug? 4404279528SbaptIf you are not sure whether you have found a bug, here are some guidelines: 4405279528Sbapt.Pp 4406279528Sbapt.Bl -bullet 4407279528Sbapt.It 4408279528SbaptIf a binary utility gets a fatal signal, for any input whatever, that is a 4409279528Sbaptbug. Reliable utilities never crash. 4410279528Sbapt.Pp 4411279528Sbapt.It 4412279528SbaptIf a binary utility produces an error message for valid input, that is a bug. 4413279528Sbapt.Pp 4414279528Sbapt.It 4415279528SbaptIf you are an experienced user of binary utilities, your suggestions for improvement 4416279528Sbaptare welcome in any case. 4417279528Sbapt.El 4418279528Sbapt.Pp 4419279528Sbapt.Ss How to Report Bugs 4420279528SbaptA number of companies and individuals offer support for GNU products. If you 4421279528Sbaptobtained the binary utilities from a support organization, we recommend you 4422279528Sbaptcontact that organization first. 4423279528Sbapt.Pp 4424279528SbaptYou can find contact information for many support companies and individuals 4425279528Sbaptin the file 4426279528Sbapt.Pa etc/SERVICE 4427279528Sbaptin the GNU Emacs distribution. 4428279528Sbapt.Pp 4429279528SbaptThe fundamental principle of reporting bugs usefully is this: 4430279528Sbapt.Sy report all the facts . 4431279528SbaptIf you are not sure whether to state a fact or leave it out, state it! 4432279528Sbapt.Pp 4433279528SbaptOften people omit facts because they think they know what causes the problem 4434279528Sbaptand assume that some details do not matter. Thus, you might assume that the 4435279528Sbaptname of a file you use in an example does not matter. Well, probably it does 4436279528Sbaptnot, but one cannot be sure. Perhaps the bug is a stray memory reference which 4437279528Sbapthappens to fetch from the location where that pathname is stored in memory; 4438279528Sbaptperhaps, if the pathname were different, the contents of that location would 4439279528Sbaptfool the utility into doing the right thing despite the bug. Play it safe 4440279528Sbaptand give a specific, complete example. That is the easiest thing for you to 4441279528Sbaptdo, and the most helpful. 4442279528Sbapt.Pp 4443279528SbaptKeep in mind that the purpose of a bug report is to enable us to fix the bug 4444279528Sbaptif it is new to us. Therefore, always write your bug reports on the assumption 4445279528Sbaptthat the bug has not been reported previously. 4446279528Sbapt.Pp 4447279528SbaptSometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq 4448279528SbaptThis cannot help us fix a bug, so it is basically useless. We respond by asking 4449279528Sbaptfor enough details to enable us to investigate. You might as well expedite 4450279528Sbaptmatters by sending them to begin with. 4451279528Sbapt.Pp 4452279528SbaptTo enable us to fix the bug, you should include all these things: 4453279528Sbapt.Pp 4454279528Sbapt.Bl -bullet 4455279528Sbapt.It 4456279528SbaptThe version of the utility. Each utility announces it if you start it with 4457279528Sbaptthe 4458279528Sbapt.Op --version 4459279528Sbaptargument. 4460279528Sbapt.Pp 4461279528SbaptWithout this, we will not know whether there is any point in looking for the 4462279528Sbaptbug in the current version of the binary utilities. 4463279528Sbapt.Pp 4464279528Sbapt.It 4465279528SbaptAny patches you may have applied to the source, including any patches made 4466279528Sbaptto the 4467279528Sbapt.Li BFD 4468279528Sbaptlibrary. 4469279528Sbapt.Pp 4470279528Sbapt.It 4471279528SbaptThe type of machine you are using, and the operating system name and version 4472279528Sbaptnumber. 4473279528Sbapt.Pp 4474279528Sbapt.It 4475279528SbaptWhat compiler (and its version) was used to compile the utilities---e.g. \(lq 4476279528Sbapt.Li gcc-2.7 4477279528Sbapt\(rq\&. 4478279528Sbapt.Pp 4479279528Sbapt.It 4480279528SbaptThe command arguments you gave the utility to observe the bug. To guarantee 4481279528Sbaptyou will not omit something important, list them all. A copy of the Makefile 4482279528Sbapt(or the output from make) is sufficient. 4483279528Sbapt.Pp 4484279528SbaptIf we were to try to guess the arguments, we would probably guess wrong and 4485279528Sbaptthen we might not encounter the bug. 4486279528Sbapt.Pp 4487279528Sbapt.It 4488279528SbaptA complete input file, or set of input files, that will reproduce the bug. 4489279528SbaptIf the utility is reading an object file or files, then it is generally most 4490279528Sbapthelpful to send the actual object files. 4491279528Sbapt.Pp 4492279528SbaptIf the source files were produced exclusively using GNU programs (e.g., 4493279528Sbapt.Xr gcc , 4494279528Sbapt.Xr gas , 4495279528Sbaptand/or the GNU 4496279528Sbapt.Xr ld ) , 4497279528Sbaptthen it may be OK to send the source files rather than the object files. In 4498279528Sbaptthis case, be sure to say exactly what version of 4499279528Sbapt.Xr gcc , 4500279528Sbaptor whatever, was used to produce the object files. Also say how 4501279528Sbapt.Xr gcc , 4502279528Sbaptor whatever, was configured. 4503279528Sbapt.Pp 4504279528Sbapt.It 4505279528SbaptA description of what behavior you observe that you believe is incorrect. 4506279528SbaptFor example, \(lqIt gets a fatal signal.\(rq 4507279528Sbapt.Pp 4508279528SbaptOf course, if the bug is that the utility gets a fatal signal, then we will 4509279528Sbaptcertainly notice it. But if the bug is incorrect output, we might not notice 4510279528Sbaptunless it is glaringly wrong. You might as well not give us a chance to make 4511279528Sbapta mistake. 4512279528Sbapt.Pp 4513279528SbaptEven if the problem you experience is a fatal signal, you should still say 4514279528Sbaptso explicitly. Suppose something strange is going on, such as your copy of 4515279528Sbaptthe utility is out of sync, or you have encountered a bug in the C library 4516279528Sbapton your system. (This has happened!) Your copy might crash and ours would 4517279528Sbaptnot. If you told us to expect a crash, then when ours fails to crash, we would 4518279528Sbaptknow that the bug was not happening for us. If you had not told us to expect 4519279528Sbapta crash, then we would not be able to draw any conclusion from our observations. 4520279528Sbapt.Pp 4521279528Sbapt.It 4522279528SbaptIf you wish to suggest changes to the source, send us context diffs, as generated 4523279528Sbaptby 4524279528Sbapt.Xr diff 4525279528Sbaptwith the 4526279528Sbapt.Op -u , 4527279528Sbapt.Op -c , 4528279528Sbaptor 4529279528Sbapt.Op -p 4530279528Sbaptoption. Always send diffs from the old file to the new file. If you wish to 4531279528Sbaptdiscuss something in the 4532279528Sbapt.Xr ld 4533279528Sbaptsource, refer to it by context, not by line number. 4534279528Sbapt.Pp 4535279528SbaptThe line numbers in our development sources will not match those in your sources. 4536279528SbaptYour line numbers would convey no useful information to us. 4537279528Sbapt.El 4538279528Sbapt.Pp 4539279528SbaptHere are some things that are not necessary: 4540279528Sbapt.Pp 4541279528Sbapt.Bl -bullet 4542279528Sbapt.It 4543279528SbaptA description of the envelope of the bug. 4544279528Sbapt.Pp 4545279528SbaptOften people who encounter a bug spend a lot of time investigating which changes 4546279528Sbaptto the input file will make the bug go away and which changes will not affect 4547279528Sbaptit. 4548279528Sbapt.Pp 4549279528SbaptThis is often time consuming and not very useful, because the way we will 4550279528Sbaptfind the bug is by running a single example under the debugger with breakpoints, 4551279528Sbaptnot by pure deduction from a series of examples. We recommend that you save 4552279528Sbaptyour time for something else. 4553279528Sbapt.Pp 4554279528SbaptOf course, if you can find a simpler example to report 4555279528Sbapt.Em instead 4556279528Sbaptof the original one, that is a convenience for us. Errors in the output will 4557279528Sbaptbe easier to spot, running under the debugger will take less time, and so 4558279528Sbapton. 4559279528Sbapt.Pp 4560279528SbaptHowever, simplification is not vital; if you do not want to do this, report 4561279528Sbaptthe bug anyway and send us the entire test case you used. 4562279528Sbapt.Pp 4563279528Sbapt.It 4564279528SbaptA patch for the bug. 4565279528Sbapt.Pp 4566279528SbaptA patch for the bug does help us if it is a good one. But do not omit the 4567279528Sbaptnecessary information, such as the test case, on the assumption that a patch 4568279528Sbaptis all we need. We might see problems with your patch and decide to fix the 4569279528Sbaptproblem another way, or we might not understand it at all. 4570279528Sbapt.Pp 4571279528SbaptSometimes with programs as complicated as the binary utilities it is very 4572279528Sbapthard to construct an example that will make the program follow a certain path 4573279528Sbaptthrough the code. If you do not send us the example, we will not be able to 4574279528Sbaptconstruct one, so we will not be able to verify that the bug is fixed. 4575279528Sbapt.Pp 4576279528SbaptAnd if we cannot understand what bug you are trying to fix, or why your patch 4577279528Sbaptshould be an improvement, we will not install it. A test case will help us 4578279528Sbaptto understand. 4579279528Sbapt.Pp 4580279528Sbapt.It 4581279528SbaptA guess about what the bug is or what it depends on. 4582279528Sbapt.Pp 4583279528SbaptSuch guesses are usually wrong. Even we cannot guess right about such things 4584279528Sbaptwithout first using the debugger to find the facts. 4585279528Sbapt.El 4586279528Sbapt.Pp 4587279528Sbapt.Sh GNU Free Documentation License 4588279528Sbapt.Bd -filled -offset indent 4589279528SbaptCopyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, 4590279528SbaptFifth Floor, Boston, MA 02110-1301 USA 4591279528Sbapt.Pp 4592279528SbaptEveryone is permitted to copy and distribute verbatim copies of this license 4593279528Sbaptdocument, but changing it is not allowed. 4594279528Sbapt.Ed 4595279528Sbapt.Pp 4596279528Sbapt.Bl -enum 4597279528Sbapt.It 4598279528SbaptPREAMBLE 4599279528Sbapt.Pp 4600279528SbaptThe purpose of this License is to make a manual, textbook, or other written 4601279528Sbaptdocument \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom 4602279528Sbaptto copy and redistribute it, with or without modifying it, either commercially 4603279528Sbaptor noncommercially. Secondarily, this License preserves for the author and 4604279528Sbaptpublisher a way to get credit for their work, while not being considered responsible 4605279528Sbaptfor modifications made by others. 4606279528Sbapt.Pp 4607279528SbaptThis License is a kind of \(lqcopyleft\(rq, which means that derivative works of the 4608279528Sbaptdocument must themselves be free in the same sense. It complements the GNU 4609279528SbaptGeneral Public License, which is a copyleft license designed for free software. 4610279528Sbapt.Pp 4611279528SbaptWe have designed this License in order to use it for manuals for free software, 4612279528Sbaptbecause free software needs free documentation: a free program should come 4613279528Sbaptwith manuals providing the same freedoms that the software does. But this 4614279528SbaptLicense is not limited to software manuals; it can be used for any textual 4615279528Sbaptwork, regardless of subject matter or whether it is published as a printed 4616279528Sbaptbook. We recommend this License principally for works whose purpose is instruction 4617279528Sbaptor reference. 4618279528Sbapt.Pp 4619279528Sbapt.It 4620279528SbaptAPPLICABILITY AND DEFINITIONS 4621279528Sbapt.Pp 4622279528SbaptThis License applies to any manual or other work that contains a notice placed 4623279528Sbaptby the copyright holder saying it can be distributed under the terms of this 4624279528SbaptLicense. The \(lqDocument\(rq, below, refers to any such manual or work. Any member 4625279528Sbaptof the public is a licensee, and is addressed as \(lqyou.\(rq 4626279528Sbapt.Pp 4627279528SbaptA \(lqModified Version\(rq of the Document means any work containing the Document 4628279528Sbaptor a portion of it, either copied verbatim, or with modifications and/or translated 4629279528Sbaptinto another language. 4630279528Sbapt.Pp 4631279528SbaptA \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document 4632279528Sbaptthat deals exclusively with the relationship of the publishers or authors 4633279528Sbaptof the Document to the Document's overall subject (or to related matters) 4634279528Sbaptand contains nothing that could fall directly within that overall subject. 4635279528Sbapt(For example, if the Document is in part a textbook of mathematics, a Secondary 4636279528SbaptSection may not explain any mathematics.) The relationship could be a matter 4637279528Sbaptof historical connection with the subject or with related matters, or of legal, 4638279528Sbaptcommercial, philosophical, ethical or political position regarding them. 4639279528Sbapt.Pp 4640279528SbaptThe \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, 4641279528Sbaptas being those of Invariant Sections, in the notice that says that the Document 4642279528Sbaptis released under this License. 4643279528Sbapt.Pp 4644279528SbaptThe \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover 4645279528SbaptTexts or Back-Cover Texts, in the notice that says that the Document is released 4646279528Sbaptunder this License. 4647279528Sbapt.Pp 4648279528SbaptA \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented 4649279528Sbaptin a format whose specification is available to the general public, whose 4650279528Sbaptcontents can be viewed and edited directly and straightforwardly with generic 4651279528Sbapttext editors or (for images composed of pixels) generic paint programs or 4652279528Sbapt(for drawings) some widely available drawing editor, and that is suitable 4653279528Sbaptfor input to text formatters or for automatic translation to a variety of 4654279528Sbaptformats suitable for input to text formatters. A copy made in an otherwise 4655279528SbaptTransparent file format whose markup has been designed to thwart or discourage 4656279528Sbaptsubsequent modification by readers is not Transparent. A copy that is not 4657279528Sbapt\(lqTransparent\(rq is called \(lqOpaque.\(rq 4658279528Sbapt.Pp 4659279528SbaptExamples of suitable formats for Transparent copies include plain ASCII without 4660279528Sbaptmarkup, Texinfo input format, LaTeX input format, SGML or XML using a publicly 4661279528Sbaptavailable DTD, and standard-conforming simple HTML designed for human modification. 4662279528SbaptOpaque formats include PostScript, PDF, proprietary formats that can be read 4663279528Sbaptand edited only by proprietary word processors, SGML or XML for which the 4664279528SbaptDTD and/or processing tools are not generally available, and the machine-generated 4665279528SbaptHTML produced by some word processors for output purposes only. 4666279528Sbapt.Pp 4667279528SbaptThe \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such 4668279528Sbaptfollowing pages as are needed to hold, legibly, the material this License 4669279528Sbaptrequires to appear in the title page. For works in formats which do not have 4670279528Sbaptany title page as such, \(lqTitle Page\(rq means the text near the most prominent 4671279528Sbaptappearance of the work's title, preceding the beginning of the body of the 4672279528Sbapttext. 4673279528Sbapt.Pp 4674279528Sbapt.It 4675279528SbaptVERBATIM COPYING 4676279528Sbapt.Pp 4677279528SbaptYou may copy and distribute the Document in any medium, either commercially 4678279528Sbaptor noncommercially, provided that this License, the copyright notices, and 4679279528Sbaptthe license notice saying this License applies to the Document are reproduced 4680279528Sbaptin all copies, and that you add no other conditions whatsoever to those of 4681279528Sbaptthis License. You may not use technical measures to obstruct or control the 4682279528Sbaptreading or further copying of the copies you make or distribute. However, 4683279528Sbaptyou may accept compensation in exchange for copies. If you distribute a large 4684279528Sbaptenough number of copies you must also follow the conditions in section 3. 4685279528Sbapt.Pp 4686279528SbaptYou may also lend copies, under the same conditions stated above, and you 4687279528Sbaptmay publicly display copies. 4688279528Sbapt.Pp 4689279528Sbapt.It 4690279528SbaptCOPYING IN QUANTITY 4691279528Sbapt.Pp 4692279528SbaptIf you publish printed copies of the Document numbering more than 100, and 4693279528Sbaptthe Document's license notice requires Cover Texts, you must enclose the copies 4694279528Sbaptin covers that carry, clearly and legibly, all these Cover Texts: Front-Cover 4695279528SbaptTexts on the front cover, and Back-Cover Texts on the back cover. Both covers 4696279528Sbaptmust also clearly and legibly identify you as the publisher of these copies. 4697279528SbaptThe front cover must present the full title with all words of the title equally 4698279528Sbaptprominent and visible. You may add other material on the covers in addition. 4699279528SbaptCopying with changes limited to the covers, as long as they preserve the title 4700279528Sbaptof the Document and satisfy these conditions, can be treated as verbatim copying 4701279528Sbaptin other respects. 4702279528Sbapt.Pp 4703279528SbaptIf the required texts for either cover are too voluminous to fit legibly, 4704279528Sbaptyou should put the first ones listed (as many as fit reasonably) on the actual 4705279528Sbaptcover, and continue the rest onto adjacent pages. 4706279528Sbapt.Pp 4707279528SbaptIf you publish or distribute Opaque copies of the Document numbering more 4708279528Sbaptthan 100, you must either include a machine-readable Transparent copy along 4709279528Sbaptwith each Opaque copy, or state in or with each Opaque copy a publicly-accessible 4710279528Sbaptcomputer-network location containing a complete Transparent copy of the Document, 4711279528Sbaptfree of added material, which the general network-using public has access 4712279528Sbaptto download anonymously at no charge using public-standard network protocols. 4713279528SbaptIf you use the latter option, you must take reasonably prudent steps, when 4714279528Sbaptyou begin distribution of Opaque copies in quantity, to ensure that this Transparent 4715279528Sbaptcopy will remain thus accessible at the stated location until at least one 4716279528Sbaptyear after the last time you distribute an Opaque copy (directly or through 4717279528Sbaptyour agents or retailers) of that edition to the public. 4718279528Sbapt.Pp 4719279528SbaptIt is requested, but not required, that you contact the authors of the Document 4720279528Sbaptwell before redistributing any large number of copies, to give them a chance 4721279528Sbaptto provide you with an updated version of the Document. 4722279528Sbapt.Pp 4723279528Sbapt.It 4724279528SbaptMODIFICATIONS 4725279528Sbapt.Pp 4726279528SbaptYou may copy and distribute a Modified Version of the Document under the conditions 4727279528Sbaptof sections 2 and 3 above, provided that you release the Modified Version 4728279528Sbaptunder precisely this License, with the Modified Version filling the role of 4729279528Sbaptthe Document, thus licensing distribution and modification of the Modified 4730279528SbaptVersion to whoever possesses a copy of it. In addition, you must do these 4731279528Sbaptthings in the Modified Version: 4732279528Sbapt.Pp 4733279528SbaptA. Use in the Title Page (and on the covers, if any) a title distinct from 4734279528Sbaptthat of the Document, and from those of previous versions (which should, if 4735279528Sbaptthere were any, be listed in the History section of the Document). You may 4736279528Sbaptuse the same title as a previous version if the original publisher of that 4737279528Sbaptversion gives permission. B. List on the Title Page, as authors, one or more 4738279528Sbaptpersons or entities responsible for authorship of the modifications in the 4739279528SbaptModified Version, together with at least five of the principal authors of 4740279528Sbaptthe Document (all of its principal authors, if it has less than five). C. 4741279528SbaptState on the Title page the name of the publisher of the Modified Version, 4742279528Sbaptas the publisher. D. Preserve all the copyright notices of the Document. 4743279528SbaptE. Add an appropriate copyright notice for your modifications adjacent to 4744279528Sbaptthe other copyright notices. F. Include, immediately after the copyright 4745279528Sbaptnotices, a license notice giving the public permission to use the Modified 4746279528SbaptVersion under the terms of this License, in the form shown in the Addendum 4747279528Sbaptbelow. G. Preserve in that license notice the full lists of Invariant Sections 4748279528Sbaptand required Cover Texts given in the Document's license notice. H. Include 4749279528Sbaptan unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, 4750279528Sbaptand its title, and add to it an item stating at least the title, year, new 4751279528Sbaptauthors, and publisher of the Modified Version as given on the Title Page. 4752279528SbaptIf there is no section entitled \(lqHistory\(rq in the Document, create one stating 4753279528Sbaptthe title, year, authors, and publisher of the Document as given on its Title 4754279528SbaptPage, then add an item describing the Modified Version as stated in the previous 4755279528Sbaptsentence. J. Preserve the network location, if any, given in the Document 4756279528Sbaptfor public access to a Transparent copy of the Document, and likewise the 4757279528Sbaptnetwork locations given in the Document for previous versions it was based 4758279528Sbapton. These may be placed in the \(lqHistory\(rq section. You may omit a network location 4759279528Sbaptfor a work that was published at least four years before the Document itself, 4760279528Sbaptor if the original publisher of the version it refers to gives permission. 4761279528SbaptK. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's 4762279528Sbapttitle, and preserve in the section all the substance and tone of each of the 4763279528Sbaptcontributor acknowledgements and/or dedications given therein. L. Preserve 4764279528Sbaptall the Invariant Sections of the Document, unaltered in their text and in 4765279528Sbapttheir titles. Section numbers or the equivalent are not considered part of 4766279528Sbaptthe section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section 4767279528Sbaptmay not be included in the Modified Version. N. Do not retitle any existing 4768279528Sbaptsection as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. 4769279528Sbapt.Pp 4770279528SbaptIf the Modified Version includes new front-matter sections or appendices that 4771279528Sbaptqualify as Secondary Sections and contain no material copied from the Document, 4772279528Sbaptyou may at your option designate some or all of these sections as invariant. 4773279528SbaptTo do this, add their titles to the list of Invariant Sections in the Modified 4774279528SbaptVersion's license notice. These titles must be distinct from any other section 4775279528Sbapttitles. 4776279528Sbapt.Pp 4777279528SbaptYou may add a section entitled \(lqEndorsements\(rq, provided it contains nothing 4778279528Sbaptbut endorsements of your Modified Version by various parties--for example, 4779279528Sbaptstatements of peer review or that the text has been approved by an organization 4780279528Sbaptas the authoritative definition of a standard. 4781279528Sbapt.Pp 4782279528SbaptYou may add a passage of up to five words as a Front-Cover Text, and a passage 4783279528Sbaptof up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts 4784279528Sbaptin the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover 4785279528SbaptText may be added by (or through arrangements made by) any one entity. If 4786279528Sbaptthe Document already includes a cover text for the same cover, previously 4787279528Sbaptadded by you or by arrangement made by the same entity you are acting on behalf 4788279528Sbaptof, you may not add another; but you may replace the old one, on explicit 4789279528Sbaptpermission from the previous publisher that added the old one. 4790279528Sbapt.Pp 4791279528SbaptThe author(s) and publisher(s) of the Document do not by this License give 4792279528Sbaptpermission to use their names for publicity for or to assert or imply endorsement 4793279528Sbaptof any Modified Version. 4794279528Sbapt.Pp 4795279528Sbapt.It 4796279528SbaptCOMBINING DOCUMENTS 4797279528Sbapt.Pp 4798279528SbaptYou may combine the Document with other documents released under this License, 4799279528Sbaptunder the terms defined in section 4 above for modified versions, provided 4800279528Sbaptthat you include in the combination all of the Invariant Sections of all of 4801279528Sbaptthe original documents, unmodified, and list them all as Invariant Sections 4802279528Sbaptof your combined work in its license notice. 4803279528Sbapt.Pp 4804279528SbaptThe combined work need only contain one copy of this License, and multiple 4805279528Sbaptidentical Invariant Sections may be replaced with a single copy. If there 4806279528Sbaptare multiple Invariant Sections with the same name but different contents, 4807279528Sbaptmake the title of each such section unique by adding at the end of it, in 4808279528Sbaptparentheses, the name of the original author or publisher of that section 4809279528Sbaptif known, or else a unique number. Make the same adjustment to the section 4810279528Sbapttitles in the list of Invariant Sections in the license notice of the combined 4811279528Sbaptwork. 4812279528Sbapt.Pp 4813279528SbaptIn the combination, you must combine any sections entitled \(lqHistory\(rq in the 4814279528Sbaptvarious original documents, forming one section entitled \(lqHistory\(rq; likewise 4815279528Sbaptcombine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled 4816279528Sbapt\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq 4817279528Sbapt.Pp 4818279528Sbapt.It 4819279528SbaptCOLLECTIONS OF DOCUMENTS 4820279528Sbapt.Pp 4821279528SbaptYou may make a collection consisting of the Document and other documents released 4822279528Sbaptunder this License, and replace the individual copies of this License in the 4823279528Sbaptvarious documents with a single copy that is included in the collection, provided 4824279528Sbaptthat you follow the rules of this License for verbatim copying of each of 4825279528Sbaptthe documents in all other respects. 4826279528Sbapt.Pp 4827279528SbaptYou may extract a single document from such a collection, and distribute it 4828279528Sbaptindividually under this License, provided you insert a copy of this License 4829279528Sbaptinto the extracted document, and follow this License in all other respects 4830279528Sbaptregarding verbatim copying of that document. 4831279528Sbapt.Pp 4832279528Sbapt.It 4833279528SbaptAGGREGATION WITH INDEPENDENT WORKS 4834279528Sbapt.Pp 4835279528SbaptA compilation of the Document or its derivatives with other separate and independent 4836279528Sbaptdocuments or works, in or on a volume of a storage or distribution medium, 4837279528Sbaptdoes not as a whole count as a Modified Version of the Document, provided 4838279528Sbaptno compilation copyright is claimed for the compilation. Such a compilation 4839279528Sbaptis called an \(lqaggregate\(rq, and this License does not apply to the other self-contained 4840279528Sbaptworks thus compiled with the Document, on account of their being thus compiled, 4841279528Sbaptif they are not themselves derivative works of the Document. 4842279528Sbapt.Pp 4843279528SbaptIf the Cover Text requirement of section 3 is applicable to these copies of 4844279528Sbaptthe Document, then if the Document is less than one quarter of the entire 4845279528Sbaptaggregate, the Document's Cover Texts may be placed on covers that surround 4846279528Sbaptonly the Document within the aggregate. Otherwise they must appear on covers 4847279528Sbaptaround the whole aggregate. 4848279528Sbapt.Pp 4849279528Sbapt.It 4850279528SbaptTRANSLATION 4851279528Sbapt.Pp 4852279528SbaptTranslation is considered a kind of modification, so you may distribute translations 4853279528Sbaptof the Document under the terms of section 4. Replacing Invariant Sections 4854279528Sbaptwith translations requires special permission from their copyright holders, 4855279528Sbaptbut you may include translations of some or all Invariant Sections in addition 4856279528Sbaptto the original versions of these Invariant Sections. You may include a translation 4857279528Sbaptof this License provided that you also include the original English version 4858279528Sbaptof this License. In case of a disagreement between the translation and the 4859279528Sbaptoriginal English version of this License, the original English version will 4860279528Sbaptprevail. 4861279528Sbapt.Pp 4862279528Sbapt.It 4863279528SbaptTERMINATION 4864279528Sbapt.Pp 4865279528SbaptYou may not copy, modify, sublicense, or distribute the Document except as 4866279528Sbaptexpressly provided for under this License. Any other attempt to copy, modify, 4867279528Sbaptsublicense or distribute the Document is void, and will automatically terminate 4868279528Sbaptyour rights under this License. However, parties who have received copies, 4869279528Sbaptor rights, from you under this License will not have their licenses terminated 4870279528Sbaptso long as such parties remain in full compliance. 4871279528Sbapt.Pp 4872279528Sbapt.It 4873279528SbaptFUTURE REVISIONS OF THIS LICENSE 4874279528Sbapt.Pp 4875279528SbaptThe Free Software Foundation may publish new, revised versions of the GNU 4876279528SbaptFree Documentation License from time to time. Such new versions will be similar 4877279528Sbaptin spirit to the present version, but may differ in detail to address new 4878279528Sbaptproblems or concerns. See http://www.gnu.org/copyleft/. 4879279528Sbapt.Pp 4880279528SbaptEach version of the License is given a distinguishing version number. If the 4881279528SbaptDocument specifies that a particular numbered version of this License \(lqor any 4882279528Sbaptlater version\(rq applies to it, you have the option of following the terms and 4883279528Sbaptconditions either of that specified version or of any later version that has 4884279528Sbaptbeen published (not as a draft) by the Free Software Foundation. If the Document 4885279528Sbaptdoes not specify a version number of this License, you may choose any version 4886279528Sbaptever published (not as a draft) by the Free Software Foundation. 4887279528Sbapt.Pp 4888279528Sbapt.El 4889279528Sbapt.Ss ADDENDUM: How to use this License for your documents 4890279528SbaptTo use this License in a document you have written, include a copy of the 4891279528SbaptLicense in the document and put the following copyright and license notices 4892279528Sbaptjust after the title page: 4893279528Sbapt.Pp 4894279528Sbapt.Bd -literal -offset indent 4895279528Sbapt 4896279528SbaptCopyright (C) year your name. 4897279528SbaptPermission is granted to copy, distribute and/or modify this document 4898279528Sbaptunder the terms of the GNU Free Documentation License, Version 1.1 4899279528Sbaptor any later version published by the Free Software Foundation; 4900279528Sbaptwith the Invariant Sections being list their titles, with the 4901279528SbaptFront-Cover Texts being list, and with the Back-Cover Texts being list. 4902279528SbaptA copy of the license is included in the section entitled "GNU 4903279528SbaptFree Documentation License." 4904279528Sbapt 4905279528Sbapt.Ed 4906279528Sbapt.Pp 4907279528SbaptIf you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead 4908279528Sbaptof saying which ones are invariant. If you have no Front-Cover Texts, write 4909279528Sbapt\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being 4910279528Sbapt.Va list 4911279528Sbapt\(rq; likewise for Back-Cover Texts. 4912279528Sbapt.Pp 4913279528SbaptIf your document contains nontrivial examples of program code, we recommend 4914279528Sbaptreleasing these examples in parallel under your choice of free software license, 4915279528Sbaptsuch as the GNU General Public License, to permit their use in free software. 4916279528Sbapt.Pp 4917279528Sbapt.Sh Binutils Index 4918