← Back to branch summary

~ubuntu-branches/ubuntu/hoary/binutils/hoary

« back to all changes in this revision

Viewing changes to bfd/doc/libbfd.texi

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2005-03-18 13:07:52 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20050318130752-j4i37zgqclj53b94
Tags: 2.15-5ubuntu2
debian/rules: Call pkgstriptranslations if present (the package does not
use debhelper, thus it does not happen automatically).

Show diffs side-by-side

added added

removed removed

Lines of Context:
bfd/doc/libbfd.texi
 
1
@section Internal functions
 
2
 
 
3
 
 
4
@strong{Description}@*
 
5
These routines are used within BFD.
 
6
They are not intended for export, but are documented here for
 
7
completeness.
 
8
 
 
9
@findex bfd_write_bigendian_4byte_int
 
10
@subsubsection @code{bfd_write_bigendian_4byte_int}
 
11
@strong{Synopsis}
 
12
@example
 
13
bfd_boolean bfd_write_bigendian_4byte_int (bfd *, unsigned int);
 
14
@end example
 
15
@strong{Description}@*
 
16
Write a 4 byte integer @var{i} to the output BFD @var{abfd}, in big
 
17
endian order regardless of what else is going on.  This is useful in
 
18
archives.
 
19
 
 
20
@findex bfd_put_size
 
21
@subsubsection @code{bfd_put_size}
 
22
@findex bfd_get_size
 
23
@subsubsection @code{bfd_get_size}
 
24
@strong{Description}@*
 
25
These macros as used for reading and writing raw data in
 
26
sections; each access (except for bytes) is vectored through
 
27
the target format of the BFD and mangled accordingly. The
 
28
mangling performs any necessary endian translations and
 
29
removes alignment restrictions.  Note that types accepted and
 
30
returned by these macros are identical so they can be swapped
 
31
around in macros---for example, @file{libaout.h} defines @code{GET_WORD}
 
32
to either @code{bfd_get_32} or @code{bfd_get_64}.
 
33
 
 
34
In the put routines, @var{val} must be a @code{bfd_vma}.  If we are on a
 
35
system without prototypes, the caller is responsible for making
 
36
sure that is true, with a cast if necessary.  We don't cast
 
37
them in the macro definitions because that would prevent @code{lint}
 
38
or @code{gcc -Wall} from detecting sins such as passing a pointer.
 
39
To detect calling these with less than a @code{bfd_vma}, use
 
40
@code{gcc -Wconversion} on a host with 64 bit @code{bfd_vma}'s.
 
41
@example
 
42
 
 
43
/* Byte swapping macros for user section data.  */
 
44
 
 
45
#define bfd_put_8(abfd, val, ptr) \
 
46
  ((void) (*((unsigned char *) (ptr)) = (val) & 0xff))
 
47
#define bfd_put_signed_8 \
 
48
  bfd_put_8
 
49
#define bfd_get_8(abfd, ptr) \
 
50
  (*(unsigned char *) (ptr) & 0xff)
 
51
#define bfd_get_signed_8(abfd, ptr) \
 
52
  (((*(unsigned char *) (ptr) & 0xff) ^ 0x80) - 0x80)
 
53
 
 
54
#define bfd_put_16(abfd, val, ptr) \
 
55
  BFD_SEND (abfd, bfd_putx16, ((val),(ptr)))
 
56
#define bfd_put_signed_16 \
 
57
  bfd_put_16
 
58
#define bfd_get_16(abfd, ptr) \
 
59
  BFD_SEND (abfd, bfd_getx16, (ptr))
 
60
#define bfd_get_signed_16(abfd, ptr) \
 
61
  BFD_SEND (abfd, bfd_getx_signed_16, (ptr))
 
62
 
 
63
#define bfd_put_32(abfd, val, ptr) \
 
64
  BFD_SEND (abfd, bfd_putx32, ((val),(ptr)))
 
65
#define bfd_put_signed_32 \
 
66
  bfd_put_32
 
67
#define bfd_get_32(abfd, ptr) \
 
68
  BFD_SEND (abfd, bfd_getx32, (ptr))
 
69
#define bfd_get_signed_32(abfd, ptr) \
 
70
  BFD_SEND (abfd, bfd_getx_signed_32, (ptr))
 
71
 
 
72
#define bfd_put_64(abfd, val, ptr) \
 
73
  BFD_SEND (abfd, bfd_putx64, ((val), (ptr)))
 
74
#define bfd_put_signed_64 \
 
75
  bfd_put_64
 
76
#define bfd_get_64(abfd, ptr) \
 
77
  BFD_SEND (abfd, bfd_getx64, (ptr))
 
78
#define bfd_get_signed_64(abfd, ptr) \
 
79
  BFD_SEND (abfd, bfd_getx_signed_64, (ptr))
 
80
 
 
81
#define bfd_get(bits, abfd, ptr)                       \
 
