diff options
Diffstat (limited to 'binutils-2.17/bfd/doc/opncls.texi')
-rw-r--r-- | binutils-2.17/bfd/doc/opncls.texi | 365 |
1 files changed, 0 insertions, 365 deletions
diff --git a/binutils-2.17/bfd/doc/opncls.texi b/binutils-2.17/bfd/doc/opncls.texi deleted file mode 100644 index 6b47adfb..00000000 --- a/binutils-2.17/bfd/doc/opncls.texi +++ /dev/null @@ -1,365 +0,0 @@ -@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. - -@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_openr_iovec -@subsubsection @code{bfd_openr_iovec} -@strong{Synopsis} -@example -bfd *bfd_openr_iovec (const char *filename, const char *target, - void *(*open) (struct bfd *nbfd, - void *open_closure), - void *open_closure, - file_ptr (*pread) (struct bfd *nbfd, - void *stream, - void *buf, - file_ptr nbytes, - file_ptr offset), - int (*close) (struct bfd *nbfd, - void *stream)); -@end example -@strong{Description}@* -Create and return a BFD backed by a read-only @var{stream}. -The @var{stream} is created using @var{open}, accessed using -@var{pread} and destroyed using @var{close}. - -Calls @code{bfd_find_target}, so @var{target} is interpreted as by -that function. - -Calls @var{open} (which can call @code{bfd_zalloc} and -@code{bfd_get_filename}) to obtain the read-only stream backing -the BFD. @var{open} either succeeds returning the -non-@code{NULL} @var{stream}, or fails returning @code{NULL} -(setting @code{bfd_error}). - -Calls @var{pread} to request @var{nbytes} of data from -@var{stream} starting at @var{offset} (e.g., via a call to -@code{bfd_read}). @var{pread} 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} when the BFD is later closed using -@code{bfd_close}. @var{close} either succeeds returning 0, or -fails returning -1 (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}. - -@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, 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 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. - |