1@section Implementation details 2 3 4@subsection Internal functions 5 6 7These routines are used within BFD. 8They are not intended for export, but are documented here for 9completeness. 10 11@findex bfd_malloc 12@subsubsection @code{bfd_malloc} 13@deftypefn {Function} void *bfd_malloc (bfd_size_type {*size*}); 14Returns a pointer to an allocated block of memory that is at least 15SIZE bytes long. If SIZE is 0 then it will be treated as if it were 161. If SIZE is too big then NULL will be returned. 17Returns 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*}); 23Returns a pointer to an allocated block of memory that is at least 24SIZE bytes long. If SIZE is 0 then it will be treated as if it were 251. If SIZE is too big then NULL will be returned. 26If MEM is not NULL then it must point to an allocated block of memory. 27If this block is large enough then MEM may be used as the return 28value for this function, but this is not guaranteed. 29 30If MEM is not returned then the first N bytes in the returned block 31will be identical to the first N bytes in region pointed to by MEM, 32where N is the lessor of SIZE and the length of the region of memory 33currently addressed by MEM. 34 35Returns 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*}); 41Returns a pointer to an allocated block of memory that is at least 42SIZE bytes long. If SIZE is 0 then no memory will be allocated, 43MEM will be freed, and NULL will be returned. This will not cause 44bfd_error to be set. 45 46If SIZE is too big then NULL will be returned and bfd_error will be 47set. 48If MEM is not NULL then it must point to an allocated block of memory. 49If this block is large enough then MEM may be used as the return 50value for this function, but this is not guaranteed. 51 52If MEM is not returned then the first N bytes in the returned block 53will be identical to the first N bytes in region pointed to by MEM, 54where N is the lessor of SIZE and the length of the region of memory 55currently 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*}); 61Returns a pointer to an allocated block of memory that is at least 62SIZE bytes long. If SIZE is 0 then it will be treated as if it were 631. If SIZE is too big then NULL will be returned. 64Returns NULL upon error and sets bfd_error. 65 66If NULL is not returned then the allocated block of memory will 67have 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); 73Allocate 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); 80Allocate a block of @var{wanted} bytes of zeroed memory 81attached 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 *); 87Free a block allocated for a BFD. 88Note: 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); 94Write a 4 byte integer @var{i} to the output BFD @var{abfd}, in big 95endian order regardless of what else is going on. This is useful in 96archives. 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} 103These macros as used for reading and writing raw data in 104sections; each access (except for bytes) is vectored through 105the target format of the BFD and mangled accordingly. The 106mangling performs any necessary endian translations and 107removes alignment restrictions. Note that types accepted and 108returned by these macros are identical so they can be swapped 109around in macros---for example, @file{libaout.h} defines @code{GET_WORD} 110to either @code{bfd_get_32} or @code{bfd_get_64}. 111 112In the put routines, @var{val} must be a @code{bfd_vma}. If we are on a 113system without prototypes, the caller is responsible for making 114sure that is true, with a cast if necessary. We don't cast 115them in the macro definitions because that would prevent @code{lint} 116or @code{gcc -Wall} from detecting sins such as passing a pointer. 117To 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 149bfd_vma bfd_getb24 (const void *p); 150bfd_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} 191These macros have the same function as their @code{bfd_get_x} 192brethren, except that they are used for removing information 193for the header records of object files. Believe it or not, 194some object files keep their header records in big endian 195order 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); 261Read and write integers in a particular endian order. getb 262and putb functions handle big-endian, getl and putl handle 263little-endian. bfd_get_bits and bfd_put_bits specify 264big-endian by passing TRUE in the last parameter, 265little-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); 271Return 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