include/simple-object.h

   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