OBJCOPY(1)

📦 version 2.16.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 OBJCOPY(1) 💖

okay so hi bestie, welcome to OBJCOPY(1), straight out of the GNU Development Tools manual. this is the one about copying and translating object files and honestly? it's giving ✨quietly powerful✨. there are three parts to this page and this is part one, so buckle up 🎀

🌸 NAME 🌸

objcopy — copy and translate object files 💅

✨ SYNOPSIS ✨

objcopy [-F bfdname⎪--target=bfdname]
        [-I bfdname⎪--input-target=bfdname]
        [-O bfdname⎪--output-target=bfdname]
        [-B bfdarch⎪--binary-architecture=bfdarch]
        [-S⎪--strip-all]
        [-g⎪--strip-debug]
        [-K symbolname⎪--keep-symbol=symbolname]
        [-N symbolname⎪--strip-symbol=symbolname]
        [--strip-unneeded-symbol=symbolname]
        [-G symbolname⎪--keep-global-symbol=symbolname]
        [-L symbolname⎪--localize-symbol=symbolname]
        [-W symbolname⎪--weaken-symbol=symbolname]
        [-w⎪--wildcard]
        [-x⎪--discard-all]
        [-X⎪--discard-locals]
        [-b byte⎪--byte=byte]
        [-i interleave⎪--interleave=interleave]
        [-j sectionname⎪--only-section=sectionname]
        [-R sectionname⎪--remove-section=sectionname]
        [-p⎪--preserve-dates]
        [--debugging]
        [--gap-fill=val]
        [--pad-to=address]
        [--set-start=val]
        [--adjust-start=incr]
        [--change-addresses=incr]
        [--change-section-address section{=,+,-}val]
        [--change-section-lma section{=,+,-}val]
        [--change-section-vma section{=,+,-}val]
        [--change-warnings] [--no-change-warnings]
        [--set-section-flags section=flags]
        [--add-section sectionname=filename]
        [--rename-section oldname=newname[,flags]]
        [--change-leading-char] [--remove-leading-char]
        [--srec-len=ival] [--srec-forceS3]
        [--redefine-sym old=new]
        [--redefine-syms=filename]
        [--weaken]
        [--keep-symbols=filename]
        [--strip-symbols=filename]
        [--strip-unneeded-symbols=filename]
        [--keep-global-symbols=filename]
        [--localize-symbols=filename]
        [--weaken-symbols=filename]
        [--alt-machine-code=index]
        [--prefix-symbols=string]
        [--prefix-sections=string]
        [--prefix-alloc-sections=string]
        [--add-gnu-debuglink=path-to-file]
        [--only-keep-debug]
        [--writable-text]
        [--readonly-text]
        [--pure]
        [--impure]
        [-v⎪--verbose]
        [-V⎪--version]
        [--help] [--info]
        infile [outfile]

like, look at all those flags. it's a lot. it's giving options menu at a restaurant with 90 pages and honestly we're gonna go through every single one, no skips 🫶

🦋 DESCRIPTION 🦋

The GNU objcopy utility copies the contents of an object file to another. it does this using the GNU BFD Library to read and write the object files, which is the whole reason it's so chill about formats. 🧚

It can write the destination object file in a format different from that of the source object file. the exact behavior of objcopy is controlled by command-line options — you're the main character, you're the one steering. 👑

Note that objcopy should be able to copy a fully linked file between any two formats. However, copying a relocatable object file between any two formats may not work as expected. so like, temper your expectations bestie 😭

objcopy creates temporary files to do its translations and deletes them afterward. 🧹 It uses BFD to do all its translation work; it has access to all the formats described in BFD and thus is able to recognize most formats without being told explicitly. lowkey iconic.

objcopy can be used to generate S-records by using an output target of srec (e.g., use -O srec). 💖

objcopy can be used to generate a raw binary file by using an output target of binary (e.g., use -O binary). When objcopy generates a raw binary file, it will essentially produce a memory dump of the contents of the input object file. All symbols and relocation information will be discarded. The memory dump will start at the load address of the lowest section copied into the output file. ✨

When generating an S-record or a raw binary file, it may be helpful to use -S to remove sections containing debugging information. In some cases -R will be useful to remove sections which contain information that is not needed by the binary file. (like, spring cleaning but for sections 🧼)

Note — objcopy is not able to change the endianness of its input files. If the input format has an endianness (some formats do not), objcopy can only copy the inputs into file formats that have the same endianness or which have no endianness (e.g., srec). so like, don't ask it to do the impossible, it will simply not 💀

💅 OPTIONS 💅

