diff options
Diffstat (limited to 'bfd/doc/opncls.texi')
| -rw-r--r-- | bfd/doc/opncls.texi | 533 |
1 files changed, 533 insertions, 0 deletions
diff --git a/bfd/doc/opncls.texi b/bfd/doc/opncls.texi new file mode 100644 index 0000000..fb552f2 --- /dev/null +++ b/bfd/doc/opncls.texi @@ -0,0 +1,533 @@ + +@example +/* Set to N to open the next N BFDs using an alternate id space. */ +extern unsigned int bfd_use_reserved_id; +@end example +@section Opening and closing BFDs + + +@subsection Functions for opening and closing + + +@findex bfd_fopen +@subsubsection @code{bfd_fopen} +@strong{Synopsis} +@example +bfd *bfd_fopen (const char *filename, const char *target, + const char *mode, int fd); +@end example +@strong{Description}@* +Open the file @var{filename} with the target @var{target}. +Return a pointer to the created BFD. If @var{fd} is not -1, +then @code{fdopen} is used to open the file; otherwise, @code{fopen} +is used. @var{mode} is passed directly to @code{fopen} or +@code{fdopen}. + +Calls @code{bfd_find_target}, so @var{target} is interpreted as by +that function. + +The new BFD is marked as cacheable iff @var{fd} is -1. + +If @code{NULL} is returned then an error has occured. Possible errors +are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or +@code{system_call} error. + +On error, @var{fd} is always closed. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@findex bfd_openr +@subsubsection @code{bfd_openr} +@strong{Synopsis} +@example +bfd *bfd_openr (const char *filename, const char *target); +@end example +@strong{Description}@* +Open the file @var{filename} (using @code{fopen}) with the target +@var{target}. Return a pointer to the created BFD. + +Calls @code{bfd_find_target}, so @var{target} is interpreted as by +that function. + +If @code{NULL} is returned then an error has occured. Possible errors +are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or +@code{system_call} error. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@findex bfd_fdopenr +@subsubsection @code{bfd_fdopenr} +@strong{Synopsis} +@example +bfd *bfd_fdopenr (const char *filename, const char *target, int fd); +@end example +@strong{Description}@* +@code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to +@code{fopen}. It opens a BFD on a file already described by the +@var{fd} supplied. + +When the file is later @code{bfd_close}d, the file descriptor will +be closed. If the caller desires that this file descriptor be +cached by BFD (opened as needed, closed as needed to free +descriptors for other opens), with the supplied @var{fd} used as +an initial file descriptor (but subject to closure at any time), +call bfd_set_cacheable(bfd, 1) on the returned BFD. The default +is to assume no caching; the file descriptor will remain open +until @code{bfd_close}, and will not be affected by BFD operations +on other files. + +Possible errors are @code{bfd_error_no_memory}, +@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. + +On error, @var{fd} is closed. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@findex bfd_openstreamr +@subsubsection @code{bfd_openstreamr} +@strong{Synopsis} +@example +bfd *bfd_openstreamr (const char * filename, const char * target, void * stream); +@end example +@strong{Description}@* +Open a BFD for read access on an existing stdio stream. When +the BFD is passed to @code{bfd_close}, the stream will be closed. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@findex bfd_openr_iovec +@subsubsection @code{bfd_openr_iovec} +@strong{Synopsis} +@example +bfd *bfd_openr_iovec (const char *filename, const char *target, + void *(*open_func) (struct bfd *nbfd, + void *open_closure), + void *open_closure, + file_ptr (*pread_func) (struct bfd *nbfd, + void *stream, + void *buf, + file_ptr nbytes, + file_ptr offset), + int (*close_func) (struct bfd *nbfd, + void *stream), + int (*stat_func) (struct bfd *abfd, + void *stream, + struct stat *sb)); +@end example +@strong{Description}@* +Create and return a BFD backed by a read-only @var{stream}. +The @var{stream} is created using @var{open_func}, accessed using +@var{pread_func} and destroyed using @var{close_func}. + +Calls @code{bfd_find_target}, so @var{target} is interpreted as by +that function. + +Calls @var{open_func} (which can call @code{bfd_zalloc} and +@code{bfd_get_filename}) to obtain the read-only stream backing +the BFD. @var{open_func} either succeeds returning the +non-@code{NULL} @var{stream}, or fails returning @code{NULL} +(setting @code{bfd_error}). + +Calls @var{pread_func} to request @var{nbytes} of data from +@var{stream} starting at @var{offset} (e.g., via a call to +@code{bfd_read}). @var{pread_func} either succeeds returning the +number of bytes read (which can be less than @var{nbytes} when +end-of-file), or fails returning -1 (setting @code{bfd_error}). + +Calls @var{close_func} when the BFD is later closed using +@code{bfd_close}. @var{close_func} either succeeds returning 0, or +fails returning -1 (setting @code{bfd_error}). + +Calls @var{stat_func} to fill in a stat structure for bfd_stat, +bfd_get_size, and bfd_get_mtime calls. @var{stat_func} returns 0 +on success, or returns -1 on failure (setting @code{bfd_error}). + +If @code{bfd_openr_iovec} returns @code{NULL} then an error has +occurred. Possible errors are @code{bfd_error_no_memory}, +@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@findex bfd_openw +@subsubsection @code{bfd_openw} +@strong{Synopsis} +@example +bfd *bfd_openw (const char *filename, const char *target); +@end example +@strong{Description}@* +Create a BFD, associated with file @var{filename}, using the +file format @var{target}, and return a pointer to it. + +Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory}, +@code{bfd_error_invalid_target}. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@findex bfd_close +@subsubsection @code{bfd_close} +@strong{Synopsis} +@example +bfd_boolean bfd_close (bfd *abfd); +@end example +@strong{Description}@* +Close a BFD. If the BFD was open for writing, then pending +operations are completed and the file written out and closed. +If the created file is executable, then @code{chmod} is called +to mark it as such. + +All memory attached to the BFD is released. + +The file descriptor associated with the BFD is closed (even +if it was passed in to BFD by @code{bfd_fdopenr}). + +@strong{Returns}@* +@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. + +@findex bfd_close_all_done +@subsubsection @code{bfd_close_all_done} +@strong{Synopsis} +@example +bfd_boolean bfd_close_all_done (bfd *); +@end example +@strong{Description}@* +Close a BFD. Differs from @code{bfd_close} since it does not +complete any pending operations. This routine would be used +if the application had just used BFD for swapping and didn't +want to use any of the writing code. + +If the created file is executable, then @code{chmod} is called +to mark it as such. + +All memory attached to the BFD is released. + +@strong{Returns}@* +@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. + +@findex bfd_create +@subsubsection @code{bfd_create} +@strong{Synopsis} +@example +bfd *bfd_create (const char *filename, bfd *templ); +@end example +@strong{Description}@* +Create a new BFD in the manner of @code{bfd_openw}, but without +opening a file. The new BFD takes the target from the target +used by @var{templ}. The format is always set to @code{bfd_object}. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@findex bfd_make_writable +@subsubsection @code{bfd_make_writable} +@strong{Synopsis} +@example +bfd_boolean bfd_make_writable (bfd *abfd); +@end example +@strong{Description}@* +Takes a BFD as created by @code{bfd_create} and converts it +into one like as returned by @code{bfd_openw}. It does this +by converting the BFD to BFD_IN_MEMORY. It's assumed that +you will call @code{bfd_make_readable} on this bfd later. + +@strong{Returns}@* +@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. + +@findex bfd_make_readable +@subsubsection @code{bfd_make_readable} +@strong{Synopsis} +@example +bfd_boolean bfd_make_readable (bfd *abfd); +@end example +@strong{Description}@* +Takes a BFD as created by @code{bfd_create} and +@code{bfd_make_writable} and converts it into one like as +returned by @code{bfd_openr}. It does this by writing the +contents out to the memory buffer, then reversing the +direction. + +@strong{Returns}@* +@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. + +@findex bfd_alloc +@subsubsection @code{bfd_alloc} +@strong{Synopsis} +@example +void *bfd_alloc (bfd *abfd, bfd_size_type wanted); +@end example +@strong{Description}@* +Allocate a block of @var{wanted} bytes of memory attached to +@code{abfd} and return a pointer to it. + +@findex bfd_alloc2 +@subsubsection @code{bfd_alloc2} +@strong{Synopsis} +@example +void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size); +@end example +@strong{Description}@* +Allocate a block of @var{nmemb} elements of @var{size} bytes each +of memory attached to @code{abfd} and return a pointer to it. + +@findex bfd_zalloc +@subsubsection @code{bfd_zalloc} +@strong{Synopsis} +@example +void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); +@end example +@strong{Description}@* +Allocate a block of @var{wanted} bytes of zeroed memory +attached to @code{abfd} and return a pointer to it. + +@findex bfd_zalloc2 +@subsubsection @code{bfd_zalloc2} +@strong{Synopsis} +@example +void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size); +@end example +@strong{Description}@* +Allocate a block of @var{nmemb} elements of @var{size} bytes each +of zeroed memory attached to @code{abfd} and return a pointer to it. + +@findex bfd_calc_gnu_debuglink_crc32 +@subsubsection @code{bfd_calc_gnu_debuglink_crc32} +@strong{Synopsis} +@example +unsigned long bfd_calc_gnu_debuglink_crc32 + (unsigned long crc, const unsigned char *buf, bfd_size_type len); +@end example +@strong{Description}@* +Computes a CRC value as used in the .gnu_debuglink section. +Advances the previously computed @var{crc} value by computing +and adding in the crc32 for @var{len} bytes of @var{buf}. + +@strong{Returns}@* +Return the updated CRC32 value. + +@findex bfd_get_debug_link_info +@subsubsection @code{bfd_get_debug_link_info} +@strong{Synopsis} +@example +char *bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out); +@end example +@strong{Description}@* +Fetch the filename and CRC32 value for any separate debuginfo +associated with @var{abfd}. Return NULL if no such info found, +otherwise return filename and update @var{crc32_out}. The +returned filename is allocated with @code{malloc}; freeing it +is the responsibility of the caller. + +@findex bfd_get_alt_debug_link_info +@subsubsection @code{bfd_get_alt_debug_link_info} +@strong{Synopsis} +@example +char *bfd_get_alt_debug_link_info (bfd * abfd, + bfd_size_type *buildid_len, + bfd_byte **buildid_out); +@end example +@strong{Description}@* +Fetch the filename and BuildID value for any alternate debuginfo +associated with @var{abfd}. Return NULL if no such info found, +otherwise return filename and update @var{buildid_len} and +@var{buildid_out}. The returned filename and build_id are +allocated with @code{malloc}; freeing them is the +responsibility of the caller. + +@findex separate_debug_file_exists +@subsubsection @code{separate_debug_file_exists} +@strong{Synopsis} +@example +bfd_boolean separate_debug_file_exists + (char *name, unsigned long crc32); +@end example +@strong{Description}@* +Checks to see if @var{name} is a file and if its contents +match @var{crc32}. + +@findex separate_alt_debug_file_exists +@subsubsection @code{separate_alt_debug_file_exists} +@strong{Synopsis} +@example +bfd_boolean separate_alt_debug_file_exists + (char *name, unsigned long buildid); +@end example +@strong{Description}@* +Checks to see if @var{name} is a file and if its BuildID +matches @var{buildid}. + +@findex find_separate_debug_file +@subsubsection @code{find_separate_debug_file} +@strong{Synopsis} +@example +char *find_separate_debug_file + (bfd *abfd, const char *dir, bfd_boolean include_dirs, + get_func_type get, check_func_type check); +@end example +@strong{Description}@* +Searches for a debug information file corresponding to @var{abfd}. +The name of the separate debug info file is returned by the @var{get} +function. This function scans various fixed locations in the +filesystem, including the file tree rooted at @var{dir}. If the +@var{include_dirs} parameter is true then the directory components of +@var{abfd}'s filename will be included in the searched locations. + +Returns the filename of the first file to be found which receives a +TRUE result from the @var{check} function. Returns NULL if no valid +file could be found. + +@findex bfd_follow_gnu_debuglink +@subsubsection @code{bfd_follow_gnu_debuglink} +@strong{Synopsis} +@example +char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); +@end example +@strong{Description}@* +Takes a BFD and searches it for a .gnu_debuglink section. If this +section is found, it examines the section for the name and checksum +of a '.debug' file containing auxiliary debugging information. It +then searches the filesystem for this .debug file in some standard +locations, including the directory tree rooted at @var{dir}, and if +found returns the full filename. + +If @var{dir} is NULL, the search will take place starting at +the current directory. + +@strong{Returns}@* +@code{NULL} on any errors or failure to locate the .debug file, +otherwise a pointer to a heap-allocated string containing the +filename. The caller is responsible for freeing this string. + +@findex bfd_follow_gnu_debugaltlink +@subsubsection @code{bfd_follow_gnu_debugaltlink} +@strong{Synopsis} +@example +char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir); +@end example +@strong{Description}@* +Takes a BFD and searches it for a .gnu_debugaltlink section. If this +section is found, it examines the section for the name of a file +containing auxiliary debugging information. It then searches the +filesystem for this file in a set of standard locations, including +the directory tree rooted at @var{dir}, and if found returns the +full filename. + +If @var{dir} is NULL, the search will take place starting at +the current directory. + +@strong{Returns}@* +@code{NULL} on any errors or failure to locate the debug file, +otherwise a pointer to a heap-allocated string containing the +filename. The caller is responsible for freeing this string. + +@findex bfd_create_gnu_debuglink_section +@subsubsection @code{bfd_create_gnu_debuglink_section} +@strong{Synopsis} +@example +struct bfd_section *bfd_create_gnu_debuglink_section + (bfd *abfd, const char *filename); +@end example +@strong{Description}@* +Takes a @var{BFD} and adds a .gnu_debuglink section to it. The section is sized +to be big enough to contain a link to the specified @var{filename}. + +@strong{Returns}@* +A pointer to the new section is returned if all is ok. Otherwise @code{NULL} is +returned and bfd_error is set. + +@findex bfd_fill_in_gnu_debuglink_section +@subsubsection @code{bfd_fill_in_gnu_debuglink_section} +@strong{Synopsis} +@example +bfd_boolean bfd_fill_in_gnu_debuglink_section + (bfd *abfd, struct bfd_section *sect, const char *filename); +@end example +@strong{Description}@* +Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT} +and fills in the contents of the section to contain a link to the +specified @var{filename}. The filename should be relative to the +current directory. + +@strong{Returns}@* +@code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned +and bfd_error is set. + +@findex get_build_id +@subsubsection @code{get_build_id} +@strong{Synopsis} +@example +struct bfd_build_id * get_build_id + (bfd *abfd); +@end example +@strong{Description}@* +Finds the build-id associated with @var{abfd}. If the build-id is +extracted from the note section then a build-id structure is built +for it, using memory allocated to @var{abfd}, and this is then +attached to the @var{abfd}. + +Returns a pointer to the build-id structure if a build-id could be +found. If no build-id is found NULL is returned and error code is +set. + +@findex get_build_id_name +@subsubsection @code{get_build_id_name} +@strong{Synopsis} +@example +char * get_build_id_name + (bfd *abfd, unsigned long *build_id_out) +@end example +@strong{Description}@* +Searches @var{abfd} for a build-id, and then constructs a pathname +from it. The path is computed as .build-id/NN/NN+NN.debug where +NNNN+NN is the build-id value as a hexadecimal string. + +Returns the constructed filename or NULL upon error. +It is the caller's responsibility to free the memory used to hold the +filename. +If a filename is returned then the @var{build_id_out} parameter is +set to a pointer to the build_id structure. + +@findex check_build_id_file +@subsubsection @code{check_build_id_file} +@strong{Synopsis} +@example +bfd_boolean check_build_id_file + (char *name, unsigned long buildid); +@end example +@strong{Description}@* +Checks to see if @var{name} is a readable file and if its build-id +matches @var{buildid}. + +Returns TRUE if the file exists, is readable, and contains a build-id +which matches @var{build-id}. + +@findex bfd_follow_build_id_debuglink +@subsubsection @code{bfd_follow_build_id_debuglink} +@strong{Synopsis} +@example +char *bfd_follow_build_id_debuglink (bfd *abfd, const char *dir); +@end example +@strong{Description}@* +Takes @var{abfd} and searches it for a .note.gnu.build-id section. +If this section is found, it extracts the value of the NT_GNU_BUILD_ID +note, which should be a hexadecimal value @var{NNNN+NN} (for +32+ hex digits). It then searches the filesystem for a file named +@var{.build-id/NN/NN+NN.debug} in a set of standard locations, +including the directory tree rooted at @var{dir}. The filename +of the first matching file to be found is returned. A matching +file should contain a .note.gnu.build-id section with the same +@var{NNNN+NN} note as @var{abfd}, although this check is currently +not implemented. + +If @var{dir} is NULL, the search will take place starting at +the current directory. + +@strong{Returns}@* +@code{NULL} on any errors or failure to locate the debug file, +otherwise a pointer to a heap-allocated string containing the +filename. The caller is responsible for freeing this string. + |