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