diff options
Diffstat (limited to 'contrib/binutils/bfd/doc/opncls.texi')
-rw-r--r-- | contrib/binutils/bfd/doc/opncls.texi | 265 |
1 files changed, 0 insertions, 265 deletions
diff --git a/contrib/binutils/bfd/doc/opncls.texi b/contrib/binutils/bfd/doc/opncls.texi deleted file mode 100644 index 8cd2ab9..0000000 --- a/contrib/binutils/bfd/doc/opncls.texi +++ /dev/null @@ -1,265 +0,0 @@ -@section Opening and closing BFDs - - -@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. - -@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}. - -@findex bfd_openstreamr -@subsubsection @code{bfd_openstreamr} -@strong{Synopsis} -@example -bfd *bfd_openstreamr (const char *, const char *, void *); -@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. - -@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}. - -@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{template}. The format is always set to @code{bfd_object}. - -@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, size_t 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_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 get_debug_link_info -@subsubsection @code{get_debug_link_info} -@strong{Synopsis} -@example -char *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}. - -@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 find_separate_debug_file -@subsubsection @code{find_separate_debug_file} -@strong{Synopsis} -@example -char *find_separate_debug_file (bfd *abfd); -@end example -@strong{Description}@* -Searches @var{abfd} for a reference to separate debugging -information, scans various locations in the filesystem, including -the file tree rooted at @var{debug_file_directory}, and returns a -filename of such debugging information if the file is found and has -matching CRC32. Returns NULL if no reference to debugging file -exists, or file cannot 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, it will search a default path configured into -libbfd at build time. [XXX this feature is not currently -implemented]. - -@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. - |