From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- libiberty/simple-object.txh | 189 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 libiberty/simple-object.txh (limited to 'libiberty/simple-object.txh') diff --git a/libiberty/simple-object.txh b/libiberty/simple-object.txh new file mode 100644 index 000000000..34639f10a --- /dev/null +++ b/libiberty/simple-object.txh @@ -0,0 +1,189 @@ +@c -*- mode: texinfo -*- +@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}) + +Opens an object file for reading. Creates and returns an +@code{simple_object_read} pointer which may be passed to other +functions to extract data from the object file. + +@var{descriptor} holds a file descriptor which permits reading. + +@var{offset} is the offset into the file; this will be @code{0} in the +normal case, but may be a different value when reading an object file +in an archive file. + +@var{segment_name} is only used with the Mach-O file format used on +Darwin aka Mac OS X. It is required on that platform, and means to +only look at sections within the segment with that name. The +parameter is ignored on other systems. + +If an error occurs, this functions returns @code{NULL} and sets +@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to +an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@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}) + +This function calls @var{pfn} for each section in @var{simple_object}. +It calls @var{pfn} with the section name, the offset within the file +of the section contents, and the length of the section contents. The +offset within the file is relative to the offset passed to +@code{simple_object_open_read}. The @var{data} argument to this +function is passed along to @var{pfn}. + +If @var{pfn} returns @code{0}, the loop over the sections stops and +@code{simple_object_find_sections} returns. If @var{pfn} returns some +other value, the loop continues. + +On success @code{simple_object_find_sections} returns. On error it +returns an error string, and sets @code{*@var{err}} to an errno value +or @code{0} if there is no relevant errno. + +@end deftypefn + +@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}) + +Look for the section @var{name} in @var{simple_object}. This returns +information for the first section with that name. + +If found, return 1 and set @code{*@var{offset}} to the offset in the +file of the section contents and set @code{*@var{length}} to the +length of the section contents. The value in @code{*@var{offset}} +will be relative to the offset passed to +@code{simple_object_open_read}. + +If the section is not found, and no error occurs, +@code{simple_object_find_section} returns @code{0} and set +@code{*@var{errmsg}} to @code{NULL}. + +If an error occurs, @code{simple_object_find_section} returns +@code{0}, sets @code{*@var{errmsg}} to an error message, and sets +@code{*@var{err}} to an errno value or @code{0} if there is no +relevant errno. + +@end deftypefn + +@deftypefn Extension {void} simple_object_release_read @ + (simple_object_read *@var{simple_object}) + +Release all resources associated with @var{simple_object}. This does +not close the file descriptor. + +@end deftypefn + +@deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @ + (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err}) + +Fetch the attributes of @var{simple_object}. The attributes are +internal information such as the format of the object file, or the +architecture it was compiled for. This information will persist until +@code{simple_object_attributes_release} is called, even if +@var{simple_object} itself is released. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@deftypefn Extension {const char *} simple_object_attributes_compare @ + (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @ + int *@var{err}) + +Compare @var{attrs1} and @var{attrs2}. If they could be linked +together without error, return @code{NULL}. Otherwise, return an +error message and set @code{*@var{err}} to an errno value or @code{0} +if there is no relevant errno. + +@end deftypefn + +@deftypefn Extension {void} simple_object_release_attributes @ + (simple_object_attributes *@var{attrs}) + +Release all resources associated with @var{attrs}. + +@end deftypefn + +@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}) + +Start creating a new object file using the object file format +described in @var{attrs}. You must fetch attribute information from +an existing object file before you can create a new one. There is +currently no support for creating an object file de novo. + +@var{segment_name} is only used with Mach-O as found on Darwin aka Mac +OS X. The parameter is required on that target. It means that all +sections are created within the named segment. It is ignored for +other object file formats. + +On error @code{simple_object_start_write} returns @code{NULL}, sets +@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} +to an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@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}) + +Add a section to @var{simple_object}. @var{name} is the name of the +new section. @var{align} is the required alignment expressed as the +number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit +boundary). + +The section is created as containing data, readable, not writable, not +executable, not loaded at runtime. The section is not written to the +file until @code{simple_object_write_to_file} is called. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@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}) + +Add data @var{buffer}/@var{size} to @var{section} in +@var{simple_object}. If @var{copy} is non-zero, the data will be +copied into memory if necessary. If @var{copy} is zero, @var{buffer} +must persist until @code{simple_object_write_to_file} is called. is +released. + +On success this returns @code{NULL}. On error this returns an error +message, and sets @code{*@var{err}} to an errno value or 0 if there is +no relevant erro. + +@end deftypefn + +@deftypefn Extension {const char *} simple_object_write_to_file @ + (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err}) + +Write the complete object file to @var{descriptor}, an open file +descriptor. This writes out all the data accumulated by calls to +@code{simple_object_write_create_section} and +@var{simple_object_write_add_data}. + +This returns @code{NULL} on success. On error this returns an error +message and sets @code{*@var{err}} to an errno value or @code{0} if +there is no relevant errno. + +@end deftypefn + +@deftypefn Extension {void} simple_object_release_write @ + (simple_object_write *@var{simple_object}) + +Release all resources associated with @var{simple_object}. + +@end deftypefn -- cgit v1.2.3