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 6Opens an object file for reading. Creates and returns an 7@code{simple_object_read} pointer which may be passed to other 8functions 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 13normal case, but may be a different value when reading an object file 14in an archive file. 15 16@var{segment_name} is only used with the Mach-O file format used on 17Darwin aka Mac OS X. It is required on that platform, and means to 18only look at sections within the segment with that name. The 19parameter is ignored on other systems. 20 21If an error occurs, this functions returns @code{NULL} and sets 22@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to 23an 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 32This function calls @var{pfn} for each section in @var{simple_object}. 33It calls @var{pfn} with the section name, the offset within the file 34of the section contents, and the length of the section contents. The 35offset within the file is relative to the offset passed to 36@code{simple_object_open_read}. The @var{data} argument to this 37function is passed along to @var{pfn}. 38 39If @var{pfn} returns @code{0}, the loop over the sections stops and 40@code{simple_object_find_sections} returns. If @var{pfn} returns some 41other value, the loop continues. 42 43On success @code{simple_object_find_sections} returns. On error it 44returns an error string, and sets @code{*@var{err}} to an errno value 45or @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 53Look for the section @var{name} in @var{simple_object}. This returns 54information for the first section with that name. 55 56If found, return 1 and set @code{*@var{offset}} to the offset in the 57file of the section contents and set @code{*@var{length}} to the 58length of the section contents. The value in @code{*@var{offset}} 59will be relative to the offset passed to 60@code{simple_object_open_read}. 61 62If 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 66If 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 69relevant errno. 70 71@end deftypefn 72 73@deftypefn Extension {void} simple_object_release_read @ 74 (simple_object_read *@var{simple_object}) 75 76Release all resources associated with @var{simple_object}. This does 77not 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 84Fetch the attributes of @var{simple_object}. The attributes are 85internal information such as the format of the object file, or the 86architecture 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 90On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 91error 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 100Compare @var{attrs1} and @var{attrs2}. If they could be linked 101together without error, return @code{NULL}. Otherwise, return an 102error message and set @code{*@var{err}} to an errno value or @code{0} 103if 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 110Release 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 118Start creating a new object file using the object file format 119described in @var{attrs}. You must fetch attribute information from 120an existing object file before you can create a new one. There is 121currently 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 124OS X. The parameter is required on that target. It means that all 125sections are created within the named segment. It is ignored for 126other object file formats. 127 128On error @code{simple_object_start_write} returns @code{NULL}, sets 129@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} 130to 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 138Add a section to @var{simple_object}. @var{name} is the name of the 139new section. @var{align} is the required alignment expressed as the 140number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit 141boundary). 142 143The section is created as containing data, readable, not writable, not 144executable, not loaded at runtime. The section is not written to the 145file until @code{simple_object_write_to_file} is called. 146 147On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 148error 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 158Add data @var{buffer}/@var{size} to @var{section} in 159@var{simple_object}. If @var{copy} is non-zero, the data will be 160copied into memory if necessary. If @var{copy} is zero, @var{buffer} 161must persist until @code{simple_object_write_to_file} is called. is 162released. 163 164On success this returns @code{NULL}. On error this returns an error 165message, and sets @code{*@var{err}} to an errno value or 0 if there is 166no 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 173Write the complete object file to @var{descriptor}, an open file 174descriptor. 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 178This returns @code{NULL} on success. On error this returns an error 179message and sets @code{*@var{err}} to an errno value or @code{0} if 180there 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 187Release all resources associated with @var{simple_object}. 188 189@end deftypefn 190