diff options
Diffstat (limited to 'gnu/usr.bin/binutils/bfd/doc/libbfd.texi')
| -rw-r--r-- | gnu/usr.bin/binutils/bfd/doc/libbfd.texi | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/gnu/usr.bin/binutils/bfd/doc/libbfd.texi b/gnu/usr.bin/binutils/bfd/doc/libbfd.texi new file mode 100644 index 00000000000..002e2f430fe --- /dev/null +++ b/gnu/usr.bin/binutils/bfd/doc/libbfd.texi @@ -0,0 +1,142 @@ +@section Internal functions + +@* +@strong{Description}@* +These routines are used within BFD. +They are not intended for export, but are documented here for +completeness. +@* +@findex bfd_write_bigendian_4byte_int +@subsubsection @code{bfd_write_bigendian_4byte_int} +@strong{Synopsis} +@example +void bfd_write_bigendian_4byte_int(bfd *abfd, int i); +@end example +@strong{Description}@* +Write a 4 byte integer @var{i} to the output BFD @var{abfd}, in big +endian order regardless of what else is going on. This is useful in +archives. +@* +@findex bfd_put_size +@subsubsection @code{bfd_put_size} +@findex bfd_get_size +@subsubsection @code{bfd_get_size} +@strong{Description}@* +These macros as used for reading and writing raw data in +sections; each access (except for bytes) is vectored through +the target format of the BFD and mangled accordingly. The +mangling performs any necessary endian translations and +removes alignment restrictions. Note that types accepted and +returned by these macros are identical so they can be swapped +around in macros---for example, @file{libaout.h} defines @code{GET_WORD} +to either @code{bfd_get_32} or @code{bfd_get_64}. + +In the put routines, @var{val} must be a @code{bfd_vma}. If we are on a +system without prototypes, the caller is responsible for making +sure that is true, with a cast if necessary. We don't cast +them in the macro definitions because that would prevent @code{lint} +or @code{gcc -Wall} from detecting sins such as passing a pointer. +To detect calling these with less than a @code{bfd_vma}, use +@code{gcc -Wconversion} on a host with 64 bit @code{bfd_vma}'s. +@example + + /* Byte swapping macros for user section data. */ + +#define bfd_put_8(abfd, val, ptr) \ + (*((unsigned char *)(ptr)) = (unsigned char)(val)) +#define bfd_put_signed_8 \ + bfd_put_8 +#define bfd_get_8(abfd, ptr) \ + (*(unsigned char *)(ptr)) +#define bfd_get_signed_8(abfd, ptr) \ + ((*(unsigned char *)(ptr) ^ 0x80) - 0x80) + +#define bfd_put_16(abfd, val, ptr) \ + BFD_SEND(abfd, bfd_putx16, ((val),(ptr))) +#define bfd_put_signed_16 \ + bfd_put_16 +#define bfd_get_16(abfd, ptr) \ + BFD_SEND(abfd, bfd_getx16, (ptr)) +#define bfd_get_signed_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_16, (ptr)) + +#define bfd_put_32(abfd, val, ptr) \ + BFD_SEND(abfd, bfd_putx32, ((val),(ptr))) +#define bfd_put_signed_32 \ + bfd_put_32 +#define bfd_get_32(abfd, ptr) \ + BFD_SEND(abfd, bfd_getx32, (ptr)) +#define bfd_get_signed_32(abfd, ptr) \ + BFD_SEND(abfd, bfd_getx_signed_32, (ptr)) + +#define bfd_put_64(abfd, val, ptr) \ + BFD_SEND(abfd, bfd_putx64, ((val), (ptr))) +#define bfd_put_signed_64 \ + bfd_put_64 +#define bfd_get_64(abfd, ptr) \ + BFD_SEND(abfd, bfd_getx64, (ptr)) +#define bfd_get_signed_64(abfd, ptr) \ + BFD_SEND(abfd, bfd_getx_signed_64, (ptr)) + +@end example +@* +@findex bfd_h_put_size +@subsubsection @code{bfd_h_put_size} +@strong{Description}@* +These macros have the same function as their @code{bfd_get_x} +bretheren, except that they are used for removing information +for the header records of object files. Believe it or not, +some object files keep their header records in big endian +order and their data in little endian order. +@example + + /* Byte swapping macros for file header data. */ + +#define bfd_h_put_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) +#define bfd_h_put_signed_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) +#define bfd_h_get_8(abfd, ptr) \ + bfd_get_8 (abfd, ptr) +#define bfd_h_get_signed_8(abfd, ptr) \ + bfd_get_signed_8 (abfd, ptr) + +#define bfd_h_put_16(abfd, val, ptr) \ + BFD_SEND(abfd, bfd_h_putx16,(val,ptr)) +#define bfd_h_put_signed_16 \ + bfd_h_put_16 +#define bfd_h_get_16(abfd, ptr) \ + BFD_SEND(abfd, bfd_h_getx16,(ptr)) +#define bfd_h_get_signed_16(abfd, ptr) \ + BFD_SEND(abfd, bfd_h_getx_signed_16, (ptr)) + +#define bfd_h_put_32(abfd, val, ptr) \ + BFD_SEND(abfd, bfd_h_putx32,(val,ptr)) +#define bfd_h_put_signed_32 \ + bfd_h_put_32 +#define bfd_h_get_32(abfd, ptr) \ + BFD_SEND(abfd, bfd_h_getx32,(ptr)) +#define bfd_h_get_signed_32(abfd, ptr) \ + BFD_SEND(abfd, bfd_h_getx_signed_32, (ptr)) + +#define bfd_h_put_64(abfd, val, ptr) \ + BFD_SEND(abfd, bfd_h_putx64,(val, ptr)) +#define bfd_h_put_signed_64 \ + bfd_h_put_64 +#define bfd_h_get_64(abfd, ptr) \ + BFD_SEND(abfd, bfd_h_getx64,(ptr)) +#define bfd_h_get_signed_64(abfd, ptr) \ + BFD_SEND(abfd, bfd_h_getx_signed_64, (ptr)) + +@end example +@* +@findex bfd_log2 +@subsubsection @code{bfd_log2} +@strong{Synopsis} +@example +unsigned int bfd_log2(bfd_vma x); +@end example +@strong{Description}@* +Return the log base 2 of the value supplied, rounded up. E.g., an +@var{x} of 1025 returns 11. +@* |