1elf(3ELF) ELF Library Functions elf(3ELF)
2
6 elf - object file access library
7
9 cc [ flag ... ] file ... -lelf [ library ... ]
10 #include <libelf.h>
11
14 Functions in the ELF access library let a program manipulate ELF (Exe‐
15 cutable and Linking Format) object files, archive files, and archive
16 members. The header provides type and function declarations for all
17 library services.
18 Programs communicate with many of the higher-level routines using an
21 ELF descriptor. That is, when the program starts working with a file,
22 elf_begin(3ELF) creates an ELF descriptor through which the program
23 manipulates the structures and information in the file. These ELF
24 descriptors can be used both to read and to write files. After the pro‐
25 gram establishes an ELF descriptor for a file, it may then obtain sec‐
26 tion descriptors to manipulate the sections of the file (see
27 elf_getscn(3ELF)). Sections hold the bulk of an object file's real
28 information, such as text, data, the symbol table, and so on. A section
29 descriptor ``belongs'' to a particular ELF descriptor, just as a sec‐
30 tion belongs to a file. Finally, data descriptors are available through
31 section descriptors, allowing the program to manipulate the information
32 associated with a section. A data descriptor ``belongs'' to a section
33 descriptor.
34 Descriptors provide private handles to a file and its pieces. In other
37 words, a data descriptor is associated with one section descriptor,
38 which is associated with one ELF descriptor, which is associated with
39 one file. Although descriptors are private, they give access to data
40 that may be shared. Consider programs that combine input files, using
41 incoming data to create or update another file. Such a program might
42 get data descriptors for an input and an output section. It then could
43 update the output descriptor to reuse the input descriptor's data. That
44 is, the descriptors are distinct, but they could share the associated
45 data bytes. This sharing avoids the space overhead for duplicate buf‐
46 fers and the performance overhead for copying data unnecessarily.
47 File Classes
49 ELF provides a framework in which to define a family of object files,
50 supporting multiple processors and architectures. An important distinc‐
51 tion among object files is the class, or capacity, of the file. The
52 32-bit class supports architectures in which a 32-bit object can repre‐
53 sent addresses, file sizes, and so on, as in the following:
54 ┌─────────────────────────────┬─────────────────────────────┐
59 │ Name │ Purpose │
60 ├─────────────────────────────┼─────────────────────────────┤
61 │Elf32_Addr │Unsigned address │
62 ├─────────────────────────────┼─────────────────────────────┤
63 │Elf32_Half │Unsigned medium integer │
64 ├─────────────────────────────┼─────────────────────────────┤
65 │Elf32_Off │Unsigned file offset │
66 ├─────────────────────────────┼─────────────────────────────┤
67 │Elf32_Sword │Signed large integer │
68 ├─────────────────────────────┼─────────────────────────────┤
69 │Elf32_Word │Unsigned large integer │
70 ├─────────────────────────────┼─────────────────────────────┤
71 │unsigned char │Unsigned small integer │
72 └─────────────────────────────┴─────────────────────────────┘
73 The 64−bit class works the same as the 32−bit class, substituting 64
76 for 32 as necessary. Other classes will be defined as necessary, to
77 support larger (or smaller) machines. Some library services deal only
78 with data objects for a specific class, while others are class-indepen‐
79 dent. To make this distinction clear, library function names reflect
80 their status, as described below.
81 Data Representation
83 Conceptually, two parallel sets of objects support cross compilation
84 environments. One set corresponds to file contents, while the other set
85 corresponds to the native memory image of the program manipulating the
86 file. Type definitions supplied by the headers work on the native
87 machine, which may have different data encodings (size, byte order, and
88 so on) than the target machine. Although native memory objects should
89 be at least as big as the file objects (to avoid information loss),
90 they may be bigger if that is more natural for the host machine.
91 Translation facilities exist to convert between file and memory repre‐
94 sentations. Some library routines convert data automatically, while
95 others leave conversion as the program's responsibility. Either way,
96 programs that create object files must write file-typed objects to
97 those files; programs that read object files must take a similar view.
98 See elf32_xlatetof(3ELF) and elf32_fsize(3ELF) for more information.
99 Programs may translate data explicitly, taking full control over the
102 object file layout and semantics. If the program prefers not to have
103 and exercise complete control, the library provides a higher-level
104 interface that hides many object file details. elf_begin() and related
105 functions let a program deal with the native memory types, converting
106 between memory objects and their file equivalents automatically when
107 reading or writing an object file.
108 ELF Versions
110 Object file versions allow ELF to adapt to new requirements. Three
111 independent versions can be important to a program. First, an applica‐
112 tion program knows about a particular version by virtue of being com‐
113 piled with certain headers. Second, the access library similarly is
114 compiled with header files that control what versions it understands.
115 Third, an ELF object file holds a value identifying its version, deter‐
116 mined by the ELF version known by the file's creator. Ideally, all
117 three versions would be the same, but they may differ.
118 If a program's version is newer than the access library, the program
121 might use information unknown to the library. Translation routines
122 might not work properly, leading to undefined behavior. This condition
123 merits installing a new library.
124 The library's version might be newer than the program's and the file's.
127 The library understands old versions, thus avoiding compatibility prob‐
128 lems in this case.
129 Finally, a file's version might be newer than either the program or the
132 library understands. The program might or might not be able to process
133 the file properly, depending on whether the file has extra information
134 and whether that information can be safely ignored. Again, the safe
135 alternative is to install a new library that understands the file's
136 version.
137 To accommodate these differences, a program must use elf_version(3ELF)
140 to pass its version to the library, thus establishing the working ver‐
141 sion for the process. Using this, the library accepts data from and
142 presents data to the program in the proper representations. When the
143 library reads object files, it uses each file's version to interpret
144 the data. When writing files or converting memory types to the file
145 equivalents, the library uses the program's working version for the
146 file data.
147 System Services
149 As mentioned above, elf_begin() and related routines provide a higher-
150 level interface to ELF files, performing input and output on behalf of
151 the application program. These routines assume a program can hold
152 entire files in memory, without explicitly using temporary files. When
153 reading a file, the library routines bring the data into memory and
154 perform subsequent operations on the memory copy. Programs that wish to
155 read or write large object files with this model must execute on a
156 machine with a large process virtual address space. If the underlying
157 operating system limits the number of open files, a program can use
158 elf_cntl(3ELF) to retrieve all necessary data from the file, allowing
159 the program to close the file descriptor and reuse it.
160 Although the elf_begin() interfaces are convenient and efficient for
163 many programs, they might be inappropriate for some. In those cases, an
164 application may invoke the elf32_xlatetom(3ELF) or elf32_xlatetof(3ELF)
165 data translation routines directly. These routines perform no input or
166 output, leaving that as the application's responsibility. By assuming a
167 larger share of the job, an application controls its input and output
168 model.
169 Library Names
171 Names associated with the library take several forms.
172 elf_name These class-independent names perform some service,
174 name, for the program.
175 elf32_name Service names with an embedded class, 32 here, indi‐
178 cate they work only for the designated class of
179 files.
180 Elf_Type Data types can be class-independent as well, distin‐
183 guished by Type.
184 Elf32_Type Class-dependent data types have an embedded class
187 name, 32 here.
188 ELF_C_CMD Several functions take commands that control their
191 actions. These values are members of the Elf_Cmd enu‐
192 meration; they range from zero through ELF_C_NUM−1.
193 ELF_F_FLAG Several functions take flags that control library
196 status and/or actions. Flags are bits that may be
197 combined.
198 ELF32_FSZ_TYPE These constants give the file sizes in bytes of the
201 basic ELF types for the 32-bit class of files. See
202 elf32_fsize() for more information.
203 ELF_K_KIND The function elf_kind() identifies the KIND of file
206 associated with an ELF descriptor. These values are
207 members of the Elf_Kind enumeration; they range from
208 zero through ELF_K_NUM−1.
209 ELF_T_TYPE When a service function, such as elf32_xlatetom() or
212 elf32_xlatetof(), deals with multiple types, names of
213 this form specify the desired TYPE. Thus, for exam‐
214 ple, ELF_T_EHDR is directly related to Elf32_Ehdr.
215 These values are members of the Elf_Type enumeration;
216 they range from zero through ELF_T_NUM−1.
217
220 Example 1 An interpretation of elf file.
221 The basic interpretation of an ELF file consists of:
224 o opening an ELF object file
227 o obtaining an ELF descriptor
229 o analyzing the file using the descriptor.
231 The following example opens the file, obtains the ELF descriptor, and
234 prints out the names of each section in the file.
235 #include <fcntl.h>
238 #include <stdio.h>
239 #include <libelf.h>
240 #include <stdlib.h>
241 #include <string.h>
242 static void failure(void);
243 void
244 main(int argc, char ** argv)
245 {
246 Elf32_Shdr * shdr;
247 Elf32_Ehdr * ehdr;
248 Elf * elf;
249 Elf_Scn * scn;
250 Elf_Data * data;
251 int fd;
252 unsigned int cnt;
253 /* Open the input file */
255 if ((fd = open(argv[1], O_RDONLY)) == -1)
256 exit(1);
257 /* Obtain the ELF descriptor */
259 (void) elf_version(EV_CURRENT);
260 if ((elf = elf_begin(fd, ELF_C_READ, NULL)) == NULL)
261 failure();
262 /* Obtain the .shstrtab data buffer */
264 if (((ehdr = elf32_getehdr(elf)) == NULL) ||
265 ((scn = elf_getscn(elf, ehdr->e_shstrndx)) == NULL) ||
266 ((data = elf_getdata(scn, NULL)) == NULL))
267 failure();
268 /* Traverse input filename, printing each section */
270 for (cnt = 1, scn = NULL; scn = elf_nextscn(elf, scn); cnt++) {
271 if ((shdr = elf32_getshdr(scn)) == NULL)
272 failure();
273 (void) printf("[%d] %s\n", cnt,
274 (char *)data->d_buf + shdr->sh_name);
275 }
276 } /* end main */
277 static void
279 failure()
280 {
281 (void) fprintf(stderr, "%s\n", elf_errmsg(elf_errno()));
282 exit(1);
283 }
284
287 See attributes(5) for descriptions of the following attributes:
288 ┌─────────────────────────────┬─────────────────────────────┐
293 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
294 ├─────────────────────────────┼─────────────────────────────┤
295 │Interface Stability │Stable │
296 ├─────────────────────────────┼─────────────────────────────┤
297 │MT-Level │MT-Safe │
298 └─────────────────────────────┴─────────────────────────────┘
299
301 ar.h(3HEAD), elf32_checksum(3ELF), elf32_fsize(3ELF), elf32_get‐
302 shdr(3ELF), elf32_xlatetof(3ELF), elf_begin(3ELF), elf_cntl(3ELF),
303 elf_errmsg(3ELF), elf_fill(3ELF), elf_getarhdr(3ELF),
304 elf_getarsym(3ELF), elf_getbase(3ELF), elf_getdata(3ELF), elf_geti‐
305 dent(3ELF), elf_getscn(3ELF), elf_hash(3ELF), elf_kind(3ELF), elf_mem‐
306 ory(3ELF), elf_rawfile(3ELF), elf_strptr(3ELF), elf_update(3ELF),
307 elf_version(3ELF), gelf(3ELF), libelf(3LIB), attributes(5), lfcom‐
308 pile(5)
309 ANSI C Programmer's Guide
312 SPARC only
314 a.out(4)
315
317 Information in the ELF headers is separated into common parts and pro‐
318 cessor-specific parts. A program can make a processor's information
319 available by including the appropriate header: <sys/elf_NAME.h> where
320 NAME matches the processor name as used in the ELF file header.
321 ┌─────────────────────────────┬─────────────────────────────┐
326 │ Name │ Processor │
327 ├─────────────────────────────┼─────────────────────────────┤
328 │M32 │AT&T WE 32100 │
329 ├─────────────────────────────┼─────────────────────────────┤
330 │SPARC │SPARC │
331 ├─────────────────────────────┼─────────────────────────────┤
332 │386 │Intel 80386, 80486, Pentium │
333 └─────────────────────────────┴─────────────────────────────┘
334 Other processors will be added to the table as necessary.
337 To illustrate, a program could use the following code to ``see'' the
340 processor-specific information for the SPARC based system.
341 #include <libelf.h>
343 #include <sys/elf_SPARC.h>
344 Without the <sys/elf_SPARC.h> definition, only the common ELF informa‐
348 tion would be visible.
349 A program could use the following code to ``see'' the processor-spe‐
352 cific information for the Intel 80386:
353 #include <libelf.h>
355 #include <sys/elf_386.h>
356 Without the <sys/elf_386.h> definition, only the common ELF information
360 would be visible.
361 Although reading the objects is rather straightforward, writing/updat‐
364 ing them can corrupt the shared offsets among sections. Upon creation,
365 relationships are established among the sections that must be main‐
366 tained even if the object's size is changed.
367SunOS 5.11 23 Jul 2001 elf(3ELF)