Project

General

Profile

patch-libelf.patch

davshao, 09/03/2018 11:42 PM

View differences:

contrib/elftoolchain/libelf/Makefile
1
# $Id: Makefile 2605 2012-10-02 17:52:20Z jkoshy $
1
# $Id: Makefile 3594 2018-04-11 18:26:50Z jkoshy $
2 2

  
3 3
TOP=	${.CURDIR}/..
4 4

  
contrib/elftoolchain/libelf/_libelf_config.h
23 23
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 24
 * SUCH DAMAGE.
25 25
 *
26
 * $Id: _libelf_config.h 3168 2015-02-24 19:17:47Z emaste $
26
 * $Id: _libelf_config.h 3566 2017-08-31 02:28:40Z emaste $
27 27
 */
28 28

  
29 29
#if defined(__APPLE__) || defined(__DragonFly__)
......
97 97
#define	LIBELF_BYTEORDER	ELFDATA2MSB
98 98
#define	LIBELF_CLASS		ELFCLASS32
99 99

  
100
#elif	defined(__riscv) && (__riscv_xlen == 64)
101

  
102
#define	LIBELF_ARCH		EM_RISCV
103
#define	LIBELF_BYTEORDER	ELFDATA2LSB
104
#define	LIBELF_CLASS		ELFCLASS64
105

  
100 106
#elif	defined(__sparc__)
101 107

  
102 108
#define	LIBELF_ARCH		EM_SPARCV9
contrib/elftoolchain/libelf/elf.3
1
.\" Copyright (c) 2006-2008,2011 Joseph Koshy.  All rights reserved.
2
.\"
3
.\" Redistribution and use in source and binary forms, with or without
4
.\" modification, are permitted provided that the following conditions
5
.\" are met:
6
.\" 1. Redistributions of source code must retain the above copyright
7
.\"    notice, this list of conditions and the following disclaimer.
8
.\" 2. Redistributions in binary form must reproduce the above copyright
9
.\"    notice, this list of conditions and the following disclaimer in the
10
.\"    documentation and/or other materials provided with the distribution.
11
.\"
12
.\" This software is provided by Joseph Koshy ``as is'' and
13
.\" any express or implied warranties, including, but not limited to, the
14
.\" implied warranties of merchantability and fitness for a particular purpose
15
.\" are disclaimed.  in no event shall Joseph Koshy be liable
16
.\" for any direct, indirect, incidental, special, exemplary, or consequential
17
.\" damages (including, but not limited to, procurement of substitute goods
18
.\" or services; loss of use, data, or profits; or business interruption)
19
.\" however caused and on any theory of liability, whether in contract, strict
20
.\" liability, or tort (including negligence or otherwise) arising in any way
21
.\" out of the use of this software, even if advised of the possibility of
22
.\" such damage.
23
.\"
24
.\" $Id: elf.3 3195 2015-05-12 17:22:19Z emaste $
25
.\"
26
.Dd July 28, 2014
27
.Os
28
.Dt ELF 3
29
.Sh NAME
30
.Nm elf
31
.Nd API for manipulating ELF objects
32
.Sh LIBRARY
33
.Lb libelf
34
.Sh SYNOPSIS
35
.In libelf.h
36
.Sh DESCRIPTION
37
The
38
.Lb libelf
39
provides functions that allow an application to read and manipulate
40
ELF object files, and to read
41
.Xr ar 1
42
archives.
43
The library allows the manipulation of ELF objects in a byte ordering
44
and word-size independent way, allowing an application to read and
45
create ELF objects for 32 and 64 bit architectures and for little-
46
and big-endian machines.
47
The library is capable of processing ELF objects that use extended
48
section numbering.
49
.Pp
50
This manual page serves to provide an overview of the functionality in
51
the ELF library.
52
Further information may found in the manual pages for individual
53
.Xr ELF 3
54
functions that comprise the library.
55
.Ss ELF Concepts
56
As described in
57
.Xr elf 5 ,
58
ELF files contain several data structures that are laid out in a
59
specific way.
60
ELF files begin with an
61
.Dq Executable Header ,
62
and may contain an optional
63
.Dq Program Header Table ,
64
and optional data in the form of ELF
65
.Dq sections .
66
A
67
.Dq Section Header Table
68
describes the content of the data in these sections.
69
.Pp
70
ELF objects have an associated
71
.Dq "ELF class"
72
which denotes the natural machine word size for the architecture
73
the object is associated with.
74
Objects for 32 bit architectures have an ELF class of
75
.Dv ELFCLASS32 .
76
Objects for 64 bit architectures have an ELF class of
77
.Dv ELFCLASS64 .
78
.Pp
79
ELF objects also have an associated
80
.Dq endianness
81
which denotes the endianness of the machine architecture associated
82
with the object.
83
This may be
84
.Dv ELFDATA2LSB
85
for little-endian architectures and
86
.Dv ELFDATA2MSB
87
for big-endian architectures.
88
.Pp
89
ELF objects are also associated with an API version number.
90
This version number determines the layout of the individual components
91
of an ELF file and the semantics associated with these.
92
.Ss Data Representation And Translation
93
The
94
.Xr ELF 3
95
library distinguishes between
96
.Dq native
97
representations of ELF data structures and their
98
.Dq file
99
representations.
100
.Pp
101
An application would work with ELF data in its
102
.Dq native
103
representation, i.e., using the native byteorder and alignment mandated
104
by the processor the application is running on.
105
The
106
.Dq file
107
representation of the same data could use a different byte ordering
108
and follow different constraints on object alignment than these native
109
constraints.
110
.Pp
111
Accordingly, the
112
.Xr ELF 3
113
library offers translation facilities
114
.Xr ( elf32_xlatetof 3 ,
115
.Xr elf32_xlatetom 3 ,
116
.Xr elf64_xlatetof 3
117
and
118
.Xr elf64_xlatetom 3 )
119
to and from these
120
representations and also provides higher-level APIs that retrieve and store
121
data from the ELF object in a transparent manner.
122
.Ss Library Working Version
123
Conceptually, there are three version numbers associated with an
124
application using the ELF library to manipulate ELF objects:
125
.Bl -bullet -compact -offset indent
126
.It
127
The ELF version that the application was compiled against.
128
This version determines the ABI expected by the application.
129
.It
130
The ELF version of the ELF object being manipulated by the
131
application through the ELF library.
132
.It
133
The ELF version (or set of versions) supported by the ELF library itself.
134
.El
135
.Pp
136
In order to facilitate working with ELF objects of differing versions,
137
the ELF library requires the application to call the
138
.Fn elf_version
139
function before invoking many of its operations, in order to inform
140
the library of the application's desired working version.
141
.Pp
142
In the current implementation, all three versions have to be
143
.Dv EV_CURRENT .
144
.Ss Namespace use
145
The ELF library uses the following prefixes:
146
.Bl -tag -width "ELF_F_*"
147
.It Dv elf_
148
Used for class-independent functions.
149
.It Dv elf32_
150
Used for functions working with 32 bit ELF objects.
151
.It Dv elf64_
152
Used for functions working with 64 bit ELF objects.
153
.It Dv Elf_
154
Used for class-independent data types.
155
.It Dv ELF_C_
156
Used for command values used in a few functions.
157
These symbols are defined as members of the
158
.Vt Dv Elf_Cmd
159
enumeration.
160
.It Dv ELF_E_
161
Used for error numbers.
162
.It Dv ELF_F_
163
Used for flags.
164
.It Dv ELF_K_
165
These constants define the kind of file associated with an ELF
166
descriptor.
167
See
168
.Xr elf_kind 3 .
169
The symbols are defined by the
170
.Vt Elf_Kind
171
enumeration.
172
.It Dv ELF_T_
173
These values are defined by the
174
.Vt Elf_Type
175
enumeration, and denote the types of ELF data structures
176
that can be present in an ELF object.
177
.El
178
.Pp
179
In addition, the library uses symbols with prefixes
180
.Dv _ELF
181
and
182
.Dv _libelf
183
for its internal use.
184
.Ss Descriptors
185
Applications communicate with the library using descriptors.
186
These are:
187
.Bl -tag -width ".Vt Elf_Data"
188
.It Vt Elf
189
An
190
.Vt Elf
191
descriptor represents an ELF object or an
192
.Xr ar 1
193
archive.
194
It is allocated using one of the
195
.Fn elf_begin
196
or
197
.Fn elf_memory
198
functions.
199
An
200
.Vt Elf
201
descriptor can be used to read and write data to an ELF file.
202
An
203
.Vt Elf
204
descriptor can be associated with zero or more
205
.Vt Elf_Scn
206
section descriptors.
207
.Pp
208
Given an ELF descriptor, the application may retrieve the ELF
209
object's class-dependent
210
.Dq "Executable Header"
211
structures using the
212
.Fn elf32_getehdr
213
or
214
.Fn elf64_getehdr
215
functions.
216
A new Ehdr structure may be allocated using the
217
.Fn elf64_newehdr
218
or
219
.Fn elf64_newehdr
220
functions.
221
.Pp
222
The
223
.Dq "Program Header Table"
224
associated with an ELF descriptor may be allocated using the
225
.Fn elf32_getphdr
226
or
227
.Fn elf64_getphdr
228
functions.
229
A new program header table may be allocated or an existing table
230
resized using the
231
.Fn elf32_newphdr
232
or
233
.Fn elf64_newphdr
234
functions.
235
.Pp
236
The
237
.Vt Elf
238
structure is opaque and has no members visible to the
239
application.
240
.\" TODO describe the Elf_Arhdr and Elf_Arsym structures.
241
.It Vt Elf_Data
242
An
243
.Vt Elf_Data
244
data structure describes an individual chunk of a ELF file as
245
represented in memory.
246
It has the following application-visible members:
247
.Bl -tag -width ".Vt unsigned int d_version" -compact
248
.It Vt "uint64_t d_align"
249
The in-file alignment of the data buffer within its containing ELF section.
250
This value must be non-zero and a power of two.
251
.It Vt "void *d_buf"
252
A pointer to data in memory.
253
.It Vt "uint64_t d_off"
254
The offset within the containing section where this descriptor's data
255
would be placed.
256
This field will be computed by the library unless the application
257
requests full control of the ELF object's layout.
258
.It Vt "uint64_t d_size"
259
The number of bytes of data in this descriptor.
260
.It Vt "Elf_Type d_type"
261
The ELF type (see below) of the data in this descriptor.
262
.It Vt "unsigned int d_version"
263
The operating version for the data in this buffer.
264
.El
265
.Pp
266
.Vt Elf_Data
267
descriptors are usually associated with
268
.Vt Elf_Scn
269
descriptors.
270
Existing data descriptors associated with an ELF section may be
271
structures are retrieved using the
272
.Fn elf_getdata
273
and
274
.Fn elf_rawdata
275
functions.
276
The
277
.Fn elf_newdata
278
function may be used to attach new data descriptors to an ELF section.
279
.It Vt Elf_Scn
280
.Vt Elf_Scn
281
descriptors represent a section in an ELF object.
282
.Pp
283
They are retrieved using the
284
.Fn elf_getscn
285
function.
286
An application may iterate through the existing sections of an ELF
287
object using the
288
.Fn elf_nextscn
289
function.
290
New sections may be allocated using the
291
.Fn elf_newscn
292
function.
293
.Pp
294
The
295
.Vt Elf_Scn
296
descriptor is opaque and contains no application modifiable fields.
297
.El
298
.Ss Supported Elf Types
299
The following ELF datatypes are supported by the library.
300
.Pp
301
.Bl -tag -width ".Dv ELF_T_SYMINFO" -compact
302
.It Dv ELF_T_ADDR
303
Machine addresses.
304
.It Dv ELF_T_BYTE
305
Byte data.
306
The library will not attempt to translate byte data.
307
.It Dv ELF_T_CAP
308
Software and hardware capability records.
309
.It Dv ELF_T_DYN
310
Records used in a section of type
311
.Dv SHT_DYNAMIC .
312
.It Dv ELF_T_EHDR
313
ELF executable header.
314
.It Dv ELF_T_GNUHASH
315
GNU-style hash tables.
316
.It Dv ELF_T_HALF
317
16-bit unsigned words.
318
.It Dv ELF_T_LWORD
319
64 bit unsigned words.
320
.It Dv ELF_T_MOVE
321
ELF Move records.
322
.\".It Dv ELF_T_MOVEP
323
.\" As yet unsupported.
324
.It Dv ELF_T_NOTE
325
ELF Note structures.
326
.It Dv ELF_T_OFF
327
File offsets.
328
.It Dv ELF_T_PHDR
329
ELF program header table entries.
330
.It Dv ELF_T_REL
331
ELF relocation entries.
332
.It Dv ELF_T_RELA
333
ELF relocation entries with addends.
334
.It Dv ELF_T_SHDR
335
ELF section header entries.
336
.It Dv ELF_T_SWORD
337
Signed 32-bit words.
338
.It Dv ELF_T_SXWORD
339
Signed 64-bit words.
340
.It Dv ELF_T_SYMINFO
341
ELF symbol information.
342
.It Dv ELF_T_SYM
343
ELF symbol table entries.
344
.It Dv ELF_T_VDEF
345
Symbol version definition records.
346
.It Dv ELF_T_VNEED
347
Symbol version requirement records.
348
.It Dv ELF_T_WORD
349
Unsigned 32-bit words.
350
.It Dv ELF_T_XWORD
351
Unsigned 64-bit words.
352
.El
353
.Pp
354
The symbol
355
.Dv ELF_T_NUM
356
denotes the number of Elf types known to the library.
357
.Pp
358
The following table shows the mapping between ELF section types
359
defined in
360
.Xr elf 5
361
and the types supported by the library.
362
.Bl -column ".Dv SHT_PREINIT_ARRAY" ".Dv ELF_T_SYMINFO"
363
.It Em Section Type Ta Em "Library Type" Ta Em Description
364
.It Dv SHT_DYNAMIC Ta Dv ELF_T_DYN Ta Xo
365
.Sq .dynamic
366
section entries.
367
.Xc
368
.It Dv SHT_DYNSYM Ta Dv ELF_T_SYM Ta Symbols for dynamic linking.
369
.It Dv SHT_FINI_ARRAY Ta Dv ELF_T_ADDR Ta Termination function pointers.
370
.It Dv SHT_GNU_HASH Ta Dv ELF_T_GNUHASH Ta GNU hash sections.
371
.It Dv SHT_GNU_LIBLIST Ta Dv ELF_T_WORD Ta List of libraries to be pre-linked.
372
.It Dv SHT_GNU_verdef Ta Dv ELF_T_VDEF Ta Symbol version definitions.
373
.It Dv SHT_GNU_verneed Ta Dv ELF_T_VNEED Ta Symbol versioning requirements.
374
.It Dv SHT_GNU_versym Ta Dv ELF_T_HALF Ta Version symbols.
375
.It Dv SHT_GROUP Ta Dv ELF_T_WORD Ta Section group marker.
376
.It Dv SHT_HASH Ta Dv ELF_T_HASH Ta Symbol hashes.
377
.It Dv SHT_INIT_ARRAY Ta Dv ELF_T_ADDR Ta Initialization function pointers.
378
.It Dv SHT_NOBITS Ta Dv ELF_T_BYTE Ta Xo
379
Empty sections.
380
See
381
.Xr elf 5 .
382
.Xc
383
.It Dv SHT_NOTE Ta Dv ELF_T_NOTE Ta ELF note records.
384
.It Dv SHT_PREINIT_ARRAY Ta Dv ELF_T_ADDR Ta Pre-initialization function pointers.
385
.It Dv SHT_PROGBITS Ta Dv ELF_T_BYTE Ta Machine code.
386
.It Dv SHT_REL Ta Dv ELF_T_REL Ta ELF relocation records.
387
.It Dv SHT_RELA Ta Dv ELF_T_RELA Ta Relocation records with addends.
388
.It Dv SHT_STRTAB Ta Dv ELF_T_BYTE Ta String tables.
389
.It Dv SHT_SYMTAB Ta Dv ELF_T_SYM Ta Symbol tables.
390
.It Dv SHT_SYMTAB_SHNDX Ta Dv ELF_T_WORD Ta Used with extended section numbering.
391
.It Dv SHT_SUNW_dof Ta Dv ELF_T_BYTE Ta Xo
392
Used by
393
.Xr dtrace 1 .
394
.Xc
395
.It Dv SHT_SUNW_move Ta Dv ELF_T_MOVE Ta ELF move records.
396
.It Dv SHT_SUNW_syminfo Ta Dv ELF_T_SYMINFO Ta Additional symbol flags.
397
.It Dv SHT_SUNW_verdef Ta Dv ELF_T_VDEF Ta Xo
398
Same as
399
.Dv SHT_GNU_verdef .
400
.Xc
401
.It Dv SHT_SUNW_verneed Ta Dv ELF_T_VNEED Ta Xo
402
Same as
403
.Dv SHT_GNU_verneed .
404
.Xc
405
.It Dv SHT_SUNW_versym Ta Dv ELF_T_HALF Ta Xo
406
Same as
407
.Dv SHT_GNU_versym .
408
.Xc
409
.El
410
.Pp
411
Section types in the range
412
.Ns [ Dv SHT_LOOS ,
413
.Dv SHT_HIUSER ]
414
are otherwise considered to be of type
415
.Dv ELF_T_BYTE .
416
.Ss Functional Grouping
417
This section contains a brief overview of the available functionality
418
in the ELF library.
419
Each function listed here is described further in its own manual page.
420
.Bl -tag -width indent
421
.It "Archive Access"
422
.Bl -tag -compact
423
.It Fn elf_getarsym
424
Retrieve the archive symbol table.
425
.It Fn elf_getarhdr
426
Retrieve the archive header for an object.
427
.It Fn elf_getbase
428
Retrieve the offset of a member inside an archive.
429
.It Fn elf_next
430
Iterate through an
431
.Xr ar 1
432
archive.
433
.It Fn elf_rand
434
Random access inside an
435
.Xr ar 1
436
archive.
437
.El
438
.It "Data Structures"
439
.Bl -tag -compact
440
.It Fn elf_getdata
441
Retrieve translated data for an ELF section.
442
.It Fn elf_getscn
443
Retrieve the section descriptor for a named section.
444
.It Fn elf_ndxscn
445
Retrieve the index for a section.
446
.It Fn elf_newdata
447
Add a new
448
.Vt Elf_Data
449
descriptor to an ELF section.
450
.It Fn elf_newscn
451
Add a new section descriptor to an ELF descriptor.
452
.It Fn elf_nextscn
453
Iterate through the sections in an ELF object.
454
.It Fn elf_rawdata
455
Retrieve untranslated data for an ELF section.
456
.It Fn elf_rawfile
457
Return a pointer to the untranslated file contents for an ELF object.
458
.It Fn elf32_getehdr , Fn elf64_getehdr
459
Retrieve the Executable Header in an ELF object.
460
.It Fn elf32_getphdr , Fn elf64_getphdr
461
Retrieve the Program Header Table in an ELF object.
462
.It Fn elf32_getshdr , Fn elf64_getshdr
463
Retrieve the ELF section header associated with an
464
.Vt Elf_Scn
465
descriptor.
466
.It Fn elf32_newehdr , Fn elf64_newehdr
467
Allocate an Executable Header in an ELF object.
468
.It Fn elf32_newphdr , Fn elf64_newphdr
469
Allocate or resize the Program Header Table in an ELF object.
470
.El
471
.It "Data Translation"
472
.Bl -tag -compact
473
.It Fn elf32_xlatetof , Fn elf64_xlatetof
474
Translate an ELF data structure from its native representation to its
475
file representation.
476
.It Fn elf32_xlatetom , Fn elf64_xlatetom
477
Translate an ELF data structure from its file representation to a
478
native representation.
479
.El
480
.It "Error Reporting"
481
.Bl -tag -compact
482
.It Fn elf_errno
483
Retrieve the current error.
484
.It Fn elf_errmsg
485
Retrieve a human readable description of the current error.
486
.El
487
.It "Initialization"
488
.Bl -tag -compact
489
.It Fn elf_begin
490
Opens an
491
.Xr ar 1
492
archive or ELF object given a file descriptor.
493
.It Fn elf_end
494
Close an ELF descriptor and release all its resources.
495
.It Fn elf_memory
496
Opens an
497
.Xr ar 1
498
archive or ELF object present in a memory arena.
499
.It Fn elf_version
500
Sets the operating version.
501
.El
502
.It "IO Control"
503
.Bl -tag -width ".Fn elf_setshstrndx" -compact
504
.It Fn elf_cntl
505
Manage the association between and ELF descriptor and its underlying file.
506
.It Fn elf_flagdata
507
Mark an
508
.Vt Elf_Data
509
descriptor as dirty.
510
.It Fn elf_flagehdr
511
Mark the ELF Executable Header in an ELF descriptor as dirty.
512
.It Fn elf_flagphdr
513
Mark the ELF Program Header Table in an ELF descriptor as dirty.
514
.It Fn elf_flagscn
515
Mark an
516
.Vt Elf_Scn
517
descriptor as dirty.
518
.It Fn elf_flagshdr
519
Mark an ELF Section Header as dirty.
520
.It Fn elf_setshstrndx
521
Set the index of the section name string table for the ELF object.
522
.It Fn elf_update
523
Recompute ELF object layout and optionally write the modified object
524
back to the underlying file.
525
.El
526
.It "Queries"
527
.Bl -tag -width ".Fn elf_getshstrndx" -compact
528
.It Fn elf32_checksum , Fn elf64_checkum
529
Compute checksum of an ELF object.
530
.It Fn elf_getident
531
Retrieve the identification bytes for an ELF object.
532
.It Fn elf_getshnum
533
Retrieve the number of sections in an ELF object.
534
.It Fn elf_getshstrndx
535
Retrieve the section index of the section name string table in
536
an ELF object.
537
.It Fn elf_hash
538
Compute the ELF hash value of a string.
539
.It Fn elf_kind
540
Query the kind of object associated with an ELF descriptor.
541
.It Fn elf32_fsize , Fn elf64_fsize
542
Return the size of the file representation of an ELF type.
543
.El
544
.El
545
.Ss Controlling ELF Object Layout
546
In the usual mode of operation, library will compute section
547
offsets and alignments based on the contents of an ELF descriptor's
548
sections without need for further intervention by the
549
application.
550
.Pp
551
However, if the application wishes to take complete charge of the
552
layout of the ELF file, it may set the
553
.Dv ELF_F_LAYOUT
554
flag on an ELF descriptor using
555
.Xr elf_flagelf 3 ,
556
following which the library will use the data offsets and alignments
557
specified by the application when laying out the file.
558
Application control of file layout is described further in the
559
.Xr elf_update 3
560
manual page.
561
.Pp
562
Gaps in between sections will be filled with the fill character
563
set by function
564
.Fn elf_fill .
565
.Ss Error Handling
566
In case an error is encountered, these library functions set an
567
internal error number and signal the presence of the error by
568
returning an special return value.
569
The application can check the
570
current error number by calling
571
.Xr elf_errno 3 .
572
A human readable description of the recorded error is available by
573
calling
574
.Xr elf_errmsg 3 .
575
.Ss Memory Management Rules
576
The library keeps track of all
577
.Vt Elf_Scn
578
and
579
.Vt Elf_Data
580
descriptors associated with an ELF descriptor and recovers them
581
when the descriptor is closed using
582
.Xr elf_end 3 .
583
Thus the application must not call
584
.Xr free 3
585
on data structures allocated by the ELF library.
586
.Pp
587
Conversely the library will not
588
free data that it has not allocated.
589
As an example, an application may call
590
.Xr elf_newdata 3
591
to allocate a new
592
.Vt Elf_Data
593
descriptor and can set the
594
.Va d_off
595
member of the descriptor to point to a region of memory allocated
596
using
597
.Xr malloc 3 .
598
It is the applications responsibility to free this arena, though the
599
library will reclaim the space used by the
600
.Vt Elf_Data
601
descriptor itself.
602
.Sh SEE ALSO
603
.Xr gelf 3 ,
604
.Xr elf 5
605
.Sh HISTORY
606
The original ELF(3) API was developed for Unix System V.
607
The current implementation of the ELF(3) API appeared in
608
.Fx 7.0 .
609
.Sh AUTHORS
610
The ELF library was written by
611
.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org .
contrib/elftoolchain/libelf/elf_begin.3
1
.\" Copyright (c) 2006,2008-2011 Joseph Koshy.  All rights reserved.
2
.\"
3
.\" Redistribution and use in source and binary forms, with or without
4
.\" modification, are permitted provided that the following conditions
5
.\" are met:
6
.\" 1. Redistributions of source code must retain the above copyright
7
.\"    notice, this list of conditions and the following disclaimer.
8
.\" 2. Redistributions in binary form must reproduce the above copyright
9
.\"    notice, this list of conditions and the following disclaimer in the
10
.\"    documentation and/or other materials provided with the distribution.
11
.\"
12
.\" This software is provided by Joseph Koshy ``as is'' and
13
.\" any express or implied warranties, including, but not limited to, the
14
.\" implied warranties of merchantability and fitness for a particular purpose
15
.\" are disclaimed.  in no event shall Joseph Koshy be liable
16
.\" for any direct, indirect, incidental, special, exemplary, or consequential
17
.\" damages (including, but not limited to, procurement of substitute goods
18
.\" or services; loss of use, data, or profits; or business interruption)
19
.\" however caused and on any theory of liability, whether in contract, strict
20
.\" liability, or tort (including negligence or otherwise) arising in any way
21
.\" out of the use of this software, even if advised of the possibility of
22
.\" such damage.
23
.\"
24
.\" $Id: elf_begin.3 3182 2015-04-10 16:08:10Z emaste $
25
.\"
26
.Dd December 11, 2011
27
.Os
28
.Dt ELF_BEGIN 3
29
.Sh NAME
30
.Nm elf_begin
31
.Nd open an ELF file or ar(1) archive
32
.Sh LIBRARY
33
.Lb libelf
34
.Sh SYNOPSIS
35
.In libelf.h
36
.Ft "Elf *"
37
.Fn elf_begin "int fd" "Elf_Cmd cmd" "Elf *elf"
38
.Sh DESCRIPTION
39
Function
40
.Fn elf_begin
41
is used to open ELF files and
42
.Xr ar 1
43
archives for further processing by other APIs in the
44
.Xr elf 3
45
library.
46
It is also used to access individual ELF members of an
47
.Xr ar 1
48
archive in combination with the
49
.Xr elf_next 3
50
and
51
.Xr elf_rand 3
52
APIs.
53
.Pp
54
Argument
55
.Ar fd
56
is an open file descriptor returned from an
57
.Xr open 2
58
system call.
59
Function
60
.Fn elf_begin
61
uses argument
62
.Ar fd
63
for reading or writing depending on the value of argument
64
.Ar cmd .
65
Argument
66
.Ar elf
67
is primarily used for iterating through archives.
68
.Pp
69
The argument
70
.Ar cmd
71
can have the following values:
72
.Bl -tag -width "ELF_C_WRITE"
73
.It ELF_C_NULL
74
Causes
75
.Fn elf_begin
76
to return NULL.
77
Arguments
78
.Ar fd
79
and
80
.Ar elf
81
are ignored, and no additional error is signalled.
82
.It ELF_C_READ
83
This value is to be when the application wishes to examine (but not
84
modify) the contents of the file specified by the arguments
85
.Ar fd
86
and
87
.Ar elf .
88
It can be used for both
89
.Xr ar 1
90
archives and for ELF objects.
91
.Pp
92
If argument
93
.Ar elf
94
is NULL, the library will allocate a new ELF descriptor for the file
95
being processed.
96
The argument
97
.Ar fd
98
should have been opened for reading.
99
.Pp
100
If argument
101
.Ar elf
102
is not NULL, and references a regular ELF file previously opened with
103
.Fn elf_begin ,
104
then the activation count for the descriptor referenced by argument
105
.Ar elf
106
is incremented.
107
The value in argument
108
.Ar fd
109
should match that used to open the descriptor argument
110
.Ar elf .
111
.Pp
112
If argument
113
.Ar elf
114
is not NULL, and references a descriptor for an
115
.Xr ar 1
116
archive opened earlier with
117
.Fn elf_begin ,
118
a descriptor for an element in the archive is returned as
119
described in the section
120
.Sx "Processing ar(1) archives"
121
below.
122
The value for argument
123
.Ar fd
124
should match that used to open the archive earlier.
125
.Pp
126
If argument
127
.Ar elf
128
is not NULL, and references an
129
.Xr ar 1
130
archive opened earlier with
131
.Fn elf_memory ,
132
then the value of the argument
133
.Ar fd
134
is ignored.
135
.It Dv ELF_C_RDWR
136
This command is used to prepare an ELF file for reading and writing.
137
This command is not supported for
138
.Xr ar 1
139
archives.
140
.Pp
141
Argument
142
.Ar fd
143
should have been opened for reading and writing.
144
If argument
145
.Ar elf
146
is NULL, the library will allocate a new ELF descriptor for
147
the file being processed.
148
If the argument
149
.Ar elf
150
is non-null, it should point to a descriptor previously
151
allocated with
152
.Fn elf_begin
153
with the same values for arguments
154
.Ar fd
155
and
156
.Ar cmd ;
157
in this case the library will increment the activation count for descriptor
158
.Ar elf
159
and return the same descriptor.
160
.Pp
161
Changes to the in-memory image of the ELF file may be written back to
162
disk using the
163
.Xr elf_update 3
164
function.
165
.It Dv ELF_C_WRITE
166
This command is used when the application wishes to create a new ELF
167
file.
168
Argument
169
.Ar fd
170
should have been opened for writing.
171
Argument
172
.Ar elf
173
is ignored, and the previous contents of file referenced by argument
174
.Ar fd
175
are overwritten.
176
.El
177
.Ss Processing ar(1) archives
178
An
179
.Xr ar 1
180
archive may be opened in read mode (with argument
181
.Ar cmd
182
set to
183
.Dv ELF_C_READ )
184
using
185
.Fn elf_begin
186
or
187
.Fn elf_memory .
188
The returned ELF descriptor can be passed into to
189
subsequent calls to
190
.Fn elf_begin
191
to access individual members of the archive.
192
.Pp
193
Random access within an opened archive is possible using
194
the
195
.Xr elf_next 3
196
and
197
.Xr elf_rand 3
198
functions.
199
.Pp
200
The symbol table of the archive may be retrieved
201
using
202
.Xr elf_getarsym 3 .
203
.Sh RETURN VALUES
204
The function returns a pointer to a ELF descriptor if successful, or NULL
205
if an error occurred.
206
.Sh EXAMPLES
207
To iterate through the members of an
208
.Xr ar 1
209
archive, use:
210
.Bd -literal -offset indent
211
Elf_Cmd c;
212
Elf *ar_e, *elf_e;
213
\&...
214
c = ELF_C_READ;
215
if ((ar_e = elf_begin(fd, c, (Elf *) 0)) == 0) {
216
	\&... handle error in opening the archive ...
217
}
218
while ((elf_e = elf_begin(fd, c, ar_e)) != 0) {
219
	\&... process member referenced by elf_e here ...
220
	c = elf_next(elf_e);
221
	elf_end(elf_e);
222
}
223
.Ed
224
.Pp
225
To create a new ELF file, use:
226
.Bd -literal -offset indent
227
int fd;
228
Elf *e;
229
\&...
230
if ((fd = open("filename", O_RDWR|O_TRUNC|O_CREAT, 0666)) < 0) {
231
	\&... handle the error from open(2) ...
232
}
233
if ((e = elf_begin(fd, ELF_C_WRITE, (Elf *) 0)) == 0) {
234
	\&... handle the error from elf_begin() ...
235
}
236
\&... create the ELF image using other elf(3) APIs ...
237
elf_update(e, ELF_C_WRITE);
238
elf_end(e);
239
.Ed
240
.Sh ERRORS
241
Function
242
.Fn elf_begin
243
can fail with the following errors:
244
.Bl -tag -width "[ELF_E_RESOURCE]"
245
.It Bq Er ELF_E_ARCHIVE
246
The archive denoted by argument
247
.Ar elf
248
could not be parsed.
249
.It Bq Er ELF_E_ARGUMENT
250
The value in argument
251
.Ar cmd
252
was unrecognized.
253
.It Bq Er ELF_E_ARGUMENT
254
A non-null value for argument
255
.Ar elf
256
was specified when
257
.Ar cmd
258
was set to
259
.Dv ELF_C_RDWR .
260
.It Bq Er ELF_E_ARGUMENT
261
The value of argument
262
.Ar fd
263
differs from the one the ELF descriptor
264
.Ar elf
265
was created with.
266
.It Bq Er ELF_E_ARGUMENT
267
Argument
268
.Ar cmd
269
differs from the value specified when ELF descriptor
270
.Ar elf
271
was created.
272
.It Bq Er ELF_E_ARGUMENT
273
An
274
.Xr ar 1
275
archive was opened with
276
.Ar cmd
277
set to
278
.Dv ELF_C_RDWR .
279
.It Bq Er ELF_E_ARGUMENT
280
The file referenced by argument
281
.Ar fd
282
was empty.
283
.It Bq Er ELF_E_ARGUMENT
284
The underlying file for argument
285
.Ar fd
286
was of an unsupported type.
287
.It Bq Er ELF_E_IO
288
The file descriptor in argument
289
.Ar fd
290
was invalid.
291
.It Bq Er ELF_E_IO
292
The file descriptor in argument
293
.Ar fd
294
could not be read or written to.
295
.It Bq Er ELF_E_RESOURCE
296
An out of memory condition was encountered.
297
.It Bq Er ELF_E_SEQUENCE
298
Function
299
.Fn elf_begin
300
was called before a working version was established with
301
.Xr elf_version 3 .
302
.It Bq Er ELF_E_VERSION
303
The ELF object referenced by argument
304
.Ar fd
305
was of an unsupported ELF version.
306
.El
307
.Sh SEE ALSO
308
.Xr elf 3 ,
309
.Xr elf_end 3 ,
310
.Xr elf_errno 3 ,
311
.Xr elf_memory 3 ,
312
.Xr elf_next 3 ,
313
.Xr elf_rand 3 ,
314
.Xr elf_update 3 ,
315
.Xr gelf 3
contrib/elftoolchain/libelf/elf_cntl.3
1
.\" Copyright (c) 2006,2008 Joseph Koshy.  All rights reserved.
2
.\"
3
.\" Redistribution and use in source and binary forms, with or without
4
.\" modification, are permitted provided that the following conditions
5
.\" are met:
6
.\" 1. Redistributions of source code must retain the above copyright
7
.\"    notice, this list of conditions and the following disclaimer.
8
.\" 2. Redistributions in binary form must reproduce the above copyright
9
.\"    notice, this list of conditions and the following disclaimer in the
10
.\"    documentation and/or other materials provided with the distribution.
11
.\"
12
.\" This software is provided by Joseph Koshy ``as is'' and
13
.\" any express or implied warranties, including, but not limited to, the
14
.\" implied warranties of merchantability and fitness for a particular purpose
15
.\" are disclaimed.  in no event shall Joseph Koshy be liable
16
.\" for any direct, indirect, incidental, special, exemplary, or consequential
17
.\" damages (including, but not limited to, procurement of substitute goods
18
.\" or services; loss of use, data, or profits; or business interruption)
19
.\" however caused and on any theory of liability, whether in contract, strict
20
.\" liability, or tort (including negligence or otherwise) arising in any way
21
.\" out of the use of this software, even if advised of the possibility of
22
.\" such damage.
23
.\"
24
.\" $Id: elf_cntl.3 3181 2015-04-10 13:22:51Z emaste $
25
.\"
26
.Dd August 9, 2006
27
.Os
28
.Dt ELF_CNTL 3
29
.Sh NAME
30
.Nm elf_cntl
31
.Nd control an elf file descriptor
32
.Sh LIBRARY
33
.Lb libelf
34
.Sh SYNOPSIS
35
.In libelf.h
36
.Ft int
37
.Fn elf_cntl "Elf *elf" "Elf_Cmd cmd"
38
.Sh DESCRIPTION
39
Function
40
.Fn elf_cntl
41
controls the ELF library's subsequent use of the file descriptor
42
used to create ELF descriptor
43
.Ar elf .
44
.Pp
45
Argument
46
.Ar cmd
47
informs the library of the action to be taken:
48
.Bl -tag -width "ELF_C_FDDONE"
49
.It Dv ELF_C_FDDONE
50
This value instructs the ELF library not to perform any further
51
I/O on the file descriptor associated with argument
52
.Ar elf .
53
For ELF descriptors opened with mode
54
.Ar ELF_C_WRITE
55
or
56
.Ar ELF_C_RDWR
57
subsequent
58
.Fn elf_update
59
operations on the descriptor will fail.
60
.It Dv ELF_C_FDREAD
61
This value instructs the ELF library to read in all necessary
62
data associated with ELF descriptor
63
.Ar elf
64
into memory so that the underlying file descriptor can be
65
safely closed with command
66
.Dv ELF_C_FDDONE .
67
.El
68
.Pp
69
Argument
70
.Ar elf
71
must be an ELF descriptor associated with a file system object
72
(e.g., an
73
.Xr ar 1
74
archive, an ELF file, or other data file).
75
.Sh IMPLEMENTATION NOTES
76
Due to use of
77
.Xr mmap 2
78
internally, this function is a no-op for ELF objects opened in
79
.Dv ELF_C_READ
80
mode.
81
.Sh RETURN VALUES
82
Function
83
.Fn elf_cntl
84
returns 0 on success, or -1 if an error was detected.
85
.Sh ERRORS
86
.Bl -tag -width "[ELF_E_RESOURCE]"
87
.It Bq Er ELF_E_ARCHIVE
88
Argument
89
.Ar elf
90
is a descriptor for an archive member.
91
.It Bq Er ELF_E_ARGUMENT
92
Argument
93
.Ar elf
94
was NULL.
95
.It Bq Er ELF_E_ARGUMENT
96
Argument
97
.Ar cmd
98
was not recognized.
99
.It Bq Er ELF_E_MODE
100
An
101
.Dv ELF_C_FDREAD
102
operation was requested on an ELF descriptor opened
103
for writing.
104
.El
105
.Sh SEE ALSO
106
.Xr elf 3 ,
107
.Xr elf_begin 3 ,
108
.Xr elf_end 3 ,
109
.Xr elf_next 3 ,
110
.Xr elf_update 3 ,
111
.Xr gelf 3
contrib/elftoolchain/libelf/elf_data.c
32 32

  
33 33
#include "_libelf.h"
34 34

  
35
ELFTC_VCSID("$Id: elf_data.c 3177 2015-03-30 18:19:41Z emaste $");
35
ELFTC_VCSID("$Id: elf_data.c 3466 2016-05-11 18:35:44Z emaste $");
36 36

  
37 37
Elf_Data *
38 38
elf_getdata(Elf_Scn *s, Elf_Data *ed)
......
94 94

  
95 95
	if ((elftype = _libelf_xlate_shtype(sh_type)) < ELF_T_FIRST ||
96 96
	    elftype > ELF_T_LAST || (sh_type != SHT_NOBITS &&
97
	    sh_offset + sh_size > (uint64_t) e->e_rawsize)) {
97
	    (sh_offset > e->e_rawsize || sh_size > e->e_rawsize - sh_offset))) {
98 98
		LIBELF_SET_ERROR(SECTION, 0);
99 99
		return (NULL);
100 100
	}
