Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src/external/bsd/elftoolchain/dist/libelf Update libelf's manual...
details: https://anonhg.NetBSD.org/src/rev/e26ffb843402
branches: trunk
changeset: 953431:e26ffb843402
user: jkoshy <jkoshy%NetBSD.org@localhost>
date: Mon Mar 08 20:55:06 2021 +0000
description:
Update libelf's manual pages to upstream revision [r3928].
diffstat:
external/bsd/elftoolchain/dist/libelf/elf.3 | 97 ++++++++------
external/bsd/elftoolchain/dist/libelf/elf_begin.3 | 32 +++-
external/bsd/elftoolchain/dist/libelf/elf_cntl.3 | 9 +-
external/bsd/elftoolchain/dist/libelf/elf_end.3 | 13 +-
external/bsd/elftoolchain/dist/libelf/elf_errmsg.3 | 14 +-
external/bsd/elftoolchain/dist/libelf/elf_fill.3 | 6 +-
external/bsd/elftoolchain/dist/libelf/elf_flagdata.3 | 26 ++-
external/bsd/elftoolchain/dist/libelf/elf_getarhdr.3 | 13 +-
external/bsd/elftoolchain/dist/libelf/elf_getarsym.3 | 16 +-
external/bsd/elftoolchain/dist/libelf/elf_getbase.3 | 9 +-
external/bsd/elftoolchain/dist/libelf/elf_getdata.3 | 19 +-
external/bsd/elftoolchain/dist/libelf/elf_getident.3 | 17 +-
external/bsd/elftoolchain/dist/libelf/elf_getphdrnum.3 | 15 +-
external/bsd/elftoolchain/dist/libelf/elf_getphnum.3 | 11 +-
external/bsd/elftoolchain/dist/libelf/elf_getscn.3 | 30 +++-
external/bsd/elftoolchain/dist/libelf/elf_getshdrnum.3 | 11 +-
external/bsd/elftoolchain/dist/libelf/elf_getshdrstrndx.3 | 11 +-
external/bsd/elftoolchain/dist/libelf/elf_getshnum.3 | 11 +-
external/bsd/elftoolchain/dist/libelf/elf_getshstrndx.3 | 26 ++-
external/bsd/elftoolchain/dist/libelf/elf_hash.3 | 6 +-
external/bsd/elftoolchain/dist/libelf/elf_kind.3 | 13 +-
external/bsd/elftoolchain/dist/libelf/elf_memory.3 | 14 +-
external/bsd/elftoolchain/dist/libelf/elf_next.3 | 11 +-
external/bsd/elftoolchain/dist/libelf/elf_open.3 | 26 ++-
external/bsd/elftoolchain/dist/libelf/elf_rand.3 | 6 +-
external/bsd/elftoolchain/dist/libelf/elf_rawfile.3 | 13 +-
external/bsd/elftoolchain/dist/libelf/elf_strptr.3 | 14 +-
external/bsd/elftoolchain/dist/libelf/elf_update.3 | 12 +-
external/bsd/elftoolchain/dist/libelf/elf_version.3 | 6 +-
external/bsd/elftoolchain/dist/libelf/gelf.3 | 27 ++-
external/bsd/elftoolchain/dist/libelf/gelf_checksum.3 | 9 +-
external/bsd/elftoolchain/dist/libelf/gelf_fsize.3 | 10 +-
external/bsd/elftoolchain/dist/libelf/gelf_getcap.3 | 21 ++-
external/bsd/elftoolchain/dist/libelf/gelf_getclass.3 | 6 +-
external/bsd/elftoolchain/dist/libelf/gelf_getdyn.3 | 22 ++-
external/bsd/elftoolchain/dist/libelf/gelf_getehdr.3 | 10 +-
external/bsd/elftoolchain/dist/libelf/gelf_getmove.3 | 21 ++-
external/bsd/elftoolchain/dist/libelf/gelf_getphdr.3 | 19 +-
external/bsd/elftoolchain/dist/libelf/gelf_getrel.3 | 21 ++-
external/bsd/elftoolchain/dist/libelf/gelf_getrela.3 | 21 ++-
external/bsd/elftoolchain/dist/libelf/gelf_getshdr.3 | 17 +-
external/bsd/elftoolchain/dist/libelf/gelf_getsym.3 | 21 ++-
external/bsd/elftoolchain/dist/libelf/gelf_getsyminfo.3 | 21 ++-
external/bsd/elftoolchain/dist/libelf/gelf_getsymshndx.3 | 52 ++++++-
external/bsd/elftoolchain/dist/libelf/gelf_newehdr.3 | 26 +++-
external/bsd/elftoolchain/dist/libelf/gelf_newphdr.3 | 27 +++-
external/bsd/elftoolchain/dist/libelf/gelf_update_ehdr.3 | 9 +-
external/bsd/elftoolchain/dist/libelf/gelf_xlatetof.3 | 71 ++++++++--
48 files changed, 603 insertions(+), 335 deletions(-)
diffs (truncated from 2664 to 300 lines):
diff -r 577d4c6a634d -r e26ffb843402 external/bsd/elftoolchain/dist/libelf/elf.3
--- a/external/bsd/elftoolchain/dist/libelf/elf.3 Mon Mar 08 20:43:22 2021 +0000
+++ b/external/bsd/elftoolchain/dist/libelf/elf.3 Mon Mar 08 20:55:06 2021 +0000
@@ -1,6 +1,6 @@
-.\" $NetBSD: elf.3,v 1.4 2016/04/28 07:06:11 wiz Exp $
+.\" $NetBSD: elf.3,v 1.5 2021/03/08 20:55:06 jkoshy Exp $
.\"
-.\" Copyright (c) 2006-2008,2011 Joseph Koshy. All rights reserved.
+.\" Copyright (c) 2006-2008,2011,2019 Joseph Koshy. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@@ -23,11 +23,11 @@
.\" out of the use of this software, even if advised of the possibility of
.\" such damage.
.\"
-.\" Id: elf.3 3195 2015-05-12 17:22:19Z emaste
+.\" Id: elf.3 3927 2021-03-07 17:22:22Z jkoshy
.\"
-.Dd July 28, 2014
+.Dd March 7, 2021
+.Dt ELF 3
.Os
-.Dt ELF 3
.Sh NAME
.Nm elf
.Nd API for manipulating ELF objects
@@ -52,7 +52,7 @@
This manual page serves to provide an overview of the functionality in
the ELF library.
Further information may found in the manual pages for individual
-.Nm
+.Xr ELF 3
functions that comprise the library.
.Ss ELF Concepts
As described in
@@ -93,7 +93,7 @@
of an ELF file and the semantics associated with these.
.Ss Data Representation And Translation
The
-.Nm
+.Xr ELF 3
library distinguishes between
.Dq native
representations of ELF data structures and their
@@ -111,16 +111,19 @@
constraints.
.Pp
Accordingly, the
-.Nm
+.Xr ELF 3
library offers translation facilities
.Xr ( elf32_xlatetof 3 ,
.Xr elf32_xlatetom 3 ,
.Xr elf64_xlatetof 3
and
.Xr elf64_xlatetom 3 )
-to and from these
-representations and also provides higher-level APIs that retrieve and store
-data from the ELF object in a transparent manner.
+to and from these representations.
+It also provides higher-level APIs
+.Xr ( gelf_xlatetof 3 ,
+.Xr gelf_xlatetom 3 )
+that retrieve and store data from the ELF object in a class-agnostic
+manner.
.Ss Library Working Version
Conceptually, there are three version numbers associated with an
application using the ELF library to manipulate ELF objects:
@@ -157,7 +160,7 @@
.It Dv ELF_C_
Used for command values used in a few functions.
These symbols are defined as members of the
-.Vt Dv Elf_Cmd
+.Vt Elf_Cmd
enumeration.
.It Dv ELF_E_
Used for error numbers.
@@ -239,7 +242,6 @@
.Vt Elf
structure is opaque and has no members visible to the
application.
-.\" TODO describe the Elf_Arhdr and Elf_Arsym structures.
.It Vt Elf_Data
An
.Vt Elf_Data
@@ -266,36 +268,43 @@
.El
.Pp
.Vt Elf_Data
-descriptors are usually associated with
+descriptors are usually used in conjunction with
.Vt Elf_Scn
descriptors.
-Existing data descriptors associated with an ELF section may be
-structures are retrieved using the
-.Fn elf_getdata
-and
-.Fn elf_rawdata
-functions.
-The
-.Fn elf_newdata
-function may be used to attach new data descriptors to an ELF section.
.It Vt Elf_Scn
.Vt Elf_Scn
-descriptors represent a section in an ELF object.
+descriptors represent sections in an ELF object.
+These descriptors are opaque and contain no application modifiable
+fields.
.Pp
-They are retrieved using the
+The
+.Vt Elf_Scn
+descriptor for a specific section in an ELF object can be
+retrieved using the
.Fn elf_getscn
function.
-An application may iterate through the existing sections of an ELF
-object using the
+The sections contained in an ELF object can be traversed using the
.Fn elf_nextscn
function.
-New sections may be allocated using the
+New sections are allocated using the
.Fn elf_newscn
function.
.Pp
The
-.Vt Elf_Scn
-descriptor is opaque and contains no application modifiable fields.
+.Vt Elf_Data
+descriptors associated with a given section can be retrieved
+using the
+.Fn elf_getdata
+function.
+New data descriptors can be added to a section
+descriptor using the
+.Fn elf_newdata
+function.
+The untranslated
+.Dq file
+representation of data in a section can be retrieved using the
+.Fn elf_rawdata
+function.
.El
.Ss Supported Elf Types
The following ELF datatypes are supported by the library.
@@ -411,7 +420,7 @@
.El
.Pp
Section types in the range
-.Ns [ Dv SHT_LOOS ,
+.Dv [ SHT_LOOS ,
.Dv SHT_HIUSER ]
are otherwise considered to be of type
.Dv ELF_T_BYTE .
@@ -421,7 +430,7 @@
Each function listed here is described further in its own manual page.
.Bl -tag -width indent
.It "Archive Access"
-.Bl -tag -compact
+.Bl -tag -compact -width indent
.It Fn elf_getarsym
Retrieve the archive symbol table.
.It Fn elf_getarhdr
@@ -438,7 +447,7 @@
archive.
.El
.It "Data Structures"
-.Bl -tag -compact
+.Bl -tag -compact -width indent
.It Fn elf_getdata
Retrieve translated data for an ELF section.
.It Fn elf_getscn
@@ -471,7 +480,7 @@
Allocate or resize the Program Header Table in an ELF object.
.El
.It "Data Translation"
-.Bl -tag -compact
+.Bl -tag -compact -width indent
.It Fn elf32_xlatetof , Fn elf64_xlatetof
Translate an ELF data structure from its native representation to its
file representation.
@@ -480,14 +489,14 @@
native representation.
.El
.It "Error Reporting"
-.Bl -tag -compact
+.Bl -tag -compact -width indent
.It Fn elf_errno
Retrieve the current error.
.It Fn elf_errmsg
Retrieve a human readable description of the current error.
.El
.It "Initialization"
-.Bl -tag -compact
+.Bl -tag -compact -width indent
.It Fn elf_begin
Opens an
.Xr ar 1
@@ -531,9 +540,11 @@
Compute checksum of an ELF object.
.It Fn elf_getident
Retrieve the identification bytes for an ELF object.
-.It Fn elf_getshnum
+.It Fn elf_getphdrnum
+Retrieve the number of program headers in an ELF object.
+.It Fn elf_getshdrnum
Retrieve the number of sections in an ELF object.
-.It Fn elf_getshstrndx
+.It Fn elf_getshdrstrndx
Retrieve the section index of the section name string table in
an ELF object.
.It Fn elf_hash
@@ -567,7 +578,7 @@
.Ss Error Handling
In case an error is encountered, these library functions set an
internal error number and signal the presence of the error by
-returning an special return value.
+returning a special return value.
The application can check the
current error number by calling
.Xr elf_errno 3 .
@@ -603,10 +614,14 @@
descriptor itself.
.Sh SEE ALSO
.Xr gelf 3 ,
+.Xr ar 5 ,
.Xr elf 5
.Sh HISTORY
-The original ELF(3) API was developed for Unix System V.
-This implementation first appeared in
+The original
+.Nm
+API was developed for
+.At V .
+The current implementation of the API appeared in
.Fx 7.0
and
.Nx 6.0 .
diff -r 577d4c6a634d -r e26ffb843402 external/bsd/elftoolchain/dist/libelf/elf_begin.3
--- a/external/bsd/elftoolchain/dist/libelf/elf_begin.3 Mon Mar 08 20:43:22 2021 +0000
+++ b/external/bsd/elftoolchain/dist/libelf/elf_begin.3 Mon Mar 08 20:55:06 2021 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: elf_begin.3,v 1.3 2016/02/20 02:43:42 christos Exp $
+.\" $NetBSD: elf_begin.3,v 1.4 2021/03/08 20:55:06 jkoshy Exp $
.\"
.\" Copyright (c) 2006,2008-2011 Joseph Koshy. All rights reserved.
.\"
@@ -23,11 +23,11 @@
.\" out of the use of this software, even if advised of the possibility of
.\" such damage.
.\"
-.\" Id: elf_begin.3 3182 2015-04-10 16:08:10Z emaste
+.\" Id: elf_begin.3 3928 2021-03-07 19:47:55Z jkoshy
.\"
.Dd December 11, 2011
+.Dt ELF_BEGIN 3
.Os
-.Dt ELF_BEGIN 3
.Sh NAME
.Nm elf_begin
.Nd open an ELF file or ar(1) archive
@@ -75,7 +75,8 @@
.It ELF_C_NULL
Causes
.Fn elf_begin
-to return NULL.
+to return
+.Dv NULL .
Arguments
.Ar fd
and
@@ -93,7 +94,9 @@
.Pp
If argument
.Ar elf
-is NULL, the library will allocate a new ELF descriptor for the file
+is
+.Dv NULL ,
+the library will allocate a new ELF descriptor for the file
being processed.
The argument
.Ar fd
@@ -101,7 +104,9 @@
.Pp
If argument
.Ar elf
-is not NULL, and references a regular ELF file previously opened with
+is not
+.Dv NULL ,
+and references a regular ELF file previously opened with
.Fn elf_begin ,
then the activation count for the descriptor referenced by argument
.Ar elf
@@ -113,7 +118,9 @@
.Pp
If argument
.Ar elf
-is not NULL, and references a descriptor for an
Home |
Main Index |
Thread Index |
Old Index