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 4Opens an object file for reading. Creates and returns an 5@code{simple_object_read} pointer which may be passed to other 6functions 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 11normal case, but may be a different value when reading an object file 12in an archive file. 13 14@var{segment_name} is only used with the Mach-O file format used on 15Darwin aka Mac OS X. It is required on that platform, and means to 16only look at sections within the segment with that name. The 17parameter is ignored on other systems. 18 19If an error occurs, this functions returns @code{NULL} and sets 20@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to 21an 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 27This function calls @var{pfn} for each section in @var{simple_object}. 28It calls @var{pfn} with the section name, the offset within the file 29of the section contents, and the length of the section contents. The 30offset within the file is relative to the offset passed to 31@code{simple_object_open_read}. The @var{data} argument to this 32function is passed along to @var{pfn}. 33 34If @var{pfn} returns @code{0}, the loop over the sections stops and 35@code{simple_object_find_sections} returns. If @var{pfn} returns some 36other value, the loop continues. 37 38On success @code{simple_object_find_sections} returns. On error it 39returns an error string, and sets @code{*@var{err}} to an errno value 40or @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 46Look for the section @var{name} in @var{simple_object}. This returns 47information for the first section with that name. 48 49If found, return 1 and set @code{*@var{offset}} to the offset in the 50file of the section contents and set @code{*@var{length}} to the 51length of the section contents. The value in @code{*@var{offset}} 52will be relative to the offset passed to 53@code{simple_object_open_read}. 54 55If 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 59If 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 62relevant errno. 63 64@end deftypefn 65 66@deftypefn Extension {void} simple_object_release_read (simple_object_read *@var{simple_object}) 67 68Release all resources associated with @var{simple_object}. This does 69not 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 75Fetch the attributes of @var{simple_object}. The attributes are 76internal information such as the format of the object file, or the 77architecture 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 81On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 82error 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 89Compare @var{attrs1} and @var{attrs2}. If they could be linked 90together without error, return @code{NULL}. Otherwise, return an 91error message and set @code{*@var{err}} to an errno value or @code{0} 92if there is no relevant errno. 93 94@end deftypefn 95 96@deftypefn Extension {void} simple_object_release_attributes (simple_object_attributes *@var{attrs}) 97 98Release 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 104Start creating a new object file using the object file format 105described in @var{attrs}. You must fetch attribute information from 106an existing object file before you can create a new one. There is 107currently 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 110OS X. The parameter is required on that target. It means that all 111sections are created within the named segment. It is ignored for 112other object file formats. 113 114On error @code{simple_object_start_write} returns @code{NULL}, sets 115@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} 116to 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 122Add a section to @var{simple_object}. @var{name} is the name of the 123new section. @var{align} is the required alignment expressed as the 124number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit 125boundary). 126 127The section is created as containing data, readable, not writable, not 128executable, not loaded at runtime. The section is not written to the 129file until @code{simple_object_write_to_file} is called. 130 131On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an 132error 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 139Add data @var{buffer}/@var{size} to @var{section} in 140@var{simple_object}. If @var{copy} is non-zero, the data will be 141copied into memory if necessary. If @var{copy} is zero, @var{buffer} 142must persist until @code{simple_object_write_to_file} is called. is 143released. 144 145On success this returns @code{NULL}. On error this returns an error 146message, and sets @code{*@var{err}} to an errno value or 0 if there is 147no 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 153Write the complete object file to @var{descriptor}, an open file 154descriptor. 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 158This returns @code{NULL} on success. On error this returns an error 159message and sets @code{*@var{err}} to an errno value or @code{0} if 160there is no relevant errno. 161 162@end deftypefn 163 164@deftypefn Extension {void} simple_object_release_write (simple_object_write *@var{simple_object}) 165 166Release all resources associated with @var{simple_object}. 167 168@end deftypefn 169