......
253 253
		return (NULL);
254 254
	}
255 255

  
256
	if (sh_type != SHT_NOBITS &&
257
	    (sh_offset > e->e_rawsize || sh_size > e->e_rawsize - sh_offset)) {
258
		LIBELF_SET_ERROR(SECTION, 0);
259
		return (NULL);
260
	}
261

  
256 262
	if ((d = _libelf_allocate_data(s)) == NULL)
257 263
		return (NULL);
258 264

  
contrib/elftoolchain/libelf/elf_end.3
1
.\" Copyright (c) 2006,2008 Joseph Koshy.  All rights reserved.
2
.\"
3
.\" Redistribution and use in source and binary forms, with or without
4
.\" modification, are permitted provided that the following conditions
5
.\" are met:
6
.\" 1. Redistributions of source code must retain the above copyright
7
.\"    notice, this list of conditions and the following disclaimer.
8
.\" 2. Redistributions in binary form must reproduce the above copyright
9
.\"    notice, this list of conditions and the following disclaimer in the
10
.\"    documentation and/or other materials provided with the distribution.
11
.\"
12
.\" This software is provided by Joseph Koshy ``as is'' and
13
.\" any express or implied warranties, including, but not limited to, the
14
.\" implied warranties of merchantability and fitness for a particular purpose
15
.\" are disclaimed.  in no event shall Joseph Koshy be liable
16
.\" for any direct, indirect, incidental, special, exemplary, or consequential
17
.\" damages (including, but not limited to, procurement of substitute goods
18
.\" or services; loss of use, data, or profits; or business interruption)
19
.\" however caused and on any theory of liability, whether in contract, strict
20
.\" liability, or tort (including negligence or otherwise) arising in any way
21
.\" out of the use of this software, even if advised of the possibility of
22
.\" such damage.
23
.\"
24
.\" $Id: elf_end.3 189 2008-07-20 10:38:08Z jkoshy $
25
.\"
26
.Dd June 29, 2006
27
.Os
28
.Dt ELF_END 3
29
.Sh NAME
30
.Nm elf_end
31
.Nd release an ELF descriptor
32
.Sh LIBRARY
33
.Lb libelf
34
.Sh SYNOPSIS
35
.In libelf.h
36
.Ft int
37
.Fn elf_end "Elf *elf"
38
.Sh DESCRIPTION
39
Function
40
.Fn elf_end
41
is used to release the resources associated with an ELF descriptor
42
pointed to by argument
43
.Ar elf .
44
This descriptor must have been allocated by a previous call to
45
.Xr elf_begin 3
46
or
47
.Xr elf_memory 3 .
48
For programming convenience, a NULL value is permitted for argument
49
.Ar elf .
50
.Pp
51
A call to
52
.Fn elf_end
53
decrements the activation count for descriptor
54
.Ar elf
55
by one.
56
The resources associated with the descriptor are only released
57
with its activation count goes to zero.
58
.Pp
59
Once function
60
.Fn elf_end
61
returns zero, the ELF descriptor
62
.Ar elf
63
will no longer be valid and should not be used further.
64
.Sh RETURN VALUES
65
Function
66
.Fn elf_end
67
returns the current value of the ELF descriptor
68
.Ar elf Ap s
69
activation count, or zero if argument
70
.Ar elf
71
was NULL.
72
.Sh SEE ALSO
73
.Xr elf 3 ,
74
.Xr elf_begin 3 ,
75
.Xr elf_memory 3 ,
76
.Xr gelf 3
contrib/elftoolchain/libelf/elf_errmsg.3
1
.\" Copyright (c) 2006,2008 Joseph Koshy.  All rights reserved.
2
.\"
3
.\" Redistribution and use in source and binary forms, with or without
4
.\" modification, are permitted provided that the following conditions
5
.\" are met:
6
.\" 1. Redistributions of source code must retain the above copyright
7
.\"    notice, this list of conditions and the following disclaimer.
8
.\" 2. Redistributions in binary form must reproduce the above copyright
9
.\"    notice, this list of conditions and the following disclaimer in the
10
.\"    documentation and/or other materials provided with the distribution.
11
.\"
12
.\" This software is provided by Joseph Koshy ``as is'' and
13
.\" any express or implied warranties, including, but not limited to, the
14
.\" implied warranties of merchantability and fitness for a particular purpose
15
.\" are disclaimed.  in no event shall Joseph Koshy be liable
16
.\" for any direct, indirect, incidental, special, exemplary, or consequential
17
.\" damages (including, but not limited to, procurement of substitute goods
18
.\" or services; loss of use, data, or profits; or business interruption)
19
.\" however caused and on any theory of liability, whether in contract, strict
20
.\" liability, or tort (including negligence or otherwise) arising in any way
21
.\" out of the use of this software, even if advised of the possibility of
22
.\" such damage.
23
.\"
24
.\" $Id: elf_errmsg.3 189 2008-07-20 10:38:08Z jkoshy $
25
.\"
26
.Dd June 11, 2006
27
.Os
28
.Dt ELF_ERRMSG 3
29
.Sh NAME
30
.Nm elf_errmsg ,
31
.Nm elf_errno
32
.Nd ELF library error message handling
33
.Sh LIBRARY
34
.Lb libelf
35
.Sh SYNOPSIS
36
.In libelf.h
37
.Ft int
38
.Fn elf_errno "void"
39
.Ft "const char *"
40
.Fn elf_errmsg "int error"
41
.Sh DESCRIPTION
42
When an error occurs during an ELF library API call, the library
43
encodes the error using an error number and stores the error number
44
internally for retrieval by the application at a later point of time.
45
Error numbers may contain an OS supplied error code in addition to
46
an ELF API specific error code.
47
An error number value of zero indicates no error.
48
.Pp
49
Function
50
.Fn elf_errno
51
is used to retrieve the last error recorded by the ELF library.
52
Invoking this function has the side-effect of resetting the
53
ELF library's recorded error number to zero.
54
.Pp
55
The function
56
.Fn elf_errmsg
57
returns a null-terminated string with a human readable
58
description of the error specified in argument
59
.Ar error .
60
A zero value for argument
61
.Ar error
62
retrieves the most recent error encountered by the ELF
63
library.
64
An argument value of -1 behaves identically, except that
65
it guarantees a non-NULL return from
66
.Fn elf_errmsg .
67
.Sh RETURN VALUES
68
Function
69
.Fn elf_errno
70
returns a non-zero value encoding the last error encountered
71
by the ELF library, or zero if no error was encountered.
72
.Pp
73
Function
74
.Fn elf_errmsg
75
returns a pointer to library local storage for non-zero values
76
of argument
77
.Ar error .
78
With a zero argument, the function will return a NULL pointer if no
79
error had been encountered by the library, or will return a pointer to
80
library local storage containing an appropriate message otherwise.
81
.Sh EXAMPLES
82
Clearing the ELF library's recorded error number can be accomplished
83
by invoking
84
.Fn elf_errno
85
and discarding its return value.
86
.Bd -literal -offset indent
87
/* clear error */
88
(void) elf_errno();
89
.Ed
90
.Pp
91
Retrieving a human-readable description of the current error number
92
can be done with the following snippet:
93
.Bd -literal -offset indent
94
int err;
95
const char *errmsg;
96
\&...
97
err = elf_errno();
98
if (err != 0)
99
	errmsg = elf_errmsg(err);
