Commit | Line | Data |
---|---|---|
ffa54e5c DD |
1 | @c -*- mode: texinfo -*- |
2 | @deftypefn Extension {simple_object_read *} simple_object_open_read (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, const char **@var{errmsg}, int *@var{err}) | |
3 | ||
4 | Opens an object file for reading. Creates and returns an | |
5 | @code{simple_object_read} pointer which may be passed to other | |
6 | functions to extract data from the object file. | |
7 | ||
8 | @var{descriptor} holds a file descriptor which permits reading. | |
9 | ||
10 | @var{offset} is the offset into the file; this will be @code{0} in the | |
11 | normal case, but may be a different value when reading an object file | |
12 | in an archive file. | |
13 | ||
14 | @var{segment_name} is only used with the Mach-O file format used on | |
15 | Darwin aka Mac OS X. It is required on that platform, and means to | |
16 | only look at sections within the segment with that name. The | |
17 | parameter is ignored on other systems. | |
18 | ||
19 | If an error occurs, this functions returns @code{NULL} and sets | |
20 | @code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to | |
21 | an errno value or @code{0} if there is no relevant errno. | |
22 | ||
23 | @end deftypefn | |
24 | ||
25 | @deftypefn Extension {const char *} simple_object_find_sections (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, const char *@var{name}, off_t @var{offset}, off_t @var{length}), void *@var{data}, int *@var{err}) | |
26 | ||
27 | This function calls @var{pfn} for each section in @var{simple_object}. | |
28 | It calls @var{pfn} with the section name, the offset within the file | |
29 | of the section contents, and the length of the section contents. The | |
30 | offset within the file is relative to the offset passed to | |
31 | @code{simple_object_open_read}. The @var{data} argument to this | |
32 | function is passed along to @var{pfn}. | |
33 | ||
34 | If @var{pfn} returns @code{0}, the loop over the sections stops and | |
35 | @code{simple_object_find_sections} returns. If @var{pfn} returns some | |
36 | other value, the loop continues. | |
37 | ||
38 | On success @code{simple_object_find_sections} returns. On error it | |
39 | returns an error string, and sets @code{*@var{err}} to an errno value | |
40 | or @code{0} if there is no relevant errno. | |
41 | ||
42 | @end deftypefn | |
43 | ||
44 | @deftypefn Extension {int} simple_object_find_section (simple_object_read *@var{simple_object} off_t *@var{offset}, off_t *@var{length}, const char **@var{errmsg}, int *@var{err}) | |
45 | ||
46 | Look for the section @var{name} in @var{simple_object}. This returns | |
47 | information for the first section with that name. | |
48 | ||
49 | If found, return 1 and set @code{*@var{offset}} to the offset in the | |
50 | file of the section contents and set @code{*@var{length}} to the | |
51 | length of the section contents. The value in @code{*@var{offset}} | |
52 | will be relative to the offset passed to | |
53 | @code{simple_object_open_read}. | |
54 | ||
55 | If the section is not found, and no error occurs, | |
56 | @code{simple_object_find_section} returns @code{0} and set | |
57 | @code{*@var{errmsg}} to @code{NULL}. | |
58 | ||
59 | If an error occurs, @code{simple_object_find_section} returns | |
60 | @code{0}, sets @code{*@var{errmsg}} to an error message, and sets | |
61 | @code{*@var{err}} to an errno value or @code{0} if there is no | |
62 | relevant errno. | |
63 | ||
64 | @end deftypefn | |
65 | ||
66 | @deftypefn Extension {void} simple_object_release_read (simple_object_read *@var{simple_object}) | |
67 | ||
68 | Release all resources associated with @var{simple_object}. This does | |
69 | not close the file descriptor. | |
70 | ||
71 | @end deftypefn | |
72 | ||
73 | @deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err}) | |
74 | ||
75 | Fetch the attributes of @var{simple_object}. The attributes are | |
76 | internal information such as the format of the object file, or the | |
77 | architecture it was compiled for. This information will persist until | |
78 | @code{simple_object_attributes_release} is called, even if | |
79 | @var{simple_object} itself is released. | |
80 | ||
81 | On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an | |
82 | error message, and sets @code{*@var{err}} to an errno value or | |
83 | @code{0} if there is no relevant errno. | |
84 | ||
85 | @end deftypefn | |
86 | ||
87 | @deftypefn Extension {const char *} simple_object_attributes_compare (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, int *@var{err}) | |
88 | ||
89 | Compare @var{attrs1} and @var{attrs2}. If they could be linked | |
90 | together without error, return @code{NULL}. Otherwise, return an | |
91 | error message and set @code{*@var{err}} to an errno value or @code{0} | |
92 | if there is no relevant errno. | |
93 | ||
94 | @end deftypefn | |
95 | ||
96 | @deftypefn Extension {void} simple_object_release_attributes (simple_object_attributes *@var{attrs}) | |
97 | ||
98 | Release all resources associated with @var{attrs}. | |
99 | ||
100 | @end deftypefn | |
101 | ||
102 | @deftypefn Extension {simple_object_write *} simple_object_start_write (simple_object_attributes @var{attrs}, const char *@var{segment_name}, const char **@var{errmsg}, int *@var{err}) | |
103 | ||
104 | Start creating a new object file using the object file format | |
105 | described in @var{attrs}. You must fetch attribute information from | |
106 | an existing object file before you can create a new one. There is | |
107 | currently no support for creating an object file de novo. | |
108 | ||
109 | @var{segment_name} is only used with Mach-O as found on Darwin aka Mac | |
110 | OS X. The parameter is required on that target. It means that all | |
111 | sections are created within the named segment. It is ignored for | |
112 | other object file formats. | |
113 | ||
114 | On error @code{simple_object_start_write} returns @code{NULL}, sets | |
115 | @code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} | |
116 | to an errno value or @code{0} if there is no relevant errno. | |
117 | ||
118 | @end deftypefn | |
119 | ||
120 | @deftypefn Extension {simple_object_write_section *} simple_object_write_create_section (simple_object_write *@var{simple_object}, const char *@var{name}, unsigned int @var{align}, const char **@var{errmsg}, int *@var{err}) | |
121 | ||
122 | Add a section to @var{simple_object}. @var{name} is the name of the | |
123 | new section. @var{align} is the required alignment expressed as the | |
124 | number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit | |
125 | boundary). | |
126 | ||
127 | The section is created as containing data, readable, not writable, not | |
128 | executable, not loaded at runtime. The section is not written to the | |
129 | file until @code{simple_object_write_to_file} is called. | |
130 | ||
131 | On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an | |
132 | error message, and sets @code{*@var{err}} to an errno value or | |
133 | @code{0} if there is no relevant errno. | |
134 | ||
135 | @end deftypefn | |
136 | ||
137 | @deftypefn Extension {const char *} simple_object_write_add_data (simple_object_write *@var{simple_object}, simple_object_write_section *@var{section}, const void *@var{buffer}, size_t @var{size}, int @var{copy}, int *@var{err}) | |
138 | ||
139 | Add data @var{buffer}/@var{size} to @var{section} in | |
140 | @var{simple_object}. If @var{copy} is non-zero, the data will be | |
141 | copied into memory if necessary. If @var{copy} is zero, @var{buffer} | |
142 | must persist until @code{simple_object_write_to_file} is called. is | |
143 | released. | |
144 | ||
145 | On success this returns @code{NULL}. On error this returns an error | |
146 | message, and sets @code{*@var{err}} to an errno value or 0 if there is | |
147 | no relevant erro. | |
148 | ||
149 | @end deftypefn | |
150 | ||
151 | @deftypefn Extension {const char *} simple_object_write_to_file (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err}) | |
152 | ||
153 | Write the complete object file to @var{descriptor}, an open file | |
154 | descriptor. This writes out all the data accumulated by calls to | |
155 | @code{simple_object_write_create_section} and | |
156 | @var{simple_object_write_add_data}. | |
157 | ||
158 | This returns @code{NULL} on success. On error this returns an error | |
159 | message and sets @code{*@var{err}} to an errno value or @code{0} if | |
160 | there is no relevant errno. | |
161 | ||
162 | @end deftypefn | |
163 | ||
164 | @deftypefn Extension {void} simple_object_release_write (simple_object_write *@var{simple_object}) | |
165 | ||
166 | Release all resources associated with @var{simple_object}. | |
167 | ||
168 | @end deftypefn |