path: root/bfd/bfd.doc

This file contains -*- Text -*-.

BFD is a set of routines for reading and writing binary files.

The user should call only the interface routines at the end of bfd.h.
The one I'm working out of is /4/gumby/bfd/bfd.h

	Sample "strip" program using BFD:

	#include "bfd.h"

	doit ()
	{
		ibfd = bfd_openr(...)
		obfd = bfd_openw(...)
		bfd_check_format (ibfd, object);
		bfd_set_format (obfd, object);

		bfd_set_arch_mach (obfd, ...)
		bfd_set_start_address (obfd, ...)
		etc...
	
		[optionally:
		  asymbol * foo = malloc (get_symtab_upper_bound (ibfd));
		  bfd_canonicalize_symtab (ibfd, foo);
		  <sort foo, frob foo, etc, using asymbol def from bfd.h>
		  bfd_set_symtab (obfd, foo, updated_symbol_count);
		]

		bfd_map_over_sections (abfd, setup, NULL);
		bfd_map_over_sections (abfd, cleaner, NULL);

		bfd_close (obfd);
		bfd_close (ibfd);
	}

	setup (ibfd, sect)
	{
	    osect = make_section (obfd, bfd_section_name (ibfd, sect));
	    bfd_set_section_size (obfd, osect, bfd_section_size (ibfd, sect));
	    ...	    
	}

	cleaner (ibfd, sect)
	{
	    osect = bfd_get_section_by_name (obfd,
				           bfd_section_name (ibfd, sect));
	    bfd_copy_section (ibfd, sect, obfd, osect);
	    [perhaps: bfd_set_reloc (osect, NULL, 0); ]
	}
	    


BFD is a package for manipulating binary files required for developing
programs.  It implements a group of structured operations designed to
shield the programmer from the underlying representation of these
binary files.  It understands object (compiled) files, archive
libraries, and core files.  It is designed to work in a variety of
target environments.

To use the library, include bfd.h and link with libbfd.a.	

A bfd iteself is a representation for a particular file.  It is opened
in a manner similar to a file; code then manipulates it rather than
the raw files.

BFD makes a distinction between TARGETS (families of file formats) and
FORMATS (individual file formats).  For instance, the "sun4os4" target
can handle core, object and archive formats of files.  The exact
layout of the different formats depends on the target environment.

The target "default" means the first one known (usually used for
environments that only support one format, or where the common format
is known at compile or link time).  The target NULL means the one
specified at runtime in the environment variable GNUTARGET; if that is
null or not defined then the first entry in the target list is chosen
(on output), or all targets are searched (on input) to find a matching
one..

Most programs should use the target NULL.

There is a way to get a list of the names of all the targets:
char**	  bfd_target_list ()
	  This function returns a freshly-malloced list of all the
	  defined targets (or NULL if it could not malloc).  The names
	  are read-only.  You could use this to prompt the user, or
	  perhaps to error-check.

char * bfd_format_string (bfd_format format)
     This function will give you a printable, single-word description
     (like "core" or "archive") for a bfd format.

Error handling