100
.Ed
101
.Sh SEE ALSO
102
.Xr elf 3 ,
103
.Xr gelf 3
104
.Sh BUGS
105
Function
106
.Fn elf_errmsg
107
is not localized.
contrib/elftoolchain/libelf/elf_fill.3
1
.\" Copyright (c) 2006,2008 Joseph Koshy.  All rights reserved.
2
.\"
3
.\" Redistribution and use in source and binary forms, with or without
4
.\" modification, are permitted provided that the following conditions
5
.\" are met:
6
.\" 1. Redistributions of source code must retain the above copyright
7
.\"    notice, this list of conditions and the following disclaimer.
8
.\" 2. Redistributions in binary form must reproduce the above copyright
9
.\"    notice, this list of conditions and the following disclaimer in the
10
.\"    documentation and/or other materials provided with the distribution.
11
.\"
12
.\" This software is provided by Joseph Koshy ``as is'' and
13
.\" any express or implied warranties, including, but not limited to, the
14
.\" implied warranties of merchantability and fitness for a particular purpose
15
.\" are disclaimed.  in no event shall Joseph Koshy be liable
16
.\" for any direct, indirect, incidental, special, exemplary, or consequential
17
.\" damages (including, but not limited to, procurement of substitute goods
18
.\" or services; loss of use, data, or profits; or business interruption)
19
.\" however caused and on any theory of liability, whether in contract, strict
20
.\" liability, or tort (including negligence or otherwise) arising in any way
21
.\" out of the use of this software, even if advised of the possibility of
22
.\" such damage.
23
.\"
24
.\" $Id: elf_fill.3 189 2008-07-20 10:38:08Z jkoshy $
25
.\"
26
.Dd June 11, 2006
27
.Os
28
.Dt ELF_FILL 3
29
.Sh NAME
30
.Nm elf_fill
31
.Nd set fill byte for inter-section padding
32
.Sh LIBRARY
33
.Lb libelf
34
.Sh SYNOPSIS
35
.In libelf.h
36
.Ft void
37
.Fn elf_fill "int fill"
38
.Sh DESCRIPTION
39
Function
40
.Fn elf_fill
41
allows an application to specify a fill value for the padding inserted
42
between two sections of an ELF file to meet section alignment
43
constraints.
44
By default the ELF library uses zero bytes for padding.
45
.Pp
46
The ELF library will only pad bytes if the
47
.Dv ELF_F_LAYOUT
48
flag is not set for the ELF file.
49
.Sh SEE ALSO
50
.Xr elf 3 ,
51
.Xr elf_flagelf 3 ,
... This diff was truncated because it exceeds the maximum size that can be displayed.