1 @section Implementation details 2 3 4 @subsection Internal functions 5 6 7 These routines are used within BFD. 8 They are not intended for export, but are documented here for 9 completeness. 10 11 @findex bfd_malloc 12 @subsubsection @code{bfd_malloc} 13 @deftypefn {Function} void *bfd_malloc (bfd_size_type {*size*}); 14 Returns a pointer to an allocated block of memory that is at least 15 SIZE bytes long. If SIZE is 0 then it will be treated as if it were 16 1. If SIZE is too big then NULL will be returned. 17 Returns NULL upon error and sets bfd_error. 18 19 @end deftypefn 20 @findex bfd_realloc 21 @subsubsection @code{bfd_realloc} 22 @deftypefn {Function} void *bfd_realloc (void *{*mem*}, bfd_size_type {*size*}); 23 Returns a pointer to an allocated block of memory that is at least 24 SIZE bytes long. If SIZE is 0 then it will be treated as if it were 25 1. If SIZE is too big then NULL will be returned. 26 If MEM is not NULL then it must point to an allocated block of memory. 27 If this block is large enough then MEM may be used as the return 28 value for this function, but this is not guaranteed. 29 30 If MEM is not returned then the first N bytes in the returned block 31 will be identical to the first N bytes in region pointed to by MEM, 32 where N is the lessor of SIZE and the length of the region of memory 33 currently addressed by MEM. 34 35 Returns NULL upon error and sets bfd_error. 36 37 @end deftypefn 38 @findex bfd_realloc_or_free 39 @subsubsection @code{bfd_realloc_or_free} 40 @deftypefn {Function} void *bfd_realloc_or_free (void *{*mem*}, bfd_size_type {*size*}); 41 Returns a pointer to an allocated block of memory that is at least 42 SIZE bytes long. If SIZE is 0 then no memory will be allocated, 43 MEM will be freed, and NULL will be returned. This will not cause 44 bfd_error to be set. 45 46 If SIZE is too big then NULL will be returned and bfd_error will be 47 set. 48 If MEM is not NULL then it must point to an allocated block of memory. 49 If this block is large enough then MEM may be used as the return 50 value for this function, but this is not guaranteed. 51 52 If MEM is not returned then the first N bytes in the returned block 53 will be identical to the first N bytes in region pointed to by MEM, 54 where N is the lessor of SIZE and the length of the region of memory 55 currently addressed by MEM. 56 57 @end deftypefn 58 @findex bfd_zmalloc 59 @subsubsection @code{bfd_zmalloc} 60 @deftypefn {Function} void *bfd_zmalloc (bfd_size_type {*size*}); 61 Returns a pointer to an allocated block of memory that is at least 62 SIZE bytes long. If SIZE is 0 then it will be treated as if it were 63 1. If SIZE is too big then NULL will be returned. 64 Returns NULL upon error and sets bfd_error. 65 66 If NULL is not returned then the allocated block of memory will 67 have been cleared. 68 69 @end deftypefn 70 @findex bfd_alloc 71 @subsubsection @code{bfd_alloc} 72 @deftypefn {Function} void *bfd_alloc (bfd *abfd, bfd_size_type wanted); 73 Allocate a block of @var{wanted} bytes of memory attached to 74 @code{abfd} and return a pointer to it. 75 76 @end deftypefn 77 @findex bfd_zalloc 78 @subsubsection @code{bfd_zalloc} 79 @deftypefn {Function} void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); 80 Allocate a block of @var{wanted} bytes of zeroed memory 81 attached to @code{abfd} and return a pointer to it. 82 83 @end deftypefn 84 @findex bfd_release 85 @subsubsection @code{bfd_release} 86 @deftypefn {Function} void bfd_release (bfd *, void *); 87 Free a block allocated for a BFD. 88 Note: Also frees all more recently allocated blocks! 89 90 @end deftypefn 91 @findex bfd_write_bigendian_4byte_int 92 @subsubsection @code{bfd_write_bigendian_4byte_int} 93 @deftypefn {Function} bool bfd_write_bigendian_4byte_int (bfd *, unsigned int); 94 Write a 4 byte integer @var{i} to the output BFD @var{abfd}, in big 95 endian order regardless of what else is going on. This is useful in 96 archives. 97 98 @end deftypefn 99 @findex bfd_put_size 100 @subsubsection @code{bfd_put_size} 101 @findex bfd_get_size 102 @subsubsection @code{bfd_get_size} 103 These macros as used for reading and writing raw data in 104 sections; each access (except for bytes) is vectored through 105 the target format of the BFD and mangled accordingly. The 106 mangling performs any necessary endian translations and 107 removes alignment restrictions. Note that types accepted and 108 returned by these macros are identical so they can be swapped 109 around in macros---for example, @file{libaout.h} defines @code{GET_WORD} 110 to either @code{bfd_get_32} or @code{bfd_get_64}. 111 112 In the put routines, @var{val} must be a @code{bfd_vma}. If we are on a 113 system without prototypes, the caller is responsible for making 114 sure that is true, with a cast if necessary. We don't cast 115 them in the macro definitions because that would prevent @code{lint} 116 or @code{gcc -Wall} from detecting sins such as passing a pointer. 117 To detect calling these with less than a @code{bfd_vma}, use 118 @code{gcc -Wconversion} on a host with 64 bit @code{bfd_vma}'s. 119 @example 120 121 /* Byte swapping macros for user section data. */ 122 123 #define bfd_put_8(abfd, val, ptr) \ 124 ((void) (*((bfd_byte *) (ptr)) = (val) & 0xff)) 125 #define bfd_put_signed_8 \ 126 bfd_put_8 127 #define bfd_get_8(abfd, ptr) \ 128 ((bfd_vma) *(const bfd_byte *) (ptr) & 0xff) 129 #define bfd_get_signed_8(abfd, ptr) \ 130 ((((bfd_signed_vma) *(const bfd_byte *) (ptr) & 0xff) ^ 0x80) - 0x80) 131 132 #define bfd_put_16(abfd, val, ptr) \ 133 BFD_SEND (abfd, bfd_putx16, ((val),(ptr))) 134 #define bfd_put_signed_16 \ 135 bfd_put_16 136 #define bfd_get_16(abfd, ptr) \ 137 BFD_SEND (abfd, bfd_getx16, (ptr)) 138 #define bfd_get_signed_16(abfd, ptr) \ 139 BFD_SEND (abfd, bfd_getx_signed_16, (ptr)) 140 141 #define bfd_put_24(abfd, val, ptr) \ 142 do \ 143 if (bfd_big_endian (abfd)) \ 144 bfd_putb24 ((val), (ptr)); \ 145 else \ 146 bfd_putl24 ((val), (ptr)); \ 147 while (0) 148 149 bfd_vma bfd_getb24 (const void *p); 150 bfd_vma bfd_getl24 (const void *p); 151 152 #define bfd_get_24(abfd, ptr) \ 153 (bfd_big_endian (abfd) ? bfd_getb24 (ptr) : bfd_getl24 (ptr)) 154 155 #define bfd_put_32(abfd, val, ptr) \ 156 BFD_SEND (abfd, bfd_putx32, ((val),(ptr))) 157 #define bfd_put_signed_32 \ 158 bfd_put_32 159 #define bfd_get_32(abfd, ptr) \ 160 BFD_SEND (abfd, bfd_getx32, (ptr)) 161 #define bfd_get_signed_32(abfd, ptr) \ 162 BFD_SEND (abfd, bfd_getx_signed_32, (ptr)) 163 164 #define bfd_put_64(abfd, val, ptr) \ 165 BFD_SEND (abfd, bfd_putx64, ((val), (ptr))) 166 #define bfd_put_signed_64 \ 167 bfd_put_64 168 #define bfd_get_64(abfd, ptr) \ 169 BFD_SEND (abfd, bfd_getx64, (ptr)) 170 #define bfd_get_signed_64(abfd, ptr) \ 171 BFD_SEND (abfd, bfd_getx_signed_64, (ptr)) 172 173 #define bfd_get(bits, abfd, ptr) \ 174 ((bits) == 8 ? bfd_get_8 (abfd, ptr) \ 175 : (bits) == 16 ? bfd_get_16 (abfd, ptr) \ 176 : (bits) == 32 ? bfd_get_32 (abfd, ptr) \ 177 : (bits) == 64 ? bfd_get_64 (abfd, ptr) \ 178 : (abort (), (bfd_vma) - 1)) 179 180 #define bfd_put(bits, abfd, val, ptr) \ 181 ((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \ 182 : (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \ 183 : (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \ 184 : (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \ 185 : (abort (), (void) 0)) 186 187 @end example 188 189 @findex bfd_h_put_size 190 @subsubsection @code{bfd_h_put_size} 191 These macros have the same function as their @code{bfd_get_x} 192 brethren, except that they are used for removing information 193 for the header records of object files. Believe it or not, 194 some object files keep their header records in big endian 195 order and their data in little endian order. 196 @example 197 198 /* Byte swapping macros for file header data. */ 199 200 #define bfd_h_put_8(abfd, val, ptr) \ 201 bfd_put_8 (abfd, val, ptr) 202 #define bfd_h_put_signed_8(abfd, val, ptr) \ 203 bfd_put_8 (abfd, val, ptr) 204 #define bfd_h_get_8(abfd, ptr) \ 205 bfd_get_8 (abfd, ptr) 206 #define bfd_h_get_signed_8(abfd, ptr) \ 207 bfd_get_signed_8 (abfd, ptr) 208 209 #define bfd_h_put_16(abfd, val, ptr) \ 210 BFD_SEND (abfd, bfd_h_putx16, (val, ptr)) 211 #define bfd_h_put_signed_16 \ 212 bfd_h_put_16 213 #define bfd_h_get_16(abfd, ptr) \ 214 BFD_SEND (abfd, bfd_h_getx16, (ptr)) 215 #define bfd_h_get_signed_16(abfd, ptr) \ 216 BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr)) 217 218 #define bfd_h_put_32(abfd, val, ptr) \ 219 BFD_SEND (abfd, bfd_h_putx32, (val, ptr)) 220 #define bfd_h_put_signed_32 \ 221 bfd_h_put_32 222 #define bfd_h_get_32(abfd, ptr) \ 223 BFD_SEND (abfd, bfd_h_getx32, (ptr)) 224 #define bfd_h_get_signed_32(abfd, ptr) \ 225 BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr)) 226 227 #define bfd_h_put_64(abfd, val, ptr) \ 228 BFD_SEND (abfd, bfd_h_putx64, (val, ptr)) 229 #define bfd_h_put_signed_64 \ 230 bfd_h_put_64 231 #define bfd_h_get_64(abfd, ptr) \ 232 BFD_SEND (abfd, bfd_h_getx64, (ptr)) 233 #define bfd_h_get_signed_64(abfd, ptr) \ 234 BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr)) 235 236 /* Aliases for the above, which should eventually go away. */ 237 238 #define H_PUT_64 bfd_h_put_64 239 #define H_PUT_32 bfd_h_put_32 240 #define H_PUT_16 bfd_h_put_16 241 #define H_PUT_8 bfd_h_put_8 242 #define H_PUT_S64 bfd_h_put_signed_64 243 #define H_PUT_S32 bfd_h_put_signed_32 244 #define H_PUT_S16 bfd_h_put_signed_16 245 #define H_PUT_S8 bfd_h_put_signed_8 246 #define H_GET_64 bfd_h_get_64 247 #define H_GET_32 bfd_h_get_32 248 #define H_GET_16 bfd_h_get_16 249 #define H_GET_8 bfd_h_get_8 250 #define H_GET_S64 bfd_h_get_signed_64 251 #define H_GET_S32 bfd_h_get_signed_32 252 #define H_GET_S16 bfd_h_get_signed_16 253 #define H_GET_S8 bfd_h_get_signed_8 254 255 256 @end example 257 258 @findex Byte swapping routines. 259 @subsubsection @code{Byte swapping routines.} 260 @deftypefn {Function} uint64_t bfd_getb64 (const void *); uint64_t bfd_getl64 (const void *); int64_t bfd_getb_signed_64 (const void *); int64_t bfd_getl_signed_64 (const void *); bfd_vma bfd_getb32 (const void *); bfd_vma bfd_getl32 (const void *); bfd_signed_vma bfd_getb_signed_32 (const void *); bfd_signed_vma bfd_getl_signed_32 (const void *); bfd_vma bfd_getb16 (const void *); bfd_vma bfd_getl16 (const void *); bfd_signed_vma bfd_getb_signed_16 (const void *); bfd_signed_vma bfd_getl_signed_16 (const void *); void bfd_putb64 (uint64_t, void *); void bfd_putl64 (uint64_t, void *); void bfd_putb32 (bfd_vma, void *); void bfd_putl32 (bfd_vma, void *); void bfd_putb24 (bfd_vma, void *); void bfd_putl24 (bfd_vma, void *); void bfd_putb16 (bfd_vma, void *); void bfd_putl16 (bfd_vma, void *); uint64_t bfd_get_bits (const void *, int, bool); void bfd_put_bits (uint64_t, void *, int, bool); 261 Read and write integers in a particular endian order. getb 262 and putb functions handle big-endian, getl and putl handle 263 little-endian. bfd_get_bits and bfd_put_bits specify 264 big-endian by passing TRUE in the last parameter, 265 little-endian by passing FALSE. 266 267 @end deftypefn 268 @findex bfd_log2 269 @subsubsection @code{bfd_log2} 270 @deftypefn {Function} unsigned int bfd_log2 (bfd_vma x); 271 Return the log base 2 of the value supplied, rounded up. E.g., an 272 @var{x} of 1025 returns 11. A @var{x} of 0 returns 0. 273 274 @end deftypefn 275
Indexes created Tue Mar 03 05:31:39 UTC 2026