here we go bestie, every single one. no skipping. 👑

  • infile, outfile — the input and output files, respectively. If you do not specify outfile, objcopy creates a temporary file and destructively renames the result with the name of infile. 🫣 so like, it will overwrite your input, that's not a typo.
  • -I bfdname, --input-target=bfdname — consider the source file's object format to be bfdname, rather than attempting to deduce it. basically you're telling it "bestie i already know, don't guess" 🎀
  • -O bfdname, --output-target=bfdname — write the output file using the object format bfdname.
  • -F bfdname, --target=bfdname — use bfdname as the object format for both the input and the output file; i.e., simply transfer data from source to destination with no translation. same in, same out, no notes. 💅
  • -B bfdarch, --binary-architecture=bfdarch — useful when transforming a raw binary input file into an object file. In this case the output architecture can be set to bfdarch. This option will be ignored if the input file has a known bfdarch. You can access this binary data inside a program by referencing the special symbols that are created by the conversion process. These symbols are called _binary_objfile_start, _binary_objfile_end and _binary_objfile_size. e.g. you can transform a picture file into an object file and then access it in your code using these symbols. 📸➡️📦
  • -j sectionname, --only-section=sectionname — copy only the named section from the input file to the output file. This option may be given more than once. Note that using this option inappropriately may make the output file unusable. ⚠️
  • -R sectionname, --remove-section=sectionname — remove any section named sectionname from the output file. This option may be given more than once. Note that using this option inappropriately may make the output file unusable. ⚠️ (same warning, different direction, it's giving ✂️ energy)
  • -S, --strip-all — do not copy relocation and symbol information from the source file. ✂️
  • -g, --strip-debug — do not copy debugging symbols or sections from the source file. 🐛🚫
  • --strip-unneeded — strip all symbols that are not needed for relocation processing.
  • -K symbolname, --keep-symbol=symbolname — copy only symbol symbolname from the source file. This option may be given more than once.
  • -N symbolname, --strip-symbol=symbolname — do not copy symbol symbolname from the source file. This option may be given more than once.
  • --strip-unneeded-symbol=symbolname — do not copy symbol symbolname from the source file unless it is needed by a relocation. This option may be given more than once.
  • -G symbolname, --keep-global-symbol=symbolname — keep only symbol symbolname global. Make all other symbols local to the file, so that they are not visible externally. This option may be given more than once. 🏠
  • -L symbolname, --localize-symbol=symbolname — make symbol symbolname local to the file, so that it is not visible externally. This option may be given more than once. 🏠
  • -W symbolname, --weaken-symbol=symbolname — make symbol symbolname weak. This option may be given more than once. 🥺
  • -w, --wildcard — permit regular expressions in symbolnames used in other command line options. The question mark (?), asterisk (*), backslash (\) and square brackets ([]) operators can be used anywhere in the symbol name. If the first character of the symbol name is the exclamation point (!) then the sense of the switch is reversed for that symbol. For example:
-w -W !foo -W fo*

would cause objcopy to weaken all symbols that start with fo'' **except** for the symbol foo''. 😌👌

  • -x, --discard-all — do not copy non-global symbols from the source file.
  • -X, --discard-locals — do not copy compiler-generated local symbols. (These usually start with L or ..) 🗑️
  • -b byte, --byte=byte — keep only every byteth byte of the input file (header data is not affected). byte can be in the range from 0 to interleave-1, where interleave is given by the -i or --interleave option, or the default of 4. This option is useful for creating files to program ROM. It is typically used with an "srec" output target. 🍰
  • -i interleave, --interleave=interleave — only copy one out of every interleave bytes. Select which byte to copy with the -b or --byte option. The default is 4. objcopy ignores this option if you do not specify either -b or --byte. 🚫
  • -p, --preserve-dates — set the access and modification dates of the output file to be the same as those of the input file. 🕰️
  • --debugging — convert debugging information, if possible. This is not the default because only certain debugging formats are supported, and the conversion process can be time consuming. 🐢
  • --gap-fill val — fill gaps between sections with val. This operation applies to the load address (LMA) of the sections. It is done by increasing the size of the section with the lower address, and filling in the extra space created with val. 🫗
  • --pad-to address — pad the output file up to the load address address. This is done by increasing the size of the last section. The extra space is filled in with the value specified by --gap-fill (default zero). 🛋️
  • --set-start val — set the start address of the new file to val. Not all object file formats support setting the start address. ⚠️
  • --change-start incr, --adjust-start incr — change the start address by adding incr. Not all object file formats support setting the start address. ⚠️
  • --change-addresses incr, --adjust-vma incr — change the VMA and LMA addresses of all sections, as well as the start address, by adding incr. Some object file formats do not permit section addresses to be changed arbitrarily. Note that this does not relocate the sections; if the program expects sections to be loaded at a certain address, and this option is used to change the sections such that they are loaded at a different address, the program may fail. 💀 so like, be careful with this one fr fr.
  • --change-section-address section{=,+,-}val, --adjust-section-vma section{=,+,-}val — set or change both the VMA address and the LMA address of the named section. If = is used, the section address is set to val. Otherwise, val is added to or subtracted from the section address. See the comments under --change-addresses, above. If section does not exist in the input file, a warning will be issued, unless --no-change-warnings is used. ⚠️
  • --change-section-lma section{=,+,-}val — ok so LMA = the address where that section gets loaded into memory at program load time. Load time, bestie. Usually it's the same as the VMA (the address where the section lives once the program is running), but on some systems — especially the ones where the program is chillin' in ROM — those two are literally different addresses. If you use =, the section address gets set to val. Otherwise val gets added to or subtracted from it. Peep the notes under --change-addresses above 👀. If section doesn't even exist in the input file, you get a warning — unless --no-change-warnings is on. 🫶
  • --change-section-vma section{=,+,-}val — same energy, but for the VMA. That's the address where the section will be located once the program has started executing. Normally it matches the LMA (where it gets loaded into memory), but again, on some systems — especially ROM-held programs — the two can differ. = sets the section address to val; otherwise val is added to or subtracted from it. See the comments under --change-addresses above. And if section isn't in the input file? Warning. Unless --no-change-warnings. 💅
  • --change-warnings
  • --adjust-warnings — if you used --change-section-address or --change-section-lma or --change-section-vma and the named section does not exist, issue a warning. This is the default, so this is just you saying it out loud. ✨
  • --no-change-warnings
  • --no-adjust-warnings — do NOT issue a warning if --change-section-address or --adjust-section-lma or --adjust-section-vma is used, even when the named section doesn't exist. Silence. Iconic. 🤫
  • --set-section-flags section=flags — sets the flags for the named section. flags is a comma-separated string of flag names. The recognized names are: alloc, contents, load, noload, readonly, code, data, rom, share, and debug. You can set the contents flag on a section that has no contents, but clearing the contents flag on a section that DOES have contents is not meaningful — just remove the section instead. And ngl, not all flags are meaningful for all object file formats. 🦋
  • --add-section sectionname=filename — adds a brand new section called sectionname while copying the file. The contents of the new section come straight from filename. The size of the section = the size of the file. Heads up: this only works on file formats that can support sections with arbitrary names. 🎀
  • --rename-section oldname=newname[,flags] — renames a section from oldname to newname, and optionally changes that section's flags to flags while it's at it. The glow-up here vs. using a linker script: the output stays an object file and does not become a linked executable. Periodt. 👑

This one is especially helpful when your input format is binary, because binary input will always create a section called .data. So if, for example, you wanted a section called .rodata holding binary data instead, you'd run this:

objcopy -I binary -O <output_format> -B <architecture> \
 --rename-section .data=.rodata,alloc,load,readonly,data,contents \
 <input_binary_file> <output_object_file>
  • --change-leading-char — some object file formats use special characters at the start of symbols. The most common one is the underscore, which compilers love to slap in front of every symbol. This option tells objcopy to change the leading character of every symbol when it converts between object file formats. If both formats use the same leading character, this option does literally nothing. Otherwise it adds a character, removes a character, or changes a character, as appropriate. Slay. ✨
  • --remove-leading-char — if the first character of a global symbol is that special symbol-leading character the object file format uses, remove it. The most common leading character is underscore, so this'll strip a leading underscore off all global symbols. Super useful when you want to link together objects from different file formats with different naming conventions. Important: this is different from --change-leading-char because it always changes the symbol name when appropriate, no matter what the output file's object file format is. 💅
  • --srec-len=ival — only meaningful for srec output. Sets the max length of the Srecords being produced to ival. That length covers the address, the data, AND the crc fields. 📏
  • --srec-forceS3 — only meaningful for srec output. Avoids generating S1/S2 records, so you get an S3-only record format. No S1/S2 erasure, we're S3-only now. 💅
  • --redefine-sym old=new — changes the name of symbol old to new. Chef's kiss when you're trying to link two things together, you have no source for them, and the names are colliding. 😤
  • --redefine-syms=filename — applies --redefine-sym to every symbol pair "old new" listed in filename. filename is just a flat file, one symbol pair per line. Line comments can be introduced with the hash character. This option may be given more than once. 🍓
  • --weaken — changes all global symbols in the file to be weak. Useful when you're building an object that'll be linked against other objects using the -R option to the linker. Only effective with an object file format that supports weak symbols, so vibe-check your format first. 🧚
  • --keep-symbols=filename — applies --keep-symbol to every symbol listed in filename. Flat file, one symbol name per line, # starts a line comment. Can be given more than once. 🫶
  • --strip-symbols=filename — applies --strip-symbol to every symbol listed in filename. Flat file, one symbol name per line, # for line comments. Can be given more than once. ✂️
  • --strip-unneeded-symbols=filename — applies --strip-unneeded-symbol to every symbol listed in filename. Flat file, one symbol name per line, # for line comments. Can be given more than once. 🧹
  • --keep-global-symbols=filename — applies --keep-global-symbol to every symbol listed in filename. Flat file, one symbol name per line, # for line comments. Can be given more than once. 💖
  • --localize-symbols=filename — applies --localize-symbol to every symbol listed in filename. Flat file, one symbol name per line, # for line comments. Can be given more than once. 🏠
  • --weaken-symbols=filename — applies --weaken-symbol to every symbol listed in filename. Flat file, one symbol name per line, # for line comments. Can be given more than once. 🥀
  • --alt-machine-code=index — if the output architecture has alternate machine codes, use the *index*th code instead of the default one. This comes in clutch when a machine gets assigned an official code and the tool-chain adopts the new code, but other applications still depend on the original code being used. Awkward little situation, but we handle it. 😌
  • --writable-text — marks the output text as writable. Not meaningful for all object file formats, bestie. ✍️
  • --readonly-text — makes the output text write protected. Also not meaningful for all object file formats. 🔒
  • --pure — marks the output file as demand paged. Not meaningful for all object file formats. 📄
  • --impure — marks the output file as impure. (Rude of you tbh.) Not meaningful for all object file formats. 😈
  • --prefix-symbols=string — prefixes all symbols in the output file with string. 🏷️
  • --prefix-sections=string — prefixes all section names in the output file with string. 📛
  • --prefix-alloc-sections=string — prefixes the names of all allocated sections in the output file with string. 🎀
  • --add-gnu-debuglink=path-to-file — creates a .gnu_debuglink section containing a reference to path-to-file, and adds it to the output file. 🔗
  • --only-keep-debug — strips a file: it removes any sections that --strip-debug would strip, and leaves the debugging sections behind. 🐛

The intention here is that you use this together with --add-gnu-debuglink to create a two-part executable. Part one: a stripped binary that takes up less space in RAM and in a distribution. Part two: a debugging info file that's only needed if you actually want debugging abilities. The suggested procedure to create these files goes like this:

  1. Link the executable as normal. Assuming that it is called "foo" then...
  2. Run "objcopy --only-keep-debug foo foo.dbg" to create a file containing the debugging info.
  3. Run "objcopy --strip-debug foo" to create a stripped executable.
  4. Run "objcopy --add-gnu-debuglink=foo.dbg foo" to add a link to the debugging info into the stripped executable.

Note — the choice of ".dbg" as an extension for the debug info file is arbitrary. Also, the "--only-keep-debug" step is optional. You could instead do this:

  1. Link the executable as normal.
  2. Copy "foo" to "foo.full".
  3. Run "objcopy --strip-debug foo".
  4. Run "objcopy --add-gnu-debuglink=foo.full foo".

ie the file pointed to by the --add-gnu-debuglink can be the full executable. It does not have to be a file created by the --only-keep-debug switch. 🫶

  • -V
  • --version — shows the version number of objcopy. 📢
  • -v
  • --verbose — verbose output: lists all object files modified. And in the case of archives, objcopy -V lists all members of the archive. 🗣️
  • --help — shows a summary of the options to objcopy. 🆘
  • --info — displays a list showing all architectures and object formats available. 🌈

👀 SEE ALSO 👀

ld(1), objdump(1), and the Info entries for binutils. 💜

Okay bestie, legal era incoming — but it's short, I promise, and it's giving very "the lawyers made us say this" energy. 🎀

Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc.

That's fourteen years of copyright dates, one after another, like a little conga line of years. Respect. 👑

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Not me translating the legal bit: you can copy this, share this, remix this — under the GNU Free Documentation License, Version 1.1 or anything newer from the FSF. No Invariant Sections, no Front-Cover Texts, no Back-Cover Texts. And the full license text is chilling in the section literally called ``GNU Free Documentation License''. Go read it, it's right there. 💅

And that's the whole page, bestie!! 🦋✨ This fine piece of documentation came to you from binutils-2.15.97, dated 2005-04-20 — so yes, she's vintage, she's iconic, and she still ate. 💜 Thanks for reading all the way to the bottom, that's real main character behavior. Now go copy some object files. Periodt. 💖🌈

📦 where this page comes from