1*86d7f5d3SJohn Marino /* simple-object.h -- simple routines to read and write object files 2*86d7f5d3SJohn Marino Copyright 2010 Free Software Foundation, Inc. 3*86d7f5d3SJohn Marino Written by Ian Lance Taylor, Google. 4*86d7f5d3SJohn Marino 5*86d7f5d3SJohn Marino This program is free software; you can redistribute it and/or modify it 6*86d7f5d3SJohn Marino under the terms of the GNU General Public License as published by the 7*86d7f5d3SJohn Marino Free Software Foundation; either version 2, or (at your option) any 8*86d7f5d3SJohn Marino later version. 9*86d7f5d3SJohn Marino 10*86d7f5d3SJohn Marino This program is distributed in the hope that it will be useful, 11*86d7f5d3SJohn Marino but WITHOUT ANY WARRANTY; without even the implied warranty of 12*86d7f5d3SJohn Marino MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13*86d7f5d3SJohn Marino GNU General Public License for more details. 14*86d7f5d3SJohn Marino 15*86d7f5d3SJohn Marino You should have received a copy of the GNU General Public License 16*86d7f5d3SJohn Marino along with this program; if not, write to the Free Software 17*86d7f5d3SJohn Marino Foundation, 51 Franklin Street - Fifth Floor, 18*86d7f5d3SJohn Marino Boston, MA 02110-1301, USA. */ 19*86d7f5d3SJohn Marino 20*86d7f5d3SJohn Marino #ifndef SIMPLE_OBJECT_H 21*86d7f5d3SJohn Marino #define SIMPLE_OBJECT_H 22*86d7f5d3SJohn Marino 23*86d7f5d3SJohn Marino #include <stddef.h> 24*86d7f5d3SJohn Marino #include <sys/types.h> 25*86d7f5d3SJohn Marino 26*86d7f5d3SJohn Marino #ifdef HAVE_UNISTD_H 27*86d7f5d3SJohn Marino #include <unistd.h> 28*86d7f5d3SJohn Marino #endif 29*86d7f5d3SJohn Marino 30*86d7f5d3SJohn Marino #ifdef __cplusplus 31*86d7f5d3SJohn Marino extern "C" { 32*86d7f5d3SJohn Marino #endif 33*86d7f5d3SJohn Marino 34*86d7f5d3SJohn Marino /* This header file provides four types with associated functions. 35*86d7f5d3SJohn Marino They are used to read and write object files. This is a minimal 36*86d7f5d3SJohn Marino interface, intended to support the needs of gcc without bringing in 37*86d7f5d3SJohn Marino all the power and complexity of BFD. */ 38*86d7f5d3SJohn Marino 39*86d7f5d3SJohn Marino /* The type simple_object_read * is used to read an existing object 40*86d7f5d3SJohn Marino file. */ 41*86d7f5d3SJohn Marino 42*86d7f5d3SJohn Marino typedef struct simple_object_read_struct simple_object_read; 43*86d7f5d3SJohn Marino 44*86d7f5d3SJohn Marino /* Create an simple_object_read given DESCRIPTOR, an open file 45*86d7f5d3SJohn Marino descriptor, and OFFSET, an offset within the file. The offset is 46*86d7f5d3SJohn Marino for use with archives, and should be 0 for an ordinary object file. 47*86d7f5d3SJohn Marino The descriptor must remain open until done with the returned 48*86d7f5d3SJohn Marino simple_object_read. SEGMENT_NAME is used on Mach-O and is required 49*86d7f5d3SJohn Marino on that platform: it means to only look at sections within the 50*86d7f5d3SJohn Marino segment with that name. It is ignored for other object file 51*86d7f5d3SJohn Marino formats. On error, this function returns NULL, and sets *ERRMSG to 52*86d7f5d3SJohn Marino an error string and sets *ERR to an errno value or 0 if there is no 53*86d7f5d3SJohn Marino relevant errno. */ 54*86d7f5d3SJohn Marino 55*86d7f5d3SJohn Marino extern simple_object_read * 56*86d7f5d3SJohn Marino simple_object_start_read (int descriptor, off_t offset, 57*86d7f5d3SJohn Marino const char *segment_name, const char **errmsg, 58*86d7f5d3SJohn Marino int *err); 59*86d7f5d3SJohn Marino 60*86d7f5d3SJohn Marino /* Call PFN for each section in SIMPLE_OBJECT, passing it the section 61*86d7f5d3SJohn Marino name, offset within the file of the section contents, and length of 62*86d7f5d3SJohn Marino the section contents. The offset within the file is relative to 63*86d7f5d3SJohn Marino the offset passed to simple_object_start_read. The DATA argument 64*86d7f5d3SJohn Marino to simple_object_find_sections is passed on to PFN. If PFN returns 65*86d7f5d3SJohn Marino 0, the loop is stopped and simple_object_find_sections returns. If 66*86d7f5d3SJohn Marino PFN returns non-zero, the loop continues. On success this returns 67*86d7f5d3SJohn Marino NULL. On error it returns an error string, and sets *ERR to an 68*86d7f5d3SJohn Marino errno value or 0 if there is no relevant errno. */ 69*86d7f5d3SJohn Marino 70*86d7f5d3SJohn Marino extern const char * 71*86d7f5d3SJohn Marino simple_object_find_sections (simple_object_read *simple_object, 72*86d7f5d3SJohn Marino int (*pfn) (void *data, const char *, 73*86d7f5d3SJohn Marino off_t offset, off_t length), 74*86d7f5d3SJohn Marino void *data, 75*86d7f5d3SJohn Marino int *err); 76*86d7f5d3SJohn Marino 77*86d7f5d3SJohn Marino /* Look for the section NAME in SIMPLE_OBJECT. This returns 78*86d7f5d3SJohn Marino information for the first section NAME in SIMPLE_OBJECT. Note that 79*86d7f5d3SJohn Marino calling this multiple times is inefficient; use 80*86d7f5d3SJohn Marino simple_object_find_sections instead. 81*86d7f5d3SJohn Marino 82*86d7f5d3SJohn Marino If found, return 1 and set *OFFSET to the offset in the file of the 83*86d7f5d3SJohn Marino section contents and set *LENGTH to the length of the section 84*86d7f5d3SJohn Marino contents. *OFFSET will be relative to the offset passed to 85*86d7f5d3SJohn Marino simple_object_start_read. 86*86d7f5d3SJohn Marino 87*86d7f5d3SJohn Marino If the section is not found, and no error occurs, return 0 and set 88*86d7f5d3SJohn Marino *ERRMSG to NULL. 89*86d7f5d3SJohn Marino 90*86d7f5d3SJohn Marino If an error occurs, return 0, set *ERRMSG to an error message, and 91*86d7f5d3SJohn Marino set *ERR to an errno value or 0 if there is no relevant errno. */ 92*86d7f5d3SJohn Marino 93*86d7f5d3SJohn Marino extern int 94*86d7f5d3SJohn Marino simple_object_find_section (simple_object_read *simple_object, 95*86d7f5d3SJohn Marino const char *name, off_t *offset, off_t *length, 96*86d7f5d3SJohn Marino const char **errmsg, int *err); 97*86d7f5d3SJohn Marino 98*86d7f5d3SJohn Marino /* Release all resources associated with SIMPLE_OBJECT. This does not 99*86d7f5d3SJohn Marino close the file descriptor. */ 100*86d7f5d3SJohn Marino 101*86d7f5d3SJohn Marino extern void 102*86d7f5d3SJohn Marino simple_object_release_read (simple_object_read *); 103*86d7f5d3SJohn Marino 104*86d7f5d3SJohn Marino /* The type simple_object_attributes holds the attributes of an object 105*86d7f5d3SJohn Marino file that matter for creating a file or ensuring that two files are 106*86d7f5d3SJohn Marino compatible. This is a set of magic numbers. */ 107*86d7f5d3SJohn Marino 108*86d7f5d3SJohn Marino typedef struct simple_object_attributes_struct simple_object_attributes; 109*86d7f5d3SJohn Marino 110*86d7f5d3SJohn Marino /* Fetch the attributes of SIMPLE_OBJECT. This information will 111*86d7f5d3SJohn Marino persist until simple_object_attributes_release is called, even if 112*86d7f5d3SJohn Marino SIMPLE_OBJECT is closed. On error this returns NULL, sets *ERRMSG 113*86d7f5d3SJohn Marino to an error message, and sets *ERR to an errno value or 0 if there 114*86d7f5d3SJohn Marino isn't one. */ 115*86d7f5d3SJohn Marino 116*86d7f5d3SJohn Marino extern simple_object_attributes * 117*86d7f5d3SJohn Marino simple_object_fetch_attributes (simple_object_read *simple_object, 118*86d7f5d3SJohn Marino const char **errmsg, int *err); 119*86d7f5d3SJohn Marino 120*86d7f5d3SJohn Marino /* Merge the FROM attributes into TO. If two objects with these 121*86d7f5d3SJohn Marino attributes could be linked together without error, returns NULL. 122*86d7f5d3SJohn Marino Otherwise, returns an error message, and sets *ERR to an errno 123*86d7f5d3SJohn Marino value or 0 if there isn't one. */ 124*86d7f5d3SJohn Marino 125*86d7f5d3SJohn Marino extern const char * 126*86d7f5d3SJohn Marino simple_object_attributes_merge (simple_object_attributes *to, 127*86d7f5d3SJohn Marino simple_object_attributes *from, 128*86d7f5d3SJohn Marino int *err); 129*86d7f5d3SJohn Marino 130*86d7f5d3SJohn Marino /* Release all resources associated with ATTRS. */ 131*86d7f5d3SJohn Marino 132*86d7f5d3SJohn Marino extern void 133*86d7f5d3SJohn Marino simple_object_release_attributes (simple_object_attributes *attrs); 134*86d7f5d3SJohn Marino 135*86d7f5d3SJohn Marino /* The type simple_object_write is used to create a new object file. */ 136*86d7f5d3SJohn Marino 137*86d7f5d3SJohn Marino typedef struct simple_object_write_struct simple_object_write; 138*86d7f5d3SJohn Marino 139*86d7f5d3SJohn Marino /* Start creating a new object file which is like ATTRS. You must 140*86d7f5d3SJohn Marino fetch attribute information from an existing object file before you 141*86d7f5d3SJohn Marino can create a new one. There is currently no support for creating 142*86d7f5d3SJohn Marino an object file de novo. The segment name is only used on Mach-O, 143*86d7f5d3SJohn Marino where it is required. It means that all sections are created 144*86d7f5d3SJohn Marino within that segment. It is ignored for other object file formats. 145*86d7f5d3SJohn Marino On error this function returns NULL, sets *ERRMSG to an error 146*86d7f5d3SJohn Marino message, and sets *ERR to an errno value or 0 if there isn't 147*86d7f5d3SJohn Marino one. */ 148*86d7f5d3SJohn Marino 149*86d7f5d3SJohn Marino extern simple_object_write * 150*86d7f5d3SJohn Marino simple_object_start_write (simple_object_attributes *attrs, 151*86d7f5d3SJohn Marino const char *segment_name, 152*86d7f5d3SJohn Marino const char **errmsg, int *err); 153*86d7f5d3SJohn Marino 154*86d7f5d3SJohn Marino /* The type simple_object_write_section is a handle for a section 155*86d7f5d3SJohn Marino which is being written. */ 156*86d7f5d3SJohn Marino 157*86d7f5d3SJohn Marino typedef struct simple_object_write_section_struct simple_object_write_section; 158*86d7f5d3SJohn Marino 159*86d7f5d3SJohn Marino /* Add a section to SIMPLE_OBJECT. NAME is the name of the new 160*86d7f5d3SJohn Marino section. ALIGN is the required alignment expressed as the number 161*86d7f5d3SJohn Marino of required low-order 0 bits (e.g., 2 for alignment to a 32-bit 162*86d7f5d3SJohn Marino boundary). The section is created as containing data, readable, 163*86d7f5d3SJohn Marino not writable, not executable, not loaded at runtime. On error this 164*86d7f5d3SJohn Marino returns NULL, sets *ERRMSG to an error message, and sets *ERR to an 165*86d7f5d3SJohn Marino errno value or 0 if there isn't one. */ 166*86d7f5d3SJohn Marino 167*86d7f5d3SJohn Marino extern simple_object_write_section * 168*86d7f5d3SJohn Marino simple_object_write_create_section (simple_object_write *simple_object, 169*86d7f5d3SJohn Marino const char *name, unsigned int align, 170*86d7f5d3SJohn Marino const char **errmsg, int *err); 171*86d7f5d3SJohn Marino 172*86d7f5d3SJohn Marino /* Add data BUFFER/SIZE to SECTION in SIMPLE_OBJECT. If COPY is 173*86d7f5d3SJohn Marino non-zero, the data will be copied into memory if necessary. If 174*86d7f5d3SJohn Marino COPY is zero, BUFFER must persist until SIMPLE_OBJECT is released. 175*86d7f5d3SJohn Marino On success this returns NULL. On error this returns an error 176*86d7f5d3SJohn Marino message, and sets *ERR to an errno value or 0 if there isn't 177*86d7f5d3SJohn Marino one. */ 178*86d7f5d3SJohn Marino 179*86d7f5d3SJohn Marino extern const char * 180*86d7f5d3SJohn Marino simple_object_write_add_data (simple_object_write *simple_object, 181*86d7f5d3SJohn Marino simple_object_write_section *section, 182*86d7f5d3SJohn Marino const void *buffer, size_t size, 183*86d7f5d3SJohn Marino int copy, int *err); 184*86d7f5d3SJohn Marino 185*86d7f5d3SJohn Marino /* Write the complete object file to DESCRIPTOR, an open file 186*86d7f5d3SJohn Marino descriptor. This returns NULL on success. On error this returns 187*86d7f5d3SJohn Marino an error message, and sets *ERR to an errno value or 0 if there 188*86d7f5d3SJohn Marino isn't one. */ 189*86d7f5d3SJohn Marino 190*86d7f5d3SJohn Marino extern const char * 191*86d7f5d3SJohn Marino simple_object_write_to_file (simple_object_write *simple_object, 192*86d7f5d3SJohn Marino int descriptor, int *err); 193*86d7f5d3SJohn Marino 194*86d7f5d3SJohn Marino /* Release all resources associated with SIMPLE_OBJECT, including any 195*86d7f5d3SJohn Marino simple_object_write_section's that may have been created. */ 196*86d7f5d3SJohn Marino 197*86d7f5d3SJohn Marino extern void 198*86d7f5d3SJohn Marino simple_object_release_write (simple_object_write *); 199*86d7f5d3SJohn Marino 200*86d7f5d3SJohn Marino #ifdef __cplusplus 201*86d7f5d3SJohn Marino } 202*86d7f5d3SJohn Marino #endif 203*86d7f5d3SJohn Marino 204*86d7f5d3SJohn Marino #endif 205