General rules:
functions which are boolean return true on success and false on failure
(unless they're a predicate).  Functions which return pointers to
objects return NULL on error.  The specifics are documented with each
function.

If a function fails, you should check the variable bfd_error.  If the
value is no_error, then check the C variable errno just as you would
with any other program.  The other values bfd_error may take on are
documented in bfd.h.

If you would prefer a comprehensible string for the error message, use
the function bfd_errmsg:
	char * bfd_errmsg (error_tag)
This function returns a read-only string which documents the error
code.  If the error code is no_error then it will return a string
depending on the value of errno.

bfd_perror() is like the perror() function except it understands
bfd_error.

Operations on bfds themselves

bfd *  bfd_openr  (char *filename, char *target);
bfd *  bfd_fdopenr  (int fd, char *target, char *filename);

	Open a binary file for reading.  TARGET is the type of the file,
	a char string like "sun4os4" or "elf".  (Note this is not the
	"function" of the file, e.g. an object versus a core file
	versus an archive, but instead describes how all these files
	are encoded.)  Returns a new bfd or NULL upon failure.
	
bfd *  bfd_openw  (char *filename, char *target);

	Open a file named `filename'  for writing.  If an existing
	file has the same name, then it will be overwritten by a
	successful bfd_close on the returned bfd.  Will return either
	a new bfd or NULL upon failure.

boolean  bfd_close  (bfd *abfd);
	
	Close a BFD opened for either reading or writing.  May involve
	several filesystem operations, depending on the data format;
	some things may not be known to the system until file-closing
	time.  Returns true if it successfully wrote the file, false
	if not.  A false return will not leave a partially-written
	file behind with the name supplied to bfd_openw.

	On a bfd open for reading will generally successfully
	complete.

	It is an error to call this on a file opened from inside an
	archive.

	FIXME -- show which error codes may be recoverable and
	followed by another call to bfd_close!


The defined formats are specified by the enumeration bfd_format.
	
boolean  bfd_check_format  (bfd *abfd, bfd_format format);

	This routine must be called after a bfd_openr.  It sets up
	internal data structures based on the contents of the file.
	It returns FALSE if the file is not really in the specified
	format.

boolean  bfd_set_format  (bfd *abfd, bfd_format format);

	This routine must be called after a bfd_openw.  It sets up
	internal data structures for the proper format of file.
	It returns FALSE if that format is not supported for output
	(e.g. core files).

The following macros may be used to obtain information about a bfd:

bfd_get_filename -- returns a pointer to a null-terminated string
	which names the bfd's file, or NULL if that is not known.
	Don't side-effect this string!
bfd_get_format -- returns the format code for the bfd.
bfd_get_target -- returns the string which names the bfd's target.
bfd_get_mtime -- returns an time_t indicating the modification time of an
	      input bfd, if that could be determined, or 0 of not.

Object files have certain properties.  For input bfds, these
properties may be read at any time.  For output bfds you should set
them before you begin building any sections.
	
bfd_vma	bfd_get_start_address  (bfd *abfd);

	Returns the address in an object file where execution will begin.

boolean	bfd_set_start_address	(bfd *abfd, int vma);  

	Set the address where execution will start in an object file.

	If the address you select is incorrect for your architecture
	(for instance, if it's required to be on a page_boundary and
	your supplied starting address is not, then you may get the
	invalid_operation error.  It is not always possible to
	generate an error in this case.

An object file has an architecture, which is the general instruction
set of the instructions that it contains.  Architectures are defined in
enum bfd_architecture in bfd.h.  New architectures can be added by
putting them in the enum, updating architectures.c, and adding code to
handle them for the object files that know that architecture.  The
bfd_architecture values are not stored in files, but are only used
within the BFD library and its callers.

An object file also has a machine type, which is the specific machine
within the architecture.  For example, if the architecture is bfd_arch_m68k,
the Motorola 68000 series, then the machine type might be 68010, the mc68010
chip.  For architectures such as the SPARC where specific versions of
the architecture exist, the version number should probably be used.

Particular object file formats may or may not store the machine architecture
and type.  When copying an object file, you should copy these fields.
Most callers of BFD will not need to know the particular values that
these fields contain, but will instead propagate them from file to file,
or compare the architectures from two files.

enum bfd_architecture bfd_get_architecture (bfd *abfd);
unsigned long bfd_get_machine	   (bfd *abfd);

	Get the machine type and architecture.

boolean bfd_set_arch_mach	   (bfd *abfd, enum bfd_architecture arch,
				    unsigned long machine);

	Set the architecture and machine type.  The result is true
	if the object file can exactly represent the specified type.
	The result is false otherwise.

boolean bfd_arch_compatible	   (bfd *abfd, bfd *bbfd,
				    enum bfd_architecture *res_arch,
				    unsigned long *res_machine);

	Decides whether two BFD's contain compatible architectures and
	machine types.  If the result is TRUE and the res_arch and
	res_machine pointers are non-NULL, the resulting "merged" 
	architecture and machine type are returned through the pointers.
	A linker could call this to decide whether two object files
	can be linked, and to deterine the arch and machine type of
	the resulting file.

char * bfd_printable_arch_mach     (enum bfd_architecture arch,
			            unsigned long machine);

	Returns a printable string that represents the particular
	combination of architecture and machine type.

boolean bfd_scan_arch_mach	   (char *string, enum bfd_architecture *archp,
			            unsigned long *machinep);

	Examines a printable string and tries to extract an
	architecture and machine type from it.  The intended use is for
	parsing specifications from the user, e.g. command line
	arguments.  The result is true if a known architecture was
	found, and the resulting architecture and machine type are
	stored through the argument pointers.  Note that an
	architecture scannable by this function might not be
	representable by the particular object file format in use.
	(i.e. bfd_set_arch_mach might return false).


There are also a number of boolean flags which apply to object bfds.

flagword bfd_get_file_flags	   (bfd *abfd); 

	 returns a flagword containing the bfd's flags.

boolean bfd_set_file_flags	   (bfd *abfd, flagword flags,
					boolean on_or_off); 

	sets (on_or_off == true) or clears (on_or_off == false) the flags
	specified by flagword.  All other flags are unaffected.
	Some flag combinations don't make sense; It is not always
	possible to detect them (since they may depend on other information).
	Returns true if the flags could be modified as requested,
	false if not.  Upon a false return, no flags will have been
	altered.


flagword bfd_applicable_file_flags	(bfd *abfd); 

	 returns a flagword with bits set for all the flags which are
	 meaningful for the bfd.

The flags are:
    HAS_RELOC -- file contains unresolved relocation information.
    EXEC_P -- file can be executed.  These two may both be on in the
	      case of some dynamically-linked binaries.
    HAS_LINENO -- has line number information.
    HAS_DEBUG -- has debugging information.
    HAS_SYMS -- has any symbols.
    HAS_LOCALS -- has local symbols.
    DYNAMIC -- binary is dynamically linked.
    WP_TEXT -- text is write-protected
    D_PAGED -- binary should be demand-paged

These flags are one bit wide and may be OR-ed together with |.

If you are building a large application with bfd there may be data
specific to your program that you may wish to associate with a bfd.
Rather than require you to build a parallel table structure, bfd
provides a void* pointer in each bfd for arbitrary user data.  The
macro bfd_usrdata (bfd *abfd) extracts these data; you may set them
with = (ie bfd_usrdata (my_bfd) = frob_it (my_bfd, moon_phase);).

Object and core files have sections.

File sections are represented by opaque pointers.  You may map over
the sections of a file or you may ask for one by name.  Note that not
all files may have all the possible sections.

Section pointers are valid from the time you get them until the bfd
to which they refer is closed.

When doing output, you must set up all the file's sections before
outputting to any.   All that means is that all the file's sections
must have already been created and their size set before output
commences.

Each section contains some small information, plus three chunks of
data in the object file:  contents, relocation, and line numbers.
In some file formats (e.g. a.out), the line number part is always
empty, and line number information (if any) is instead recorded in
the symbol table.

sec_ptr	bfd_get_section_by_name	(bfd *abfd, char *name); 
	Returns a section named NAME, or NULL if none by that name
	exists.  Works on input and output bfds.

sec_ptr	bfd_make_section	(bfd *abfd, char *name); 
	Creates a section named name in the output bfd abfd.
	returns NULL if it cannot create the section (if, for instance,
	the output format does not permit such a section).  If a
	section with that name already exists, it is returned; a new
	one with the same name is NOT created.

unsigned int bfd_count_sections (bfd *abfd)

	This function returns the number of sections in the bfd abfd.

void	bfd_map_over_sections	(bfd *abfd, void (*operation)(),
				 void *user_storage); 

	This is how you operate on all sections of an input file.
	Pass in a function pointer.  The function will be called for each
	section of the file, in random order.  It will be passed
	three arguments: the bfd, the sec_ptr for the section, and
	whatever was passed in as user_storage.

char *	bfd_section_name	(bfd *abfd, sec_ptr ptr); 

	Produces the name of a section, e.g. ".text" or ".data".
	This will produce arbitrary names for files with extensible
	section names (e.g. COFF, ELF) so don't assume that you will
	only see a few values here.

long	bfd_section_size	(bfd *abfd, sec_ptr ptr); 

	The size of a section in bytes.  Result == -1 for error.

boolean	bfd_set_section_size	(bfd *abfd, sec_ptr section unsigned long size);

	Set the size of a section.  This must be done before any data
	transfer is done for the section.

bfd_vma	bfd_section_vma	(bfd *abfd, sec_ptr ptr); 

	Virtual memory address where a section "belongs".

boolean	bfd_set_section_vma	(bfd *abfd, bfd_vma vma);

	Set the virtual memory address of a section.

int bfd_get_section_alignment  (bfd *abfd, sec_ptr ptr); 

        returns the alignment of a section.  If alignment is not
	possible, return value is undefined.
	
boolean bfd_set_section_alignment  (bfd *abfd, sec_ptr ptr, int alignment) 

	returns true if it can set the section to the requested value.
	Alignment is an integer; it refers to the power of two
	specifying the byte boundary we want (ie 0 is byte-aligned; 4
 	is word aligned).  If the requested alignment is not available
	any existing value is unchanged.

Sections have properties just as object files may:

flagword bfd_get_section_flags	   (bfd *abfd, sec_ptr section); 

	 returns a flagword containing the section's flags.

boolean bfd_set_section_flags	   (bfd *abfd, sec_ptr section,
					flagword flags, boolean on_or_off); 

	sets (on_or_off == true) or clears (on_or_off == false) the flags
	specified by flagword.  All other flags are unaffected.
	Some flag combinations don't make sense; It is not always
	possible to detect them (since they may depend on other information).
	Returns true if the flags could me modified as requested,
	false if not.  Unpon a false return, no flags will have been
	altered.

flagword bfd_applicable_section_flags	(bfd *abfd); 

	 returns a flagword with bits set for all the flags which are
	 meaningful for a section.

The flags are:

    SEC_BALIGN -- segment can be byte-aligned.
    SEC_RELOC -- segment should be relocated.
    SEC_ALLOC -- when converted into a memory image with the intent of
	    constructing a runable process, memory space will be
	    allocated for this section.
    SEC_LOAD -- when converted into a memory image with the intent of
	    constructing a runable process, section contents will be
	    copied from the object file into memory.  When this flag
	    is set, SEC_ALLOC is guaranteed to also be set.
    SEC_HAS_CONTENTS -- The contents of this section exist in the
	    object file.  Sections whose contents do not exist in the
	    object file may still have their contents read.  On read,
	    a segment filled with zeroes will be invented to satisfy
	    the read request.  It is an error to attempt to set the
	    contents of a section that has no contents.

These last three probably need some explanation.  In a traditional,
native unix object format, there are three real sections, text, data,
and bss.  The text section will be allocated memory on exec, and will
be loaded from file into memory on exec.  So the flags for a
traditional unix text section would typically be at least (SEC_ALLOC |
SEC_LOAD | SEC_HAS_CONTENTS).  The data section has basically these
same traits.  The bss section, however is a little different.  It is
not relocated, and it is not loaded from file on exec, but it is
allocated memory on exec.  Thus, its flags would be more like
(SEC_ALLOC).  It is possible to have a section which is the converse
of the bss section.  That is, (SEC_HAS_CONTENTS & ~SEC_ALLOC).  This
could be anything from profiling information or notes from one pass of
a toolchain to another to time and version stamp information.

Note that the section flags currently lack information on position
dependance.

boolean	bfd_get_section_contents  (bfd *abfd, sec_ptr section,
				   unsigned char *location,
				   int offset, int count); 

	Stores count bytes from the section's contents starting at
	offset from within those contents.  The values are stored into
	location.  Returns true if it could do so.  Supplying invalid
	values for offset and count will produce unpredictable results.

boolean	bfd_set_section_contents (bfd *abfd, sec_ptr section,
				 unsigned char *location,
				 int offset, int count); 
	Stores count bytes from location into offset within the
	section contents.  You need not write all the contents contiguously
	(that is, you may write words 5-7 followed by 0-4 if you
	wish).  However once you start writing into a section, any
	other sections into which you have previously written are
	considered finished, and you may not write in them any more.

*** Line numbers ***

bfd_get_section_lineno_size (bfd *abfd, sec_ptr section);
	Returns how many bytes of line numbers are associated with this
	section.

bfd_set_section_lineno_size (bfd *abfd, sec_ptr section, unsigned long val);
	Sets the number of bytes of line numbers that this section should
	contain.

boolean bfd_get_section_linenos (bfd *abfd, sec_ptr section,
				 unsigned char *location,
				 int offset, int count); 
	Same as get_section_contents, except that it works on the linenos
	for this section.

boolean bfd_set_section_linenos (bfd *abfd, sec_ptr section,
				 unsigned char *location,
				 int offset, int count); 
	Same as set_section_contents, except that it works on the linenos
	for this section.

As with files, you may associate arbitrary program-specific data with
a section of a bfd.  The following two functions are provided for
manipulating these data:

void * bfd_get_section_userdata (bfd *abfd, sec_ptr section)
       Returns whatever was stored in section's user data, or NULL if nothing.

boolean bfd_set_section_userdata (bfd *abfd, sec_ptr section, void *contents)
	Set the section contents.  Returns true if it can, false if not.

Core files

Core files are currently only supported for reading.

Apart from opening them, looking at the various sections (generally
the .data, .stack, and .regs sections; maybe a .user_struct section
eventually), you can make some queries about the status of the core
file, detailed below.  The ".regs" section contains the general and
floating point registers of the process that died, in some machine-
specific order and format "intended to be unsurprising to someone who
knows the machine".

char *  bfd_core_file_failing_command  (bfd *abfd);

	The command name of the program that failed, creating the core file.
	The result is NULL if BFD can't figure out what the failing command was.

int  bfd_core_file_failing_signal  (bfd *abfd);

 	The signal number which caused the program to die, causing the
 	core file to be created.  It will be positive if valid.

boolean	core_file_matches_executable_p	(bfd *core_bfd, bfd *exec_bfd);

	For debuggers, checks whether a core file "matches" (is likely to
	have come from) an executable file.  This will not be perfect on
	most systems, but will just provide a way to reject gross mismatches.

Archives.

An archive is a special file which can contain other files.
Originally it was intended to be a general way to group files, the way
tar is today.  But now it is used almost exclusively to hold object
files.

An archive may be opened for reading or writing just like any other
bfd.  Once it is open for reading you may obtain bfds for each of the
files contained within it with the following function:

bfd *	bfd_openr_next_archived_file	(bfd *arch_bfd, bfd *last_file);

	If called with NULL as the second argument, returns the first
	file contained in the archive arch_bfd.  If called with a file
	contained within arch_bfd, returns the one which follows that
	one, or NULL if it was the last.  Returns NULL also if the
	bfd supplied as last_file did not come from the archive arch_bfd.
						       
Any bfd open for read may be placed in an output archive.  When the
output archive is closed, the contents will be placed into the
archive.

You control the order of files in an archive.  You set the first one
with the following function:

boolean bfd_set_archive_head (bfd *output_archive, bfd *new_head)

	This function sets the first file in the archive
	output_archive to be the bfd new_head.

bfd's contain a pointer called next, which is bfd *.  It is used by
bfd_close when an archive is closed to decide which file should next
go into the archive.  So to place a group of files into an archive,
open bfds for each of them, chain them together using the next pointer
in the order you desire (be sure to store NULL into the final one's
next pointer), then do bfd_set_archive_head with the head of the
chain.  The next pointer may be freely smashed at any time; it is only
looked at when closing an output archive.

bfds for files contained within archives are normal bfds; you can do
any input operations on them that you can do with a normal bfd.

bfd_my_archive is a macro which takes an input bfd and returns NULL if
it lives in the filesystem and a bfd if it is contained in an archive.
In the latter case, the returned bfd is the archive itself.

Archives containing only object files may have a "map" -- a table in
the front which maps external symbols to the files which contain them.

Archive maps will refer only to object files; if an archive contains a
file which is not an archive that file will of course not appear in
the map.	 
	 
boolean  bfd_has_map (bfd *archive_bfd)

	 This macro takes a bfd of an archive and returns true or
	 false depending on whether the bfd has a map.  For output
	 bfds this may be set to true or false, depending on whether
	 you want the map to be maintained or not.  For some targets,
	 setting this to false will cause no map to be generated; for
	 others it will merely cause an empty map to be created, since
	 a map is required by that target.

For archives with maps you may use the following function:

int bfd_get_next_mapent (bfd *abfd, int prev, char **name)

    You may use this to step through all the entries in the archive
    map.  Supply BFD_NO_MORE_SYMBOLS as the 'prev' entry to get the
    first entry; then use successive returned values from this
    function to get the succeeding ones.  The name of the next entry
    will be stored through the pointer name.

    This function returns BFD_NO_MORE_SYMBOLS when there are no more
    entries or on error.
 
bfd * bfd_get_elt_at_index (abfd, int index)

    This function takes an index as returned by bfd_get_next_mapent
    and returns the bfd which corresponds to that entry.  Returns NULL
    on error.

Symbol and relocation information.

Symbol-table information is the area of greatest incompatibility.
bfd has a canonical symbol representation; all formats are parsed into
and out of it.

Note that canonicalize_symtab takes a pointer to an array of pointers
to canonical symbols.  This is necessary so that the end of the array
can be marked with NULL.  You may shuffle the pointers and you may
clobber the symbol contents.  But don't move the symbols themselves.

unsigned int bfd_get_symtab_upper_bound	(bfd *abfd);

	Returns the maximum number of bytes that would be taken by
	the output of canonicalize_symtab.  Returns 0 on error.
							      
unsigned int bfd_canonicalize_symtab (bfd *abfd, asymbol **location);

	Produces a symbol table in canonical format at LOCATION, which 
	must be of size specified by get_symtab_upper_bound bytes.
	Not all those bytes may be used.   Returns the number of
	symbol pointers written.  Returns 0 upon error.

boolean	bfd_set_symtab	(bfd *outbfd, asymbol **location,
			unsigned int symcount);

	Takes a generic symbol table and an output bfd.  Used to set
	the symbol table for an output bfd.  Do not change the table
	after using this function (although the storage may be
	reclaimed once the bfd has been closed).
	
If you're done with the symbol table you can tell bfd about it by
calling bfd_reclaim_symbol_table, which takes a bfd.  Calling this
function will also reclaim any relocation entries you may have
requested.  If you don't use this function, bfd will keep around all
symbol information until the bfd is closed.

Similarly, relocations have a canonical format.  See the file bfd.h for
the exact definition.  It is similar to the sun-4 relocation format.
Please note that:
o - Each relocation has a pointer to a generic symbol.
o - Not all values of reloc_type are supported for all targets.  There
    is a bitvector which explains which are; you can index into it by
    relocation type.  The macro which extracts it is bfd_valid_reloc_types.

Since relocation information is saved on a per-section basis, the
interface is slightly different from that of the symbol table:

unsigned int get_reloc_upper_bound	(bfd *abfd, sec_ptr asect);

	Returns the maximum number of bytes that would be taken by
	the output of canonicalize_reloc.  Returns 0 on error.

unsigned int canonicalize_reloc (bfd *abfd, sec_ptr asect, arelent *location);

	Produces a relocation table in canonical format at LOCATION,
	which must be of size specified by get_reloc_upper_bound
	bytes.  Not all those bytes may be used.  Returns the number
	of entries written.  Returns 0 upon error.

boolean	bfd_set_reloc	(bfd *outbfd, sec_ptr asect, arelent *location,
			 unsigned int count);

	Takes a generic reloc table and an output bfd.  Used to set
	the reloc table for an output bfd.  Do not change the table
	after using this function (although the storage may be
	reclaimed once the bfd has been closed).

Byte-swapping

Unfortunately, not all machines have the same byte order.  Worse,
storage layout is in general highly machine-dependent.  Although bfd
can hide that from you in most cases, it cannot do so with the section
contents, since they are totally uninterpreted.  Hence you must
byte-swap those data yourself.  This is not usually much of an issue
since you should just generate your data in the correct byte order.

[THIS IS WRONG AND ALSO DOES NOT REFLECT THE CODE WHICH IS CORRECT]

Fortunately, bfd can tell if byte-swapping or realignment is required
at all!  The macro bfd_bit_twiddle_required takes a pointer to a bfd
and returns true if byte-swapping is required, false if not.

However if you don't wish to check this you may just use the following
functions which will do the conversions required:


long	bfd_getlong	(bfd *abfd, unsigned char *ptr);
	bfd_putlong	(bfd *abfd, unsigned char *ptr, long time);

short	bfd_getshort	(bfd *abfd, unsigned char *ptr);
	bfd_putshort	(bfd *abfd, unsigned char *ptr, short stop);

	These functions take a pointer that points to data which is,
	or will be, part of a section contents.  They extract numbers
	from the data, or insert numbers into the data.  The argument
	or result is in the host's number format; the data stored at
	the pointer or retrieved from it is in the target's number format.
	Typically this transfer is either a no-op or is a byte-swap;
	sometimes it involves an access to a "misaligned" location from
	the host's point of view..