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