bfd/doc/opncls.texi

   1
   2 @example
   3 /* Set to N to open the next N BFDs using an alternate id space.  */
   4 extern unsigned int bfd_use_reserved_id;
   5 @end example
   6 @section Opening and closing BFDs
   7
   8
   9 @subsection Functions for opening and closing
  10
  11
  12 @findex bfd_fopen
  13 @subsubsection @code{bfd_fopen}
  14 @strong{Synopsis}
  15 @example
  16 bfd *bfd_fopen (const char *filename, const char *target,
  17     const char *mode, int fd);
  18 @end example
  19 @strong{Description}@*
  20 Open the file @var{filename} with the target @var{target}.
  21 Return a pointer to the created BFD.  If @var{fd} is not -1,
  22 then @code{fdopen} is used to open the file; otherwise, @code{fopen}
  23 is used.  @var{mode} is passed directly to @code{fopen} or
  24 @code{fdopen}.
  25
  26 Calls @code{bfd_find_target}, so @var{target} is interpreted as by
  27 that function.
  28
  29 The new BFD is marked as cacheable iff @var{fd} is -1.
  30
  31 If @code{NULL} is returned then an error has occured.   Possible errors
  32 are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
  33 @code{system_call} error.
  34
  35 On error, @var{fd} is always closed.
  36
  37 A copy of the @var{filename} argument is stored in the newly created
  38 BFD.  It can be accessed via the bfd_get_filename() macro.
  39
  40 @findex bfd_openr
  41 @subsubsection @code{bfd_openr}
  42 @strong{Synopsis}
  43 @example
  44 bfd *bfd_openr (const char *filename, const char *target);
  45 @end example
  46 @strong{Description}@*
  47 Open the file @var{filename} (using @code{fopen}) with the target
  48 @var{target}.  Return a pointer to the created BFD.
  49
  50 Calls @code{bfd_find_target}, so @var{target} is interpreted as by
  51 that function.
  52
  53 If @code{NULL} is returned then an error has occured.   Possible errors
  54 are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or
  55 @code{system_call} error.
  56
  57 A copy of the @var{filename} argument is stored in the newly created
  58 BFD.  It can be accessed via the bfd_get_filename() macro.
  59
  60 @findex bfd_fdopenr
  61 @subsubsection @code{bfd_fdopenr}
  62 @strong{Synopsis}
  63 @example
  64 bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
  65 @end example
  66 @strong{Description}@*
  67 @code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to
  68 @code{fopen}.  It opens a BFD on a file already described by the
  69 @var{fd} supplied.
  70
  71 When the file is later @code{bfd_close}d, the file descriptor will
  72 be closed.  If the caller desires that this file descriptor be
  73 cached by BFD (opened as needed, closed as needed to free
  74 descriptors for other opens), with the supplied @var{fd} used as
  75 an initial file descriptor (but subject to closure at any time),
  76 call bfd_set_cacheable(bfd, 1) on the returned BFD.  The default
  77 is to assume no caching; the file descriptor will remain open
  78 until @code{bfd_close}, and will not be affected by BFD operations
  79 on other files.
  80
  81 Possible errors are @code{bfd_error_no_memory},
  82 @code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
  83
  84 On error, @var{fd} is closed.
  85
  86 A copy of the @var{filename} argument is stored in the newly created
  87 BFD.  It can be accessed via the bfd_get_filename() macro.
  88
  89 @findex bfd_openstreamr
  90 @subsubsection @code{bfd_openstreamr}
  91 @strong{Synopsis}
  92 @example
  93 bfd *bfd_openstreamr (const char * filename, const char * target, void * stream);
  94 @end example
  95 @strong{Description}@*
  96 Open a BFD for read access on an existing stdio stream.  When
  97 the BFD is passed to @code{bfd_close}, the stream will be closed.
  98
  99 A copy of the @var{filename} argument is stored in the newly created
 100 BFD.  It can be accessed via the bfd_get_filename() macro.
 101
 102 @findex bfd_openr_iovec
 103 @subsubsection @code{bfd_openr_iovec}
 104 @strong{Synopsis}
 105 @example
 106 bfd *bfd_openr_iovec (const char *filename, const char *target,
 107     void *(*open_func) (struct bfd *nbfd,
 108     void *open_closure),
 109     void *open_closure,
 110     file_ptr (*pread_func) (struct bfd *nbfd,
 111     void *stream,
 112     void *buf,
 113     file_ptr nbytes,
 114     file_ptr offset),
 115     int (*close_func) (struct bfd *nbfd,
 116     void *stream),
 117     int (*stat_func) (struct bfd *abfd,
 118     void *stream,
 119     struct stat *sb));
 120 @end example
 121 @strong{Description}@*
 122 Create and return a BFD backed by a read-only @var{stream}.
 123 The @var{stream} is created using @var{open_func}, accessed using
 124 @var{pread_func} and destroyed using @var{close_func}.
 125
 126 Calls @code{bfd_find_target}, so @var{target} is interpreted as by
 127 that function.
 128
 129 Calls @var{open_func} (which can call @code{bfd_zalloc} and
 130 @code{bfd_get_filename}) to obtain the read-only stream backing
 131 the BFD.  @var{open_func} either succeeds returning the
 132 non-@code{NULL} @var{stream}, or fails returning @code{NULL}
 133 (setting @code{bfd_error}).
 134
 135 Calls @var{pread_func} to request @var{nbytes} of data from
 136 @var{stream} starting at @var{offset} (e.g., via a call to
 137 @code{bfd_read}).  @var{pread_func} either succeeds returning the
 138 number of bytes read (which can be less than @var{nbytes} when
 139 end-of-file), or fails returning -1 (setting @code{bfd_error}).
 140
 141 Calls @var{close_func} when the BFD is later closed using
 142 @code{bfd_close}.  @var{close_func} either succeeds returning 0, or
 143 fails returning -1 (setting @code{bfd_error}).
 144
 145 Calls @var{stat_func} to fill in a stat structure for bfd_stat,
 146 bfd_get_size, and bfd_get_mtime calls.  @var{stat_func} returns 0
 147 on success, or returns -1 on failure (setting @code{bfd_error}).
 148
 149 If @code{bfd_openr_iovec} returns @code{NULL} then an error has
 150 occurred.  Possible errors are @code{bfd_error_no_memory},
 151 @code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
 152
 153 A copy of the @var{filename} argument is stored in the newly created
 154 BFD.  It can be accessed via the bfd_get_filename() macro.
 155
 156 @findex bfd_openw
 157 @subsubsection @code{bfd_openw}
 158 @strong{Synopsis}
 159 @example
 160 bfd *bfd_openw (const char *filename, const char *target);
 161 @end example
 162 @strong{Description}@*
 163 Create a BFD, associated with file @var{filename}, using the
 164 file format @var{target}, and return a pointer to it.
 165
 166 Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
 167 @code{bfd_error_invalid_target}.
 168
 169 A copy of the @var{filename} argument is stored in the newly created
 170 BFD.  It can be accessed via the bfd_get_filename() macro.
 171
 172 @findex bfd_close
 173 @subsubsection @code{bfd_close}
 174 @strong{Synopsis}
 175 @example
 176 bfd_boolean bfd_close (bfd *abfd);
 177 @end example
 178 @strong{Description}@*
 179 Close a BFD. If the BFD was open for writing, then pending
 180 operations are completed and the file written out and closed.
 181 If the created file is executable, then @code{chmod} is called
 182 to mark it as such.
 183
 184 All memory attached to the BFD is released.
 185
 186 The file descriptor associated with the BFD is closed (even
 187 if it was passed in to BFD by @code{bfd_fdopenr}).
 188
 189 @strong{Returns}@*
 190 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 191
 192 @findex bfd_close_all_done
 193 @subsubsection @code{bfd_close_all_done}
 194 @strong{Synopsis}
 195 @example
 196 bfd_boolean bfd_close_all_done (bfd *);
 197 @end example
 198 @strong{Description}@*
 199 Close a BFD.  Differs from @code{bfd_close} since it does not
 200 complete any pending operations.  This routine would be used
 201 if the application had just used BFD for swapping and didn't
 202 want to use any of the writing code.
 203
 204 If the created file is executable, then @code{chmod} is called
 205 to mark it as such.
 206
 207 All memory attached to the BFD is released.
 208
 209 @strong{Returns}@*
 210 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 211
 212 @findex bfd_create
 213 @subsubsection @code{bfd_create}
 214 @strong{Synopsis}
 215 @example
 216 bfd *bfd_create (const char *filename, bfd *templ);
 217 @end example
 218 @strong{Description}@*
 219 Create a new BFD in the manner of @code{bfd_openw}, but without
 220 opening a file. The new BFD takes the target from the target
 221 used by @var{templ}. The format is always set to @code{bfd_object}.
 222
 223 A copy of the @var{filename} argument is stored in the newly created
 224 BFD.  It can be accessed via the bfd_get_filename() macro.
 225
 226 @findex bfd_make_writable
 227 @subsubsection @code{bfd_make_writable}
 228 @strong{Synopsis}
 229 @example
 230 bfd_boolean bfd_make_writable (bfd *abfd);
 231 @end example
 232 @strong{Description}@*
 233 Takes a BFD as created by @code{bfd_create} and converts it
 234 into one like as returned by @code{bfd_openw}.  It does this
 235 by converting the BFD to BFD_IN_MEMORY.  It's assumed that
 236 you will call @code{bfd_make_readable} on this bfd later.
 237
 238 @strong{Returns}@*
 239 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 240
 241 @findex bfd_make_readable
 242 @subsubsection @code{bfd_make_readable}
 243 @strong{Synopsis}
 244 @example
 245 bfd_boolean bfd_make_readable (bfd *abfd);
 246 @end example
 247 @strong{Description}@*
 248 Takes a BFD as created by @code{bfd_create} and
 249 @code{bfd_make_writable} and converts it into one like as
 250 returned by @code{bfd_openr}.  It does this by writing the
 251 contents out to the memory buffer, then reversing the
 252 direction.
 253
 254 @strong{Returns}@*
 255 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 256
 257 @findex bfd_alloc
 258 @subsubsection @code{bfd_alloc}
 259 @strong{Synopsis}
 260 @example
 261 void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
 262 @end example
 263 @strong{Description}@*
 264 Allocate a block of @var{wanted} bytes of memory attached to
 265 @code{abfd} and return a pointer to it.
 266
 267 @findex bfd_alloc2
 268 @subsubsection @code{bfd_alloc2}
 269 @strong{Synopsis}
 270 @example
 271 void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
 272 @end example
 273 @strong{Description}@*
 274 Allocate a block of @var{nmemb} elements of @var{size} bytes each
 275 of memory attached to @code{abfd} and return a pointer to it.
 276
 277 @findex bfd_zalloc
 278 @subsubsection @code{bfd_zalloc}
 279 @strong{Synopsis}
 280 @example
 281 void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
 282 @end example
 283 @strong{Description}@*
 284 Allocate a block of @var{wanted} bytes of zeroed memory
 285 attached to @code{abfd} and return a pointer to it.
 286
 287 @findex bfd_zalloc2
 288 @subsubsection @code{bfd_zalloc2}
 289 @strong{Synopsis}
 290 @example
 291 void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
 292 @end example
 293 @strong{Description}@*
 294 Allocate a block of @var{nmemb} elements of @var{size} bytes each
 295 of zeroed memory attached to @code{abfd} and return a pointer to it.
 296
 297 @findex bfd_calc_gnu_debuglink_crc32
 298 @subsubsection @code{bfd_calc_gnu_debuglink_crc32}
 299 @strong{Synopsis}
 300 @example
 301 unsigned long bfd_calc_gnu_debuglink_crc32
 302    (unsigned long crc, const unsigned char *buf, bfd_size_type len);
 303 @end example
 304 @strong{Description}@*
 305 Computes a CRC value as used in the .gnu_debuglink section.
 306 Advances the previously computed @var{crc} value by computing
 307 and adding in the crc32 for @var{len} bytes of @var{buf}.
 308
 309 @strong{Returns}@*
 310 Return the updated CRC32 value.
 311
 312 @findex bfd_get_debug_link_info
 313 @subsubsection @code{bfd_get_debug_link_info}
 314 @strong{Synopsis}
 315 @example
 316 char *bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
 317 @end example
 318 @strong{Description}@*
 319 Fetch the filename and CRC32 value for any separate debuginfo
 320 associated with @var{abfd}.  Return NULL if no such info found,
 321 otherwise return filename and update @var{crc32_out}.  The
 322 returned filename is allocated with @code{malloc}; freeing it
 323 is the responsibility of the caller.
 324
 325 @findex bfd_get_alt_debug_link_info
 326 @subsubsection @code{bfd_get_alt_debug_link_info}
 327 @strong{Synopsis}
 328 @example
 329 char *bfd_get_alt_debug_link_info (bfd * abfd,
 330     bfd_size_type *buildid_len,
 331     bfd_byte **buildid_out);
 332 @end example
 333 @strong{Description}@*
 334 Fetch the filename and BuildID value for any alternate debuginfo
 335 associated with @var{abfd}.  Return NULL if no such info found,
 336 otherwise return filename and update @var{buildid_len} and
 337 @var{buildid_out}.  The returned filename and build_id are
 338 allocated with @code{malloc}; freeing them is the
 339 responsibility of the caller.
 340
 341 @findex separate_debug_file_exists
 342 @subsubsection @code{separate_debug_file_exists}
 343 @strong{Synopsis}
 344 @example
 345 bfd_boolean separate_debug_file_exists
 346    (char *name, unsigned long crc32);
 347 @end example
 348 @strong{Description}@*
 349 Checks to see if @var{name} is a file and if its contents
 350 match @var{crc32}.
 351
 352 @findex separate_alt_debug_file_exists
 353 @subsubsection @code{separate_alt_debug_file_exists}
 354 @strong{Synopsis}
 355 @example
 356 bfd_boolean separate_alt_debug_file_exists
 357    (char *name, unsigned long crc32);
 358 @end example
 359 @strong{Description}@*
 360 Checks to see if @var{name} is a file and if its BuildID
 361 matches @var{buildid}.
 362
 363 @findex find_separate_debug_file
 364 @subsubsection @code{find_separate_debug_file}
 365 @strong{Synopsis}
 366 @example
 367 char *find_separate_debug_file (bfd *abfd);
 368 @end example
 369 @strong{Description}@*
 370 Searches @var{abfd} for a section called @var{section_name} which
 371 is expected to contain a reference to a file containing separate
 372 debugging information.  The function scans various locations in
 373 the filesystem, including the file tree rooted at
 374 @var{debug_file_directory}, and returns the first matching
 375 filename that it finds.  If @var{check_crc} is TRUE then the
 376 contents of the file must also match the CRC value contained in
 377 @var{section_name}.  Returns NULL if no valid file could be found.
 378
 379 @findex bfd_follow_gnu_debuglink
 380 @subsubsection @code{bfd_follow_gnu_debuglink}
 381 @strong{Synopsis}
 382 @example
 383 char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
 384 @end example
 385 @strong{Description}@*
 386 Takes a BFD and searches it for a .gnu_debuglink section.  If this
 387 section is found, it examines the section for the name and checksum
 388 of a '.debug' file containing auxiliary debugging information.  It
 389 then searches the filesystem for this .debug file in some standard
 390 locations, including the directory tree rooted at @var{dir}, and if
 391 found returns the full filename.
 392
 393 If @var{dir} is NULL, it will search a default path configured into
 394 libbfd at build time.  [XXX this feature is not currently
 395 implemented].
 396
 397 @strong{Returns}@*
 398 @code{NULL} on any errors or failure to locate the .debug file,
 399 otherwise a pointer to a heap-allocated string containing the
 400 filename.  The caller is responsible for freeing this string.
 401
 402 @findex bfd_follow_gnu_debugaltlink
 403 @subsubsection @code{bfd_follow_gnu_debugaltlink}
 404 @strong{Synopsis}
 405 @example
 406 char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir);
 407 @end example
 408 @strong{Description}@*
 409 Takes a BFD and searches it for a .gnu_debugaltlink section.  If this
 410 section is found, it examines the section for the name of a file
 411 containing auxiliary debugging information.  It then searches the
 412 filesystem for this file in a set of standard locations, including
 413 the directory tree rooted at @var{dir}, and if found returns the
 414 full filename.
 415
 416 If @var{dir} is NULL, it will search a default path configured into
 417 libbfd at build time.  [FIXME: This feature is not currently
 418 implemented].
 419
 420 @strong{Returns}@*
 421 @code{NULL} on any errors or failure to locate the debug file,
 422 otherwise a pointer to a heap-allocated string containing the
 423 filename.  The caller is responsible for freeing this string.
 424
 425 @findex bfd_create_gnu_debuglink_section
 426 @subsubsection @code{bfd_create_gnu_debuglink_section}
 427 @strong{Synopsis}
 428 @example
 429 struct bfd_section *bfd_create_gnu_debuglink_section
 430    (bfd *abfd, const char *filename);
 431 @end example
 432 @strong{Description}@*
 433 Takes a @var{BFD} and adds a .gnu_debuglink section to it.  The section is sized
 434 to be big enough to contain a link to the specified @var{filename}.
 435
 436 @strong{Returns}@*
 437 A pointer to the new section is returned if all is ok.  Otherwise @code{NULL} is
 438 returned and bfd_error is set.
 439
 440 @findex bfd_fill_in_gnu_debuglink_section
 441 @subsubsection @code{bfd_fill_in_gnu_debuglink_section}
 442 @strong{Synopsis}
 443 @example
 444 bfd_boolean bfd_fill_in_gnu_debuglink_section
 445    (bfd *abfd, struct bfd_section *sect, const char *filename);
 446 @end example
 447 @strong{Description}@*
 448 Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
 449 and fills in the contents of the section to contain a link to the
 450 specified @var{filename}.  The filename should be relative to the
 451 current directory.
 452
 453 @strong{Returns}@*
 454 @code{TRUE} is returned if all is ok.  Otherwise @code{FALSE} is returned
 455 and bfd_error is set.
 456