1130812Smarcel/* simple-object.h -- simple routines to read and write object files 2130812Smarcel Copyright 2010 Free Software Foundation, Inc. 3130812Smarcel Written by Ian Lance Taylor, Google. 4130812Smarcel 5130812SmarcelThis program is free software; you can redistribute it and/or modify it 6130812Smarcelunder the terms of the GNU General Public License as published by the 7130812SmarcelFree Software Foundation; either version 2, or (at your option) any 8130812Smarcellater version. 9130812Smarcel 10130812SmarcelThis program is distributed in the hope that it will be useful, 11130812Smarcelbut WITHOUT ANY WARRANTY; without even the implied warranty of 12130812SmarcelMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13130812SmarcelGNU General Public License for more details. 14130812Smarcel 15130812SmarcelYou should have received a copy of the GNU General Public License 16130812Smarcelalong with this program; if not, write to the Free Software 17130812SmarcelFoundation, 51 Franklin Street - Fifth Floor, 18130812SmarcelBoston, MA 02110-1301, USA. */ 19130812Smarcel 20130812Smarcel#ifndef SIMPLE_OBJECT_H 21130812Smarcel#define SIMPLE_OBJECT_H 22130812Smarcel 23130812Smarcel#include <stddef.h> 24130812Smarcel#include <sys/types.h> 25130812Smarcel 26130812Smarcel#ifdef HAVE_UNISTD_H 27130812Smarcel#include <unistd.h> 28130812Smarcel#endif 29130812Smarcel 30130812Smarcel#ifdef __cplusplus 31130812Smarcelextern "C" { 32130812Smarcel#endif 33130812Smarcel 34130812Smarcel/* This header file provides four types with associated functions. 35130812Smarcel They are used to read and write object files. This is a minimal 36130812Smarcel interface, intended to support the needs of gcc without bringing in 37130812Smarcel all the power and complexity of BFD. */ 38130812Smarcel 39130812Smarcel/* The type simple_object_read * is used to read an existing object 40130812Smarcel file. */ 41130812Smarcel 42130812Smarceltypedef struct simple_object_read_struct simple_object_read; 43130812Smarcel 44130812Smarcel/* Create an simple_object_read given DESCRIPTOR, an open file 45130812Smarcel descriptor, and OFFSET, an offset within the file. The offset is 46130812Smarcel for use with archives, and should be 0 for an ordinary object file. 47130812Smarcel The descriptor must remain open until done with the returned 48130812Smarcel simple_object_read. SEGMENT_NAME is used on Mach-O and is required 49130812Smarcel on that platform: it means to only look at sections within the 50130812Smarcel segment with that name. It is ignored for other object file 51130812Smarcel formats. On error, this function returns NULL, and sets *ERRMSG to 52130812Smarcel an error string and sets *ERR to an errno value or 0 if there is no 53130812Smarcel relevant errno. */ 54130812Smarcel 55130812Smarcelextern simple_object_read * 56130812Smarcelsimple_object_start_read (int descriptor, off_t offset, 57130812Smarcel const char *segment_name, const char **errmsg, 58130812Smarcel int *err); 59130812Smarcel 60130812Smarcel/* Call PFN for each section in SIMPLE_OBJECT, passing it the section 61130812Smarcel name, offset within the file of the section contents, and length of 62130812Smarcel the section contents. The offset within the file is relative to 63130812Smarcel the offset passed to simple_object_start_read. The DATA argument 64130812Smarcel to simple_object_find_sections is passed on to PFN. If PFN returns 65130812Smarcel 0, the loop is stopped and simple_object_find_sections returns. If 66130812Smarcel PFN returns non-zero, the loop continues. On success this returns 67130812Smarcel NULL. On error it returns an error string, and sets *ERR to an 68130812Smarcel errno value or 0 if there is no relevant errno. */ 69130812Smarcel 70130812Smarcelextern const char * 71130812Smarcelsimple_object_find_sections (simple_object_read *simple_object, 72130812Smarcel int (*pfn) (void *data, const char *, 73130812Smarcel off_t offset, off_t length), 74130812Smarcel void *data, 75130812Smarcel int *err); 76130812Smarcel 77130812Smarcel/* Look for the section NAME in SIMPLE_OBJECT. This returns 78130812Smarcel information for the first section NAME in SIMPLE_OBJECT. Note that 79130812Smarcel calling this multiple times is inefficient; use 80130812Smarcel simple_object_find_sections instead. 81130812Smarcel 82130812Smarcel If found, return 1 and set *OFFSET to the offset in the file of the 83130812Smarcel section contents and set *LENGTH to the length of the section 84130812Smarcel contents. *OFFSET will be relative to the offset passed to 85130812Smarcel simple_object_start_read. 86130812Smarcel 87130812Smarcel If the section is not found, and no error occurs, return 0 and set 88130812Smarcel *ERRMSG to NULL. 89130812Smarcel 90130812Smarcel If an error occurs, return 0, set *ERRMSG to an error message, and 91130812Smarcel set *ERR to an errno value or 0 if there is no relevant errno. */ 92130812Smarcel 93130812Smarcelextern int 94130812Smarcelsimple_object_find_section (simple_object_read *simple_object, 95130812Smarcel const char *name, off_t *offset, off_t *length, 96130812Smarcel const char **errmsg, int *err); 97130812Smarcel 98130812Smarcel/* Release all resources associated with SIMPLE_OBJECT. This does not 99130812Smarcel close the file descriptor. */ 100130812Smarcel 101130812Smarcelextern void 102130812Smarcelsimple_object_release_read (simple_object_read *); 103130812Smarcel 104130812Smarcel/* The type simple_object_attributes holds the attributes of an object 105130812Smarcel file that matter for creating a file or ensuring that two files are 106130812Smarcel compatible. This is a set of magic numbers. */ 107130812Smarcel 108130812Smarceltypedef struct simple_object_attributes_struct simple_object_attributes; 109130812Smarcel 110130812Smarcel/* Fetch the attributes of SIMPLE_OBJECT. This information will 111130812Smarcel persist until simple_object_attributes_release is called, even if 112130812Smarcel SIMPLE_OBJECT is closed. On error this returns NULL, sets *ERRMSG 113130812Smarcel to an error message, and sets *ERR to an errno value or 0 if there 114130812Smarcel isn't one. */ 115130812Smarcel 116130812Smarcelextern simple_object_attributes * 117130812Smarcelsimple_object_fetch_attributes (simple_object_read *simple_object, 118130812Smarcel const char **errmsg, int *err); 119130812Smarcel 120130812Smarcel/* Merge the FROM attributes into TO. If two objects with these 121130812Smarcel attributes could be linked together without error, returns NULL. 122130812Smarcel Otherwise, returns an error message, and sets *ERR to an errno 123130812Smarcel value or 0 if there isn't one. */ 124130812Smarcel 125130812Smarcelextern const char * 126130812Smarcelsimple_object_attributes_merge (simple_object_attributes *to, 127130812Smarcel simple_object_attributes *from, 128130812Smarcel int *err); 129130812Smarcel 130130812Smarcel/* Release all resources associated with ATTRS. */ 131130812Smarcel 132130812Smarcelextern void 133130812Smarcelsimple_object_release_attributes (simple_object_attributes *attrs); 134130812Smarcel 135130812Smarcel/* The type simple_object_write is used to create a new object file. */ 136130812Smarcel 137130812Smarceltypedef struct simple_object_write_struct simple_object_write; 138130812Smarcel 139130812Smarcel/* Start creating a new object file which is like ATTRS. You must 140130812Smarcel fetch attribute information from an existing object file before you 141130812Smarcel can create a new one. There is currently no support for creating 142130812Smarcel an object file de novo. The segment name is only used on Mach-O, 143130812Smarcel where it is required. It means that all sections are created 144130812Smarcel within that segment. It is ignored for other object file formats. 145130812Smarcel On error this function returns NULL, sets *ERRMSG to an error 146130812Smarcel message, and sets *ERR to an errno value or 0 if there isn't 147130812Smarcel one. */ 148130812Smarcel 149130812Smarcelextern simple_object_write * 150130812Smarcelsimple_object_start_write (simple_object_attributes *attrs, 151130812Smarcel const char *segment_name, 152130812Smarcel const char **errmsg, int *err); 153130812Smarcel 154130812Smarcel/* The type simple_object_write_section is a handle for a section 155130812Smarcel which is being written. */ 156130812Smarcel 157130812Smarceltypedef struct simple_object_write_section_struct simple_object_write_section; 158130812Smarcel 159130812Smarcel/* Add a section to SIMPLE_OBJECT. NAME is the name of the new 160130812Smarcel section. ALIGN is the required alignment expressed as the number 161130812Smarcel of required low-order 0 bits (e.g., 2 for alignment to a 32-bit 162130812Smarcel boundary). The section is created as containing data, readable, 163130812Smarcel not writable, not executable, not loaded at runtime. On error this 164130812Smarcel returns NULL, sets *ERRMSG to an error message, and sets *ERR to an 165130812Smarcel errno value or 0 if there isn't one. */ 166130812Smarcel 167130812Smarcelextern simple_object_write_section * 168130812Smarcelsimple_object_write_create_section (simple_object_write *simple_object, 169130812Smarcel const char *name, unsigned int align, 170130812Smarcel const char **errmsg, int *err); 171130812Smarcel 172130812Smarcel/* Add data BUFFER/SIZE to SECTION in SIMPLE_OBJECT. If COPY is 173130812Smarcel non-zero, the data will be copied into memory if necessary. If 174130812Smarcel COPY is zero, BUFFER must persist until SIMPLE_OBJECT is released. 175130812Smarcel On success this returns NULL. On error this returns an error 176130812Smarcel message, and sets *ERR to an errno value or 0 if there isn't 177130812Smarcel one. */ 178130812Smarcel 179130812Smarcelextern const char * 180130812Smarcelsimple_object_write_add_data (simple_object_write *simple_object, 181130812Smarcel simple_object_write_section *section, 182130812Smarcel const void *buffer, size_t size, 183130812Smarcel int copy, int *err); 184130812Smarcel 185130812Smarcel/* Write the complete object file to DESCRIPTOR, an open file 186130812Smarcel descriptor. This returns NULL on success. On error this returns 187130812Smarcel an error message, and sets *ERR to an errno value or 0 if there 188130812Smarcel isn't one. */ 189130812Smarcel 190130812Smarcelextern const char * 191130812Smarcelsimple_object_write_to_file (simple_object_write *simple_object, 192130812Smarcel int descriptor, int *err); 193130812Smarcel 194130812Smarcel/* Release all resources associated with SIMPLE_OBJECT, including any 195130812Smarcel simple_object_write_section's that may have been created. */ 196130812Smarcel 197130812Smarcelextern void 198130812Smarcelsimple_object_release_write (simple_object_write *); 199130812Smarcel 200130812Smarcel#ifdef __cplusplus 201130812Smarcel} 202130812Smarcel#endif 203130812Smarcel 204130812Smarcel#endif 205130812Smarcel