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
5This program is free software; you can redistribute it and/or modify it
6under the terms of the GNU General Public License as published by the
7Free Software Foundation; either version 2, or (at your option) any
8later version.
9
10This program is distributed in the hope that it will be useful,
11but WITHOUT ANY WARRANTY; without even the implied warranty of
12MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13GNU General Public License for more details.
14
15You should have received a copy of the GNU General Public License
16along with this program; if not, write to the Free Software
17Foundation, 51 Franklin Street - Fifth Floor,
18Boston, 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
31extern "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
42typedef 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
55extern simple_object_read *
56simple_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
70extern const char *
71simple_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
93extern int
94simple_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
101extern void
102simple_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
108typedef 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
116extern simple_object_attributes *
117simple_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
124extern const char *
125simple_object_attributes_compare (simple_object_attributes *attrs1,
126			    simple_object_attributes *attrs2,
127			    int *err);
128
129/* Release all resources associated with ATTRS.  */
130
131extern void
132simple_object_release_attributes (simple_object_attributes *attrs);
133
134/* The type simple_object_write is used to create a new object file.  */
135
136typedef 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
148extern simple_object_write *
149simple_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
156typedef 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
166extern simple_object_write_section *
167simple_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
178extern const char *
179simple_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
189extern const char *
190simple_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
196extern void
197simple_object_release_write (simple_object_write *);
198
199#ifdef __cplusplus
200}
201#endif
202
203#endif
204