bfd/doc/opncls.texi

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