contrib/binutils-2.17/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 @end example
  97 @strong{Description}@*
  98 Create and return a BFD backed by a read-only @var{stream}.
  99 The @var{stream} is created using @var{open}, accessed using
 100 @var{pread} and destroyed using @var{close}.
 101
 102 Calls @code{bfd_find_target}, so @var{target} is interpreted as by
 103 that function.
 104
 105 Calls @var{open} (which can call @code{bfd_zalloc} and
 106 @code{bfd_get_filename}) to obtain the read-only stream backing
 107 the BFD.  @var{open} either succeeds returning the
 108 non-@code{NULL} @var{stream}, or fails returning @code{NULL}
 109 (setting @code{bfd_error}).
 110
 111 Calls @var{pread} to request @var{nbytes} of data from
 112 @var{stream} starting at @var{offset} (e.g., via a call to
 113 @code{bfd_read}).  @var{pread} either succeeds returning the
 114 number of bytes read (which can be less than @var{nbytes} when
 115 end-of-file), or fails returning -1 (setting @code{bfd_error}).
 116
 117 Calls @var{close} when the BFD is later closed using
 118 @code{bfd_close}.  @var{close} either succeeds returning 0, or
 119 fails returning -1 (setting @code{bfd_error}).
 120
 121 If @code{bfd_openr_iovec} returns @code{NULL} then an error has
 122 occurred.  Possible errors are @code{bfd_error_no_memory},
 123 @code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
 124
 125 @findex bfd_openw
 126 @subsubsection @code{bfd_openw}
 127 @strong{Synopsis}
 128 @example
 129 bfd *bfd_openw (const char *filename, const char *target);
 130 @end example
 131 @strong{Description}@*
 132 Create a BFD, associated with file @var{filename}, using the
 133 file format @var{target}, and return a pointer to it.
 134
 135 Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
 136 @code{bfd_error_invalid_target}.
 137
 138 @findex bfd_close
 139 @subsubsection @code{bfd_close}
 140 @strong{Synopsis}
 141 @example
 142 bfd_boolean bfd_close (bfd *abfd);
 143 @end example
 144 @strong{Description}@*
 145 Close a BFD. If the BFD was open for writing, then pending
 146 operations are completed and the file written out and closed.
 147 If the created file is executable, then @code{chmod} is called
 148 to mark it as such.
 149
 150 All memory attached to the BFD is released.
 151
 152 The file descriptor associated with the BFD is closed (even
 153 if it was passed in to BFD by @code{bfd_fdopenr}).
 154
 155 @strong{Returns}@*
 156 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 157
 158 @findex bfd_close_all_done
 159 @subsubsection @code{bfd_close_all_done}
 160 @strong{Synopsis}
 161 @example
 162 bfd_boolean bfd_close_all_done (bfd *);
 163 @end example
 164 @strong{Description}@*
 165 Close a BFD.  Differs from @code{bfd_close} since it does not
 166 complete any pending operations.  This routine would be used
 167 if the application had just used BFD for swapping and didn't
 168 want to use any of the writing code.
 169
 170 If the created file is executable, then @code{chmod} is called
 171 to mark it as such.
 172
 173 All memory attached to the BFD is released.
 174
 175 @strong{Returns}@*
 176 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 177
 178 @findex bfd_create
 179 @subsubsection @code{bfd_create}
 180 @strong{Synopsis}
 181 @example
 182 bfd *bfd_create (const char *filename, bfd *templ);
 183 @end example
 184 @strong{Description}@*
 185 Create a new BFD in the manner of @code{bfd_openw}, but without
 186 opening a file. The new BFD takes the target from the target
 187 used by @var{template}. The format is always set to @code{bfd_object}.
 188
 189 @findex bfd_make_writable
 190 @subsubsection @code{bfd_make_writable}
 191 @strong{Synopsis}
 192 @example
 193 bfd_boolean bfd_make_writable (bfd *abfd);
 194 @end example
 195 @strong{Description}@*
 196 Takes a BFD as created by @code{bfd_create} and converts it
 197 into one like as returned by @code{bfd_openw}.  It does this
 198 by converting the BFD to BFD_IN_MEMORY.  It's assumed that
 199 you will call @code{bfd_make_readable} on this bfd later.
 200
 201 @strong{Returns}@*
 202 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 203
 204 @findex bfd_make_readable
 205 @subsubsection @code{bfd_make_readable}
 206 @strong{Synopsis}
 207 @example
 208 bfd_boolean bfd_make_readable (bfd *abfd);
 209 @end example
 210 @strong{Description}@*
 211 Takes a BFD as created by @code{bfd_create} and
 212 @code{bfd_make_writable} and converts it into one like as
 213 returned by @code{bfd_openr}.  It does this by writing the
 214 contents out to the memory buffer, then reversing the
 215 direction.
 216
 217 @strong{Returns}@*
 218 @code{TRUE} is returned if all is ok, otherwise @code{FALSE}.
 219
 220 @findex bfd_alloc
 221 @subsubsection @code{bfd_alloc}
 222 @strong{Synopsis}
 223 @example
 224 void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
 225 @end example
 226 @strong{Description}@*
 227 Allocate a block of @var{wanted} bytes of memory attached to
 228 @code{abfd} and return a pointer to it.
 229
 230 @findex bfd_alloc2
 231 @subsubsection @code{bfd_alloc2}
 232 @strong{Synopsis}
 233 @example
 234 void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
 235 @end example
 236 @strong{Description}@*
 237 Allocate a block of @var{nmemb} elements of @var{size} bytes each
 238 of memory attached to @code{abfd} and return a pointer to it.
 239
 240 @findex bfd_zalloc
 241 @subsubsection @code{bfd_zalloc}
 242 @strong{Synopsis}
 243 @example
 244 void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
 245 @end example
 246 @strong{Description}@*
 247 Allocate a block of @var{wanted} bytes of zeroed memory
 248 attached to @code{abfd} and return a pointer to it.
 249
 250 @findex bfd_zalloc2
 251 @subsubsection @code{bfd_zalloc2}
 252 @strong{Synopsis}
 253 @example
 254 void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
 255 @end example
 256 @strong{Description}@*
 257 Allocate a block of @var{nmemb} elements of @var{size} bytes each
 258 of zeroed memory attached to @code{abfd} and return a pointer to it.
 259
 260 @findex bfd_calc_gnu_debuglink_crc32
 261 @subsubsection @code{bfd_calc_gnu_debuglink_crc32}
 262 @strong{Synopsis}
 263 @example
 264 unsigned long bfd_calc_gnu_debuglink_crc32
 265    (unsigned long crc, const unsigned char *buf, bfd_size_type len);
 266 @end example
 267 @strong{Description}@*
 268 Computes a CRC value as used in the .gnu_debuglink section.
 269 Advances the previously computed @var{crc} value by computing
 270 and adding in the crc32 for @var{len} bytes of @var{buf}.
 271
 272 @strong{Returns}@*
 273 Return the updated CRC32 value.
 274
 275 @findex get_debug_link_info
 276 @subsubsection @code{get_debug_link_info}
 277 @strong{Synopsis}
 278 @example
 279 char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
 280 @end example
 281 @strong{Description}@*
 282 fetch the filename and CRC32 value for any separate debuginfo
 283 associated with @var{abfd}. Return NULL if no such info found,
 284 otherwise return filename and update @var{crc32_out}.
 285
 286 @findex separate_debug_file_exists
 287 @subsubsection @code{separate_debug_file_exists}
 288 @strong{Synopsis}
 289 @example
 290 bfd_boolean separate_debug_file_exists
 291    (char *name, unsigned long crc32);
 292 @end example
 293 @strong{Description}@*
 294 Checks to see if @var{name} is a file and if its contents
 295 match @var{crc32}.
 296
 297 @findex find_separate_debug_file
 298 @subsubsection @code{find_separate_debug_file}
 299 @strong{Synopsis}
 300 @example
 301 char *find_separate_debug_file (bfd *abfd);
 302 @end example
 303 @strong{Description}@*
 304 Searches @var{abfd} for a reference to separate debugging
 305 information, scans various locations in the filesystem, including
 306 the file tree rooted at @var{debug_file_directory}, and returns a
 307 filename of such debugging information if the file is found and has
 308 matching CRC32.  Returns NULL if no reference to debugging file
 309 exists, or file cannot be found.
 310
 311 @findex bfd_follow_gnu_debuglink
 312 @subsubsection @code{bfd_follow_gnu_debuglink}
 313 @strong{Synopsis}
 314 @example
 315 char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
 316 @end example
 317 @strong{Description}@*
 318 Takes a BFD and searches it for a .gnu_debuglink section.  If this
 319 section is found, it examines the section for the name and checksum
 320 of a '.debug' file containing auxiliary debugging information.  It
 321 then searches the filesystem for this .debug file in some standard
 322 locations, including the directory tree rooted at @var{dir}, and if
 323 found returns the full filename.
 324
 325 If @var{dir} is NULL, it will search a default path configured into
 326 libbfd at build time.  [XXX this feature is not currently
 327 implemented].
 328
 329 @strong{Returns}@*
 330 @code{NULL} on any errors or failure to locate the .debug file,
 331 otherwise a pointer to a heap-allocated string containing the
 332 filename.  The caller is responsible for freeing this string.
 333
 334 @findex bfd_create_gnu_debuglink_section
 335 @subsubsection @code{bfd_create_gnu_debuglink_section}
 336 @strong{Synopsis}
 337 @example
 338 struct bfd_section *bfd_create_gnu_debuglink_section
 339    (bfd *abfd, const char *filename);
 340 @end example
 341 @strong{Description}@*
 342 Takes a @var{BFD} and adds a .gnu_debuglink section to it.  The section is sized
 343 to be big enough to contain a link to the specified @var{filename}.
 344
 345 @strong{Returns}@*
 346 A pointer to the new section is returned if all is ok.  Otherwise @code{NULL} is
 347 returned and bfd_error is set.
 348
 349 @findex bfd_fill_in_gnu_debuglink_section
 350 @subsubsection @code{bfd_fill_in_gnu_debuglink_section}
 351 @strong{Synopsis}
 352 @example
 353 bfd_boolean bfd_fill_in_gnu_debuglink_section
 354    (bfd *abfd, struct bfd_section *sect, const char *filename);
 355 @end example
 356 @strong{Description}@*
 357 Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
 358 and fills in the contents of the section to contain a link to the
 359 specified @var{filename}.  The filename should be relative to the
 360 current directory.
 361
 362 @strong{Returns}@*
 363 @code{TRUE} is returned if all is ok.  Otherwise @code{FALSE} is returned
 364 and bfd_error is set.
 365