82
  ((bits) == 8 ? (bfd_vma) bfd_get_8 (abfd, ptr)       \
 
83
   : (bits) == 16 ? bfd_get_16 (abfd, ptr)             \
 
84
   : (bits) == 32 ? bfd_get_32 (abfd, ptr)             \
 
85
   : (bits) == 64 ? bfd_get_64 (abfd, ptr)             \
 
86
   : (abort (), (bfd_vma) - 1))
 
87
 
 
88
#define bfd_put(bits, abfd, val, ptr)                  \
 
89
  ((bits) == 8 ? bfd_put_8  (abfd, val, ptr)           \
 
90
   : (bits) == 16 ? bfd_put_16 (abfd, val, ptr)                \
 
91
   : (bits) == 32 ? bfd_put_32 (abfd, val, ptr)                \
 
92
   : (bits) == 64 ? bfd_put_64 (abfd, val, ptr)                \
 
93
   : (abort (), (void) 0))
 
94
 
 
95
@end example
 
96
 
 
97
@findex bfd_h_put_size
 
98
@subsubsection @code{bfd_h_put_size}
 
99
@strong{Description}@*
 
100
These macros have the same function as their @code{bfd_get_x}
 
101
brethren, except that they are used for removing information
 
102
for the header records of object files. Believe it or not,
 
103
some object files keep their header records in big endian
 
104
order and their data in little endian order.
 
105
@example
 
106
 
 
107
/* Byte swapping macros for file header data.  */
 
108
 
 
109
#define bfd_h_put_8(abfd, val, ptr) \
 
110
  bfd_put_8 (abfd, val, ptr)
 
111
#define bfd_h_put_signed_8(abfd, val, ptr) \
 
112
  bfd_put_8 (abfd, val, ptr)
 
113
#define bfd_h_get_8(abfd, ptr) \
 
114
  bfd_get_8 (abfd, ptr)
 
115
#define bfd_h_get_signed_8(abfd, ptr) \
 
116
  bfd_get_signed_8 (abfd, ptr)
 
117
 
 
118
#define bfd_h_put_16(abfd, val, ptr) \
 
119
  BFD_SEND (abfd, bfd_h_putx16, (val, ptr))
 
120
#define bfd_h_put_signed_16 \
 
121
  bfd_h_put_16
 
122
#define bfd_h_get_16(abfd, ptr) \
 
123
  BFD_SEND (abfd, bfd_h_getx16, (ptr))
 
124
#define bfd_h_get_signed_16(abfd, ptr) \
 
125
  BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr))
 
126
 
 
127
#define bfd_h_put_32(abfd, val, ptr) \
 
128
  BFD_SEND (abfd, bfd_h_putx32, (val, ptr))
 
129
#define bfd_h_put_signed_32 \
 
130
  bfd_h_put_32
 
131
#define bfd_h_get_32(abfd, ptr) \
 
132
  BFD_SEND (abfd, bfd_h_getx32, (ptr))
 
133
#define bfd_h_get_signed_32(abfd, ptr) \
 
134
  BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr))
 
135
 
 
136
#define bfd_h_put_64(abfd, val, ptr) \
 
137
  BFD_SEND (abfd, bfd_h_putx64, (val, ptr))
 
138
#define bfd_h_put_signed_64 \
 
139
  bfd_h_put_64
 
140
#define bfd_h_get_64(abfd, ptr) \
 
141
  BFD_SEND (abfd, bfd_h_getx64, (ptr))
 
142
#define bfd_h_get_signed_64(abfd, ptr) \
 
143
  BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr))
 
144
 
 
145
/* Aliases for the above, which should eventually go away.  */
 
146
 
 
147
#define H_PUT_64  bfd_h_put_64
 
148
#define H_PUT_32  bfd_h_put_32
 
149
#define H_PUT_16  bfd_h_put_16
 
150
#define H_PUT_8   bfd_h_put_8
 
151
#define H_PUT_S64 bfd_h_put_signed_64
 
152
#define H_PUT_S32 bfd_h_put_signed_32
 
153
#define H_PUT_S16 bfd_h_put_signed_16
 
154
#define H_PUT_S8  bfd_h_put_signed_8
 
155
#define H_GET_64  bfd_h_get_64
 
156
#define H_GET_32  bfd_h_get_32
 
157
#define H_GET_16  bfd_h_get_16
 
158
#define H_GET_8   bfd_h_get_8
 
159
#define H_GET_S64 bfd_h_get_signed_64
 
160
#define H_GET_S32 bfd_h_get_signed_32
 
161
#define H_GET_S16 bfd_h_get_signed_16
 
162
#define H_GET_S8  bfd_h_get_signed_8
 
163
 
 
164
 
 
165
@end example
 
166
 
 
167
@findex bfd_log2
 
168
@subsubsection @code{bfd_log2}
 
169
@strong{Synopsis}
 
170
@example
 
171
unsigned int bfd_log2 (bfd_vma x);
 
172
@end example
 
173
@strong{Description}@*
 
174
Return the log base 2 of the value supplied, rounded up.  E.g., an
 
175
@var{x} of 1025 returns 11.  A @var{x} of 0 returns 0.
 
176