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 @code{system_call} error.
  19
  20 @findex bfd_fdopenr
  21 @subsubsection @code{bfd_fdopenr}
  22 @strong{Synopsis}
  23 @example
  24 bfd *bfd_fdopenr(const char *filename, const char *target, int fd);
  25 @end example
  26 @strong{Description}@*
  27 @code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to @code{fopen}.
  28 It opens a BFD on a file already described by the @var{fd}
  29 supplied.
  30
  31 When the file is later @code{bfd_close}d, the file descriptor will be closed.
  32
  33 If the caller desires that this file descriptor be cached by BFD
  34 (opened as needed, closed as needed to free descriptors for
  35 other opens), with the supplied @var{fd} used as an initial
  36 file descriptor (but subject to closure at any time), call
  37 bfd_set_cacheable(bfd, 1) on the returned BFD.  The default is to
  38 assume no cacheing; the file descriptor will remain open until
  39 @code{bfd_close}, and will not be affected by BFD operations on other
  40 files.
  41
  42 Possible errors are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} and @code{bfd_error_system_call}.
  43
  44 @findex bfd_openstreamr
  45 @subsubsection @code{bfd_openstreamr}
  46 @strong{Synopsis}
  47 @example
  48 bfd *bfd_openstreamr(const char *, const char *, PTR);
  49 @end example
  50 @strong{Description}@*
  51 Open a BFD for read access on an existing stdio stream.  When
  52 the BFD is passed to @code{bfd_close}, the stream will be closed.
  53
  54 @findex bfd_openw
  55 @subsubsection @code{bfd_openw}
  56 @strong{Synopsis}
  57 @example
  58 bfd *bfd_openw(const char *filename, const char *target);
  59 @end example
  60 @strong{Description}@*
  61 Create a BFD, associated with file @var{filename}, using the
  62 file format @var{target}, and return a pointer to it.
  63
  64 Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory},
  65 @code{bfd_error_invalid_target}.
  66
  67 @findex bfd_close
  68 @subsubsection @code{bfd_close}
  69 @strong{Synopsis}
  70 @example
  71 boolean bfd_close(bfd *abfd);
  72 @end example
  73 @strong{Description}@*
  74 Close a BFD. If the BFD was open for writing,
  75 then pending operations are completed and the file written out
  76 and closed. If the created file is executable, then
  77 @code{chmod} is called to mark it as such.
  78
  79 All memory attached to the BFD is released.
  80
  81 The file descriptor associated with the BFD is closed (even
  82 if it was passed in to BFD by @code{bfd_fdopenr}).
  83
  84 @strong{Returns}@*
  85 @code{true} is returned if all is ok, otherwise @code{false}.
  86
  87 @findex bfd_close_all_done
  88 @subsubsection @code{bfd_close_all_done}
  89 @strong{Synopsis}
  90 @example
  91 boolean bfd_close_all_done(bfd *);
  92 @end example
  93 @strong{Description}@*
  94 Close a BFD.  Differs from @code{bfd_close}
  95 since it does not complete any pending operations.  This
  96 routine would be used if the application had just used BFD for
  97 swapping and didn't want to use any of the writing code.
  98
  99 If the created file is executable, then @code{chmod} is called
 100 to mark it as such.
 101
 102 All memory attached to the BFD is released.
 103
 104 @strong{Returns}@*
 105 @code{true} is returned if all is ok, otherwise @code{false}.
 106
 107 @findex bfd_create
 108 @subsubsection @code{bfd_create}
 109 @strong{Synopsis}
 110 @example
 111 bfd *bfd_create(const char *filename, bfd *templ);
 112 @end example
 113 @strong{Description}@*
 114 Create a new BFD in the manner of
 115 @code{bfd_openw}, but without opening a file. The new BFD
 116 takes the target from the target used by @var{template}. The
 117 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 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 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 PTR 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