contrib/binutils/bfd/doc/opncls.texi

   1 @section Opening and closing BFDs
   2
   3
   4 @findex bfd_openr
   5 @subsubsection @code{bfd_openr}
   6 @strong{Synopsis}
   7 @example
   8 bfd *bfd_openr (const char *filename, const char *target);
   9 @end example
  10 @strong{Description}@*
  11 Open the file @var{filename} (using @code{fopen}) with the target
  12 @var{target}.  Return a pointer to the created BFD.
  13
  14 Calls @code{bfd_find_target}, so @var{target} is interpreted as by
  15 that function.
  16
  17 If @code{NULL} is returned then an error has occured.   Possible errors
  18 are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
  19 @code{system_call} error.
  20
  21 @findex bfd_fdopenr
  22 @subsubsection @code{bfd_fdopenr}
  23 @strong{Synopsis}
  24 @example
  25 bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
  26 @end example
  27 @strong{Description}@*
  28 @code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to
  29 @code{fopen}.  It opens a BFD on a file already described by the
  30 @var{fd} supplied.
  31
  32 When the file is later @code{bfd_close}d, the file descriptor will
  33 be closed.  If the caller desires that this file descriptor be
  34 cached by BFD (opened as needed, closed as needed to free
  35 descriptors for other opens), with the supplied @var{fd} used as
  36 an initial file descriptor (but subject to closure at any time),
  37 call bfd_set_cacheable(bfd, 1) on the returned BFD.  The default
  38 is to assume no caching; the file descriptor will remain open
  39 until @code{bfd_close}, and will not be affected by BFD operations
  40 on other files.
  41
  42 Possible errors are @code{bfd_error_no_memory},
  43 @code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
  44
  45 @findex bfd_openstreamr
  46 @subsubsection @code{bfd_openstreamr}
  47 @strong{Synopsis}
  48 @example
  49 bfd *bfd_openstreamr (const char *, const char *, void *);
  50 @end example
  51 @strong{Description}@*
  52 Open a BFD for read access on an existing stdio stream.  When
  53 the BFD is passed to @code{bfd_close}, the stream will be closed.
  54
  55 @findex bfd_openw
  56 @subsubsection @code{bfd_openw}
  57 @strong{Synopsis}
  58 @example
  59 bfd *bfd_openw (const char *filename, const char *target);
  60 @end example
  61 @strong{Description}@*
  62 Create a BFD, associated with file @var{filename}, using the
  63 file format @var{target}, and return a pointer to it.
  64
  65 Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
  66 @code{bfd_error_invalid_target}.
  67
  68 @findex bfd_close
  69 @subsubsection @code{bfd_close}
  70 @strong{Synopsis}
  71 @example
  72 bfd_boolean bfd_close (bfd *abfd);
  73 @end example
  74 @strong{Description}@*
  75 Close a BFD. If the BFD was open for writing, then pending
  76 operations are completed and the file written out and closed.
  77 If the created file is executable, then @code{chmod} is called
  78 to mark it as such.
  79
  80 All memory attached to the BFD is released.
  81
  82 The file descriptor associated with the BFD is closed (even
  83 if it was passed in to BFD by @code{bfd_fdopenr}).
  84
  85 @strong{Returns}@*
  86 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
  87
  88 @findex bfd_close_all_done
  89 @subsubsection @code{bfd_close_all_done}
  90 @strong{Synopsis}
  91 @example
  92 bfd_boolean bfd_close_all_done (bfd *);
  93 @end example
  94 @strong{Description}@*
  95 Close a BFD.  Differs from @code{bfd_close} since it does not
  96 complete any pending operations.  This routine would be used
  97 if the application had just used BFD for swapping and didn't
  98 want to use any of the writing code.
  99
 100 If the created file is executable, then @code{chmod} is called
 101 to mark it as such.
 102
 103 All memory attached to the BFD is released.
 104
 105 @strong{Returns}@*
 106 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 107
 108 @findex bfd_create
 109 @subsubsection @code{bfd_create}
 110 @strong{Synopsis}
 111 @example
 112 bfd *bfd_create (const char *filename, bfd *templ);
 113 @end example
 114 @strong{Description}@*
 115 Create a new BFD in the manner of @code{bfd_openw}, but without
 116 opening a file. The new BFD takes the target from the target
 117 used by @var{template}. The format is always set to @code{bfd_object}.
 118
 119 @findex bfd_make_writable
 120 @subsubsection @code{bfd_make_writable}
 121 @strong{Synopsis}
 122 @example
 123 bfd_boolean bfd_make_writable (bfd *abfd);
 124 @end example
 125 @strong{Description}@*
 126 Takes a BFD as created by @code{bfd_create} and converts it
 127 into one like as returned by @code{bfd_openw}.  It does this
 128 by converting the BFD to BFD_IN_MEMORY.  It's assumed that
 129 you will call @code{bfd_make_readable} on this bfd later.
 130
 131 @strong{Returns}@*
 132 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 133
 134 @findex bfd_make_readable
 135 @subsubsection @code{bfd_make_readable}
 136 @strong{Synopsis}
 137 @example
 138 bfd_boolean bfd_make_readable (bfd *abfd);
 139 @end example
 140 @strong{Description}@*
 141 Takes a BFD as created by @code{bfd_create} and
 142 @code{bfd_make_writable} and converts it into one like as
 143 returned by @code{bfd_openr}.  It does this by writing the
 144 contents out to the memory buffer, then reversing the
 145 direction.
 146
 147 @strong{Returns}@*
 148 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 149
 150 @findex bfd_alloc
 151 @subsubsection @code{bfd_alloc}
 152 @strong{Synopsis}
 153 @example
 154 void *bfd_alloc (bfd *abfd, size_t wanted);
 155 @end example
 156 @strong{Description}@*
 157 Allocate a block of @var{wanted} bytes of memory attached to
 158 @code{abfd} and return a pointer to it.
 159
 160 @findex bfd_calc_gnu_debuglink_crc32
 161 @subsubsection @code{bfd_calc_gnu_debuglink_crc32}
 162 @strong{Synopsis}
 163 @example
 164 unsigned long bfd_calc_gnu_debuglink_crc32
 165    (unsigned long crc, const unsigned char *buf, bfd_size_type len);
 166 @end example
 167 @strong{Description}@*
 168 Computes a CRC value as used in the .gnu_debuglink section.
 169 Advances the previously computed @var{crc} value by computing
 170 and adding in the crc32 for @var{len} bytes of @var{buf}.
 171
 172 @strong{Returns}@*
 173 Return the updated CRC32 value.
 174
 175 @findex get_debug_link_info
 176 @subsubsection @code{get_debug_link_info}
 177 @strong{Synopsis}
 178 @example
 179 char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
 180 @end example
 181 @strong{Description}@*
 182 fetch the filename and CRC32 value for any separate debuginfo
 183 associated with @var{abfd}. Return NULL if no such info found,
 184 otherwise return filename and update @var{crc32_out}.
 185
 186 @findex separate_debug_file_exists
 187 @subsubsection @code{separate_debug_file_exists}
 188 @strong{Synopsis}
 189 @example
 190 bfd_boolean separate_debug_file_exists
 191    (char *name, unsigned long crc32);
 192 @end example
 193 @strong{Description}@*
 194 Checks to see if @var{name} is a file and if its contents
 195 match @var{crc32}.
 196
 197 @findex find_separate_debug_file
 198 @subsubsection @code{find_separate_debug_file}
 199 @strong{Synopsis}
 200 @example
 201 char *find_separate_debug_file (bfd *abfd);
 202 @end example
 203 @strong{Description}@*
 204 Searches @var{abfd} for a reference to separate debugging
 205 information, scans various locations in the filesystem, including
 206 the file tree rooted at @var{debug_file_directory}, and returns a
 207 filename of such debugging information if the file is found and has
 208 matching CRC32.  Returns NULL if no reference to debugging file
 209 exists, or file cannot be found.
 210
 211 @findex bfd_follow_gnu_debuglink
 212 @subsubsection @code{bfd_follow_gnu_debuglink}
 213 @strong{Synopsis}
 214 @example
 215 char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
 216 @end example
 217 @strong{Description}@*
 218 Takes a BFD and searches it for a .gnu_debuglink section.  If this
 219 section is found, it examines the section for the name and checksum
 220 of a '.debug' file containing auxiliary debugging information.  It
 221 then searches the filesystem for this .debug file in some standard
 222 locations, including the directory tree rooted at @var{dir}, and if
 223 found returns the full filename.
 224
 225 If @var{dir} is NULL, it will search a default path configured into
 226 libbfd at build time.  [XXX this feature is not currently
 227 implemented].
 228
 229 @strong{Returns}@*
 230 @code{NULL} on any errors or failure to locate the .debug file,
 231 otherwise a pointer to a heap-allocated string containing the
 232 filename.  The caller is responsible for freeing this string.
 233
 234 @findex bfd_create_gnu_debuglink_section
 235 @subsubsection @code{bfd_create_gnu_debuglink_section}
 236 @strong{Synopsis}
 237 @example
 238 struct bfd_section *bfd_create_gnu_debuglink_section
 239    (bfd *abfd, const char *filename);
 240 @end example
 241 @strong{Description}@*
 242 Takes a @var{BFD} and adds a .gnu_debuglink section to it.  The section is sized
 243 to be big enough to contain a link to the specified @var{filename}.
 244
 245 @strong{Returns}@*
 246 A pointer to the new section is returned if all is ok.  Otherwise @code{NULL} is
 247 returned and bfd_error is set.
 248
 249 @findex bfd_fill_in_gnu_debuglink_section
 250 @subsubsection @code{bfd_fill_in_gnu_debuglink_section}
 251 @strong{Synopsis}
 252 @example
 253 bfd_boolean bfd_fill_in_gnu_debuglink_section
 254    (bfd *abfd, struct bfd_section *sect, const char *filename);
 255 @end example
 256 @strong{Description}@*
 257 Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
 258 and fills in the contents of the section to contain a link to the
 259 specified @var{filename}.  The filename should be relative to the
 260 current directory.
 261
 262 @strong{Returns}@*
 263 @code{TRUE} is returned if all is ok.  Otherwise @code{FALSE} is returned
 264 and bfd_error is set.
 265