1 /* simple-object.h -- simple routines to read and write object files
2    Copyright (C) 2010-2020 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 /* Merge the FROM attributes into TO.  If two objects with these
121    attributes could be linked together without error, returns NULL.
122    Otherwise, returns an error message, and sets *ERR to an errno
123    value or 0 if there isn't one.  */
124 
125 extern const char *
126 simple_object_attributes_merge (simple_object_attributes *to,
127 				simple_object_attributes *from,
128 				int *err);
129 
130 /* Release all resources associated with ATTRS.  */
131 
132 extern void
133 simple_object_release_attributes (simple_object_attributes *attrs);
134 
135 /* The type simple_object_write is used to create a new object file.  */
136 
137 typedef struct simple_object_write_struct simple_object_write;
138 
139 /* Start creating a new object file which is like ATTRS.  You must
140    fetch attribute information from an existing object file before you
141    can create a new one.  There is currently no support for creating
142    an object file de novo.  The segment name is only used on Mach-O,
143    where it is required.  It means that all sections are created
144    within that segment.  It is ignored for other object file formats.
145    On error this function returns NULL, sets *ERRMSG to an error
146    message, and sets *ERR to an errno value or 0 if there isn't
147    one.  */
148 
149 extern simple_object_write *
150 simple_object_start_write (simple_object_attributes *attrs,
151 			   const char *segment_name,
152 			   const char **errmsg, int *err);
153 
154 /* The type simple_object_write_section is a handle for a section
155    which is being written.  */
156 
157 typedef struct simple_object_write_section_struct simple_object_write_section;
158 
159 /* Add a section to SIMPLE_OBJECT.  NAME is the name of the new
160    section.  ALIGN is the required alignment expressed as the number
161    of required low-order 0 bits (e.g., 2 for alignment to a 32-bit
162    boundary).  The section is created as containing data, readable,
163    not writable, not executable, not loaded at runtime.  On error this
164    returns NULL, sets *ERRMSG to an error message, and sets *ERR to an
165    errno value or 0 if there isn't one.  */
166 
167 extern simple_object_write_section *
168 simple_object_write_create_section (simple_object_write *simple_object,
169 				    const char *name, unsigned int align,
170 				    const char **errmsg, int *err);
171 
172 /* Add data BUFFER/SIZE to SECTION in SIMPLE_OBJECT.  If COPY is
173    non-zero, the data will be copied into memory if necessary.  If
174    COPY is zero, BUFFER must persist until SIMPLE_OBJECT is released.
175    On success this returns NULL.  On error this returns an error
176    message, and sets *ERR to an errno value or 0 if there isn't
177    one.  */
178 
179 extern const char *
180 simple_object_write_add_data (simple_object_write *simple_object,
181 			      simple_object_write_section *section,
182 			      const void *buffer, size_t size,
183 			      int copy, int *err);
184 
185 /* Write the complete object file to DESCRIPTOR, an open file
186    descriptor.  This returns NULL on success.  On error this returns
187    an error message, and sets *ERR to an errno value or 0 if there
188    isn't one.  */
189 
190 extern const char *
191 simple_object_write_to_file (simple_object_write *simple_object,
192 			     int descriptor, int *err);
193 
194 /* Release all resources associated with SIMPLE_OBJECT, including any
195    simple_object_write_section's that may have been created.  */
196 
197 extern void
198 simple_object_release_write (simple_object_write *);
199 
200 /* Copy LTO debug sections from SRC_OBJECT to DEST.
201    If RENAME is true, rename LTO debug section into debug section (i.e.
202    when producing final binary) and if it is false, keep the sections with
203    original names (when incrementally linking).
204    If an error occurs, return the errno value in ERR and an error string.  */
205 
206 extern const char *
207 simple_object_copy_lto_debug_sections (simple_object_read *src_object,
208 				       const char *dest,
209 				       int *err, int rename);
210 
211 #ifdef __cplusplus
212 }
213 #endif
214 
215 #endif
216