diff options
267 files changed, 2928 insertions, 1227 deletions
@@ -14,7 +14,7 @@ operating systems. Operating System Version Supported Architectures ----------------- -------- ----------------------- `DragonFly BSD`_ 5.2 amd64 - FreeBSD_ 11.1 amd64 & i386 + FreeBSD_ 11.2 amd64 & i386 Minix_ 3.0.2 i386 NetBSD_ 7.1.2 i386 OpenBSD_ 6.3 amd64 @@ -56,7 +56,7 @@ Prerequisites - Building additional documentation is not currently supported under DragonFly BSD. -:FreeBSD 11.1: +:FreeBSD 11.2: - The core libraries and utilities should build out of the box on a stock install of FreeBSD. @@ -73,7 +73,7 @@ Prerequisites % sudo pkg install python py27-yaml - Building additional documentation is not currently supported under - FreeBSD 11.1. + FreeBSD 11.2. :Minix 3.2.0: - The following packages are pre-requisites for building the @@ -242,7 +242,7 @@ website`_. .. _project website: http://elftoolchain.sourceforge.net/ -.. $Id: INSTALL 3613 2018-04-21 19:34:37Z jkoshy $ +.. $Id: INSTALL 3667 2018-12-28 22:19:46Z emaste $ .. Local Variables: .. mode: rst @@ -1,8 +1,7 @@ The Elftoolchain Project ======================== -.. contents:: -.. +.. contents:: Table of Contents Description ----------- @@ -15,26 +14,26 @@ This software implements essential compilation tools and libraries for: The project currently implements the following utilities and libraries: - =========== ============================================ - Name Description - =========== ============================================ - ar Archive manager. - addr2line Debug tool. - brandelf Manage the ELF brand on executables. - c++filt Translate encoded symbols. - elfcopy Copy and translate between object formats. - elfdump Diagnostic tool. - findtextrel Find undesired text relocations. - libdwarf DWARF access library. - libelf ELF access library. - mcs Manage comment sections. - nm List symbols in an ELF object. - ranlib Add archive symbol tables to an archive. - readelf Display ELF information. - size List object sizes. - strings Extract printable strings. - strip Discard information from ELF objects. - =========== ============================================ +=========== ============================================ +Name Description +=========== ============================================ +ar Archive manager. +addr2line Debug tool. +brandelf Manage the ELF brand on executables. +c++filt Translate encoded symbols. +elfcopy Copy and translate between object formats. +elfdump Diagnostic tool. +findtextrel Find undesired text relocations. +libdwarf DWARF access library. +libelf ELF access library. +mcs Manage comment sections. +nm List symbols in an ELF object. +ranlib Add archive symbol tables to an archive. +readelf Display ELF information. +size List object sizes. +strings Extract printable strings. +strip Discard information from ELF objects. +=========== ============================================ .. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format .. _DWARF: http://www.dwarfstd.org/ @@ -58,10 +57,12 @@ Tracking Ongoing Development The project uses subversion_ for its version control system. +.. _subversion: https://subversion.apache.org/ + The subversion branch for the current set of sources may be accessed -at the following URL: +at the following URL:: - https://elftoolchain.svn.sourceforge.net/svnroot/elftoolchain/trunk + https://elftoolchain.svn.sourceforge.net/svnroot/elftoolchain/trunk The project's source tree may be checked out from its repository by using the ``svn checkout`` command:: @@ -71,14 +72,12 @@ using the ``svn checkout`` command:: Checked-out sources may be kept upto-date by running ``svn update`` inside the source directory:: - % svn update + % svn update Instructions on building and installing the software are given in the file ``INSTALL`` in the current directory. -.. _Subversion: - Downloading Released Software ----------------------------- @@ -120,7 +119,7 @@ website`_. .. _project website: http://elftoolchain.sourceforge.net/ -.. $Id: README 2146 2011-11-11 09:39:00Z jkoshy $ +.. $Id: README.rst 3656 2018-12-26 09:46:24Z jkoshy $ .. Local Variables: .. mode: rst diff --git a/addr2line/addr2line.1 b/addr2line/addr2line.1 index 15c24acb6b68..f1b01954b3a6 100644 --- a/addr2line/addr2line.1 +++ b/addr2line/addr2line.1 @@ -22,11 +22,11 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $Id: addr2line.1 3263 2015-11-30 04:25:54Z kaiwang27 $ +.\" $Id: addr2line.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd November 30, 2015 -.Os .Dt ADDR2LINE 1 +.Os .Sh NAME .Nm addr2line .Nd translate program addresses to source file names and line numbers diff --git a/addr2line/addr2line.c b/addr2line/addr2line.c index 9c3a764fcd0d..619214fb0fae 100644 --- a/addr2line/addr2line.c +++ b/addr2line/addr2line.c @@ -40,7 +40,7 @@ #include "uthash.h" #include "_elftc.h" -ELFTC_VCSID("$Id: addr2line.c 3499 2016-11-25 16:06:29Z emaste $"); +ELFTC_VCSID("$Id: addr2line.c 3544 2017-06-05 14:51:44Z emaste $"); struct Func { char *name; @@ -21,51 +21,52 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: ar.1 3230 2015-07-27 17:11:38Z emaste $ +.\" $Id: ar.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" -.Dd July 27, 2015 -.Os +.Dd September 30, 2018 .Dt AR 1 +.Os .Sh NAME .Nm ar .Nd manage archives .Sh SYNOPSIS .Nm .Fl d -.Op Fl T .Op Fl f .Op Fl j +.Op Fl T .Op Fl v .Op Fl z .Ar archive .Ar .Nm .Fl m -.Op Fl T .Op Fl a Ar position-after .Op Fl b Ar position-before .Op Fl f .Op Fl i Ar position-before .Op Fl j .Op Fl s | Fl S +.Op Fl T .Op Fl z .Ar archive .Ar .Nm .Fl p -.Op Fl T .Op Fl f +.Op Fl s +.Op Fl T .Op Fl v .Ar archive .Op Ar .Nm .Fl q -.Op Fl T .Op Fl c .Op Fl D .Op Fl f .Op Fl F Ar flavor | Fl -flavor Ar flavor .Op Fl s | Fl S +.Op Fl T .Op Fl U .Op Fl v .Op Fl z @@ -73,7 +74,6 @@ .Ar .Nm .Fl r -.Op Fl T .Op Fl a Ar position-after .Op Fl b Ar position-before .Op Fl c @@ -83,6 +83,7 @@ .Op Fl i Ar position-before .Op Fl j .Op Fl s | Fl S +.Op Fl T .Op Fl u .Op Fl U .Op Fl v @@ -99,6 +100,7 @@ .Nm .Fl t .Op Fl f +.Op Fl s .Op Fl T .Op Fl v .Ar archive @@ -106,9 +108,10 @@ .Nm .Fl x .Op Fl C -.Op Fl T .Op Fl f .Op Fl o +.Op Fl s +.Op Fl T .Op Fl u .Op Fl v .Ar archive @@ -21,11 +21,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: ar.5 3182 2015-04-10 16:08:10Z emaste $ +.\" $Id: ar.5 3642 2018-10-14 14:24:28Z jkoshy $ .\" -.Dd November 28, 2010 -.Os +.Dd September 30, 2018 .Dt AR 5 +.Os .Sh NAME .Nm ar .Nd archive file format for @@ -84,6 +84,8 @@ An archive header comprises the following fixed sized fields: .Bl -tag -width "Li ar_name" .It Ar ar_name (16 bytes) The file name of the archive member. +This field names a leaf file; absolute paths and relative paths containing +directory names are not supported. The format of this field varies between the BSD and SVR4/GNU formats and is described in more detail in the section .Sx "Representing File Names" @@ -72,7 +72,7 @@ #include "ar.h" -ELFTC_VCSID("$Id: ar.c 3319 2016-01-13 21:37:53Z jkoshy $"); +ELFTC_VCSID("$Id: ar.c 3629 2018-09-30 19:26:28Z jkoshy $"); enum options { @@ -100,11 +100,12 @@ main(int argc, char **argv) struct bsdar *bsdar, bsdar_storage; char *arcmd, *argv1_saved; size_t len; - int i, opt; + int exitcode, i, opt; bsdar = &bsdar_storage; memset(bsdar, 0, sizeof(*bsdar)); + exitcode = EXIT_SUCCESS; arcmd = argv1_saved = NULL; bsdar->output = stdout; @@ -152,9 +153,9 @@ main(int argc, char **argv) bsdar->options |= AR_S; while ((bsdar->filename = *argv++) != NULL) - ar_write_archive(bsdar, 's'); + exitcode |= ar_write_archive(bsdar, 's'); - exit(EXIT_SUCCESS); + exit(exitcode); } else { if (argc < 2) bsdar_usage(); @@ -331,30 +332,33 @@ main(int argc, char **argv) if ((!bsdar->mode || strchr("ptx", bsdar->mode)) && bsdar->options & AR_S) { - ar_write_archive(bsdar, 's'); + exitcode = ar_write_archive(bsdar, 's'); if (!bsdar->mode) - exit(EXIT_SUCCESS); + exit(exitcode); } switch(bsdar->mode) { case 'd': case 'm': case 'q': case 'r': - ar_write_archive(bsdar, bsdar->mode); + exitcode = ar_write_archive(bsdar, bsdar->mode); break; case 'p': case 't': case 'x': - ar_read_archive(bsdar, bsdar->mode); + exitcode = ar_read_archive(bsdar, bsdar->mode); break; default: bsdar_usage(); /* NOTREACHED */ } - for (i = 0; i < bsdar->argc; i++) - if (bsdar->argv[i] != NULL) + for (i = 0; i < bsdar->argc; i++) { + if (bsdar->argv[i] != NULL) { bsdar_warnc(bsdar, 0, "%s: not found in archive", bsdar->argv[i]); + exitcode = EXIT_FAILURE; + } + } - exit(EXIT_SUCCESS); + exit(exitcode); } static void @@ -23,7 +23,7 @@ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * - * $Id: ar.h 2496 2012-04-24 02:33:40Z jkoshy $ + * $Id: ar.h 3629 2018-09-30 19:26:28Z jkoshy $ */ #include <libelf.h> @@ -135,8 +135,8 @@ struct bsdar { }; void ar_mode_script(struct bsdar *ar); -void ar_read_archive(struct bsdar *_ar, int _mode); -void ar_write_archive(struct bsdar *_ar, int _mode); +int ar_read_archive(struct bsdar *_ar, int _mode); +int ar_write_archive(struct bsdar *_ar, int _mode); void bsdar_errc(struct bsdar *, int _code, const char *fmt, ...); int bsdar_is_pseudomember(struct bsdar *_ar, const char *_name); const char *bsdar_strmode(mode_t m); diff --git a/ar/ranlib.1 b/ar/ranlib.1 index 89ab4ab49cab..84738634e9e7 100644 --- a/ar/ranlib.1 +++ b/ar/ranlib.1 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: ranlib.1 3195 2015-05-12 17:22:19Z emaste $ +.\" $Id: ranlib.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd December 9, 2012 -.Os .Dt RANLIB 1 +.Os .Sh NAME .Nm ranlib .Nd update archive symbol tables diff --git a/ar/read.c b/ar/read.c index 08b3224db17e..0aea381478b9 100644 --- a/ar/read.c +++ b/ar/read.c @@ -34,16 +34,20 @@ #include <errno.h> #include <libgen.h> #include <stdio.h> +#include <stdlib.h> #include <string.h> #include "ar.h" -ELFTC_VCSID("$Id: read.c 3180 2015-04-09 15:13:57Z emaste $"); +ELFTC_VCSID("$Id: read.c 3629 2018-09-30 19:26:28Z jkoshy $"); /* * Handle read modes: 'x', 't' and 'p'. + * + * Returns EXIT_SUCCESS if all operations completed successfully or returns + * EXIT_FAILURE otherwise. */ -void +int ar_read_archive(struct bsdar *bsdar, int mode) { FILE *out; @@ -60,8 +64,8 @@ ar_read_archive(struct bsdar *bsdar, int mode) gid_t gid; char **av; char buf[25]; - char find; - int i, flags, r; + int found; + int exitcode, i, flags, r; assert(mode == 'p' || mode == 't' || mode == 'x'); @@ -70,6 +74,7 @@ ar_read_archive(struct bsdar *bsdar, int mode) archive_read_support_format_ar(a); AC(archive_read_open_filename(a, bsdar->filename, DEF_BLKSZ)); + exitcode = EXIT_SUCCESS; out = bsdar->output; for (;;) { @@ -96,12 +101,27 @@ ar_read_archive(struct bsdar *bsdar, int mode) if (bsdar_is_pseudomember(bsdar, name)) continue; + /* The ar(5) format only supports 'leaf' file names. */ + if (strchr(name, '/')) { + bsdar_warnc(bsdar, 0, "ignoring entry: %s", + name); + continue; + } + + /* + * If we had been given a list of file names to process, check + * that the current entry is present in this list. + */ if (bsdar->argc > 0) { - find = 0; + found = 0; for(i = 0; i < bsdar->argc; i++) { av = &bsdar->argv[i]; if (*av == NULL) continue; + /* + * Per POSIX, only the basename of a file + * argument should be compared. + */ if ((bname = basename(*av)) == NULL) bsdar_errc(bsdar, errno, "basename failed"); @@ -109,10 +129,10 @@ ar_read_archive(struct bsdar *bsdar, int mode) continue; *av = NULL; - find = 1; + found = 1; break; } - if (!find) + if (!found) continue; } @@ -157,7 +177,7 @@ ar_read_archive(struct bsdar *bsdar, int mode) /* mode == 'x' */ if (stat(name, &sb) != 0) { if (errno != ENOENT) { - bsdar_warnc(bsdar, 0, + bsdar_warnc(bsdar, errno, "stat %s failed", bsdar->filename); continue; @@ -174,12 +194,6 @@ ar_read_archive(struct bsdar *bsdar, int mode) if (bsdar->options & AR_V) (void)fprintf(out, "x - %s\n", name); - /* Disallow absolute paths. */ - if (name[0] == '/') { - bsdar_warnc(bsdar, 0, - "Absolute path '%s'", name); - continue; - } /* Basic path security flags. */ flags = ARCHIVE_EXTRACT_SECURE_SYMLINKS | ARCHIVE_EXTRACT_SECURE_NODOTDOT; @@ -189,11 +203,19 @@ ar_read_archive(struct bsdar *bsdar, int mode) r = archive_read_extract(a, entry, flags); } - if (r) + if (r) { bsdar_warnc(bsdar, 0, "%s", archive_error_string(a)); + exitcode = EXIT_FAILURE; + } } } + + if (r == ARCHIVE_FATAL) + exitcode = EXIT_FAILURE; + AC(archive_read_close(a)); ACV(archive_read_free(a)); + + return (exitcode); } diff --git a/ar/write.c b/ar/write.c index 90be5da11937..a522d66feff9 100644 --- a/ar/write.c +++ b/ar/write.c @@ -40,7 +40,7 @@ #include "ar.h" -ELFTC_VCSID("$Id: write.c 3183 2015-04-10 16:18:42Z emaste $"); +ELFTC_VCSID("$Id: write.c 3629 2018-09-30 19:26:28Z jkoshy $"); #define _ARMAG_LEN 8 /* length of the magic string */ #define _ARHDR_LEN 60 /* length of the archive header */ @@ -352,17 +352,20 @@ read_objs(struct bsdar *bsdar, const char *archive, int checkargv) /* * Write an archive. + * + * Returns EXIT_SUCCESS if the write succeeded or EXIT_FAILURE otherwise. */ -void +int ar_write_archive(struct bsdar *bsdar, int mode) { struct ar_obj *nobj, *obj, *obj_temp, *pos; struct stat sb; const char *bname; char **av; - int i; + int exitcode, i; TAILQ_INIT(&bsdar->v_obj); + exitcode = EXIT_SUCCESS; nobj = NULL; pos = NULL; memset(&sb, 0, sizeof(sb)); @@ -376,16 +379,16 @@ ar_write_archive(struct bsdar *bsdar, int mode) */ if (stat(bsdar->filename, &sb) != 0) { if (errno != ENOENT) { - bsdar_warnc(bsdar, 0, "stat %s failed", + bsdar_warnc(bsdar, errno, "stat %s failed", bsdar->filename); - return; + return (EXIT_FAILURE); } /* We do not create archive in mode 'd', 'm' and 's'. */ if (mode != 'r' && mode != 'q') { bsdar_warnc(bsdar, 0, "%s: no such file", bsdar->filename); - return; + return (EXIT_FAILURE); } /* Issue a message if the '-c' option was not specified. */ @@ -474,8 +477,10 @@ ar_write_archive(struct bsdar *bsdar, int mode) */ nobj = create_obj_from_file(bsdar, *av, obj->mtime); - if (nobj == NULL) + if (nobj == NULL) { + exitcode = EXIT_FAILURE; goto skip_obj; + } } if (bsdar->options & AR_V) @@ -510,9 +515,13 @@ new_archive: av = &bsdar->argv[i]; if (*av != NULL && (mode == 'r' || mode == 'q')) { nobj = create_obj_from_file(bsdar, *av, 0); - if (nobj != NULL) - insert_obj(bsdar, nobj, pos); - if (bsdar->options & AR_V && nobj != NULL) + if (nobj == NULL) { + exitcode = EXIT_FAILURE; + *av = NULL; + continue; + } + insert_obj(bsdar, nobj, pos); + if (bsdar->options & AR_V) (void)fprintf(bsdar->output, "a - %s\n", *av); *av = NULL; } @@ -521,6 +530,8 @@ new_archive: write_objs: write_objs(bsdar); write_cleanup(bsdar); + + return (exitcode); } /* @@ -22,11 +22,11 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $Id: as.1 2798 2012-12-22 09:02:50Z jkoshy $ +.\" $Id: as.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd December 22, 2012 -.Os .Dt AS 1 +.Os .Sh NAME .Nm as .Nd an assembler diff --git a/common/native-elf-format b/common/native-elf-format index 2bdd914c3052..f29bcb16716b 100755 --- a/common/native-elf-format +++ b/common/native-elf-format @@ -1,6 +1,6 @@ #!/bin/sh # -# $Id: native-elf-format 3293 2016-01-07 19:26:27Z emaste $ +# $Id: native-elf-format 3650 2018-11-25 12:06:28Z jkoshy $ # # Find the native ELF format for a host platform by compiling a # test object and examining the resulting object. @@ -35,7 +35,7 @@ $1 ~ "Machine:" { elfarch = "EM_386"; } else if (match($0, "MIPS")) { elfarch = "EM_MIPS"; - } else if (match($0, ".*[xX]86-64")) { + } else if (match($0, ".*[xX]86[-_]64")) { elfarch = "EM_X86_64"; } else { elfarch = "unknown"; diff --git a/cxxfilt/c++filt.1 b/cxxfilt/c++filt.1 index b191b44e8215..a473bc38e52c 100644 --- a/cxxfilt/c++filt.1 +++ b/cxxfilt/c++filt.1 @@ -22,11 +22,11 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $Id: c++filt.1 3195 2015-05-12 17:22:19Z emaste $ +.\" $Id: c++filt.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd August 24, 2011 -.Os .Dt C++FILT 1 +.Os .Sh NAME .Nm c++filt .Nd decode C++ symbols diff --git a/elfcopy/elfcopy.1 b/elfcopy/elfcopy.1 index a71451056aa3..89d694f46b4e 100644 --- a/elfcopy/elfcopy.1 +++ b/elfcopy/elfcopy.1 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elfcopy.1 3565 2017-08-31 02:24:19Z emaste $ +.\" $Id: elfcopy.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd August 30, 2017 -.Os .Dt ELFCOPY 1 +.Os .Sh NAME .Nm elfcopy , .Nm objcopy diff --git a/elfcopy/elfcopy.h b/elfcopy/elfcopy.h index 5593a9a40218..a6578113fe55 100644 --- a/elfcopy/elfcopy.h +++ b/elfcopy/elfcopy.h @@ -23,7 +23,7 @@ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * - * $Id: elfcopy.h 3446 2016-05-03 01:31:17Z emaste $ + * $Id: elfcopy.h 3615 2018-05-17 04:12:24Z kaiwang27 $ */ #include <sys/queue.h> @@ -127,6 +127,7 @@ struct section { uint64_t cap; /* section capacity */ uint64_t align; /* section alignment */ uint64_t type; /* section type */ + uint64_t flags; /* section flags */ uint64_t vma; /* section virtual addr */ uint64_t lma; /* section load addr */ uint64_t pad_sz;/* section padding size */ diff --git a/elfcopy/mcs.1 b/elfcopy/mcs.1 index edbafb7b88a7..890154c19d33 100644 --- a/elfcopy/mcs.1 +++ b/elfcopy/mcs.1 @@ -21,11 +21,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: mcs.1 2247 2011-11-29 08:41:34Z jkoshy $ +.\" $Id: mcs.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd November 29, 2011 -.Os .Dt MCS 1 +.Os .Sh NAME .Nm mcs .Nd manipulate the comment section of an ELF object diff --git a/elfcopy/sections.c b/elfcopy/sections.c index bd703e906584..d9d0edda676a 100644 --- a/elfcopy/sections.c +++ b/elfcopy/sections.c @@ -34,7 +34,7 @@ #include "elfcopy.h" -ELFTC_VCSID("$Id: sections.c 3443 2016-04-15 18:57:54Z kaiwang27 $"); +ELFTC_VCSID("$Id: sections.c 3646 2018-10-27 02:25:39Z emaste $"); static void add_gnu_debuglink(struct elfcopy *ecp); static uint32_t calc_crc32(const char *p, size_t len, uint32_t crc); @@ -411,6 +411,7 @@ create_scn(struct elfcopy *ecp) s->sz = ish.sh_size; s->align = ish.sh_addralign; s->type = ish.sh_type; + s->flags = ish.sh_flags; s->vma = ish.sh_addr; /* @@ -685,7 +686,7 @@ filter_reloc(struct elfcopy *ecp, struct section *s) Elf32_Rela *rela32; Elf64_Rela *rela64; Elf_Data *id; - uint64_t cap, n, nrels; + uint64_t cap, n, nrels, sym; int elferr, i; if (gelf_getshdr(s->is, &ish) == NULL) @@ -694,15 +695,13 @@ filter_reloc(struct elfcopy *ecp, struct section *s) /* We don't want to touch relocation info for dynamic symbols. */ if ((ecp->flags & SYMTAB_EXIST) == 0) { - if (ish.sh_link == 0 || ecp->secndx[ish.sh_link] == 0) { - /* - * This reloc section applies to the symbol table - * that was stripped, so discard whole section. - */ - s->nocopy = 1; - s->sz = 0; - } - return; + /* + * No symbol table in output. If sh_link points to a section + * that exists in the output object, this relocation section + * is for dynamic symbols. Don't touch it. + */ + if (ish.sh_link != 0 && ecp->secndx[ish.sh_link] != 0) + return; } else { /* Symbol table exist, check if index equals. */ if (ish.sh_link != elf_ndxscn(ecp->symtab->is)) @@ -743,28 +742,45 @@ filter_reloc(struct elfcopy *ecp, struct section *s) if (gelf_getrel(id, i, &rel) != &rel) errx(EXIT_FAILURE, "gelf_getrel failed: %s", elf_errmsg(-1)); + sym = GELF_R_SYM(rel.r_info); } else { if (gelf_getrela(id, i, &rela) != &rela) errx(EXIT_FAILURE, "gelf_getrel failed: %s", elf_errmsg(-1)); + sym = GELF_R_SYM(rela.r_info); } - name = elf_strptr(ecp->ein, elf_ndxscn(ecp->strtab->is), - GELF_R_SYM(rel.r_info)); - if (name == NULL) - errx(EXIT_FAILURE, "elf_strptr failed: %s", - elf_errmsg(-1)); - if (lookup_symop_list(ecp, name, SYMOP_KEEP) != NULL) { - if (ecp->oec == ELFCLASS32) { - if (s->type == SHT_REL) - COPYREL(rel, 32); - else - COPYREL(rela, 32); - } else { - if (s->type == SHT_REL) - COPYREL(rel, 64); - else - COPYREL(rela, 64); - } + /* + * If a relocation references a symbol and we are omitting + * either that symbol or the entire symbol table we cannot + * produce valid output, and so just omit the relocation. + * Broken output like this is generally not useful, but some + * uses of elfcopy/strip rely on it - for example, GCC's build + * process uses it to check for build reproducibility by + * stripping objects and comparing them. + * + * Relocations that do not reference a symbol are retained. + */ + if (sym != 0) { + if (ish.sh_link == 0 || ecp->secndx[ish.sh_link] == 0) + continue; + name = elf_strptr(ecp->ein, elf_ndxscn(ecp->strtab->is), + sym); + if (name == NULL) + errx(EXIT_FAILURE, "elf_strptr failed: %s", + elf_errmsg(-1)); + if (lookup_symop_list(ecp, name, SYMOP_KEEP) == NULL) + continue; + } + if (ecp->oec == ELFCLASS32) { + if (s->type == SHT_REL) + COPYREL(rel, 32); + else + COPYREL(rela, 32); + } else { + if (s->type == SHT_REL) + COPYREL(rel, 64); + else + COPYREL(rela, 64); } } elferr = elf_errno(); diff --git a/elfcopy/segments.c b/elfcopy/segments.c index 9a26bba88cfc..9030248f8d85 100644 --- a/elfcopy/segments.c +++ b/elfcopy/segments.c @@ -34,7 +34,7 @@ #include "elfcopy.h" -ELFTC_VCSID("$Id: segments.c 3449 2016-05-03 13:59:29Z emaste $"); +ELFTC_VCSID("$Id: segments.c 3615 2018-05-17 04:12:24Z kaiwang27 $"); static void insert_to_inseg_list(struct segment *seg, struct section *sec); @@ -79,6 +79,8 @@ add_to_inseg_list(struct elfcopy *ecp, struct section *s) continue; if (s->vma + s->sz > seg->vaddr + seg->msz) continue; + if (seg->type == PT_TLS && ((s->flags & SHF_TLS) == 0)) + continue; insert_to_inseg_list(seg, s); if (seg->type == PT_LOAD) diff --git a/elfcopy/strip.1 b/elfcopy/strip.1 index e07affbb9440..b1633a51693b 100644 --- a/elfcopy/strip.1 +++ b/elfcopy/strip.1 @@ -21,11 +21,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: strip.1 2069 2011-10-26 15:53:48Z jkoshy $ +.\" $Id: strip.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd September 17, 2011 -.Os .Dt STRIP 1 +.Os .Sh NAME .Nm strip .Nd discard information from ELF objects diff --git a/isa/isa.1 b/isa/isa.1 index c987bdcd6621..e515283fe2dc 100644 --- a/isa/isa.1 +++ b/isa/isa.1 @@ -22,11 +22,11 @@ \" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, \" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $Id: isa.1 3195 2015-05-12 17:22:19Z emaste $ +.\" $Id: isa.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd January 13, 2013 -.Os .Dt ISA 1 +.Os .Sh NAME .Nm isa .Nd instruction set analyser @@ -25,8 +25,8 @@ .\" $Id$ .\" .Dd February 14, 2016 -.Os .Dt LD 1 +.Os .Sh NAME .Nm ld .Nd link editor diff --git a/libdwarf/dwarf.3 b/libdwarf/dwarf.3 index 863bee6dcfdf..182b04f7685b 100644 --- a/libdwarf/dwarf.3 +++ b/libdwarf/dwarf.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf.3 3295 2016-01-08 22:08:10Z jkoshy $ +.\" $Id: dwarf.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd December 21, 2014 -.Os .Dt DWARF 3 +.Os .Sh NAME .Nm dwarf .Nd access debugging information in object files @@ -34,7 +34,6 @@ .Sh SYNOPSIS .In libdwarf.h .Sh DESCRIPTION -.Pp The .Lb libdwarf provides functions that allow an application to read and write debugging @@ -129,7 +128,6 @@ A descriptor representing a static variable. A descriptor representing a weak name. .El .Ss Error Handling -.Pp Library functions that encounter an error will return with a value other than .Dv DW_DLV_OK . @@ -173,7 +171,7 @@ below. .Pp .Bl -tag -compact -width "CCCC" .It Abbreviations -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_abbrev Retrieve abbreviation information at a given offset. .It Fn dwarf_get_abbrev_children_flag @@ -187,7 +185,7 @@ descriptor. Retrieve the tag for an abbreviation entry. .El .It Addresses -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_address_size Return the number of bytes needed to represent an address. .It Fn dwarf_get_arange @@ -206,7 +204,7 @@ Retrieve information about non-contiguous address ranges for a debugging information entry. .El .It Attributes -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_arrayorder Retrieve the value of a .Dv DW_AT_ordering @@ -279,7 +277,7 @@ Retrieve the attribute code for an attribute. Retrieve the form of an attribute. .El .It Call Information Entries and Frame Descriptor Entries -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_cie_index Retrieve the index for a CIE descriptor. .It Fn dwarf_get_cie_info @@ -308,7 +306,7 @@ Retrieve an FDE descriptor. Retrieve range information from an FDE descriptor. .El .It Compilation Units -.Bl -tag -compact +.Bl -tag -compact -width indent .It Xo .Fn dwarf_get_cu_die_offset_given_cu_header_offset , .Fn dwarf_get_cu_die_offset_given_cu_header_offset_b @@ -323,7 +321,7 @@ compilation or type unit. Step through compilation units in a debug context. .El .It Debugging Information Entries -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_child Returns the child of a debugging information entry. .It Fn dwarf_die_abbrev_code @@ -353,7 +351,7 @@ entry. Retrieve the tag for a debugging information entry. .El .It Functions -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_func_cu_offset Retrieves the offset for the compilation unit for a function. .It Fn dwarf_func_die_offset @@ -367,7 +365,7 @@ Retrieve both the name and offsets for a function. Retrieve information about static functions. .El .It Globals -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_globals Retrieve a list of globals. .It Fn dwarf_global_cu_offset @@ -396,7 +394,7 @@ and allow an application to specify alternate low-level file access routines. .It Line Numbers -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_lineaddr Retrieve the program address for a source line. .It Fn dwarf_linebeginstatement @@ -420,7 +418,7 @@ Retrieve source files for a compilation unit. Return line number information for a compilation unit. .El .It Location Lists -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_loclist_entry Retrieve a location list entry. .It Fn dwarf_loclist , Fn dwarf_loclist_n @@ -433,7 +431,7 @@ Retrieve location expressions. Translate a location expression into a location descriptor. .El .It Error Handling -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_errmsg Retrieve a human-readable error message. .It Fn dwarf_errno @@ -444,7 +442,7 @@ Set the argument passed to a callback error handler. Set the callback handler to be called in case of an error. .El .It Frame Handling -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_expand_frame_instructions Translate frame instruction bytes. .It Fn dwarf_set_frame_cfa_value @@ -464,7 +462,7 @@ Set the register number representing the rule. .El .It Macros -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_find_macro_value_start Return the macro value part of a macro string. .It Fn dwarf_get_macro_details @@ -523,7 +521,7 @@ for DWARF constants: and .Fn dwarf_get_VIS_name . .It Types -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_pubtypes , Fn dwarf_get_types Retrieve descriptors for user-defined types. .It Fn dwarf_next_types_section @@ -540,7 +538,7 @@ Retrieve the name of a type. Retrieve the name and offsets for a type. .El .It Variables -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_vars Retrieve descriptors for static variables. .It Fn dwarf_var_cu_offset @@ -553,7 +551,7 @@ Retrieve the name of a variable. Retrieve the name and offsets for a variable. .El .It Weak Symbols -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_weaks Retrieve information about weak symbols. .It Fn dwarf_weak_cu_offset @@ -566,7 +564,7 @@ Retrieve the name of a weak symbol. Retrieve the name and offsets for a weak symbol. .El .It Miscellaneous -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_elf Retrieve the ELF descriptor for a debug context, see .Xr elf 3 . @@ -605,7 +603,7 @@ information entry: and .Fn dwarf_add_AT_unsigned_const . .It Debugging Information Entry Management -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_add_die_to_debug Set the root debugging information entry for a DWARF producer instance. .It Fn dwarf_die_link @@ -623,7 +621,7 @@ are used to initialize a producer instance. When done, applications release resources using the function .Fn dwarf_producer_finish . .It Relocations and Sections -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_get_relocation_info Retrieve a relocation array from a producer instance. .It Fn dwarf_get_relocation_info_count @@ -636,7 +634,7 @@ Reset internal state for a producer instance. Prepare byte streams for writing out. .El .It Macros -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_def_macro Add a macro definition. .It Fn dwarf_end_macro_file , Fn dwarf_start_macro_file @@ -647,7 +645,7 @@ Note the removal of a macro definition. Enables storing macro information as specified in the DWARF standard. .El .It Symbols, Expressions, Addresses and Offsets -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn dwarf_add_arange , Fn dwarf_add_arange_b Add address range information. .It Fn dwarf_add_directory_decl @@ -741,7 +739,9 @@ The DWARF(3) API originated at Silicon Graphics Inc. .Pp A BSD-licensed implementation of a subset of the API was written by .An John Birrell Aq Mt jb@FreeBSD.org -for the FreeBSD project. +for the +.Fx +project. The implementation was subsequently revised and completed by .An Kai Wang Aq Mt kaiwang27@users.sourceforge.net . .Pp diff --git a/libdwarf/dwarf_add_AT_comp_dir.3 b/libdwarf/dwarf_add_AT_comp_dir.3 index 875e13d931db..4477a29476d4 100644 --- a/libdwarf/dwarf_add_AT_comp_dir.3 +++ b/libdwarf/dwarf_add_AT_comp_dir.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_comp_dir.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_comp_dir.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_COMP_DIR 3 +.Os .Sh NAME .Nm dwarf_add_AT_comp_dir .Nd create and attach a DW_AT_comp_dir attribute diff --git a/libdwarf/dwarf_add_AT_const_value_string.3 b/libdwarf/dwarf_add_AT_const_value_string.3 index d6177482c2ad..6baaf2087e2e 100644 --- a/libdwarf/dwarf_add_AT_const_value_string.3 +++ b/libdwarf/dwarf_add_AT_const_value_string.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_const_value_string.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_const_value_string.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_CONST_VALUE_STRING 3 +.Os .Sh NAME .Nm dwarf_add_AT_const_value_signedint , .Nm dwarf_add_AT_const_value_string , diff --git a/libdwarf/dwarf_add_AT_dataref.3 b/libdwarf/dwarf_add_AT_dataref.3 index 29a09e06c1ad..22f753225d77 100644 --- a/libdwarf/dwarf_add_AT_dataref.3 +++ b/libdwarf/dwarf_add_AT_dataref.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_dataref.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_dataref.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_DATAREF 3 +.Os .Sh NAME .Nm dwarf_add_AT_dataref .Nd create an attribute descriptor for a relocatable address @@ -113,8 +113,8 @@ function. .El .Sh SEE ALSO .Xr dwarf 3 , -.Xr dwarf_add_AT_reference 3 , .Xr dwarf_add_AT_ref_address 3 , +.Xr dwarf_add_AT_reference 3 , .Xr dwarf_add_AT_signed_const 3 , .Xr dwarf_add_AT_unsigned_const 3 , .Xr dwarf_new_die 3 , diff --git a/libdwarf/dwarf_add_AT_flag.3 b/libdwarf/dwarf_add_AT_flag.3 index 19b345ecd5c1..ad56714ba333 100644 --- a/libdwarf/dwarf_add_AT_flag.3 +++ b/libdwarf/dwarf_add_AT_flag.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_flag.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_flag.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_FLAG 3 +.Os .Sh NAME .Nm dwarf_add_AT_flag .Nd create and attach a flag attribute diff --git a/libdwarf/dwarf_add_AT_location_expr.3 b/libdwarf/dwarf_add_AT_location_expr.3 index 3c9327337855..6edfc59f4cc1 100644 --- a/libdwarf/dwarf_add_AT_location_expr.3 +++ b/libdwarf/dwarf_add_AT_location_expr.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_location_expr.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_location_expr.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 5, 2011 -.Os .Dt DWARF_ADD_AT_LOCATION_EXPR 3 +.Os .Sh NAME .Nm dwarf_add_AT_location_expr .Nd create an attribute descriptor for a location expression diff --git a/libdwarf/dwarf_add_AT_name.3 b/libdwarf/dwarf_add_AT_name.3 index d5ee761c86f9..352e8bf79222 100644 --- a/libdwarf/dwarf_add_AT_name.3 +++ b/libdwarf/dwarf_add_AT_name.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_name.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_name.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_NAME 3 +.Os .Sh NAME .Nm dwarf_add_AT_name .Nd create and attach a DW_AT_name attribute diff --git a/libdwarf/dwarf_add_AT_producer.3 b/libdwarf/dwarf_add_AT_producer.3 index ae0b088579a4..3aa270d59489 100644 --- a/libdwarf/dwarf_add_AT_producer.3 +++ b/libdwarf/dwarf_add_AT_producer.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_producer.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_producer.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_PRODUCER 3 +.Os .Sh NAME .Nm dwarf_add_AT_producer .Nd create and attach a DW_AT_producer attribute diff --git a/libdwarf/dwarf_add_AT_ref_address.3 b/libdwarf/dwarf_add_AT_ref_address.3 index 8b2efc8f8f62..a255167e6431 100644 --- a/libdwarf/dwarf_add_AT_ref_address.3 +++ b/libdwarf/dwarf_add_AT_ref_address.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_ref_address.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_ref_address.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 7, 2011 -.Os .Dt DWARF_ADD_AT_REF_ADDRESS 3 +.Os .Sh NAME .Nm dwarf_add_AT_ref_address .Nd create a reference class attribute descriptor diff --git a/libdwarf/dwarf_add_AT_reference.3 b/libdwarf/dwarf_add_AT_reference.3 index 4f6d51a727c6..7b91b904ae4a 100644 --- a/libdwarf/dwarf_add_AT_reference.3 +++ b/libdwarf/dwarf_add_AT_reference.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_reference.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_reference.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_REFERENCE 3 +.Os .Sh NAME .Nm dwarf_add_AT_reference .Nd create and attach an attribute that references another DIE diff --git a/libdwarf/dwarf_add_AT_signed_const.3 b/libdwarf/dwarf_add_AT_signed_const.3 index df7900ddb4b8..cff11d352a2e 100644 --- a/libdwarf/dwarf_add_AT_signed_const.3 +++ b/libdwarf/dwarf_add_AT_signed_const.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_signed_const.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_signed_const.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_SIGNED_CONST 3 +.Os .Sh NAME .Nm dwarf_add_AT_signed_const , .Nm dwarf_add_AT_unsigned_const diff --git a/libdwarf/dwarf_add_AT_string.3 b/libdwarf/dwarf_add_AT_string.3 index a05a19d28946..d70bae4d5f3c 100644 --- a/libdwarf/dwarf_add_AT_string.3 +++ b/libdwarf/dwarf_add_AT_string.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_string.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_string.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_STRING 3 +.Os .Sh NAME .Nm dwarf_add_AT_string .Nd create and attach a string class attribute diff --git a/libdwarf/dwarf_add_AT_targ_address.3 b/libdwarf/dwarf_add_AT_targ_address.3 index ce803c89c2bb..1e3798204543 100644 --- a/libdwarf/dwarf_add_AT_targ_address.3 +++ b/libdwarf/dwarf_add_AT_targ_address.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_AT_targ_address.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_AT_targ_address.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_ADD_AT_TARG_ADDRESS 3 +.Os .Sh NAME .Nm dwarf_add_AT_targ_address , .Nm dwarf_add_AT_targ_address_b diff --git a/libdwarf/dwarf_add_arange.3 b/libdwarf/dwarf_add_arange.3 index 90a088a9e4ff..84631bf36a78 100644 --- a/libdwarf/dwarf_add_arange.3 +++ b/libdwarf/dwarf_add_arange.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_arange.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_arange.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 18, 2011 -.Os .Dt DWARF_ADD_ARANGE 3 +.Os .Sh NAME .Nm dwarf_add_arange , .Nm dwarf_add_arange_b diff --git a/libdwarf/dwarf_add_die_to_debug.3 b/libdwarf/dwarf_add_die_to_debug.3 index 5ea4e3f0a123..f89b4c8722f6 100644 --- a/libdwarf/dwarf_add_die_to_debug.3 +++ b/libdwarf/dwarf_add_die_to_debug.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_die_to_debug.3 2938 2013-04-27 05:09:17Z jkoshy $ +.\" $Id: dwarf_add_die_to_debug.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd August 21, 2011 -.Os .Dt DWARF_ADD_DIE_TO_DEBUG 3 +.Os .Sh NAME .Nm dwarf_add_die_to_debug .Nd set the root debugging information entry diff --git a/libdwarf/dwarf_add_directory_decl.3 b/libdwarf/dwarf_add_directory_decl.3 index df1970762b94..2d91b0d813db 100644 --- a/libdwarf/dwarf_add_directory_decl.3 +++ b/libdwarf/dwarf_add_directory_decl.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_directory_decl.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_directory_decl.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 17, 2011 -.Os .Dt DWARF_ADD_DIRECTORY_DECL 3 +.Os .Sh NAME .Nm dwarf_add_directory_decl .Nd add a directory name to a producer instance diff --git a/libdwarf/dwarf_add_expr_addr.3 b/libdwarf/dwarf_add_expr_addr.3 index 4a19ee8aae86..959ad3c70800 100644 --- a/libdwarf/dwarf_add_expr_addr.3 +++ b/libdwarf/dwarf_add_expr_addr.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_expr_addr.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_expr_addr.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 9, 2011 -.Os .Dt DWARF_ADD_EXPR_ADDR 3 +.Os .Sh NAME .Nm dwarf_add_expr_addr , .Nm dwarf_add_expr_addr_b diff --git a/libdwarf/dwarf_add_expr_gen.3 b/libdwarf/dwarf_add_expr_gen.3 index 71f297704536..0c68935b90ce 100644 --- a/libdwarf/dwarf_add_expr_gen.3 +++ b/libdwarf/dwarf_add_expr_gen.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_expr_gen.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_expr_gen.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 9, 2011 -.Os .Dt DWARF_ADD_EXPR_GEN 3 +.Os .Sh NAME .Nm dwarf_add_expr_gen .Nd add an operator to a location expression descriptor diff --git a/libdwarf/dwarf_add_fde_inst.3 b/libdwarf/dwarf_add_fde_inst.3 index d2d91570be13..e138962b1778 100644 --- a/libdwarf/dwarf_add_fde_inst.3 +++ b/libdwarf/dwarf_add_fde_inst.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_fde_inst.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_fde_inst.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 26, 2011 -.Os .Dt DWARF_ADD_FDE_INST 3 +.Os .Sh NAME .Nm dwarf_add_fde_inst .Nd add a call frame instruction to a DWARF frame descriptor @@ -101,9 +101,9 @@ function. .El .Sh SEE ALSO .Xr dwarf 3 , +.Xr dwarf_add_frame_cie 3 , .Xr dwarf_add_frame_fde 3 , .Xr dwarf_add_frame_fde_b 3 , -.Xr dwarf_add_frame_cie 3 , .Xr dwarf_fde_cfa_offset 3 , .Xr dwarf_new_fde 3 .Rs diff --git a/libdwarf/dwarf_add_file_decl.3 b/libdwarf/dwarf_add_file_decl.3 index c389484242d4..960253265834 100644 --- a/libdwarf/dwarf_add_file_decl.3 +++ b/libdwarf/dwarf_add_file_decl.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_file_decl.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_file_decl.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 17, 2011 -.Os .Dt DWARF_ADD_FILE_DECL 3 +.Os .Sh NAME .Nm dwarf_add_file_decl .Nd add a source file entry to a producer instance diff --git a/libdwarf/dwarf_add_frame_cie.3 b/libdwarf/dwarf_add_frame_cie.3 index 1bc6db571f45..ba9d2c8dea9c 100644 --- a/libdwarf/dwarf_add_frame_cie.3 +++ b/libdwarf/dwarf_add_frame_cie.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_frame_cie.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_frame_cie.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 26, 2011 -.Os .Dt DWARF_ADD_FRAME_CIE 3 +.Os .Sh NAME .Nm dwarf_add_frame_cie .Nd add a call frame common information entry to a DWARF producer instance diff --git a/libdwarf/dwarf_add_frame_fde.3 b/libdwarf/dwarf_add_frame_fde.3 index 3c1ee11ea20e..b4358e42cbd9 100644 --- a/libdwarf/dwarf_add_frame_fde.3 +++ b/libdwarf/dwarf_add_frame_fde.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_frame_fde.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_frame_fde.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 26, 2011 -.Os .Dt DWARF_ADD_FRAME_FDE 3 +.Os .Sh NAME .Nm dwarf_add_frame_fde .Nd add a call frame descriptor to a DWARF producer instance diff --git a/libdwarf/dwarf_add_funcname.3 b/libdwarf/dwarf_add_funcname.3 index ebc358c4fe35..7d8c2f307686 100644 --- a/libdwarf/dwarf_add_funcname.3 +++ b/libdwarf/dwarf_add_funcname.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_funcname.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_funcname.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 24, 2011 -.Os .Dt DWARF_ADD_FUNCNAME 3 +.Os .Sh NAME .Nm dwarf_add_funcname .Nd add information about a static function to a DWARF producer instance diff --git a/libdwarf/dwarf_add_line_entry.3 b/libdwarf/dwarf_add_line_entry.3 index 16e807512a44..4d7c5a982777 100644 --- a/libdwarf/dwarf_add_line_entry.3 +++ b/libdwarf/dwarf_add_line_entry.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_line_entry.3 3182 2015-04-10 16:08:10Z emaste $ +.\" $Id: dwarf_add_line_entry.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd June 30, 2013 -.Os .Dt DWARF_ADD_LINE_ENTRY 3 +.Os .Sh NAME .Nm dwarf_add_line_entry .Nd add a line number information entry to a producer instance @@ -109,24 +109,7 @@ returns .Dv DW_DLV_NOCOUNT and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_add_line_entry -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" -.It Bq Er DW_DLE_ARGUMENT -Argument -.Ar dbg -was NULL. -.It Bq Er DW_DLE_ARGUMENT -The function -.Xr dwarf_lne_set_address 3 -was not called before calling this function. -.It Bq Er DW_DLE_MEMORY -An out of memory condition was encountered during the execution of the -function. -.El -.Sh EXAMPLE +.Sh EXAMPLES To add line number information to the producer instance, use: .Bd -literal -offset indent Dwarf_P_Debug dbg; @@ -154,6 +137,23 @@ if (dwarf_add_line_entry(dbg, filendx, 10, 258, 0, 1, 1, &de) != errx(EXIT_FAILURE, "dwarf_add_line_entry failed: %s", dwarf_errmsg(-1)); .Ed +.Sh ERRORS +Function +.Fn dwarf_add_line_entry +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Ar dbg +was NULL. +.It Bq Er DW_DLE_ARGUMENT +The function +.Xr dwarf_lne_set_address 3 +was not called before calling this function. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_add_directory_decl 3 , diff --git a/libdwarf/dwarf_add_pubname.3 b/libdwarf/dwarf_add_pubname.3 index 8839178da0fd..3b133c6e4074 100644 --- a/libdwarf/dwarf_add_pubname.3 +++ b/libdwarf/dwarf_add_pubname.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_pubname.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_pubname.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 24, 2011 -.Os .Dt DWARF_ADD_PUBNAME 3 +.Os .Sh NAME .Nm dwarf_add_pubname .Nd add information about a global object to a DWARF producer instance diff --git a/libdwarf/dwarf_add_typename.3 b/libdwarf/dwarf_add_typename.3 index 22a2b0626988..8b0ccb5a1cf7 100644 --- a/libdwarf/dwarf_add_typename.3 +++ b/libdwarf/dwarf_add_typename.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_typename.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_typename.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 24, 2011 -.Os .Dt DWARF_ADD_TYPENAME 3 +.Os .Sh NAME .Nm dwarf_add_typename .Nd add information about a user-defined type to a DWARF producer instance diff --git a/libdwarf/dwarf_add_varname.3 b/libdwarf/dwarf_add_varname.3 index efcb0d3c1960..10c22d49f677 100644 --- a/libdwarf/dwarf_add_varname.3 +++ b/libdwarf/dwarf_add_varname.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_varname.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_varname.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 24, 2011 -.Os .Dt DWARF_ADD_VARNAME 3 +.Os .Sh NAME .Nm dwarf_add_varname .Nd add information about a static variable to a DWARF producer instance diff --git a/libdwarf/dwarf_add_weakname.3 b/libdwarf/dwarf_add_weakname.3 index ac1ecbdca285..503f35c72fa3 100644 --- a/libdwarf/dwarf_add_weakname.3 +++ b/libdwarf/dwarf_add_weakname.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_add_weakname.3 2072 2011-10-27 03:26:49Z jkoshy $ +.\" $Id: dwarf_add_weakname.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 24, 2011 -.Os .Dt DWARF_ADD_WEAKNAME 3 +.Os .Sh NAME .Nm dwarf_add_weakname .Nd add information about a weak object to a DWARF producer instance diff --git a/libdwarf/dwarf_attr.3 b/libdwarf/dwarf_attr.3 index 9ba367be5f69..ac745fd2fb7a 100644 --- a/libdwarf/dwarf_attr.3 +++ b/libdwarf/dwarf_attr.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_attr.3 3093 2014-09-02 22:09:40Z kaiwang27 $ +.\" $Id: dwarf_attr.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd April 8, 2010 -.Os .Dt DWARF_ATTR 3 +.Os .Sh NAME .Nm dwarf_attr .Nd retrieve an attribute descriptor associated with a DWARF debugging information entry @@ -80,7 +80,8 @@ of an error. Function .Fn dwarf_attr returns -.Dv DW_DLV_OK on success. +.Dv DW_DLV_OK +on success. .Pp If the debugging information entry descriptor denoted by argument .Ar die diff --git a/libdwarf/dwarf_attrlist.3 b/libdwarf/dwarf_attrlist.3 index 0cb918df4f19..e932cc5675cd 100644 --- a/libdwarf/dwarf_attrlist.3 +++ b/libdwarf/dwarf_attrlist.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_attrlist.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_attrlist.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_ATTRLIST 3 +.Os .Sh NAME .Nm dwarf_attrlist .Nd retrieve DWARF attribute descriptors @@ -82,7 +82,8 @@ function. Function .Fn dwarf_attrlist returns -.Dv DW_DLV_OK on success. +.Dv DW_DLV_OK +on success. .Pp If the debugging information entry descriptor denoted by argument .Ar die diff --git a/libdwarf/dwarf_attroffset.3 b/libdwarf/dwarf_attroffset.3 index af24cebab8e9..e592edf14f63 100644 --- a/libdwarf/dwarf_attroffset.3 +++ b/libdwarf/dwarf_attroffset.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_attroffset.3 3115 2014-12-20 18:26:46Z jkoshy $ +.\" $Id: dwarf_attroffset.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd December 20, 2014 -.Os .Dt DWARF_ATTROFFSET 3 +.Os .Sh NAME .Nm dwarf_attroffset .Nd retrieve the section-relative offset of an attribute descriptor diff --git a/libdwarf/dwarf_attrval_signed.3 b/libdwarf/dwarf_attrval_signed.3 index c9416bc050bc..7bfc9841e2f9 100644 --- a/libdwarf/dwarf_attrval_signed.3 +++ b/libdwarf/dwarf_attrval_signed.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_attrval_signed.3 3509 2016-12-29 03:58:41Z emaste $ +.\" $Id: dwarf_attrval_signed.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd December 26, 2016 -.Os .Dt DWARF_ATTRVAL_SIGNED 3 +.Os .Sh NAME .Nm dwarf_attrval_flag , .Nm dwarf_attrval_signed , diff --git a/libdwarf/dwarf_child.3 b/libdwarf/dwarf_child.3 index 1e32e58d4451..c537293ff701 100644 --- a/libdwarf/dwarf_child.3 +++ b/libdwarf/dwarf_child.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_child.3 3127 2014-12-21 19:09:19Z jkoshy $ +.\" $Id: dwarf_child.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd December 21, 2014 -.Os .Dt DWARF_CHILD 3 +.Os .Sh NAME .Nm dwarf_child , .Nm dwarf_offdie , @@ -215,27 +215,6 @@ there was no debugging information entry at the offset specified by argument .Ar offset . .El -.Sh ERRORS -These functions may fail with the following errors: -.Bl -tag -width ".Bq Er DW_DLE_DIE_NO_CU_CONTEXT" -.It Bq Er DW_DLE_ARGUMENT -Arguments -.Ar dbg , -.Ar die -or -.Ar ret_die -were NULL. -.It Bq Er DW_DLE_DIE_NO_CU_CONTEXT -Argument -.Ar dbg -was not associated with a compilation unit. -.It Bq Er DW_DLE_NO_ENTRY -The descriptor denoted by argument -.Ar die -had no child or sibling, or there was no DWARF debugging information -entry at the offset specified by argument -.Va offset . -.El .Sh EXAMPLES To retrieve the first DWARF Debugging Information Entry descriptor for the first compilation unit associated with a @@ -271,8 +250,29 @@ do { dwarf_errmsg(de)); } while (die0 != NULL); .Ed +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_DIE_NO_CU_CONTEXT" +.It Bq Er DW_DLE_ARGUMENT +Arguments +.Ar dbg , +.Ar die +or +.Ar ret_die +were NULL. +.It Bq Er DW_DLE_DIE_NO_CU_CONTEXT +Argument +.Ar dbg +was not associated with a compilation unit. +.It Bq Er DW_DLE_NO_ENTRY +The descriptor denoted by argument +.Ar die +had no child or sibling, or there was no DWARF debugging information +entry at the offset specified by argument +.Va offset . +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_errmsg 3 , -.Xr dwarf_get_die_infotypes_flag.3 , +.Xr dwarf_get_die_infotypes_flag 3 , .Xr dwarf_next_cu_header 3 diff --git a/libdwarf/dwarf_dealloc.3 b/libdwarf/dwarf_dealloc.3 index 51d355b6afde..5a7f875abb65 100644 --- a/libdwarf/dwarf_dealloc.3 +++ b/libdwarf/dwarf_dealloc.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_dealloc.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_dealloc.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd July 23, 2011 -.Os .Dt DWARF_DEALLOC 3 +.Os .Sh NAME .Nm dwarf_dealloc , .Nm dwarf_fde_cie_list_dealloc , diff --git a/libdwarf/dwarf_def_macro.3 b/libdwarf/dwarf_def_macro.3 index daa090f29f0a..6d3018f3fc20 100644 --- a/libdwarf/dwarf_def_macro.3 +++ b/libdwarf/dwarf_def_macro.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_def_macro.3 3182 2015-04-10 16:08:10Z emaste $ +.\" $Id: dwarf_def_macro.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_DEF_MACRO 3 +.Os .Sh NAME .Nm dwarf_def_macro .Nd add a macro definition to a DWARF producer instance @@ -91,7 +91,7 @@ returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh EXAMPLE +.Sh EXAMPLES To record the fact that a macro named .Dv _STDIO_H_ was defined at line 20 of the current macro file, use: diff --git a/libdwarf/dwarf_die_abbrev_code.3 b/libdwarf/dwarf_die_abbrev_code.3 index 82caf3b81785..c296e135b880 100644 --- a/libdwarf/dwarf_die_abbrev_code.3 +++ b/libdwarf/dwarf_die_abbrev_code.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_die_abbrev_code.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_die_abbrev_code.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 14, 2010 -.Os .Dt DWARF_DIE_ABBREV_CODE 3 +.Os .Sh NAME .Nm dwarf_die_abbrev_code .Nd retrieve the abbreviation code for a DWARF debugging information entry diff --git a/libdwarf/dwarf_die_link.3 b/libdwarf/dwarf_die_link.3 index 89ddb5b41987..f251e8b945bc 100644 --- a/libdwarf/dwarf_die_link.3 +++ b/libdwarf/dwarf_die_link.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_die_link.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_die_link.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_DIE_LINK 3 +.Os .Sh NAME .Nm dwarf_die_link .Nd link a debugging information entry diff --git a/libdwarf/dwarf_diename.3 b/libdwarf/dwarf_diename.3 index d9404dea3fe4..224bdcc9d264 100644 --- a/libdwarf/dwarf_diename.3 +++ b/libdwarf/dwarf_diename.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_diename.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_diename.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd March 31, 2010 -.Os .Dt DWARF_DIENAME 3 +.Os .Sh NAME .Nm dwarf_diename .Nd retrieve the name associated with a debugging information entry @@ -51,7 +51,8 @@ pointed to by argument Function .Fn dwarf_diename returns -.Dv DW_DLV_OK on success. +.Dv DW_DLV_OK +on success. .Pp If the debugging information entry descriptor denoted by argument .Ar die @@ -85,6 +86,6 @@ attribute. .El .Sh SEE ALSO .Xr dwarf 3 , -.Xr dwarf_tag 3 , +.Xr dwarf_die_abbrev_code 3 , .Xr dwarf_dieoffset 3 , -.Xr dwarf_die_abbrev_code 3 +.Xr dwarf_tag 3 diff --git a/libdwarf/dwarf_dieoffset.3 b/libdwarf/dwarf_dieoffset.3 index 00b0e71b8389..bc6276148917 100644 --- a/libdwarf/dwarf_dieoffset.3 +++ b/libdwarf/dwarf_dieoffset.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_dieoffset.3 3129 2014-12-21 20:06:26Z jkoshy $ +.\" $Id: dwarf_dieoffset.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd December 21, 2014 -.Os .Dt DWARF_DIEOFFSET 3 +.Os .Sh NAME .Nm dwarf_die_CU_offset , .Nm dwarf_die_CU_offset_range , diff --git a/libdwarf/dwarf_end_macro_file.3 b/libdwarf/dwarf_end_macro_file.3 index a4de18ce8d26..486fe1d180bc 100644 --- a/libdwarf/dwarf_end_macro_file.3 +++ b/libdwarf/dwarf_end_macro_file.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_end_macro_file.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_end_macro_file.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 25, 2011 -.Os .Dt DWARF_END_MACRO_FILE 3 +.Os .Sh NAME .Nm dwarf_end_macro_file .Nd mark the end of the current source file inclusion @@ -38,7 +38,6 @@ .Fo dwarf_end_macro_file .Fa "Dwarf_P_Debug dbg" .Fa "Dwarf_Error *err" -.Fa .Fc .Sh DESCRIPTION Function diff --git a/libdwarf/dwarf_errmsg.3 b/libdwarf/dwarf_errmsg.3 index 466c091f5db6..adbd2d8453df 100644 --- a/libdwarf/dwarf_errmsg.3 +++ b/libdwarf/dwarf_errmsg.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_errmsg.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_errmsg.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd December 12, 2009 -.Os .Dt DWARF_ERRMSG 3 +.Os .Sh NAME .Nm dwarf_errmsg .Nd retrieve a human-readable string corresponding to a diff --git a/libdwarf/dwarf_errno.3 b/libdwarf/dwarf_errno.3 index 7e1a1ebfa2bf..cd7ddfccbbfe 100644 --- a/libdwarf/dwarf_errno.3 +++ b/libdwarf/dwarf_errno.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_errno.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_errno.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd March 25, 2010 -.Os .Dt DWARF_ERRNO 3 +.Os .Sh NAME .Nm dwarf_errno .Nd retrieve the error number corresponding to a diff --git a/libdwarf/dwarf_expand_frame_instructions.3 b/libdwarf/dwarf_expand_frame_instructions.3 index 7bcd105f030f..b19912d5f723 100644 --- a/libdwarf/dwarf_expand_frame_instructions.3 +++ b/libdwarf/dwarf_expand_frame_instructions.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_expand_frame_instructions.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: dwarf_expand_frame_instructions.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_EXPAND_FRAME_INSTRUCTIONS 3 +.Os .Sh NAME .Nm dwarf_expand_frame_instructions .Nd expand frame instructions @@ -104,32 +104,7 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_expand_frame_instructions -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar cie , -.Ar instructions , -.Ar ret_ops -or -.Ar ret_opcnt -was NULL. -.It Bq Er DW_DLE_ARGUMENT -Argument -.Ar len -was 0. -.It Bq Er DW_DLE_MEMORY -An out of memory condition was encountered during the execution of -this function. -.It Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR -An unknown instruction was found in the instruction bytes provided -in argument -.Ar instructions . -.El -.Sh EXAMPLE +.Sh EXAMPLES To retrieve and expand the frame instructions for a given FDE descriptor, use: .Bd -literal -offset indent @@ -164,12 +139,37 @@ for (i = 0; i < opcnt; i++) { /* Free the memory area when no longer needed. */ dwarf_dealloc(dbg, ops, DW_DLA_FRAME_BLOCK); .Ed +.Sh ERRORS +Function +.Fn dwarf_expand_frame_instructions +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar cie , +.Ar instructions , +.Ar ret_ops +or +.Ar ret_opcnt +was NULL. +.It Bq Er DW_DLE_ARGUMENT +Argument +.Ar len +was 0. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +this function. +.It Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR +An unknown instruction was found in the instruction bytes provided +in argument +.Ar instructions . +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_frame_instructions_dealloc 3 , -.Xr dwarf_get_cie_info 3 , .Xr dwarf_get_cie_index 3 , -.Xr dwarf_get_cie_of_fde , +.Xr dwarf_get_cie_info 3 , +.Xr dwarf_get_cie_of_fde 3 , .Xr dwarf_get_fde_at_pc 3 , .Xr dwarf_get_fde_info_for_all_regs 3 , .Xr dwarf_get_fde_info_for_all_regs3 3 , diff --git a/libdwarf/dwarf_expr_current_offset.3 b/libdwarf/dwarf_expr_current_offset.3 index f22294e6c8d4..c1221c50bb44 100644 --- a/libdwarf/dwarf_expr_current_offset.3 +++ b/libdwarf/dwarf_expr_current_offset.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_expr_current_offset.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_expr_current_offset.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 13, 2011 -.Os .Dt DWARF_EXPR_CURRENT_OFFSET 3 +.Os .Sh NAME .Nm dwarf_expr_current_offset .Nd retrieve the number of bytes in a location expression stream diff --git a/libdwarf/dwarf_expr_into_block.3 b/libdwarf/dwarf_expr_into_block.3 index 69f1d9cad7a7..49aefb172f99 100644 --- a/libdwarf/dwarf_expr_into_block.3 +++ b/libdwarf/dwarf_expr_into_block.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_expr_into_block.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_expr_into_block.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 13, 2011 -.Os .Dt DWARF_EXPR_INTO_BLOCK 3 +.Os .Sh NAME .Nm dwarf_expr_into_block .Nd retrieve the byte stream for a location expression diff --git a/libdwarf/dwarf_fde_cfa_offset.3 b/libdwarf/dwarf_fde_cfa_offset.3 index 8150e78e5b42..c00ee9a84173 100644 --- a/libdwarf/dwarf_fde_cfa_offset.3 +++ b/libdwarf/dwarf_fde_cfa_offset.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_fde_cfa_offset.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_fde_cfa_offset.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 26, 2011 -.Os .Dt DWARF_FDE_CFA_OFFSET 3 +.Os .Sh NAME .Nm dwarf_fde_cfa_offset .Nd add a DW_CFA_offset frame instruction to a DWARF frame descriptor @@ -93,7 +93,7 @@ function. .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_add_fde_inst 3 , +.Xr dwarf_add_frame_cie 3 , .Xr dwarf_add_frame_fde 3 , .Xr dwarf_add_frame_fde_b 3 , -.Xr dwarf_add_frame_cie 3 , .Xr dwarf_new_fde 3 diff --git a/libdwarf/dwarf_find_macro_value_start.3 b/libdwarf/dwarf_find_macro_value_start.3 index ede0df9bd558..0902ccbf10e5 100644 --- a/libdwarf/dwarf_find_macro_value_start.3 +++ b/libdwarf/dwarf_find_macro_value_start.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_find_macro_value_start.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_find_macro_value_start.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd March 26, 2011 -.Os .Dt DWARF_FIND_MACRO_VALUE_START 3 +.Os .Sh NAME .Nm dwarf_find_macro_value_start .Nd return the address of the first byte of a macro value diff --git a/libdwarf/dwarf_finish.3 b/libdwarf/dwarf_finish.3 index a26bf9b9c59c..161acb0a25a4 100644 --- a/libdwarf/dwarf_finish.3 +++ b/libdwarf/dwarf_finish.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_finish.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_finish.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_FINISH 3 +.Os .Sh NAME .Nm dwarf_finish , .Nm dwarf_object_finish @@ -133,8 +133,8 @@ if (dwarf_finish(dbg, &de) != DW_DLV_OK) (void) elf_end(e); .Ed .Sh SEE ALSO -.Xr elf_end 3 , .Xr dwarf_elf_init 3 , .Xr dwarf_get_elf 3 , .Xr dwarf_init 3 , -.Xr dwarf_object_init 3 +.Xr dwarf_object_init 3 , +.Xr elf_end 3 diff --git a/libdwarf/dwarf_formaddr.3 b/libdwarf/dwarf_formaddr.3 index 6b8c70d00342..a6bb85d0b885 100644 --- a/libdwarf/dwarf_formaddr.3 +++ b/libdwarf/dwarf_formaddr.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_formaddr.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_formaddr.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd July 23, 2010 -.Os .Dt DWARF_FORMADDR 3 +.Os .Sh NAME .Nm dwarf_formaddr .Nd return the value of an ADDRESS class attribute diff --git a/libdwarf/dwarf_formblock.3 b/libdwarf/dwarf_formblock.3 index 1ffb6e6fec0d..a3a8aae8bf53 100644 --- a/libdwarf/dwarf_formblock.3 +++ b/libdwarf/dwarf_formblock.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_formblock.3 3182 2015-04-10 16:08:10Z emaste $ +.\" $Id: dwarf_formblock.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd July 23, 2010 -.Os .Dt DWARF_FORMBLOCK 3 +.Os .Sh NAME .Nm dwarf_formblock .Nd return the value of a BLOCK attribute diff --git a/libdwarf/dwarf_formexprloc.3 b/libdwarf/dwarf_formexprloc.3 index 231ba3ac3bbf..278edcdfb6eb 100644 --- a/libdwarf/dwarf_formexprloc.3 +++ b/libdwarf/dwarf_formexprloc.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_formexprloc.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_formexprloc.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd July 25, 2010 -.Os .Dt DWARF_FORMEXPRLOC 3 +.Os .Sh NAME .Nm dwarf_formexprloc .Nd return information about a location expression diff --git a/libdwarf/dwarf_formflag.3 b/libdwarf/dwarf_formflag.3 index 2e23b3301661..29fa303e0953 100644 --- a/libdwarf/dwarf_formflag.3 +++ b/libdwarf/dwarf_formflag.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_formflag.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: dwarf_formflag.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd June 21, 2010 -.Os .Dt DWARF_FORMFLAG 3 +.Os .Sh NAME .Nm dwarf_formflag .Nd return the value of a BOOLEAN class attribute diff --git a/libdwarf/dwarf_formref.3 b/libdwarf/dwarf_formref.3 index abde30cfb9e4..9c6669cc43a4 100644 --- a/libdwarf/dwarf_formref.3 +++ b/libdwarf/dwarf_formref.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_formref.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: dwarf_formref.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd June 21, 2010 -.Os .Dt DWARF_FORMREF 3 +.Os .Sh NAME .Nm dwarf_formref , .Nm dwarf_global_formref diff --git a/libdwarf/dwarf_formsig8.3 b/libdwarf/dwarf_formsig8.3 index a76c1107d9eb..a2549a16f4d2 100644 --- a/libdwarf/dwarf_formsig8.3 +++ b/libdwarf/dwarf_formsig8.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_formsig8.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: dwarf_formsig8.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd July 24, 2010 -.Os .Dt DWARF_FORMSIG8 3 +.Os .Sh NAME .Nm dwarf_formsig8 .Nd return the 64-bit type signature for a DWARF type diff --git a/libdwarf/dwarf_formstring.3 b/libdwarf/dwarf_formstring.3 index 63e83f684be6..1da92f80e201 100644 --- a/libdwarf/dwarf_formstring.3 +++ b/libdwarf/dwarf_formstring.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_formstring.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_formstring.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd July 24, 2010 -.Os .Dt DWARF_FORMSTRING 3 +.Os .Sh NAME .Nm dwarf_formstring .Nd return the value of a STRING class attribute diff --git a/libdwarf/dwarf_formudata.3 b/libdwarf/dwarf_formudata.3 index 9ed154eebb97..ddcaeecbf581 100644 --- a/libdwarf/dwarf_formudata.3 +++ b/libdwarf/dwarf_formudata.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_formudata.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: dwarf_formudata.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd June 21, 2010 -.Os .Dt DWARF_FORMUDATA 3 +.Os .Sh NAME .Nm dwarf_formudata , .Nm dwarf_formsdata diff --git a/libdwarf/dwarf_get_AT_name.3 b/libdwarf/dwarf_get_AT_name.3 index 473adc331f3f..f84202664557 100644 --- a/libdwarf/dwarf_get_AT_name.3 +++ b/libdwarf/dwarf_get_AT_name.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_AT_name.3 3142 2015-01-29 23:11:14Z jkoshy $ +.\" $Id: dwarf_get_AT_name.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd April 22, 2011 -.Os .Dt DWARF_GET_AT_NAME 3 +.Os .Sh NAME .Nm dwarf_get_ACCESS_name , .Nm dwarf_get_AT_name , @@ -250,7 +250,8 @@ constants. .El .Sh RETURN VALUES These functions return -.Dv DW_DLV_OK on success. +.Dv DW_DLV_OK +on success. If the DWARF constant denoted by argument .Ar val is not recognized, these function return diff --git a/libdwarf/dwarf_get_abbrev.3 b/libdwarf/dwarf_get_abbrev.3 index afb546839248..2e4ae2e28ecc 100644 --- a/libdwarf/dwarf_get_abbrev.3 +++ b/libdwarf/dwarf_get_abbrev.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_abbrev.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_abbrev.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd March 27, 2011 -.Os .Dt DWARF_GET_ABBREV 3 +.Os .Sh NAME .Nm dwarf_get_abbrev .Nd retrieve abbreviation information @@ -123,24 +123,7 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_get_abbrev -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar dbg , -.Ar ret_abbrev , -.Ar length -or -.Ar attr_count -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -There is no abbreviation information at offset -.Ar offset . -.El -.Sh EXAMPLE +.Sh EXAMPLES To loop through all the abbreviation information associated with a DWARF debug context, use: .Bd -literal -offset indent @@ -170,10 +153,27 @@ while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff, if (ret == DW_DLV_ERROR) warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de)); .Ed +.Sh ERRORS +Function +.Fn dwarf_get_abbrev +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar dbg , +.Ar ret_abbrev , +.Ar length +or +.Ar attr_count +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +There is no abbreviation information at offset +.Ar offset . +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_dealloc 3 , -.Xr dwarf_get_abbrev_tag 3 , -.Xr dwarf_get_abbrev_code 3 , .Xr dwarf_get_abbrev_children_flag 3 , -.Xr dwarf_get_abbrev_entry 3 +.Xr dwarf_get_abbrev_code 3 , +.Xr dwarf_get_abbrev_entry 3 , +.Xr dwarf_get_abbrev_tag 3 diff --git a/libdwarf/dwarf_get_abbrev_children_flag.3 b/libdwarf/dwarf_get_abbrev_children_flag.3 index 6f9ed84176e0..8660b57e5a82 100644 --- a/libdwarf/dwarf_get_abbrev_children_flag.3 +++ b/libdwarf/dwarf_get_abbrev_children_flag.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_abbrev_children_flag.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_abbrev_children_flag.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd March 14, 2011 -.Os .Dt DWARF_GET_ABBREV_CHILDREN_FLAG 3 +.Os .Sh NAME .Nm dwarf_get_abbrev_children_flag .Nd return a flag indicating the presence of children @@ -69,7 +69,6 @@ If argument .Ar err is not NULL, it will be used to store error information in case of an error. -.Pp .Sh RETURN VALUES Function .Fn dwarf_get_abbrev_children_flag @@ -96,5 +95,5 @@ was NULL. .Xr dwarf 3 , .Xr dwarf_get_abbrev 3 , .Xr dwarf_get_abbrev_code 3 , -.Xr dwarf_get_abbrev_tag 3 , -.Xr dwarf_get_abbrev_entry 3 +.Xr dwarf_get_abbrev_entry 3 , +.Xr dwarf_get_abbrev_tag 3 diff --git a/libdwarf/dwarf_get_abbrev_code.3 b/libdwarf/dwarf_get_abbrev_code.3 index 18c3c297059e..bc8c25978d48 100644 --- a/libdwarf/dwarf_get_abbrev_code.3 +++ b/libdwarf/dwarf_get_abbrev_code.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_abbrev_code.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_abbrev_code.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd March 13, 2011 -.Os .Dt DWARF_GET_ABBREV_CODE 3 +.Os .Sh NAME .Nm dwarf_get_abbrev_code .Nd retrieve the abbreviation code for an abbreviation @@ -81,6 +81,6 @@ was NULL. .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_get_abbrev 3 , -.Xr dwarf_get_abbrev_tag 3 , .Xr dwarf_get_abbrev_children_flag 3 , -.Xr dwarf_get_abbrev_entry 3 +.Xr dwarf_get_abbrev_entry 3 , +.Xr dwarf_get_abbrev_tag 3 diff --git a/libdwarf/dwarf_get_abbrev_entry.3 b/libdwarf/dwarf_get_abbrev_entry.3 index f9e084b134de..5cadb8084003 100644 --- a/libdwarf/dwarf_get_abbrev_entry.3 +++ b/libdwarf/dwarf_get_abbrev_entry.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_abbrev_entry.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_abbrev_entry.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd April 02, 2011 -.Os .Dt DWARF_GET_ABBREV_ENTRY 3 +.Os .Sh NAME .Nm dwarf_get_abbrev_entry .Nd retrieve attribute information from an abbreviation descriptor @@ -96,25 +96,7 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_get_abbrev_entry -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar abbrev , -.Ar code , -.Ar form -or -.Ar offset -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -The attribute index specified by argument -.Ar ndx -was out of range. -.El -.Sh EXAMPLE +.Sh EXAMPLES To loop through all the attribute entries contained in the abbreviation section, use: .Bd -literal -offset indent @@ -154,6 +136,24 @@ while ((ret = dwarf_next_cu_header(dbg, NULL, NULL, &aboff, if (ret == DW_DLV_ERROR) warnx("dwarf_next_cu_header: %s", dwarf_errmsg(de)); .Ed +.Sh ERRORS +Function +.Fn dwarf_get_abbrev_entry +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar abbrev , +.Ar code , +.Ar form +or +.Ar offset +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +The attribute index specified by argument +.Ar ndx +was out of range. +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_get_abbrev 3 diff --git a/libdwarf/dwarf_get_abbrev_tag.3 b/libdwarf/dwarf_get_abbrev_tag.3 index c1fc37f049d1..d8b8c07962b1 100644 --- a/libdwarf/dwarf_get_abbrev_tag.3 +++ b/libdwarf/dwarf_get_abbrev_tag.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_abbrev_tag.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_abbrev_tag.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd March 13, 2011 -.Os .Dt DWARF_GET_ABBREV_TAG 3 +.Os .Sh NAME .Nm dwarf_get_abbrev_tag .Nd retrieve the tag for an abbreviation @@ -81,6 +81,6 @@ was NULL. .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_get_abbrev 3 , -.Xr dwarf_get_abbrev_code 3 , .Xr dwarf_get_abbrev_children_flag 3 , +.Xr dwarf_get_abbrev_code 3 , .Xr dwarf_get_abbrev_entry 3 diff --git a/libdwarf/dwarf_get_address_size.3 b/libdwarf/dwarf_get_address_size.3 index 856b375e1ba9..d03ef00d301c 100644 --- a/libdwarf/dwarf_get_address_size.3 +++ b/libdwarf/dwarf_get_address_size.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_address_size.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_address_size.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd April 14, 2010 -.Os .Dt DWARF_GET_ADDRESS_SIZE 3 +.Os .Sh NAME .Nm dwarf_get_address_size .Nd return the number of bytes needed to represent an address @@ -78,5 +78,5 @@ was NULL. .El .Sh SEE ALSO .Xr dwarf 3 , -.Xr dwarf_init 3 , -.Xr dwarf_finish 3 +.Xr dwarf_finish 3 , +.Xr dwarf_init 3 diff --git a/libdwarf/dwarf_get_arange.3 b/libdwarf/dwarf_get_arange.3 index b16914087729..bde55ec08b19 100644 --- a/libdwarf/dwarf_get_arange.3 +++ b/libdwarf/dwarf_get_arange.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_arange.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_arange.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd April 16, 2011 -.Os .Dt DWARF_GET_ARANGE 3 +.Os .Sh NAME .Nm dwarf_get_arange .Nd retrieve the address range descriptor for an address @@ -115,7 +115,7 @@ was not found. .El .Sh SEE ALSO .Xr dwarf 3 , -.Xr dwarf_get_aranges 3 , .Xr dwarf_get_arange_cu_header_offset 3 , .Xr dwarf_get_arange_info 3 , +.Xr dwarf_get_aranges 3 , .Xr dwarf_get_cu_die_offset 3 diff --git a/libdwarf/dwarf_get_arange_info.3 b/libdwarf/dwarf_get_arange_info.3 index 3878edde19bb..b3cca0e216a0 100644 --- a/libdwarf/dwarf_get_arange_info.3 +++ b/libdwarf/dwarf_get_arange_info.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_arange_info.3 3142 2015-01-29 23:11:14Z jkoshy $ +.\" $Id: dwarf_get_arange_info.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd April 16, 2011 -.Os .Dt DWARF_GET_ARANGE_INFO 3 +.Os .Sh NAME .Nm dwarf_get_arange_info .Nd extract address range information from a descriptor @@ -89,21 +89,7 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_get_arange_info -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar ar , -.Ar start , -.Ar length -or -.Ar cu_die_offset -was NULL. -.El -.Sh EXAMPLE +.Sh EXAMPLES To loop through all the address lookup table entries, use: .Bd -literal -offset indent Dwarf_Debug dbg; @@ -127,9 +113,23 @@ for (i = 0; i < cnt; i++) { /* Do something with the returned information. */ } .Ed +.Sh ERRORS +Function +.Fn dwarf_get_arange_info +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar ar , +.Ar start , +.Ar length +or +.Ar cu_die_offset +was NULL. +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_get_arange 3 , -.Xr dwarf_get_aranges 3 , .Xr dwarf_get_arange_cu_header_offset 3 , +.Xr dwarf_get_aranges 3 , .Xr dwarf_get_cu_die_offset 3 diff --git a/libdwarf/dwarf_get_aranges.3 b/libdwarf/dwarf_get_aranges.3 index 1444704293f4..db1c1bfea507 100644 --- a/libdwarf/dwarf_get_aranges.3 +++ b/libdwarf/dwarf_get_aranges.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_aranges.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_get_aranges.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_GET_ARANGES 3 +.Os .Sh NAME .Nm dwarf_get_aranges .Nd retrieve program address space mappings @@ -96,26 +96,7 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_get_aranges -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar dbg , -.Ar ar_list -or -.Ar ar_cnt -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -The debugging context -.Ar dbg -did not contain a -.Dq ".debug_aranges" -string section. -.El -.Sh EXAMPLE +.Sh EXAMPLES To loop through all the address lookup table entries, use: .Bd -literal -offset indent Dwarf_Debug dbg; @@ -140,6 +121,25 @@ for (i = 0; i < cnt; i++) { /* Do something with the returned information. */ } .Ed +.Sh ERRORS +Function +.Fn dwarf_get_aranges +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar dbg , +.Ar ar_list +or +.Ar ar_cnt +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +The debugging context +.Ar dbg +did not contain a +.Dq ".debug_aranges" +string section. +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_get_arange 3 , diff --git a/libdwarf/dwarf_get_cie_index.3 b/libdwarf/dwarf_get_cie_index.3 index d6bc015b2d0a..ffcca4747385 100644 --- a/libdwarf/dwarf_get_cie_index.3 +++ b/libdwarf/dwarf_get_cie_index.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_cie_index.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_cie_index.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd May 22, 2011 -.Os .Dt DWARF_GET_CIE_INDEX 3 +.Os .Sh NAME .Nm dwarf_get_cie_index .Nd retrieve the index of a CIE descriptor diff --git a/libdwarf/dwarf_get_cie_info.3 b/libdwarf/dwarf_get_cie_info.3 index f3710ca5bbe9..f40053e2e7a2 100644 --- a/libdwarf/dwarf_get_cie_info.3 +++ b/libdwarf/dwarf_get_cie_info.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_cie_info.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_cie_info.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd May 29, 2011 -.Os .Dt DWARF_GET_CIE_INFO 3 +.Os .Sh NAME .Nm dwarf_get_cie_info .Nd retrieve information associated with a CIE descriptor diff --git a/libdwarf/dwarf_get_cie_of_fde.3 b/libdwarf/dwarf_get_cie_of_fde.3 index 4fa5c5d0931f..bd414f1353f4 100644 --- a/libdwarf/dwarf_get_cie_of_fde.3 +++ b/libdwarf/dwarf_get_cie_of_fde.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_cie_of_fde.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_cie_of_fde.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd May 22, 2011 -.Os .Dt DWARF_GET_CIE_OF_FDE 3 +.Os .Sh NAME .Nm dwarf_get_cie_of_fde .Nd retrieve CIE descriptor @@ -82,7 +82,7 @@ was NULL. .El .Sh SEE ALSO .Xr dwarf 3 , -.Xr dwarf_get_cie_info 3 , .Xr dwarf_get_cie_index 3 , +.Xr dwarf_get_cie_info 3 , .Xr dwarf_get_fde_at_pc 3 , .Xr dwarf_get_fde_n 3 diff --git a/libdwarf/dwarf_get_cu_die_offset.3 b/libdwarf/dwarf_get_cu_die_offset.3 index b71e431fc9f3..b842b7e864ae 100644 --- a/libdwarf/dwarf_get_cu_die_offset.3 +++ b/libdwarf/dwarf_get_cu_die_offset.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_cu_die_offset.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_cu_die_offset.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 10, 2011 -.Os .Dt DWARF_GET_CU_DIE_OFFSET 3 +.Os .Sh NAME .Nm dwarf_get_arange_cu_header_offset , .Nm dwarf_get_cu_die_offset diff --git a/libdwarf/dwarf_get_die_infotypes_flag.3 b/libdwarf/dwarf_get_die_infotypes_flag.3 index 4f5a19ace367..ef84375b20f5 100644 --- a/libdwarf/dwarf_get_die_infotypes_flag.3 +++ b/libdwarf/dwarf_get_die_infotypes_flag.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_die_infotypes_flag.3 3118 2014-12-20 20:30:06Z jkoshy $ +.\" $Id: dwarf_get_die_infotypes_flag.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd December 20, 2014 -.Os .Dt DWARF_GET_DIE_INFOTYPES_FLAG 3 +.Os .Sh NAME .Nm dwarf_get_die_infotypes_flag .Nd indicate the originating DWARF section for a DIE diff --git a/libdwarf/dwarf_get_elf.3 b/libdwarf/dwarf_get_elf.3 index c93a7ef48ceb..9363171320cd 100644 --- a/libdwarf/dwarf_get_elf.3 +++ b/libdwarf/dwarf_get_elf.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_get_elf.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_get_elf.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_GET_ELF 3 +.Os .Sh NAME .Nm dwarf_get_elf .Nd retrieve the @@ -98,6 +98,6 @@ if (dwarf_get_elf(dbg, &elf, &de) != DW_DLV_OK) .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_errmsg 3 , -.Xr dwarf_init 3 , .Xr dwarf_finish 3 , +.Xr dwarf_init 3 , .Xr elf 3 diff --git a/libdwarf/dwarf_get_fde_at_pc.3 b/libdwarf/dwarf_get_fde_at_pc.3 index 8aa36ec8d583..843a5d78d76a 100644 --- a/libdwarf/dwarf_get_fde_at_pc.3 +++ b/libdwarf/dwarf_get_fde_at_pc.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_at_pc.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_fde_at_pc.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd May 22, 2011 -.Os .Dt DWARF_GET_FDE_AT_PC 3 +.Os .Sh NAME .Nm dwarf_get_fde_at_pc .Nd retrieve the FDE descriptor for an address diff --git a/libdwarf/dwarf_get_fde_info_for_all_regs.3 b/libdwarf/dwarf_get_fde_info_for_all_regs.3 index f55d3d68a5bb..58c0ed002646 100644 --- a/libdwarf/dwarf_get_fde_info_for_all_regs.3 +++ b/libdwarf/dwarf_get_fde_info_for_all_regs.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_info_for_all_regs.3 3182 2015-04-10 16:08:10Z emaste $ +.\" $Id: dwarf_get_fde_info_for_all_regs.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd June 4, 2011 -.Os .Dt DWARF_GET_FDE_INFO_FOR_ALL_REGS 3 +.Os .Sh NAME .Nm dwarf_get_fde_info_for_all_regs .Nd retrieve register rule row @@ -150,7 +150,7 @@ did not fall in the range covered by argument .Xr dwarf_get_fde_info_for_reg3 3 , .Xr dwarf_get_fde_n 3 , .Xr dwarf_set_frame_cfa_value 3 , -.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_same_value 3 , .Xr dwarf_set_frame_undefined_value 3 diff --git a/libdwarf/dwarf_get_fde_info_for_all_regs3.3 b/libdwarf/dwarf_get_fde_info_for_all_regs3.3 index 841d98346959..96c160eb9b57 100644 --- a/libdwarf/dwarf_get_fde_info_for_all_regs3.3 +++ b/libdwarf/dwarf_get_fde_info_for_all_regs3.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_info_for_all_regs3.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_fde_info_for_all_regs3.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd June 26, 2011 -.Os .Dt DWARF_GET_FDE_INFO_FOR_ALL_REGS3 3 +.Os .Sh NAME .Nm dwarf_get_fde_info_for_all_regs3 .Nd retrieve register rule row @@ -177,7 +177,7 @@ did not fall in the range covered by argument .Xr dwarf_get_fde_info_for_reg3 3 , .Xr dwarf_get_fde_n 3 , .Xr dwarf_set_frame_cfa_value 3 , -.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_same_value 3 , .Xr dwarf_set_frame_undefined_value 3 diff --git a/libdwarf/dwarf_get_fde_info_for_cfa_reg3.3 b/libdwarf/dwarf_get_fde_info_for_cfa_reg3.3 index f8271f065671..6e339aec8179 100644 --- a/libdwarf/dwarf_get_fde_info_for_cfa_reg3.3 +++ b/libdwarf/dwarf_get_fde_info_for_cfa_reg3.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_info_for_cfa_reg3.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_fde_info_for_cfa_reg3.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd June 12, 2011 -.Os .Dt DWARF_GET_FDE_INFO_FOR_CFA_REGS3 3 +.Os .Sh NAME .Nm dwarf_get_fde_info_for_cfa_regs3 .Nd retrieve a CFA register rule @@ -165,7 +165,7 @@ did not fall in the range covered by argument .Xr dwarf_get_fde_info_for_reg3 3 , .Xr dwarf_get_fde_n 3 , .Xr dwarf_set_frame_cfa_value 3 , -.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_same_value 3 , .Xr dwarf_set_frame_undefined_value 3 diff --git a/libdwarf/dwarf_get_fde_info_for_reg.3 b/libdwarf/dwarf_get_fde_info_for_reg.3 index fd05814a3630..5a241570be76 100644 --- a/libdwarf/dwarf_get_fde_info_for_reg.3 +++ b/libdwarf/dwarf_get_fde_info_for_reg.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_info_for_reg.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: dwarf_get_fde_info_for_reg.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd June 4, 2011 -.Os .Dt DWARF_GET_FDE_INFO_FOR_REG 3 +.Os .Sh NAME .Nm dwarf_get_fde_info_for_reg .Nd retrieve register rule @@ -150,7 +150,7 @@ did not fall in the range covered by argument .Xr dwarf_get_fde_info_for_reg3 3 , .Xr dwarf_get_fde_n 3 , .Xr dwarf_set_frame_cfa_value 3 , -.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_same_value 3 , .Xr dwarf_set_frame_undefined_value 3 diff --git a/libdwarf/dwarf_get_fde_info_for_reg3.3 b/libdwarf/dwarf_get_fde_info_for_reg3.3 index 85c0f7f0ea0d..8e26fa6c65b5 100644 --- a/libdwarf/dwarf_get_fde_info_for_reg3.3 +++ b/libdwarf/dwarf_get_fde_info_for_reg3.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_info_for_reg3.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_get_fde_info_for_reg3.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_GET_FDE_INFO_FOR_REG3 3 +.Os .Sh NAME .Nm dwarf_get_fde_info_for_reg3 .Nd retrieve register rule @@ -140,33 +140,7 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_get_fde_info_for_reg3 -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_FRAME_TABLE_COL_BAD" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar block_ptr , -.Ar fde , -.Ar offset_or_block_len , -.Ar offset_relevant , -.Ar register_num , -.Ar row_pc , -or -.Ar type -was NULL. -.It Bq Er DW_DLE_FRAME_TABLE_COL_BAD -The column number provided in argument -.Ar table_column -was too large. -.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE -The program counter value provided in argument -.Ar pc -did not fall in the range covered by argument -.Ar fde . -.El -.Sh EXAMPLE +.Sh EXAMPLES To retrieve the register rules at column 3 from a rule table associated with a FDE descriptor: .Bd -literal -offset indent @@ -199,6 +173,32 @@ for (pc = low_pc; pc < low_pc + func_len; pc++) { /* ... use the retrieved register rule ... */ } .Ed +.Sh ERRORS +Function +.Fn dwarf_get_fde_info_for_reg3 +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_FRAME_TABLE_COL_BAD" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar block_ptr , +.Ar fde , +.Ar offset_or_block_len , +.Ar offset_relevant , +.Ar register_num , +.Ar row_pc , +or +.Ar type +was NULL. +.It Bq Er DW_DLE_FRAME_TABLE_COL_BAD +The column number provided in argument +.Ar table_column +was too large. +.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE +The program counter value provided in argument +.Ar pc +did not fall in the range covered by argument +.Ar fde . +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_get_fde_at_pc 3 , @@ -208,7 +208,7 @@ for (pc = low_pc; pc < low_pc + func_len; pc++) { .Xr dwarf_get_fde_info_for_reg 3 , .Xr dwarf_get_fde_n 3 , .Xr dwarf_set_frame_cfa_value 3 , -.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_same_value 3 , .Xr dwarf_set_frame_undefined_value 3 diff --git a/libdwarf/dwarf_get_fde_instr_bytes.3 b/libdwarf/dwarf_get_fde_instr_bytes.3 index 488d56633c18..d8c8734bfb22 100644 --- a/libdwarf/dwarf_get_fde_instr_bytes.3 +++ b/libdwarf/dwarf_get_fde_instr_bytes.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_instr_bytes.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_fde_instr_bytes.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd May 23, 2011 -.Os .Dt DWARF_GET_FDE_INSTR_BYTES 3 +.Os .Sh NAME .Nm dwarf_get_fde_instr_bytes .Nd retrieve instructions from FDE descritpor @@ -98,9 +98,9 @@ was NULL. .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_expand_frame_instructions 3 , -.Xr dwarf_get_cie_info 3 , .Xr dwarf_get_cie_index 3 , -.Xr dwarf_get_cie_of_fde , +.Xr dwarf_get_cie_info 3 , +.Xr dwarf_get_cie_of_fde 3 , .Xr dwarf_get_fde_at_pc 3 , .Xr dwarf_get_fde_info_for_all_regs 3 , .Xr dwarf_get_fde_info_for_all_regs3 3 , diff --git a/libdwarf/dwarf_get_fde_list.3 b/libdwarf/dwarf_get_fde_list.3 index 7164ae6e1123..bc4034fd3156 100644 --- a/libdwarf/dwarf_get_fde_list.3 +++ b/libdwarf/dwarf_get_fde_list.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_list.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_get_fde_list.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_GET_FDE_LIST 3 +.Os .Sh NAME .Nm dwarf_get_fde_list .Nd retrieve frame information @@ -132,23 +132,7 @@ In case of an error, they return .Dv DW_DLV_ERROR and set the argument .Ar err . -.Sh ERRORS -These functions may fail with the following errors: -.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Va dbg , -.Va cie_list , -.Va cie_count , -.Va fde_list -or -.Va fde_count -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -There is no frame information associated with the giving DWARF debug -context. -.El -.Sh EXAMPLE +.Sh EXAMPLES To obtain frame information from the .Dq ".debug_frame" section, use: @@ -202,17 +186,33 @@ for (i = 0; i < fde_count; i++) { dwarf_fde_cie_list_dealloc(dbg, cie_list, cie_count, fde_list, fde_count); .Ed +.Sh ERRORS +These functions may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Va dbg , +.Va cie_list , +.Va cie_count , +.Va fde_list +or +.Va fde_count +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +There is no frame information associated with the giving DWARF debug +context. +.El .Sh SEE ALSO .Xr dwarf 3 , +.Xr dwarf_fde_cie_list_dealloc 3 , .Xr dwarf_get_cie_index 3 , .Xr dwarf_get_cie_of_fde 3 , .Xr dwarf_get_fde_at_pc 3 , .Xr dwarf_get_fde_instr_bytes 3 , .Xr dwarf_get_fde_n 3 , .Xr dwarf_get_fde_range 3 , -.Xr dwarf_fde_cie_list_dealloc 3 , .Xr dwarf_set_frame_cfa_value 3 , -.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_rule_initial_value 3 , +.Xr dwarf_set_frame_rule_table_size 3 , .Xr dwarf_set_frame_same_value 3 , .Xr dwarf_set_frame_undefined_value 3 diff --git a/libdwarf/dwarf_get_fde_n.3 b/libdwarf/dwarf_get_fde_n.3 index dbb6c27a883b..a44eeabe7705 100644 --- a/libdwarf/dwarf_get_fde_n.3 +++ b/libdwarf/dwarf_get_fde_n.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_n.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_fde_n.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd May 14, 2011 -.Os .Dt DWARF_GET_FDE_N 3 +.Os .Sh NAME .Nm dwarf_get_fde_n .Nd retrieve FDE descriptor diff --git a/libdwarf/dwarf_get_fde_range.3 b/libdwarf/dwarf_get_fde_range.3 index 1ea708cebccf..d3e978927378 100644 --- a/libdwarf/dwarf_get_fde_range.3 +++ b/libdwarf/dwarf_get_fde_range.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_fde_range.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_fde_range.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd May 22, 2011 -.Os .Dt DWARF_GET_FDE_RANGE 3 +.Os .Sh NAME .Nm dwarf_get_fde_range .Nd retrieve range information from an FDE descriptor @@ -134,9 +134,9 @@ was NULL. .El .Sh SEE ALSO .Xr dwarf 3 , -.Xr dwarf_get_cie_info 3 , .Xr dwarf_get_cie_index 3 , -.Xr dwarf_get_cie_of_fde , +.Xr dwarf_get_cie_info 3 , +.Xr dwarf_get_cie_of_fde 3 , .Xr dwarf_get_fde_at_pc 3 , .Xr dwarf_get_fde_info_for_all_regs 3 , .Xr dwarf_get_fde_info_for_all_regs3 3 , diff --git a/libdwarf/dwarf_get_form_class.3 b/libdwarf/dwarf_get_form_class.3 index 82cbe1a6cafc..12d69d066db4 100644 --- a/libdwarf/dwarf_get_form_class.3 +++ b/libdwarf/dwarf_get_form_class.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_form_class.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_form_class.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd June 26, 2011 -.Os .Dt DWARF_GET_FORM_CLASS 3 +.Os .Sh NAME .Nm dwarf_get_form_class .Nd retrieve the form class of an attribute diff --git a/libdwarf/dwarf_get_funcs.3 b/libdwarf/dwarf_get_funcs.3 index 4abc1d92c47e..649fa5de94db 100644 --- a/libdwarf/dwarf_get_funcs.3 +++ b/libdwarf/dwarf_get_funcs.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_funcs.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_funcs.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd April 10, 2011 -.Os .Dt DWARF_GET_FUNCS 3 +.Os .Sh NAME .Nm dwarf_get_funcs , .Nm dwarf_func_cu_offset , @@ -211,5 +211,5 @@ did not contain information about static functions. .El .Sh SEE ALSO .Xr dwarf 3 , -.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , -.Xr dwarf_funcs_dealloc 3 +.Xr dwarf_funcs_dealloc 3 , +.Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 diff --git a/libdwarf/dwarf_get_globals.3 b/libdwarf/dwarf_get_globals.3 index b5f976e45465..ac6aa172e381 100644 --- a/libdwarf/dwarf_get_globals.3 +++ b/libdwarf/dwarf_get_globals.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_globals.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_globals.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 2, 2011 -.Os .Dt DWARF_GET_GLOBALS 3 +.Os .Sh NAME .Nm dwarf_get_globals , .Nm dwarf_global_cu_offset , diff --git a/libdwarf/dwarf_get_loclist_entry.3 b/libdwarf/dwarf_get_loclist_entry.3 index 50c3455de674..02bc7afc704e 100644 --- a/libdwarf/dwarf_get_loclist_entry.3 +++ b/libdwarf/dwarf_get_loclist_entry.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_loclist_entry.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_loclist_entry.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd July 6, 2011 -.Os .Dt DWARF_GET_LOCLIST_ENTRY 3 +.Os .Sh NAME .Nm dwarf_get_loclist_entry .Nd retrieve DWARF location list entry @@ -108,26 +108,7 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_get_loclist_entry -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar dbg , -.Ar hipc , -.Ar lopc , -.Ar data , -.Ar entry_len -or -.Ar next_entry -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -There is no location list at the specified offset -.Ar offset . -.El -.Sh EXAMPLE +.Sh EXAMPLES To iterate through all the location list entries in the .Dq ".debug_loc" section, use: @@ -148,9 +129,28 @@ while ((ret = dwarf_get_loclist_entry(dbg, off, &hipc, &lopc, &data, if (ret == DW_DLV_ERROR) warnx("dwarf_get_loclist_entry failed: %s", dwarf_errmsg(de)); .Ed +.Sh ERRORS +Function +.Fn dwarf_get_loclist_entry +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar dbg , +.Ar hipc , +.Ar lopc , +.Ar data , +.Ar entry_len +or +.Ar next_entry +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +There is no location list at the specified offset +.Ar offset . +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_loclist 3 , -.Xr dwarf_loclist_n 3 , .Xr dwarf_loclist_from_expr 3 , -.Xr dwarf_loclist_from_expr_a 3 +.Xr dwarf_loclist_from_expr_a 3 , +.Xr dwarf_loclist_n 3 diff --git a/libdwarf/dwarf_get_macro_details.3 b/libdwarf/dwarf_get_macro_details.3 index 71e491420642..cd2f55b0ba3c 100644 --- a/libdwarf/dwarf_get_macro_details.3 +++ b/libdwarf/dwarf_get_macro_details.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_macro_details.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_macro_details.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd March 20, 2011 -.Os .Dt DWARF_GET_MACRO_DETAILS 3 +.Os .Sh NAME .Nm dwarf_get_macro_details .Nd retrieve macro information @@ -150,23 +150,7 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_get_macro_details -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar dbg , -.Ar entry_cnt -or -.Ar details -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -There is no more macro information at the specified offset -.Ar offset . -.El -.Sh EXAMPLE +.Sh EXAMPLES To loop through all the macro information entries associated with a DWARF debug context: .Bd -literal -offset indent @@ -185,6 +169,22 @@ while (dwarf_get_macro_details(dbg, offset, 0, offset = md[cnt - 1].dmd_offset + 1; } .Ed +.Sh ERRORS +Function +.Fn dwarf_get_macro_details +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar dbg , +.Ar entry_cnt +or +.Ar details +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +There is no more macro information at the specified offset +.Ar offset . +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_dealloc 3 , diff --git a/libdwarf/dwarf_get_pubtypes.3 b/libdwarf/dwarf_get_pubtypes.3 index 23ad78341132..700f2aa06c7b 100644 --- a/libdwarf/dwarf_get_pubtypes.3 +++ b/libdwarf/dwarf_get_pubtypes.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_pubtypes.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_pubtypes.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 4, 2011 -.Os .Dt DWARF_GET_PUBTYPES 3 +.Os .Sh NAME .Nm dwarf_get_pubtypes , .Nm dwarf_pubtype_cu_offset , diff --git a/libdwarf/dwarf_get_ranges.3 b/libdwarf/dwarf_get_ranges.3 index 15bad4dfd7ac..f8e84ead35a7 100644 --- a/libdwarf/dwarf_get_ranges.3 +++ b/libdwarf/dwarf_get_ranges.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_ranges.3 3182 2015-04-10 16:08:10Z emaste $ +.\" $Id: dwarf_get_ranges.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_GET_RANGES 3 +.Os .Sh NAME .Nm dwarf_get_ranges .Nd retrieve non-contiguous address ranges @@ -159,23 +159,6 @@ The application should not attempt to directly free this pointer. Portable code should instead use .Fn dwarf_ranges_dealloc to indicate that the memory may be freed. -.Sh COMPATIBILITY -Function -.Fn dwarf_get_ranges_a -is identical to -.Fn dwarf_get_ranges , -except that it requires one additional argument -.Ar die -denoting the debugging information entry associated with -the address range list. -In this implementation of the -.Lb libdwarf , -the argument -.Ar die -is ignored, and function -.Fn dwarf_get_ranges_a -is only provided for compatibility with other implementations of the -DWARF(3) API. .Sh RETURN VALUES These functions return @@ -189,21 +172,7 @@ In case of an error, they return .Dv DW_DLV_ERROR and set the argument .Ar err . -.Sh ERRORS -These function can fail with: -.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar dbg , -.Ar ranges -or -.Ar cnt -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -There is no address range list at the specified offset -.Ar offset . -.El -.Sh EXAMPLE +.Sh EXAMPLES To retrieve the address range list associated with a debugging information entry, use: .Bd -literal -offset indent @@ -253,6 +222,37 @@ for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) { } } .Ed +.Sh COMPATIBILITY +Function +.Fn dwarf_get_ranges_a +is identical to +.Fn dwarf_get_ranges , +except that it requires one additional argument +.Ar die +denoting the debugging information entry associated with +the address range list. +In this implementation of the +.Lb libdwarf , +the argument +.Ar die +is ignored, and function +.Fn dwarf_get_ranges_a +is only provided for compatibility with other implementations of the +DWARF(3) API. +.Sh ERRORS +These function can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar dbg , +.Ar ranges +or +.Ar cnt +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +There is no address range list at the specified offset +.Ar offset . +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_ranges_dealloc 3 diff --git a/libdwarf/dwarf_get_relocation_info.3 b/libdwarf/dwarf_get_relocation_info.3 index 96166cfa9ce9..04fb460f8c8b 100644 --- a/libdwarf/dwarf_get_relocation_info.3 +++ b/libdwarf/dwarf_get_relocation_info.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_relocation_info.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_relocation_info.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 3, 2011 -.Os .Dt DWARF_GET_RELOCATION_INFO 3 +.Os .Sh NAME .Nm dwarf_get_relocation_info .Nd retrieve generated relocation arrays @@ -147,32 +147,6 @@ returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_get_relocation_info -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar dbg , -.Ar elf_section_index , -.Ar elf_section_link , -.Ar reloc_entry_count -or -.Ar reloc_buf -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -There were no more ELF relocation arrays to retrieve. -.It Bq Er DW_DLE_NO_ENTRY -The flag -.Dv DW_DLC_SYMBOLIC_RELOCATIONS -was not set on the producer instance. -.It Bq Er DW_DLE_NO_ENTRY -Function -.Xr dwarf_transform_to_disk_form 3 -was not called prior to calling function -.Fn dwarf_get_relocation_info . -.El .Sh EXAMPLES To generate relocation entries and retrieve them, use: .Bd -literal -offset indent @@ -218,11 +192,37 @@ for (i = 0; (Dwarf_Unsigned) i < reloc_cnt; i++) { dwarf_producer_finish(dbg, &de); .Ed +.Sh ERRORS +Function +.Fn dwarf_get_relocation_info +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar dbg , +.Ar elf_section_index , +.Ar elf_section_link , +.Ar reloc_entry_count +or +.Ar reloc_buf +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +There were no more ELF relocation arrays to retrieve. +.It Bq Er DW_DLE_NO_ENTRY +The flag +.Dv DW_DLC_SYMBOLIC_RELOCATIONS +was not set on the producer instance. +.It Bq Er DW_DLE_NO_ENTRY +Function +.Xr dwarf_transform_to_disk_form 3 +was not called prior to calling function +.Fn dwarf_get_relocation_info . +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_get_relocation_info_count 3 , -.Xr dwarf_reset_section_bytes 3 , .Xr dwarf_producer_finish 3 , .Xr dwarf_producer_init 3 , .Xr dwarf_producer_init_b 3 , +.Xr dwarf_reset_section_bytes 3 , .Xr dwarf_transform_to_disk_form 3 diff --git a/libdwarf/dwarf_get_relocation_info_count.3 b/libdwarf/dwarf_get_relocation_info_count.3 index 38e1a004f3b9..05b70a32ea47 100644 --- a/libdwarf/dwarf_get_relocation_info_count.3 +++ b/libdwarf/dwarf_get_relocation_info_count.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_relocation_info_count.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_relocation_info_count.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 3, 2011 -.Os .Dt DWARF_GET_RELOCATION_INFO_COUNT 3 +.Os .Sh NAME .Nm dwarf_get_relocation_info_count .Nd return the number of relocation arrays diff --git a/libdwarf/dwarf_get_section_bytes.3 b/libdwarf/dwarf_get_section_bytes.3 index 1b0ac9eb6d5f..5256459efcc6 100644 --- a/libdwarf/dwarf_get_section_bytes.3 +++ b/libdwarf/dwarf_get_section_bytes.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_section_bytes.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_section_bytes.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd August 26, 2011 -.Os .Dt DWARF_GET_SECTION_BYTES 3 +.Os .Sh NAME .Nm dwarf_get_section_bytes .Nd retrieve ELF section byte streams @@ -96,23 +96,6 @@ In case of an error, function .Fn dwarf_get_section_bytes will return NULL and set the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_get_section_bytes -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar dbg , -.Ar elf_section_index , -or -.Ar length -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -There were no more ELF sections to retrieve, or the function was -called before a call to -.Xr dwarf_transform_to_disk_form 3 . -.El .Sh EXAMPLES To generate and retrieve ELF section byte streams, use: .Bd -literal -offset indent @@ -148,10 +131,27 @@ for (i = 0; i < count; i++) { /* Release resources. */ dwarf_producer_finish(dbg, &de); .Ed +.Sh ERRORS +Function +.Fn dwarf_get_section_bytes +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar dbg , +.Ar elf_section_index , +or +.Ar length +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +There were no more ELF sections to retrieve, or the function was +called before a call to +.Xr dwarf_transform_to_disk_form 3 . +.El .Sh SEE ALSO .Xr dwarf 3 , -.Xr dwarf_reset_section_bytes 3 , .Xr dwarf_producer_finish 3 , .Xr dwarf_producer_init 3 , .Xr dwarf_producer_init_b 3 , +.Xr dwarf_reset_section_bytes 3 , .Xr dwarf_transform_to_disk_form 3 diff --git a/libdwarf/dwarf_get_section_max_offsets.3 b/libdwarf/dwarf_get_section_max_offsets.3 index 963d4ac3814e..d8280a5d56cf 100644 --- a/libdwarf/dwarf_get_section_max_offsets.3 +++ b/libdwarf/dwarf_get_section_max_offsets.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_section_max_offsets.3 3141 2015-01-29 23:11:10Z jkoshy $ +.\" $Id: dwarf_get_section_max_offsets.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd December 21, 2014 +.Dt DWARF_GET_SECTION_MAX_OFFSETS 3 .Os -.Dt DWARF_GET_SECTION_MAX_OFFSETS .Sh NAME .Nm dwarf_get_section_max_offsets , .Nm dwarf_get_section_max_offsets_b diff --git a/libdwarf/dwarf_get_str.3 b/libdwarf/dwarf_get_str.3 index 5917c97a4752..cdc302a55559 100644 --- a/libdwarf/dwarf_get_str.3 +++ b/libdwarf/dwarf_get_str.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_str.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_str.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd April 3, 2011 -.Os .Dt DWARF_GET_STR 3 +.Os .Sh NAME .Nm dwarf_get_str .Nd retrieve a string from the DWARF string section @@ -95,6 +95,26 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . +.Sh EXAMPLES +To retrieve all the strings in the DWARF string section, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Off offset; +Dwarf_Signed len; +Dwarf_Error de; +char *str; +int ret + +offset = 0; +while ((ret = dwarf_get_str(dbg, offset, &str, &len, &de)) == + DW_DLV_OK) { + /* .. Use the retrieved string. .. */ + offset += len + 1; /* Account for the terminating NUL. */ +} + +if (ret == DW_DLV_ERROR) + warnx("dwarf_get_str: %s", dwarf_errmsg(de)); +.Ed .Sh ERRORS Function .Fn dwarf_get_str @@ -124,26 +144,6 @@ was at the very end of the .Dq ".debug_str" section. .El -.Sh EXAMPLE -To retrieve all the strings in the DWARF string section, use: -.Bd -literal -offset indent -Dwarf_Debug dbg; -Dwarf_Off offset; -Dwarf_Signed len; -Dwarf_Error de; -char *str; -int ret - -offset = 0; -while ((ret = dwarf_get_str(dbg, offset, &str, &len, &de)) == - DW_DLV_OK) { - /* .. Use the retrieved string. .. */ - offset += len + 1; /* Account for the terminating NUL. */ -} - -if (ret == DW_DLV_ERROR) - warnx("dwarf_get_str: %s", dwarf_errmsg(de)); -.Ed .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_init 3 diff --git a/libdwarf/dwarf_get_types.3 b/libdwarf/dwarf_get_types.3 index 59e58681d613..e095f16af80c 100644 --- a/libdwarf/dwarf_get_types.3 +++ b/libdwarf/dwarf_get_types.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_types.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_types.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 10, 2011 -.Os .Dt DWARF_GET_TYPES 3 +.Os .Sh NAME .Nm dwarf_get_types , .Nm dwarf_type_cu_offset , diff --git a/libdwarf/dwarf_get_vars.3 b/libdwarf/dwarf_get_vars.3 index d2c3ebd17b8b..a82b6ce1a5b8 100644 --- a/libdwarf/dwarf_get_vars.3 +++ b/libdwarf/dwarf_get_vars.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_vars.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_vars.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 2, 2011 -.Os .Dt DWARF_GET_VARS 3 +.Os .Sh NAME .Nm dwarf_get_vars , .Nm dwarf_var_cu_offset , diff --git a/libdwarf/dwarf_get_weaks.3 b/libdwarf/dwarf_get_weaks.3 index 470973e4369d..4e347ba1804b 100644 --- a/libdwarf/dwarf_get_weaks.3 +++ b/libdwarf/dwarf_get_weaks.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_get_weaks.3 2071 2011-10-27 03:20:00Z jkoshy $ +.\" $Id: dwarf_get_weaks.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 10, 2011 -.Os .Dt DWARF_GET_WEAKS 3 +.Os .Sh NAME .Nm dwarf_get_weaks , .Nm dwarf_weak_cu_offset , diff --git a/libdwarf/dwarf_hasattr.3 b/libdwarf/dwarf_hasattr.3 index 659887588563..31d6e3e44b95 100644 --- a/libdwarf/dwarf_hasattr.3 +++ b/libdwarf/dwarf_hasattr.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_hasattr.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: dwarf_hasattr.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 17, 2010 -.Os .Dt DWARF_HASATTR 3 +.Os .Sh NAME .Nm dwarf_hasattr .Nd check for the presence of an attribute diff --git a/libdwarf/dwarf_hasform.3 b/libdwarf/dwarf_hasform.3 index 2cb6fc536bd4..bba706820ca7 100644 --- a/libdwarf/dwarf_hasform.3 +++ b/libdwarf/dwarf_hasform.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_hasform.3 2073 2011-10-27 03:30:47Z jkoshy $ +.\" $Id: dwarf_hasform.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd May 22, 2010 -.Os .Dt DWARF_HASFORM 3 +.Os .Sh NAME .Nm dwarf_hasform , .Nm dwarf_whatform , diff --git a/libdwarf/dwarf_highpc.3 b/libdwarf/dwarf_highpc.3 index 4d31f5c8d1a2..94cc4cf62ece 100644 --- a/libdwarf/dwarf_highpc.3 +++ b/libdwarf/dwarf_highpc.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_highpc.3 3092 2014-09-02 22:09:30Z kaiwang27 $ +.\" $Id: dwarf_highpc.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd July 22, 2014 -.Os .Dt DWARF_HIGHPC 3 +.Os .Sh NAME .Nm dwarf_arrayorder , .Nm dwarf_bitoffset , @@ -155,7 +155,8 @@ or if the caller is not interested in the respective value. .Sh RETURN VALUES These functions return -.Dv DW_DLV_OK on success. +.Dv DW_DLV_OK +on success. .Pp If the debugging information entry descriptor denoted by argument .Ar die @@ -189,5 +190,5 @@ had no requested attribute. .Xr dwarf 3 , .Xr dwarf_attr 3 , .Xr dwarf_attrlist 3 , -.Xr dwarf_hasattr 3 , -.Xr dwarf_get_form_class 3 +.Xr dwarf_get_form_class 3 , +.Xr dwarf_hasattr 3 diff --git a/libdwarf/dwarf_init.3 b/libdwarf/dwarf_init.3 index 36c6449dc991..094126ae7978 100644 --- a/libdwarf/dwarf_init.3 +++ b/libdwarf/dwarf_init.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_init.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_init.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_INIT 3 +.Os .Sh NAME .Nm dwarf_init , .Nm dwarf_elf_init @@ -137,6 +137,11 @@ The .Vt Dwarf_Debug instance returned by these functions should be freed using .Fn dwarf_finish . +.Sh IMPLEMENTATION NOTES +The current implementation does not support access modes +.Dv DW_DLC_RDWR +and +.Dv DW_DLC_WRITE . .Sh RETURN VALUES These functions return the following values: .Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY" @@ -151,11 +156,6 @@ or .Ar "elf" did not contain debug information. .El -.Sh IMPLEMENTATION NOTES -The current implementation does not support access modes -.Dv DW_DLC_RDWR -and -.Dv DW_DLC_WRITE . .Sh EXAMPLES To initialize a .Vt Dwarf_Debug diff --git a/libdwarf/dwarf_lineno.3 b/libdwarf/dwarf_lineno.3 index 0a0362f80e9d..d1811819b391 100644 --- a/libdwarf/dwarf_lineno.3 +++ b/libdwarf/dwarf_lineno.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_lineno.3 2074 2011-10-27 03:34:33Z jkoshy $ +.\" $Id: dwarf_lineno.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd February 5, 2011 -.Os .Dt DWARF_LINENO 3 +.Os .Sh NAME .Nm dwarf_lineaddr , .Nm dwarf_linebeginstatement , diff --git a/libdwarf/dwarf_lne_end_sequence.3 b/libdwarf/dwarf_lne_end_sequence.3 index a826acbbacda..efa33a49c2b7 100644 --- a/libdwarf/dwarf_lne_end_sequence.3 +++ b/libdwarf/dwarf_lne_end_sequence.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_lne_end_sequence.3 2074 2011-10-27 03:34:33Z jkoshy $ +.\" $Id: dwarf_lne_end_sequence.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 15, 2011 -.Os .Dt DWARF_LNE_END_SEQUENCE 3 +.Os .Sh NAME .Nm dwarf_lne_end_sequence .Nd set the end of instruction sequence diff --git a/libdwarf/dwarf_lne_set_address.3 b/libdwarf/dwarf_lne_set_address.3 index 8a46b7b434d6..208a3d81f635 100644 --- a/libdwarf/dwarf_lne_set_address.3 +++ b/libdwarf/dwarf_lne_set_address.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_lne_set_address.3 2074 2011-10-27 03:34:33Z jkoshy $ +.\" $Id: dwarf_lne_set_address.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 14, 2011 -.Os .Dt DWARF_LNE_SET_ADDRESS 3 +.Os .Sh NAME .Nm dwarf_lne_set_address .Nd set the base address for line number information diff --git a/libdwarf/dwarf_loclist.3 b/libdwarf/dwarf_loclist.3 index 2e95d74405ae..4350fc7db951 100644 --- a/libdwarf/dwarf_loclist.3 +++ b/libdwarf/dwarf_loclist.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_loclist.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_loclist.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_LOCLIST 3 +.Os .Sh NAME .Nm dwarf_loclist , .Nm dwarf_loclist_n @@ -181,23 +181,7 @@ In case of an error, they return .Dv DW_DLV_ERROR and set the argument .Ar err . -.Sh ERRORS -These functions can fail with: -.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar at , -.Ar llbuf -or -.Ar listlen -was NULL. -.It Bq Er DW_DLE_ARGUMENT -The attribute provided by argument -.Ar at -does not contain a location expression or is not associated with a -location expression list. -.El -.Sh EXAMPLE +.Sh EXAMPLES To retrieve the location list associated with an attribute, use: .Bd -literal -offset indent Dwarf_Attribute at; @@ -222,9 +206,25 @@ for (i = 0; i < lcnt; i++) { } dwarf_dealloc(dbg, llbuf, DW_DLA_LIST); .Ed +.Sh ERRORS +These functions can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar at , +.Ar llbuf +or +.Ar listlen +was NULL. +.It Bq Er DW_DLE_ARGUMENT +The attribute provided by argument +.Ar at +does not contain a location expression or is not associated with a +location expression list. +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_dealloc 3 , +.Xr dwarf_get_loclist_entry 3 , .Xr dwarf_loclist_from_expr 3 , -.Xr dwarf_loclist_from_expr_a 3 , -.Xr dwarf_get_loclist_entry 3 +.Xr dwarf_loclist_from_expr_a 3 diff --git a/libdwarf/dwarf_loclist_from_expr.3 b/libdwarf/dwarf_loclist_from_expr.3 index d0eb88c464d2..cc2a61844aca 100644 --- a/libdwarf/dwarf_loclist_from_expr.3 +++ b/libdwarf/dwarf_loclist_from_expr.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_loclist_from_expr.3 3129 2014-12-21 20:06:26Z jkoshy $ +.\" $Id: dwarf_loclist_from_expr.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd December 21, 2014 -.Os .Dt DWARF_LOCLIST_FROM_EXPR 3 +.Os .Sh NAME .Nm dwarf_loclist_from_expr , .Nm dwarf_loclist_from_expr_a , @@ -194,8 +194,8 @@ this function. .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_dealloc 3 , -.Xr dwarf_loclist_n 3 , .Xr dwarf_get_fde_info_for_all_regs3 3 , .Xr dwarf_get_fde_info_for_cfa_reg3 3 , .Xr dwarf_get_fde_info_for_reg3 3 , -.Xr dwarf_get_loclist_entry 3 +.Xr dwarf_get_loclist_entry 3 , +.Xr dwarf_loclist_n 3 diff --git a/libdwarf/dwarf_new_die.3 b/libdwarf/dwarf_new_die.3 index 1c463d35f030..70ff2b6fe004 100644 --- a/libdwarf/dwarf_new_die.3 +++ b/libdwarf/dwarf_new_die.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_new_die.3 2074 2011-10-27 03:34:33Z jkoshy $ +.\" $Id: dwarf_new_die.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 4, 2011 -.Os .Dt DWARF_NEW_DIE 3 +.Os .Sh NAME .Nm dwarf_new_die .Nd allocate a new debugging information entry @@ -106,27 +106,6 @@ returns .Dv DW_DLV_BADADDR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_new_die -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" -.It Bq Er DW_DLE_ARGUMENT -Argument -.Ar dbg -was NULL. -.It Bq Er DW_DLE_ARGUMENT -More than one of the arguments -.Ar parent , -.Ar child , -.Ar left -and -.Ar right -were non-NULL. -.It Bq Er DW_DLE_MEMORY -An out of memory condition was encountered during the execution of the -function. -.El .Sh EXAMPLES To create debugging information entries and add them to the producer instance, use: @@ -156,6 +135,27 @@ if (dwarf_add_die_to_debug(dbg, die1, &de) != DW_DLV_OK) { return; } .Ed +.Sh ERRORS +Function +.Fn dwarf_new_die +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Ar dbg +was NULL. +.It Bq Er DW_DLE_ARGUMENT +More than one of the arguments +.Ar parent , +.Ar child , +.Ar left +and +.Ar right +were non-NULL. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of the +function. +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_add_die_to_debug 3 , diff --git a/libdwarf/dwarf_new_expr.3 b/libdwarf/dwarf_new_expr.3 index d8f4c8adb373..242699a60a73 100644 --- a/libdwarf/dwarf_new_expr.3 +++ b/libdwarf/dwarf_new_expr.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_new_expr.3 2074 2011-10-27 03:34:33Z jkoshy $ +.\" $Id: dwarf_new_expr.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 8, 2011 -.Os .Dt DWARF_NEW_EXPR 3 +.Os .Sh NAME .Nm dwarf_new_expr .Nd create a location expression descriptor @@ -79,19 +79,6 @@ returns .Dv DW_DLV_BADADDR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_new_expr -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" -.It Bq Er DW_DLE_ARGUMENT -Argument -.Ar dbg -was NULL. -.It Bq Er DW_DLE_MEMORY -An out of memory condition was encountered during the execution of -the function. -.El .Sh EXAMPLES To create a location expression descriptor, add location expression operators to it and to retrieve the generated byte stream, @@ -123,12 +110,25 @@ if ((buf = dwarf_expr_into_block(pe, &len, &de)) == return; } .Ed +.Sh ERRORS +Function +.Fn dwarf_new_expr +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Ar dbg +was NULL. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +the function. +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_add_AT_location_expr 3 , -.Xr dwarf_add_expr_gen 3 , .Xr dwarf_add_expr_addr 3 , .Xr dwarf_add_expr_addr_b 3 , +.Xr dwarf_add_expr_gen 3 , .Xr dwarf_expr_current_offset 3 , .Xr dwarf_expr_into_block 3 , .Xr dwarf_producer_init 3 , diff --git a/libdwarf/dwarf_new_fde.3 b/libdwarf/dwarf_new_fde.3 index 1ca19a858429..790addebb663 100644 --- a/libdwarf/dwarf_new_fde.3 +++ b/libdwarf/dwarf_new_fde.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_new_fde.3 2074 2011-10-27 03:34:33Z jkoshy $ +.\" $Id: dwarf_new_fde.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 24, 2011 -.Os .Dt DWARF_NEW_FDE 3 +.Os .Sh NAME .Nm dwarf_new_fde .Nd allocate a DWARF frame descriptor @@ -81,7 +81,7 @@ function. .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_add_fde_inst 3 , +.Xr dwarf_add_frame_cie 3 , .Xr dwarf_add_frame_fde 3 , .Xr dwarf_add_frame_fde_b 3 , -.Xr dwarf_add_frame_cie 3 , .Xr dwarf_fde_cfa_offset 3 diff --git a/libdwarf/dwarf_next_cu_header.3 b/libdwarf/dwarf_next_cu_header.3 index f68867d7f21e..97f1d32eaf78 100644 --- a/libdwarf/dwarf_next_cu_header.3 +++ b/libdwarf/dwarf_next_cu_header.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_next_cu_header.3 3182 2015-04-10 16:08:10Z emaste $ +.\" $Id: dwarf_next_cu_header.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd December 21, 2014 -.Os .Dt DWARF_NEXT_CU_HEADER 3 +.Os .Sh NAME .Nm dwarf_next_cu_header , .Nm dwarf_next_cu_header_b , @@ -198,7 +198,6 @@ and .Ar err if the caller is not interested in the respective value. .Ss Iterating Through Compilation Units in a Debug Context -.Pp The first call to function .Fn dwarf_next_cu_header_c for a given debug context with argument diff --git a/libdwarf/dwarf_next_types_section.3 b/libdwarf/dwarf_next_types_section.3 index 98ff70d82668..5e01d81f9207 100644 --- a/libdwarf/dwarf_next_types_section.3 +++ b/libdwarf/dwarf_next_types_section.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_next_types_section.3 3116 2014-12-20 18:26:55Z jkoshy $ +.\" $Id: dwarf_next_types_section.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd December 20, 2014 -.Os .Dt DWARF_NEXT_TYPES_SECTION 3 +.Os .Sh NAME .Nm dwarf_next_types_section .Nd step through .debug_types sections in a debug context @@ -95,20 +95,6 @@ When there are no more .Dq \&.debug_types sections left to traverse, it returns .Dv DW_DLV_NO_ENTRY . -.Sh COMPATIBILITY -This function is an extension to the -.Xr DWARF 3 -API. -.Sh ERRORS -The -.Fn dwarf_next_types_section -function may fail with the following errors: -.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" -.It Bq Er DW_DLE_ARGUMENT -Argument -.Va dbg -was NULL. -.El .Sh EXAMPLES To iterate though every type unit in all the .Dq \&.debug_types @@ -128,6 +114,20 @@ do { } } while (dwarf_next_types_section(dbg, &de) == DW_DLV_OK); .Ed +.Sh COMPATIBILITY +This function is an extension to the +.Xr DWARF 3 +API. +.Sh ERRORS +The +.Fn dwarf_next_types_section +function may fail with the following errors: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +Argument +.Va dbg +was NULL. +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_init 3 , diff --git a/libdwarf/dwarf_object_init.3 b/libdwarf/dwarf_object_init.3 index 2915669155e1..06e0a8618780 100644 --- a/libdwarf/dwarf_object_init.3 +++ b/libdwarf/dwarf_object_init.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_object_init.3 2074 2011-10-27 03:34:33Z jkoshy $ +.\" $Id: dwarf_object_init.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 29, 2011 -.Os .Dt DWARF_OBJECT_INIT 3 +.Os .Sh NAME .Nm dwarf_object_init .Nd allocate a DWARF debug descriptor with application-specific file \ @@ -44,7 +44,6 @@ access methods .Fa "Dwarf_Error *err" .Fc .Sh DESCRIPTION -.Pp The .Fn dwarf_object_init function allocates and returns a @@ -202,7 +201,7 @@ function returns In case of an error, the function returns .Dv DW_DLV_ERROR and sets the argument -.Ar err. +.Ar err . .Sh ERRORS The .Fn dwarf_object_init diff --git a/libdwarf/dwarf_producer_init.3 b/libdwarf/dwarf_producer_init.3 index b8ca6a9ce657..7d4dff3880bc 100644 --- a/libdwarf/dwarf_producer_init.3 +++ b/libdwarf/dwarf_producer_init.3 @@ -22,13 +22,13 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_producer_init.3 3182 2015-04-10 16:08:10Z emaste $ +.\" $Id: dwarf_producer_init.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd August 20, 2011 -.Os .Dt DWARF_PRODUCER_INIT 3 +.Os .Sh NAME -.Nm dwarf_producer_init +.Nm dwarf_producer_init , .Nm dwarf_producer_init_b .Nd allocate a DWARF producer descriptor .Sh LIBRARY @@ -79,7 +79,6 @@ The argument .Ar flags specifies additional characteristics of the DWARF producer instance. The following flags are recognized: -.Pp .Bl -tag -width "Dv DW_DLC_ISA_MIPS" .It Dv DW_DLC_ISA_IA64 .Pq Deprecated @@ -229,6 +228,23 @@ In case of an error, they return .Dv DW_DLV_BADADDR and set the argument .Ar err . +.Sh EXAMPLES +To initialize a +.Vt Dwarf_P_Debug +instance for a MIPS32 big endian object, use: +.Bd -literal -offset indent +Dwarf_P_Debug dbg; +Dwarf_Unsigned flags; +Dwarf_Error de; + +/* ... assume cb_func points to the callback function ... */ + +flags = DW_DLC_WRITE | DW_DLC_SIZE_32 | DW_DLC_ISA_MIPS | + DW_DLC_STREAM_RELOCATIONS | DW_DLC_TARGET_BIGENDIAN; +if ((dbg = dwarf_producer_init(flags, cb_func, NULL, NULL, &de)) == + DW_DLV_BADADDR) + warnx("dwarf_producer_init failed: %s", dwarf_errmsg(-1)); +.Ed .Sh ERRORS These functions can fail with: .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" @@ -272,23 +288,6 @@ were both set in argument .It Bq Er DW_DLE_MEMORY An out of memory condition was encountered. .El -.Sh EXAMPLES -To initialize a -.Vt Dwarf_P_Debug -instance for a MIPS32 big endian object, use: -.Bd -literal -offset indent -Dwarf_P_Debug dbg; -Dwarf_Unsigned flags; -Dwarf_Error de; - -/* ... assume cb_func points to the callback function ... */ - -flags = DW_DLC_WRITE | DW_DLC_SIZE_32 | DW_DLC_ISA_MIPS | - DW_DLC_STREAM_RELOCATIONS | DW_DLC_TARGET_BIGENDIAN; -if ((dbg = dwarf_producer_init(flags, cb_func, NULL, NULL, &de)) == - DW_DLV_BADADDR) - warnx("dwarf_producer_init failed: %s", dwarf_errmsg(-1)); -.Ed .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_errmsg 3 , diff --git a/libdwarf/dwarf_producer_set_isa.3 b/libdwarf/dwarf_producer_set_isa.3 index fc8a31f8526f..e97bd1efbfe8 100644 --- a/libdwarf/dwarf_producer_set_isa.3 +++ b/libdwarf/dwarf_producer_set_isa.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_producer_set_isa.3 2074 2011-10-27 03:34:33Z jkoshy $ +.\" $Id: dwarf_producer_set_isa.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 29, 2011 -.Os .Dt DWARF_PRODUCER_SET_ISA 3 +.Os .Sh NAME .Nm dwarf_producer_set_isa .Nd specify the instruction set architecture for a DWARF producer instance @@ -65,10 +65,6 @@ If the argument .Ar err is not NULL, it will be used to store error information in case of an error. -.Sh COMPATIBILITY -The -.Fn dwarf_producer_set_isa -function is a local extension. .Sh RETURN VALUES On success, the function .Fn dwarf_producer_set_isa @@ -78,6 +74,10 @@ In case of an error, this function returns .Dv DW_DLV_ERROR and sets the argument .Ar err . +.Sh COMPATIBILITY +The +.Fn dwarf_producer_set_isa +function is a local extension. .Sh ERRORS The .Fn dwarf_producer_set_isa diff --git a/libdwarf/dwarf_reset_section_bytes.3 b/libdwarf/dwarf_reset_section_bytes.3 index 702d56898cc3..7f7132a42af9 100644 --- a/libdwarf/dwarf_reset_section_bytes.3 +++ b/libdwarf/dwarf_reset_section_bytes.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_reset_section_bytes.3 2075 2011-10-27 03:47:28Z jkoshy $ +.\" $Id: dwarf_reset_section_bytes.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 3, 2011 -.Os .Dt DWARF_RESET_SECTION_BYTES 3 +.Os .Sh NAME .Nm dwarf_reset_section_bytes .Nd reset the internal state of a producer instance diff --git a/libdwarf/dwarf_set_frame_cfa_value.3 b/libdwarf/dwarf_set_frame_cfa_value.3 index c3d9c48bcb18..329c76968c44 100644 --- a/libdwarf/dwarf_set_frame_cfa_value.3 +++ b/libdwarf/dwarf_set_frame_cfa_value.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_set_frame_cfa_value.3 2075 2011-10-27 03:47:28Z jkoshy $ +.\" $Id: dwarf_set_frame_cfa_value.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd June 18, 2011 -.Os .Dt DWARF_SET_FRAME_CFA_VALUE 3 +.Os .Sh NAME .Nm dwarf_set_frame_cfa_value , .Nm dwarf_set_frame_rule_initial_value , diff --git a/libdwarf/dwarf_set_reloc_application.3 b/libdwarf/dwarf_set_reloc_application.3 index db40cbb2522a..76262ed76115 100644 --- a/libdwarf/dwarf_set_reloc_application.3 +++ b/libdwarf/dwarf_set_reloc_application.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_set_reloc_application.3 3161 2015-02-15 21:43:36Z emaste $ +.\" $Id: dwarf_set_reloc_application.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd February 11, 2015 -.Os .Dt DWARF_SET_RELOC_APPLICATION 3 +.Os .Sh NAME .Nm dwarf_set_reloc_application .Nd set a library-wide relocation flag @@ -78,5 +78,5 @@ Function does not return an error. .Sh SEE ALSO .Xr dwarf 3 , -.Xr dwarf_init 3 , -.Xr dwarf_elf_init 3 +.Xr dwarf_elf_init 3 , +.Xr dwarf_init 3 diff --git a/libdwarf/dwarf_seterrarg.3 b/libdwarf/dwarf_seterrarg.3 index 55d78d94258f..437e3943ac4c 100644 --- a/libdwarf/dwarf_seterrarg.3 +++ b/libdwarf/dwarf_seterrarg.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_seterrarg.3 2075 2011-10-27 03:47:28Z jkoshy $ +.\" $Id: dwarf_seterrarg.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd May 01, 2010 -.Os .Dt DWARF_SETERRARG 3 +.Os .Sh NAME .Nm dwarf_seterrarg , .Nm dwarf_seterrhand @@ -90,7 +90,6 @@ If argument is NULL, function .Fn dwarf_seterrarg returns the previous library-wide callback argument. -.Pp .Sh COMPATIBILITY The behavior of these functions when argument .Ar dbg diff --git a/libdwarf/dwarf_srcfiles.3 b/libdwarf/dwarf_srcfiles.3 index 906bb925ab31..55606812c5f2 100644 --- a/libdwarf/dwarf_srcfiles.3 +++ b/libdwarf/dwarf_srcfiles.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_srcfiles.3 2075 2011-10-27 03:47:28Z jkoshy $ +.\" $Id: dwarf_srcfiles.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 28, 2010 -.Os .Dt DWARF_SRCFILES 3 +.Os .Sh NAME .Nm dwarf_srcfiles .Nd retrieve source file information diff --git a/libdwarf/dwarf_srclines.3 b/libdwarf/dwarf_srclines.3 index 0f8d8307fdca..3c10de42c7c3 100644 --- a/libdwarf/dwarf_srclines.3 +++ b/libdwarf/dwarf_srclines.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: dwarf_srclines.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_srclines.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_SRCLINES 3 +.Os .Sh NAME .Nm dwarf_srclines .Nd retrieve line number information for a debugging information entry @@ -93,27 +93,7 @@ In case of an error, it returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh ERRORS -Function -.Fn dwarf_srclines -can fail with: -.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" -.It Bq Er DW_DLE_ARGUMENT -One of the arguments -.Ar die , -.Ar lines -or -.Ar nlines -was NULL. -.It Bq Er DW_DLE_NO_ENTRY -The compilation unit referenced by argument -.Ar die -does not have associated line number information. -.It Bq Er DW_DLE_MEMORY -An out of memory condition was encountered during the execution of -this function. -.El -.Sh EXAMPLE +.Sh EXAMPLES To obtain an array of .Vt Dwarf_Line descriptors and to retrieve the source file, line number, and virtual address @@ -149,6 +129,26 @@ for (n = 0; n < nlines; n++) { dwarf_errmsg(de)); } .Ed +.Sh ERRORS +Function +.Fn dwarf_srclines +can fail with: +.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar die , +.Ar lines +or +.Ar nlines +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +The compilation unit referenced by argument +.Ar die +does not have associated line number information. +.It Bq Er DW_DLE_MEMORY +An out of memory condition was encountered during the execution of +this function. +.El .Sh SEE ALSO .Xr dwarf 3 , .Xr dwarf_line_srcfileno 3 , diff --git a/libdwarf/dwarf_start_macro_file.3 b/libdwarf/dwarf_start_macro_file.3 index 1e821d7fd7b9..945aa99f2a7d 100644 --- a/libdwarf/dwarf_start_macro_file.3 +++ b/libdwarf/dwarf_start_macro_file.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_start_macro_file.3 2075 2011-10-27 03:47:28Z jkoshy $ +.\" $Id: dwarf_start_macro_file.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd September 25, 2011 -.Os .Dt DWARF_START_MACRO_FILE 3 +.Os .Sh NAME .Nm dwarf_start_macro_file .Nd mark the start of a source file inclusion @@ -40,7 +40,6 @@ .Fa "Dwarf_Unsigned lineno" .Fa "Dwarf_Unsigned fileindex" .Fa "Dwarf_Error *err" -.Fa .Fc .Sh DESCRIPTION Function diff --git a/libdwarf/dwarf_tag.3 b/libdwarf/dwarf_tag.3 index bb49a495bef7..eae0181723c6 100644 --- a/libdwarf/dwarf_tag.3 +++ b/libdwarf/dwarf_tag.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_tag.3 2075 2011-10-27 03:47:28Z jkoshy $ +.\" $Id: dwarf_tag.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd April 14, 2010 -.Os .Dt DWARF_TAG 3 +.Os .Sh NAME .Nm dwarf_tag .Nd retrieve the tag associated with a DWARF debugging information entry diff --git a/libdwarf/dwarf_transform_to_disk_form.3 b/libdwarf/dwarf_transform_to_disk_form.3 index 54896caa7ea3..97ec8c328556 100644 --- a/libdwarf/dwarf_transform_to_disk_form.3 +++ b/libdwarf/dwarf_transform_to_disk_form.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_transform_to_disk_form.3 2075 2011-10-27 03:47:28Z jkoshy $ +.\" $Id: dwarf_transform_to_disk_form.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd August 25, 2011 -.Os .Dt DWARF_TRANSFORM_TO_DISK_FORM 3 +.Os .Sh NAME .Nm dwarf_transform_to_disk_form .Nd transform DWARF information into byte streams diff --git a/libdwarf/dwarf_undef_macro.3 b/libdwarf/dwarf_undef_macro.3 index b787289ab2e7..c5a6d4115373 100644 --- a/libdwarf/dwarf_undef_macro.3 +++ b/libdwarf/dwarf_undef_macro.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_undef_macro.3 2122 2011-11-09 15:35:14Z jkoshy $ +.\" $Id: dwarf_undef_macro.3 3644 2018-10-15 19:55:01Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt DWARF_UNDEF_MACRO 3 +.Os .Sh NAME .Nm dwarf_undef_macro .Nd record the removal of a macro definition @@ -81,7 +81,7 @@ returns .Dv DW_DLV_ERROR and sets the argument .Ar err . -.Sh EXAMPLE +.Sh EXAMPLES To record the fact that the macro named .Dv _STDIO_H_ was removed at line 220 of the current macro file, use: diff --git a/libdwarf/dwarf_vendor_ext.3 b/libdwarf/dwarf_vendor_ext.3 index c7ae56fc87e7..31e01d817c6f 100644 --- a/libdwarf/dwarf_vendor_ext.3 +++ b/libdwarf/dwarf_vendor_ext.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_vendor_ext.3 2075 2011-10-27 03:47:28Z jkoshy $ +.\" $Id: dwarf_vendor_ext.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd September 25, 2011 -.Os .Dt DWARF_VENDOR_EXT 3 +.Os .Sh NAME .Nm dwarf_vendor_ext .Nd add vendor-specific macro information to a DWARF producer instance diff --git a/libdwarf/dwarf_whatattr.3 b/libdwarf/dwarf_whatattr.3 index d7f6dd4e38b9..f25c8c851517 100644 --- a/libdwarf/dwarf_whatattr.3 +++ b/libdwarf/dwarf_whatattr.3 @@ -22,11 +22,11 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_whatattr.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: dwarf_whatattr.3 3640 2018-10-14 14:09:13Z jkoshy $ .\" .Dd May 22, 2010 -.Os .Dt DWARF_WHATATTR 3 +.Os .Sh NAME .Nm dwarf_whatattr .Nd retrieve the attribute code for a DWARF attribute diff --git a/libelf/Makefile b/libelf/Makefile index 5d4beaa08e44..28524d249d8a 100644 --- a/libelf/Makefile +++ b/libelf/Makefile @@ -1,4 +1,4 @@ -# $Id: Makefile 3594 2018-04-11 18:26:50Z jkoshy $ +# $Id: Makefile 3632 2018-10-10 21:12:43Z jkoshy $ TOP= .. @@ -51,6 +51,7 @@ SRCS= elf.c \ libelf_checksum.c \ libelf_data.c \ libelf_ehdr.c \ + libelf_elfmachine.c \ libelf_extended.c \ libelf_memory.c \ libelf_open.c \ diff --git a/libelf/_libelf.h b/libelf/_libelf.h index be45335907f3..26f17276b170 100644 --- a/libelf/_libelf.h +++ b/libelf/_libelf.h @@ -23,7 +23,7 @@ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * - * $Id: _libelf.h 3174 2015-03-27 17:13:41Z emaste $ + * $Id: _libelf.h 3632 2018-10-10 21:12:43Z jkoshy $ */ #ifndef __LIBELF_H_ @@ -194,6 +194,9 @@ enum { * Function Prototypes. */ +typedef int _libelf_translator_function(unsigned char *_dst, size_t dsz, + unsigned char *_src, size_t _cnt, int _byteswap); + #ifdef __cplusplus extern "C" { #endif @@ -207,12 +210,12 @@ Elf_Arsym *_libelf_ar_process_bsd_symtab(Elf *_ar, size_t *_dst); Elf_Arsym *_libelf_ar_process_svr4_symtab(Elf *_ar, size_t *_dst); long _libelf_checksum(Elf *_e, int _elfclass); void *_libelf_ehdr(Elf *_e, int _elfclass, int _allocate); +int _libelf_elfmachine(Elf *_e); unsigned int _libelf_falign(Elf_Type _t, int _elfclass); size_t _libelf_fsize(Elf_Type _t, int _elfclass, unsigned int _version, size_t count); -int (*_libelf_get_translator(Elf_Type _t, int _direction, int _elfclass)) - (unsigned char *_dst, size_t dsz, unsigned char *_src, - size_t _cnt, int _byteswap); +_libelf_translator_function *_libelf_get_translator(Elf_Type _t, + int _direction, int _elfclass, int _elfmachine); void *_libelf_getphdr(Elf *_e, int _elfclass); void *_libelf_getshdr(Elf_Scn *_scn, int _elfclass); void _libelf_init_elf(Elf *_e, Elf_Kind _kind); @@ -230,7 +233,7 @@ int _libelf_setshnum(Elf *_e, void *_eh, int _elfclass, size_t _shnum); int _libelf_setshstrndx(Elf *_e, void *_eh, int _elfclass, size_t _shstrndx); Elf_Data *_libelf_xlate(Elf_Data *_d, const Elf_Data *_s, - unsigned int _encoding, int _elfclass, int _direction); + unsigned int _encoding, int _elfclass, int _elfmachine, int _direction); int _libelf_xlate_shtype(uint32_t _sht); #ifdef __cplusplus } diff --git a/libelf/elf.3 b/libelf/elf.3 index 20cb9445535d..269725a09ac8 100644 --- a/libelf/elf.3 +++ b/libelf/elf.3 @@ -21,11 +21,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 3643 2018-10-14 21:09:24Z jkoshy $ .\" -.Dd July 28, 2014 -.Os +.Dd October 10, 2018 .Dt ELF 3 +.Os .Sh NAME .Nm elf .Nd API for manipulating ELF objects @@ -116,9 +116,12 @@ library offers translation facilities .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: @@ -155,7 +158,7 @@ Used for class-independent data types. .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. @@ -237,7 +240,6 @@ The .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 @@ -409,7 +411,7 @@ Same as .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 . @@ -419,7 +421,7 @@ in the ELF library. 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 @@ -436,7 +438,7 @@ Random access inside an 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 @@ -469,7 +471,7 @@ Allocate an Executable Header in an ELF object. 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. @@ -478,14 +480,14 @@ Translate an ELF data structure from its file representation to a 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 @@ -529,9 +531,11 @@ back to the underlying file. 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 @@ -601,6 +605,7 @@ library will reclaim the space used by the 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. diff --git a/libelf/elf_begin.3 b/libelf/elf_begin.3 index e6c11b60e865..b7d8a9ec88b0 100644 --- a/libelf/elf_begin.3 +++ b/libelf/elf_begin.3 @@ -21,11 +21,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 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd December 11, 2011 -.Os .Dt ELF_BEGIN 3 +.Os .Sh NAME .Nm elf_begin .Nd open an ELF file or ar(1) archive diff --git a/libelf/elf_cntl.3 b/libelf/elf_cntl.3 index 257897590db2..59d375dad07d 100644 --- a/libelf/elf_cntl.3 +++ b/libelf/elf_cntl.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_cntl.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: elf_cntl.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 9, 2006 -.Os .Dt ELF_CNTL 3 +.Os .Sh NAME .Nm elf_cntl .Nd control an elf file descriptor diff --git a/libelf/elf_data.c b/libelf/elf_data.c index d494eda2de3f..bab70d003cee 100644 --- a/libelf/elf_data.c +++ b/libelf/elf_data.c @@ -32,7 +32,7 @@ #include "_libelf.h" -ELFTC_VCSID("$Id: elf_data.c 3466 2016-05-11 18:35:44Z emaste $"); +ELFTC_VCSID("$Id: elf_data.c 3632 2018-10-10 21:12:43Z jkoshy $"); Elf_Data * elf_getdata(Elf_Scn *s, Elf_Data *ed) @@ -43,8 +43,7 @@ elf_getdata(Elf_Scn *s, Elf_Data *ed) size_t count, fsz, msz; struct _Libelf_Data *d; uint64_t sh_align, sh_offset, sh_size; - int (*xlate)(unsigned char *_d, size_t _dsz, unsigned char *_s, - size_t _c, int _swap); + _libelf_translator_function *xlate; d = (struct _Libelf_Data *) ed; @@ -151,7 +150,8 @@ elf_getdata(Elf_Scn *s, Elf_Data *ed) d->d_flags |= LIBELF_F_DATA_MALLOCED; - xlate = _libelf_get_translator(elftype, ELF_TOMEMORY, elfclass); + xlate = _libelf_get_translator(elftype, ELF_TOMEMORY, elfclass, + _libelf_elfmachine(e)); if (!(*xlate)(d->d_data.d_buf, (size_t) d->d_data.d_size, e->e_rawfile + sh_offset, count, e->e_byteorder != LIBELF_PRIVATE(byteorder))) { diff --git a/libelf/elf_end.3 b/libelf/elf_end.3 index 8649faaa696d..fab4df34eefb 100644 --- a/libelf/elf_end.3 +++ b/libelf/elf_end.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_end.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_end.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd June 29, 2006 -.Os .Dt ELF_END 3 +.Os .Sh NAME .Nm elf_end .Nd release an ELF descriptor diff --git a/libelf/elf_errmsg.3 b/libelf/elf_errmsg.3 index 822ba6ac894f..ec2561e42c80 100644 --- a/libelf/elf_errmsg.3 +++ b/libelf/elf_errmsg.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_errmsg.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_errmsg.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd June 11, 2006 -.Os .Dt ELF_ERRMSG 3 +.Os .Sh NAME .Nm elf_errmsg , .Nm elf_errno diff --git a/libelf/elf_fill.3 b/libelf/elf_fill.3 index ab42a4245f77..2b78d5907cf4 100644 --- a/libelf/elf_fill.3 +++ b/libelf/elf_fill.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_fill.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_fill.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd June 11, 2006 -.Os .Dt ELF_FILL 3 +.Os .Sh NAME .Nm elf_fill .Nd set fill byte for inter-section padding diff --git a/libelf/elf_flagdata.3 b/libelf/elf_flagdata.3 index de3cfd973160..c210e4a56971 100644 --- a/libelf/elf_flagdata.3 +++ b/libelf/elf_flagdata.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_flagdata.3 3479 2016-06-25 20:44:33Z jkoshy $ +.\" $Id: elf_flagdata.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd December 3, 2011 -.Os .Dt ELF_FLAGDATA 3 +.Os .Sh NAME .Nm elf_flagarhdr , .Nm elf_flagdata , diff --git a/libelf/elf_getarhdr.3 b/libelf/elf_getarhdr.3 index 1aab71ce4306..7af2e726c75c 100644 --- a/libelf/elf_getarhdr.3 +++ b/libelf/elf_getarhdr.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getarhdr.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_getarhdr.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 15, 2006 -.Os .Dt ELF_GETARHDR 3 +.Os .Sh NAME .Nm elf_getarhdr .Nd retrieve ar(1) header for an archive member diff --git a/libelf/elf_getarsym.3 b/libelf/elf_getarsym.3 index cda0511dfd7a..c42aab4ffb6f 100644 --- a/libelf/elf_getarsym.3 +++ b/libelf/elf_getarsym.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getarsym.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_getarsym.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 15, 2006 -.Os .Dt ELF_GETARSYM 3 +.Os .Sh NAME .Nm elf_getarsym .Nd retrieve the symbol table of an archive diff --git a/libelf/elf_getbase.3 b/libelf/elf_getbase.3 index fa1735394173..6319b8ad9d1a 100644 --- a/libelf/elf_getbase.3 +++ b/libelf/elf_getbase.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getbase.3 978 2010-06-06 12:40:19Z jkoshy $ +.\" $Id: elf_getbase.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd June 6, 2010 -.Os .Dt ELF_GETBASE 3 +.Os .Sh NAME .Nm elf_getbase .Nd get the base offset for an object file diff --git a/libelf/elf_getdata.3 b/libelf/elf_getdata.3 index 68b28890b4d6..b287a25a00bc 100644 --- a/libelf/elf_getdata.3 +++ b/libelf/elf_getdata.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getdata.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: elf_getdata.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" .Dd January 26, 2011 -.Os .Dt ELF_GETDATA 3 +.Os .Sh NAME .Nm elf_getdata , .Nm elf_newdata , @@ -144,7 +144,7 @@ structures of type .Dv ELF_T_BYTE . .Ss Special handling of zero-sized and SHT_NOBITS sections For sections of type -.Dv SHT_NOBITS, +.Dv SHT_NOBITS , and for zero-sized sections, the functions .Fn elf_getdata diff --git a/libelf/elf_getident.3 b/libelf/elf_getident.3 index 01d7f9733ade..200fa4e350fb 100644 --- a/libelf/elf_getident.3 +++ b/libelf/elf_getident.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getident.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_getident.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd July 3, 2006 -.Os .Dt ELF_GETIDENT 3 +.Os .Sh NAME .Nm elf_getident .Nd return the initial bytes of a file diff --git a/libelf/elf_getphdrnum.3 b/libelf/elf_getphdrnum.3 index f0fae5ebb01e..d20a457e408e 100644 --- a/libelf/elf_getphdrnum.3 +++ b/libelf/elf_getphdrnum.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getphdrnum.3 467 2009-08-05 18:18:49Z jkoshy $ +.\" $Id: elf_getphdrnum.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" -.Dd August 5, 2009 -.Os +.Dd July 25, 2018 .Dt ELF_GETPHDRNUM 3 +.Os .Sh NAME .Nm elf_getphdrnum .Nd return the number of program headers in an ELF file @@ -45,14 +45,13 @@ and stores it into the location pointed to by argument .Pp This routine allows applications to uniformly process both normal ELF objects and ELF objects that use extended numbering. -.Pp .Sh RETURN VALUES Function .Fn elf_getphdrnum returns a zero value if successful, or -1 in case of an error. .Sh ERRORS Function -.Fn elf_getphnum +.Fn elf_getphdrnum can fail with the following errors: .Bl -tag -width "[ELF_E_RESOURCE]" .It Bq Er ELF_E_ARGUMENT diff --git a/libelf/elf_getphnum.3 b/libelf/elf_getphnum.3 index 95c75403c35e..77c595730890 100644 --- a/libelf/elf_getphnum.3 +++ b/libelf/elf_getphnum.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getphnum.3 467 2009-08-05 18:18:49Z jkoshy $ +.\" $Id: elf_getphnum.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" .Dd August 5, 2009 -.Os .Dt ELF_GETPHNUM 3 +.Os .Sh NAME .Nm elf_getphnum .Nd return the number of program headers in an ELF file @@ -50,7 +50,6 @@ and stores it into the location pointed to by argument .Pp This routine allows applications to uniformly process both normal ELF objects and ELF objects that use extended numbering. -.Pp .Sh RETURN VALUES Function .Fn elf_getphnum diff --git a/libelf/elf_getscn.3 b/libelf/elf_getscn.3 index 0afe44340cc0..ad3c88b82b2a 100644 --- a/libelf/elf_getscn.3 +++ b/libelf/elf_getscn.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2006-2008 Joseph Koshy. All rights reserved. +.\" Copyright (c) 2006-2008,2018 Joseph Koshy. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getscn.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_getscn.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" -.Dd October 22, 2007 -.Os +.Dd September 24, 2018 .Dt ELF_GETSCN 3 +.Os .Sh NAME .Nm elf_getscn , .Nm elf_ndxscn , @@ -86,6 +86,10 @@ takes a section descriptor .Ar scn and returns a pointer to the section descriptor at the next higher index. +As a consequence, +.Fn elf_nextscn +will never return a pointer to the empty section at index zero +.Dv ( SHN_UNDEF ) . Argument .Ar scn is allowed to be NULL, in which case this function will return a diff --git a/libelf/elf_getshdrnum.3 b/libelf/elf_getshdrnum.3 index e2bf354baebd..744fcf2dbf6c 100644 --- a/libelf/elf_getshdrnum.3 +++ b/libelf/elf_getshdrnum.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getshdrnum.3 467 2009-08-05 18:18:49Z jkoshy $ +.\" $Id: elf_getshdrnum.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" .Dd August 4, 2009 -.Os .Dt ELF_GETSHDRNUM 3 +.Os .Sh NAME .Nm elf_getshdrnum .Nd return the number of sections in an ELF file @@ -45,7 +45,6 @@ and stores it into the location pointed to by argument .Pp This routine allows applications to uniformly process both normal ELF objects, and ELF objects that use extended section numbering. -.Pp .Sh RETURN VALUES Function .Fn elf_getshdrnum diff --git a/libelf/elf_getshdrstrndx.3 b/libelf/elf_getshdrstrndx.3 index b02e71582403..e6c4eb774f26 100644 --- a/libelf/elf_getshdrstrndx.3 +++ b/libelf/elf_getshdrstrndx.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getshdrstrndx.3 467 2009-08-05 18:18:49Z jkoshy $ +.\" $Id: elf_getshdrstrndx.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" .Dd August 5, 2009 -.Os .Dt ELF_GETSHDRSTRNDX 3 +.Os .Sh NAME .Nm elf_getshdrstrndx .Nd retrieve the index of the section name string table @@ -46,7 +46,6 @@ and stores it into the location pointed to by argument .Pp This function allow applications to process both normal ELF objects and ELF objects that use extended section numbering uniformly. -.Pp .Sh RETURN VALUES These functions return zero if successful, or -1 in case of an error. .Sh ERRORS diff --git a/libelf/elf_getshnum.3 b/libelf/elf_getshnum.3 index 615aa71faa84..20be5c546773 100644 --- a/libelf/elf_getshnum.3 +++ b/libelf/elf_getshnum.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getshnum.3 467 2009-08-05 18:18:49Z jkoshy $ +.\" $Id: elf_getshnum.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" .Dd August 5, 2009 -.Os .Dt ELF_GETSHNUM 3 +.Os .Sh NAME .Nm elf_getshnum .Nd return the number of sections in an ELF file @@ -50,7 +50,6 @@ and stores it into the location pointed to by argument .Pp This routine allows applications to uniformly process both normal ELF objects, and ELF objects that use extended section numbering. -.Pp .Sh RETURN VALUES Function .Fn elf_getshnum diff --git a/libelf/elf_getshstrndx.3 b/libelf/elf_getshstrndx.3 index 71c6f9518c93..b03820f9c02c 100644 --- a/libelf/elf_getshstrndx.3 +++ b/libelf/elf_getshstrndx.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_getshstrndx.3 467 2009-08-05 18:18:49Z jkoshy $ +.\" $Id: elf_getshstrndx.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" -.Dd August 5, 2009 -.Os +.Dd July 25, 2018 .Dt ELF_GETSHSTRNDX 3 +.Os .Sh NAME .Nm elf_getshstrndx , .Nm elf_setshstrndx @@ -41,17 +41,18 @@ .Sh DESCRIPTION Function .Fn elf_getshstrndx +is deprecated. +Please use +.Xr elf_getshdrstrndx 3 +instead. +.Pp +Function +.Fn elf_getshstrndx retrieves the section index of the string table containing section names from descriptor .Ar elf and stores it into the location pointed to by argument .Ar ndxptr . -Function -.Fn elf_getshstrndx -is deprecated. -Please use -.Xr elf_getshdrstrndx 3 -instead. .Pp Function .Fn elf_setshstrndx @@ -60,7 +61,6 @@ sets the index of the section name string table to argument .Pp These routines allow applications to process both normal ELF objects and ELF objects that use extended section numbering uniformly. -.Pp .Sh RETURN VALUES These functions return a non-zero value if successful, or zero in case of an error. diff --git a/libelf/elf_hash.3 b/libelf/elf_hash.3 index f099558570fd..a772a1a52ac1 100644 --- a/libelf/elf_hash.3 +++ b/libelf/elf_hash.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_hash.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_hash.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 15, 2006 -.Os .Dt ELF_HASH 3 +.Os .Sh NAME .Nm elf_hash .Nd compute a hash value for a string diff --git a/libelf/elf_kind.3 b/libelf/elf_kind.3 index a5bbf9df4554..e7f5b9d232a0 100644 --- a/libelf/elf_kind.3 +++ b/libelf/elf_kind.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_kind.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_kind.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd June 1, 2006 -.Os .Dt ELF_KIND 3 +.Os .Sh NAME .Nm elf_kind .Nd determine ELF file type diff --git a/libelf/elf_memory.3 b/libelf/elf_memory.3 index bcb888ff8d8b..f7b0e7f2270e 100644 --- a/libelf/elf_memory.3 +++ b/libelf/elf_memory.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_memory.3 2314 2011-12-11 06:19:51Z jkoshy $ +.\" $Id: elf_memory.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd June 28, 2006 -.Os .Dt ELF_MEMORY 3 +.Os .Sh NAME .Nm elf_memory .Nd process an ELF or ar(1) archive mapped into memory diff --git a/libelf/elf_next.3 b/libelf/elf_next.3 index 859d06cccda9..0c2d92d67e2d 100644 --- a/libelf/elf_next.3 +++ b/libelf/elf_next.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_next.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_next.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd June 17, 2006 -.Os .Dt ELF_NEXT 3 +.Os .Sh NAME .Nm elf_next .Nd provide sequential access to the next archive member diff --git a/libelf/elf_open.3 b/libelf/elf_open.3 index 3dd1e36a03f4..acfbe8bc1cfd 100644 --- a/libelf/elf_open.3 +++ b/libelf/elf_open.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_open.3 3181 2015-04-10 13:22:51Z emaste $ +.\" $Id: elf_open.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" .Dd May 31, 2012 -.Os .Dt ELF_OPEN 3 +.Os .Sh NAME .Nm elf_open .Nd open ELF objects and ar(1) archives @@ -67,6 +67,9 @@ archive contained in the memory area pointed to by the argument The argument .Ar sz specifies the size of the memory area in bytes. +.Sh RETURN VALUES +The function returns a pointer to a ELF descriptor if successful, or +NULL if an error occurred. .Sh COMPATIBILITY These functions are non-standard extensions to the ELF(3) API set. .Pp @@ -79,9 +82,6 @@ and .Xr ar 1 archives, returning an Elf descriptor of type .Dv ELF_K_NONE . -.Sh RETURN VALUES -The function returns a pointer to a ELF descriptor if successful, or -NULL if an error occurred. .Sh ERRORS These functions can fail with the following errors: .Bl -tag -width "[ELF_E_RESOURCE]" diff --git a/libelf/elf_rand.3 b/libelf/elf_rand.3 index e5affd6a3f7d..1a4696073f09 100644 --- a/libelf/elf_rand.3 +++ b/libelf/elf_rand.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_rand.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_rand.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd June 17, 2006 -.Os .Dt ELF_RAND 3 +.Os .Sh NAME .Nm elf_rand .Nd provide sequential access to the next archive member diff --git a/libelf/elf_rawfile.3 b/libelf/elf_rawfile.3 index a713b4295305..355301cf6c12 100644 --- a/libelf/elf_rawfile.3 +++ b/libelf/elf_rawfile.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_rawfile.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: elf_rawfile.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd July 3, 2006 -.Os .Dt ELF_RAWFILE 3 +.Os .Sh NAME .Nm elf_rawfile .Nd return uninterpreted contents of an ELF file diff --git a/libelf/elf_scn.c b/libelf/elf_scn.c index d3e274715b78..b72fef66c46b 100644 --- a/libelf/elf_scn.c +++ b/libelf/elf_scn.c @@ -36,7 +36,7 @@ #include "_libelf.h" -ELFTC_VCSID("$Id: elf_scn.c 3177 2015-03-30 18:19:41Z emaste $"); +ELFTC_VCSID("$Id: elf_scn.c 3632 2018-10-10 21:12:43Z jkoshy $"); /* * Load an ELF section table and create a list of Elf_Scn structures. @@ -51,8 +51,7 @@ _libelf_load_section_headers(Elf *e, void *ehdr) int ec, swapbytes; unsigned char *src; size_t fsz, i, shnum; - int (*xlator)(unsigned char *_d, size_t _dsz, unsigned char *_s, - size_t _c, int _swap); + _libelf_translator_function *xlator; assert(e != NULL); assert(ehdr != NULL); @@ -84,7 +83,8 @@ _libelf_load_section_headers(Elf *e, void *ehdr) CHECK_EHDR(e, eh64); } - xlator = _libelf_get_translator(ELF_T_SHDR, ELF_TOMEMORY, ec); + xlator = _libelf_get_translator(ELF_T_SHDR, ELF_TOMEMORY, ec, + _libelf_elfmachine(e)); swapbytes = e->e_byteorder != LIBELF_PRIVATE(byteorder); src = e->e_rawfile + shoff; diff --git a/libelf/elf_strptr.3 b/libelf/elf_strptr.3 index 31e0f830a0af..8fb9118ebada 100644 --- a/libelf/elf_strptr.3 +++ b/libelf/elf_strptr.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_strptr.3 1081 2010-08-14 02:23:48Z jkoshy $ +.\" $Id: elf_strptr.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd December 16, 2006 -.Os .Dt ELF_STRPTR 3 +.Os .Sh NAME .Nm elf_strptr .Nd retrieve a string pointer in a string table diff --git a/libelf/elf_update.3 b/libelf/elf_update.3 index 40a1e40c2d50..b6419cf9bf53 100644 --- a/libelf/elf_update.3 +++ b/libelf/elf_update.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_update.3 1729 2011-08-14 09:13:00Z jkoshy $ +.\" $Id: elf_update.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 14, 2011 -.Os .Dt ELF_UPDATE 3 +.Os .Sh NAME .Nm elf_update .Nd update an ELF descriptor diff --git a/libelf/elf_update.c b/libelf/elf_update.c index 6cc109daafcc..25fa98d0bb12 100644 --- a/libelf/elf_update.c +++ b/libelf/elf_update.c @@ -41,7 +41,7 @@ #include <sys/mman.h> #endif -ELFTC_VCSID("$Id: elf_update.c 3190 2015-05-04 15:23:08Z jkoshy $"); +ELFTC_VCSID("$Id: elf_update.c 3632 2018-10-10 21:12:43Z jkoshy $"); /* * Layout strategy: @@ -712,8 +712,8 @@ _libelf_resync_elf(Elf *e, struct _Elf_Extent_List *extents) static off_t _libelf_write_scn(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) { - int ec; off_t rc; + int ec, em; Elf_Scn *s; int elftype; Elf_Data *d, dst; @@ -747,6 +747,9 @@ _libelf_write_scn(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) sh_off = s->s_offset; assert(sh_off % _libelf_falign(elftype, ec) == 0); + em = _libelf_elfmachine(e); + assert(em >= EM_NONE && em < EM__LAST__); + /* * If the section has a `rawdata' descriptor, and the section * contents have not been modified, use its contents directly. @@ -817,8 +820,8 @@ _libelf_write_scn(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) dst.d_buf = nf + rc; dst.d_size = fsz; - if (_libelf_xlate(&dst, d, e->e_byteorder, ec, ELF_TOFILE) == - NULL) + if (_libelf_xlate(&dst, d, e->e_byteorder, ec, em, ELF_TOFILE) + == NULL) return ((off_t) -1); rc += (off_t) fsz; @@ -834,7 +837,7 @@ _libelf_write_scn(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) static off_t _libelf_write_ehdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) { - int ec; + int ec, em; void *ehdr; size_t fsz, msz; Elf_Data dst, src; @@ -850,6 +853,8 @@ _libelf_write_ehdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) fsz = _libelf_fsize(ELF_T_EHDR, ec, e->e_version, (size_t) 1); msz = _libelf_msize(ELF_T_EHDR, ec, e->e_version); + em = _libelf_elfmachine(e); + (void) memset(&dst, 0, sizeof(dst)); (void) memset(&src, 0, sizeof(src)); @@ -861,7 +866,7 @@ _libelf_write_ehdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) dst.d_buf = nf; dst.d_size = fsz; - if (_libelf_xlate(&dst, &src, e->e_byteorder, ec, ELF_TOFILE) == + if (_libelf_xlate(&dst, &src, e->e_byteorder, ec, em, ELF_TOFILE) == NULL) return ((off_t) -1); @@ -875,7 +880,7 @@ _libelf_write_ehdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) static off_t _libelf_write_phdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) { - int ec; + int ec, em; void *ehdr; Elf32_Ehdr *eh32; Elf64_Ehdr *eh64; @@ -899,6 +904,8 @@ _libelf_write_phdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) phoff = eh64->e_phoff; } + em = _libelf_elfmachine(e); + assert(phoff > 0); assert(ex->ex_start == phoff); assert(phoff % _libelf_falign(ELF_T_PHDR, ec) == 0); @@ -918,7 +925,7 @@ _libelf_write_phdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) dst.d_size = fsz; dst.d_buf = nf + ex->ex_start; - if (_libelf_xlate(&dst, &src, e->e_byteorder, ec, ELF_TOFILE) == + if (_libelf_xlate(&dst, &src, e->e_byteorder, ec, em, ELF_TOFILE) == NULL) return ((off_t) -1); @@ -932,7 +939,7 @@ _libelf_write_phdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) static off_t _libelf_write_shdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) { - int ec; + int ec, em; void *ehdr; Elf_Scn *scn; uint64_t shoff; @@ -955,6 +962,8 @@ _libelf_write_shdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) shoff = eh64->e_shoff; } + em = _libelf_elfmachine(e); + assert(nscn > 0); assert(shoff % _libelf_falign(ELF_T_SHDR, ec) == 0); assert(ex->ex_start == shoff); @@ -977,8 +986,8 @@ _libelf_write_shdr(Elf *e, unsigned char *nf, struct _Elf_Extent *ex) dst.d_size = fsz; dst.d_buf = nf + ex->ex_start + scn->s_ndx * fsz; - if (_libelf_xlate(&dst, &src, e->e_byteorder, ec, - ELF_TOFILE) == NULL) + if (_libelf_xlate(&dst, &src, e->e_byteorder, ec, em, + ELF_TOFILE) == NULL) return ((off_t) -1); } diff --git a/libelf/elf_version.3 b/libelf/elf_version.3 index b09fb479cfae..b679aa7aaa03 100644 --- a/libelf/elf_version.3 +++ b/libelf/elf_version.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elf_version.3 2123 2011-11-09 15:40:09Z jkoshy $ +.\" $Id: elf_version.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd November 9, 2011 -.Os .Dt ELF_VERSION 3 +.Os .Sh NAME .Nm elf_version .Nd retrieve or set ELF library operating version diff --git a/libelf/gelf.3 b/libelf/gelf.3 index d00d5b330980..704ae154700f 100644 --- a/libelf/gelf.3 +++ b/libelf/gelf.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf.3 3195 2015-05-12 17:22:19Z emaste $ +.\" $Id: gelf.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" .Dd September 1, 2006 -.Os .Dt GELF 3 +.Os .Sh NAME .Nm GElf .Nd class-independent API for ELF manipulation @@ -115,7 +115,7 @@ routines will signal an error if a GElf value is out of range for the underlying ELF data type. .Ss Namespace use The GElf interface uses the following symbols: -.Bl -tag +.Bl -tag -width indent .It GElf_* Class-independent data types. .It gelf_* @@ -125,16 +125,16 @@ For functions defined in the API set. This section provides an overview of the GElf programming APIs. Further information is provided in the manual page of each function listed here. -.Bl -tag +.Bl -tag -width indent .It "Allocating ELF Data Structures" -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn gelf_newehdr Allocate a new ELF Executable Header. .It Fn gelf_newphdr Allocate a new ELF Program Header Table. .El .It "Data Translation" -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn gelf_xlatetof Translate the native representation of an ELF data structure to its file representation. @@ -143,7 +143,7 @@ Translate from the file representation of an ELF data structure to a native representation. .El .It "Retrieving ELF Data" -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn gelf_getdyn Retrieve an ELF .Sy .dynamic @@ -162,7 +162,7 @@ Retrieve an ELF Section Header Table entry from the underlying ELF descriptor. Retrieve an ELF symbol table entry. .El .It Queries -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn gelf_checksum Retrieves the ELF checksum for an ELF descriptor. .It Fn gelf_fsize diff --git a/libelf/gelf_checksum.3 b/libelf/gelf_checksum.3 index e5f845f6c922..7972cb90cd55 100644 --- a/libelf/gelf_checksum.3 +++ b/libelf/gelf_checksum.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_checksum.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_checksum.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 29, 2006 -.Os .Dt GELF_CHECKSUM 3 +.Os .Sh NAME .Nm elf32_checksum , .Nm elf64_checksum , diff --git a/libelf/gelf_fsize.3 b/libelf/gelf_fsize.3 index ac7996f9296b..7103d69ba1c8 100644 --- a/libelf/gelf_fsize.3 +++ b/libelf/gelf_fsize.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_fsize.3 317 2009-03-06 17:29:22Z jkoshy $ +.\" $Id: gelf_fsize.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd February 5, 2008 -.Os .Dt GELF_FSIZE 3 +.Os .Sh NAME .Nm gelf_fsize , .Nm elf32_fsize , diff --git a/libelf/gelf_getcap.3 b/libelf/gelf_getcap.3 index ed8eb0275825..276933a8365a 100644 --- a/libelf/gelf_getcap.3 +++ b/libelf/gelf_getcap.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getcap.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getcap.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 29, 2006 -.Os .Dt GELF_GETCAP 3 +.Os .Sh NAME .Nm gelf_getcap , .Nm gelf_update_cap diff --git a/libelf/gelf_getclass.3 b/libelf/gelf_getclass.3 index 3504569fd141..f3d204995cd4 100644 --- a/libelf/gelf_getclass.3 +++ b/libelf/gelf_getclass.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getclass.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getclass.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd July 3, 2006 -.Os .Dt GELF_GETCLASS 3 +.Os .Sh NAME .Nm gelf_getclass .Nd retrieve the class of an ELF descriptor diff --git a/libelf/gelf_getdyn.3 b/libelf/gelf_getdyn.3 index f8c177876d07..a4e51ecd0ee2 100644 --- a/libelf/gelf_getdyn.3 +++ b/libelf/gelf_getdyn.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getdyn.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getdyn.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 29, 2006 -.Os .Dt GELF_GETDYN 3 +.Os .Sh NAME .Nm gelf_getdyn , .Nm gelf_update_dyn diff --git a/libelf/gelf_getehdr.3 b/libelf/gelf_getehdr.3 index 56bdcd405646..ce27ea7f0006 100644 --- a/libelf/gelf_getehdr.3 +++ b/libelf/gelf_getehdr.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getehdr.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getehdr.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd December 16, 2006 -.Os .Dt GELF_GETEHDR 3 +.Os .Sh NAME .Nm elf32_getehdr , .Nm elf64_getehdr , diff --git a/libelf/gelf_getmove.3 b/libelf/gelf_getmove.3 index 871a040ad447..64c52d9682ed 100644 --- a/libelf/gelf_getmove.3 +++ b/libelf/gelf_getmove.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getmove.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getmove.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 29, 2006 -.Os .Dt GELF_GETMOVE 3 +.Os .Sh NAME .Nm gelf_getmove , .Nm gelf_update_move diff --git a/libelf/gelf_getphdr.3 b/libelf/gelf_getphdr.3 index f2d38aa8316b..5ccac4aa6ff2 100644 --- a/libelf/gelf_getphdr.3 +++ b/libelf/gelf_getphdr.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getphdr.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getphdr.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" .Dd October 21, 2007 -.Os .Dt GELF_GETPHDR 3 +.Os .Sh NAME .Nm elf32_getphdr , .Nm elf64_getphdr , @@ -66,7 +66,7 @@ Function will retrieve the program header table entry at index .Ar index from ELF descriptor -.Ar elf. +.Ar elf . The translated program header table entry will be written to the address pointed to be argument .Ar dst . diff --git a/libelf/gelf_getrel.3 b/libelf/gelf_getrel.3 index c7566e64e697..c21be0da8b46 100644 --- a/libelf/gelf_getrel.3 +++ b/libelf/gelf_getrel.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getrel.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getrel.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 29, 2006 -.Os .Dt GELF_GETREL 3 +.Os .Sh NAME .Nm gelf_getrel , .Nm gelf_update_rel diff --git a/libelf/gelf_getrela.3 b/libelf/gelf_getrela.3 index c77d52a4021d..946482e605ef 100644 --- a/libelf/gelf_getrela.3 +++ b/libelf/gelf_getrela.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getrela.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getrela.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 29, 2006 -.Os .Dt GELF_GETRELA 3 +.Os .Sh NAME .Nm gelf_getrela , .Nm gelf_update_rela diff --git a/libelf/gelf_getshdr.3 b/libelf/gelf_getshdr.3 index e92d414371d1..8bb06d6be57e 100644 --- a/libelf/gelf_getshdr.3 +++ b/libelf/gelf_getshdr.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getshdr.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getshdr.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 27, 2006 -.Os .Dt GELF_GETSHDR 3 +.Os .Sh NAME .Nm elf32_getshdr , .Nm elf64_getshdr , diff --git a/libelf/gelf_getsym.3 b/libelf/gelf_getsym.3 index 98d886f88223..a139c152d15d 100644 --- a/libelf/gelf_getsym.3 +++ b/libelf/gelf_getsym.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getsym.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getsym.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 29, 2006 -.Os .Dt GELF_GETSYM 3 +.Os .Sh NAME .Nm gelf_getsym , .Nm gelf_update_sym diff --git a/libelf/gelf_getsyminfo.3 b/libelf/gelf_getsyminfo.3 index a1169f80dc08..0f602c289795 100644 --- a/libelf/gelf_getsyminfo.3 +++ b/libelf/gelf_getsyminfo.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getsyminfo.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getsyminfo.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 29, 2006 -.Os .Dt GELF_GETSYMINFO 3 +.Os .Sh NAME .Nm gelf_getsyminfo , .Nm gelf_update_syminfo diff --git a/libelf/gelf_getsymshndx.3 b/libelf/gelf_getsymshndx.3 index b635aac6d514..595472a429e3 100644 --- a/libelf/gelf_getsymshndx.3 +++ b/libelf/gelf_getsymshndx.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_getsymshndx.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_getsymshndx.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd November 5, 2006 -.Os .Dt GELF_GETSYMSHNDX 3 +.Os .Sh NAME .Nm gelf_getsymshndx , .Nm gelf_update_symshndx diff --git a/libelf/gelf_newehdr.3 b/libelf/gelf_newehdr.3 index cba9de0c8fe5..38698c32e8b0 100644 --- a/libelf/gelf_newehdr.3 +++ b/libelf/gelf_newehdr.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_newehdr.3 3500 2016-12-04 11:08:44Z jkoshy $ +.\" $Id: gelf_newehdr.3 3643 2018-10-14 21:09:24Z jkoshy $ .\" .Dd October 22, 2007 -.Os .Dt GELF_NEWEHDR 3 +.Os .Sh NAME .Nm elf32_newehdr , .Nm elf64_newehdr , @@ -58,7 +58,8 @@ structure. Function .Fn elf64_newehdr returns a pointer to a 64 bit -.Vt Elf64_Ehdr structure. +.Vt Elf64_Ehdr +structure. .Pp When argument .Ar elfclass diff --git a/libelf/gelf_newphdr.3 b/libelf/gelf_newphdr.3 index 27e561d01052..a881aab4dd6e 100644 --- a/libelf/gelf_newphdr.3 +++ b/libelf/gelf_newphdr.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_newphdr.3 3500 2016-12-04 11:08:44Z jkoshy $ +.\" $Id: gelf_newphdr.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd October 22, 2007 -.Os .Dt GELF_NEWPHDR 3 +.Os .Sh NAME .Nm elf32_newphdr , .Nm elf64_newphdr , diff --git a/libelf/gelf_update_ehdr.3 b/libelf/gelf_update_ehdr.3 index f5e041d797b8..02cf51a2751e 100644 --- a/libelf/gelf_update_ehdr.3 +++ b/libelf/gelf_update_ehdr.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_update_ehdr.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_update_ehdr.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" .Dd August 27, 2006 -.Os .Dt GELF_UPDATE_EHDR 3 +.Os .Sh NAME .Nm gelf_update_ehdr , .Nm gelf_update_phdr , diff --git a/libelf/gelf_xlate.c b/libelf/gelf_xlate.c index f50181925f21..11618a4537af 100644 --- a/libelf/gelf_xlate.c +++ b/libelf/gelf_xlate.c @@ -1,5 +1,5 @@ /*- - * Copyright (c) 2006,2008 Joseph Koshy + * Copyright (c) 2006,2008,2018 Joseph Koshy * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -30,30 +30,34 @@ #include "_libelf.h" -ELFTC_VCSID("$Id: gelf_xlate.c 3174 2015-03-27 17:13:41Z emaste $"); +ELFTC_VCSID("$Id: gelf_xlate.c 3632 2018-10-10 21:12:43Z jkoshy $"); Elf_Data * elf32_xlatetof(Elf_Data *dst, const Elf_Data *src, unsigned int encoding) { - return _libelf_xlate(dst, src, encoding, ELFCLASS32, ELF_TOFILE); + return _libelf_xlate(dst, src, encoding, ELFCLASS32, EM_NONE, + ELF_TOFILE); } Elf_Data * elf64_xlatetof(Elf_Data *dst, const Elf_Data *src, unsigned int encoding) { - return _libelf_xlate(dst, src, encoding, ELFCLASS64, ELF_TOFILE); + return _libelf_xlate(dst, src, encoding, ELFCLASS64, EM_NONE, + ELF_TOFILE); } Elf_Data * elf32_xlatetom(Elf_Data *dst, const Elf_Data *src, unsigned int encoding) { - return _libelf_xlate(dst, src, encoding, ELFCLASS32, ELF_TOMEMORY); + return _libelf_xlate(dst, src, encoding, ELFCLASS32, EM_NONE, + ELF_TOMEMORY); } Elf_Data * elf64_xlatetom(Elf_Data *dst, const Elf_Data *src, unsigned int encoding) { - return _libelf_xlate(dst, src, encoding, ELFCLASS64, ELF_TOMEMORY); + return _libelf_xlate(dst, src, encoding, ELFCLASS64, EM_NONE, + ELF_TOMEMORY); } Elf_Data * @@ -62,7 +66,7 @@ gelf_xlatetom(Elf *e, Elf_Data *dst, const Elf_Data *src, { if (e != NULL) return (_libelf_xlate(dst, src, encoding, e->e_class, - ELF_TOMEMORY)); + _libelf_elfmachine(e), ELF_TOMEMORY)); LIBELF_SET_ERROR(ARGUMENT, 0); return (NULL); } @@ -73,7 +77,7 @@ gelf_xlatetof(Elf *e, Elf_Data *dst, const Elf_Data *src, { if (e != NULL) return (_libelf_xlate(dst, src, encoding, e->e_class, - ELF_TOFILE)); + _libelf_elfmachine(e), ELF_TOFILE)); LIBELF_SET_ERROR(ARGUMENT, 0); return (NULL); } diff --git a/libelf/gelf_xlatetof.3 b/libelf/gelf_xlatetof.3 index ca90002096eb..2e5ee0fe15e0 100644 --- a/libelf/gelf_xlatetof.3 +++ b/libelf/gelf_xlatetof.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2006,2008 Joseph Koshy. All rights reserved. +.\" Copyright (c) 2006,2008,2018 Joseph Koshy. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: gelf_xlatetof.3 189 2008-07-20 10:38:08Z jkoshy $ +.\" $Id: gelf_xlatetof.3 3639 2018-10-14 14:07:02Z jkoshy $ .\" -.Dd July 24, 2006 -.Os +.Dd October 11, 2018 .Dt GELF_XLATETOF 3 +.Os .Sh NAME .Nm elf32_xlate , .Nm elf64_xlate , @@ -36,36 +36,39 @@ .Sh SYNOPSIS .In libelf.h .Ft "Elf_Data *" -.Fn elf32_xlatetof "Elf_Data *dst" "Elf_Data *src" "unsigned int encode" +.Fn elf32_xlatetof "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding" .Ft "Elf_Data *" -.Fn elf32_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int encode" +.Fn elf32_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding" .Ft "Elf_Data *" -.Fn elf64_xlatetof "Elf_Data *dst" "Elf_Data *src" "unsigned int encode" +.Fn elf64_xlatetof "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding" .Ft "Elf_Data *" -.Fn elf64_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int encode" +.Fn elf64_xlatetom "Elf_Data *dst" "Elf_Data *src" "unsigned int file_encoding" .In gelf.h .Ft "Elf_Data *" .Fo gelf_xlatetof .Fa "Elf *elf" .Fa "Elf_Data *dst" .Fa "Elf_Data *src" -.Fa "unsigned int encode" +.Fa "unsigned int file_encoding" .Fc .Ft "Elf_Data *" .Fo gelf_xlatetom .Fa "Elf *elf" .Fa "Elf_Data *dst" .Fa "Elf_Data *src" -.Fa "unsigned int encode" +.Fa "unsigned int file_encoding" .Fc .Sh DESCRIPTION These functions translate between the file and memory representations of ELF data structures. -The in-memory representation of an ELF data structure would confirm to +The in-memory representation of an ELF data structure would conform to the byte ordering and data alignment restrictions dictated by the host processor. -A file representation of the same data structure could use a non-native byte -ordering and in addition may be laid out differently with the file. +As described in +.Xr elf 3 , +the file representation of this data structure could use a different byte +ordering from that of the host, or could use a different layout within +the file. .Pp Functions .Fn elf32_xlatetom , @@ -153,7 +156,7 @@ value of the source data descriptor. .El .Pp Argument -.Ar encode +.Ar file_encoding specifies the encoding in which the file objects are represented. It must be one of: .Bl -hang -offset indent @@ -169,14 +172,41 @@ The functions .Fn gelf_xlatetof and .Fn gelf_xlatetom -select the appropriate 32 or 64 bit translations based on the class of argument +select the appropriate translation scheme based on the properties of +argument .Ar elf . .Sh RETURN VALUES These functions return argument .Ar dst if successful, or NULL in case of an error. .Sh EXAMPLES -TODO +To translate a +.Vt GElf_Rel +structure to its LSB file representation use: +.Bd -literal -offset indent +Elf_Data dst, src; +GElf_Rel rel; +Elf *e; + +e = ...; /* See elf_begin(3). */ + +/* Set up the 'src' descriptor. */ +memset(&src, 0, sizeof src); +src.d_buf = &rel; +src.d_size = sizeof(rel); +src.d_type = ELF_T_REL; +src.d_version = EV_CURRENT; + +/* Set up the 'dst' descriptor. */ +memset(&dst, 0, sizeof dst); +dst.d_buf = filebuf; +dst.d_size = gelf_fsize(e, ELF_T_REL, 1, EV_CURRENT); +dst.d_version = EV_CURRENT; + +if (gelf_xlatetof(e, &dst, &src, ELFDATA2LSB) == NULL) { + printf("error: %s", elf_errmsg(0)); +} +.Ed .Sh ERRORS These functions may fail with the following errors: .Bl -tag -width "[ELF_E_RESOURCE]" diff --git a/libelf/libelf_convert.m4 b/libelf/libelf_convert.m4 index ec395902a182..04adeb3114a7 100644 --- a/libelf/libelf_convert.m4 +++ b/libelf/libelf_convert.m4 @@ -30,7 +30,7 @@ #include "_libelf.h" -ELFTC_VCSID("$Id: libelf_convert.m4 3429 2016-03-12 04:12:39Z emaste $"); +ELFTC_VCSID("$Id: libelf_convert.m4 3632 2018-10-10 21:12:43Z jkoshy $"); /* WARNING: GENERATED FROM __file__. */ @@ -1070,11 +1070,15 @@ CONVERTER_NAMES(ELF_TYPE_LIST) } }; -int (*_libelf_get_translator(Elf_Type t, int direction, int elfclass)) - (unsigned char *_dst, size_t dsz, unsigned char *_src, size_t _cnt, - int _byteswap) +/* + * Return a translator function for the specified ELF section type, conversion + * direction, ELF class and ELF machine. + */ +_libelf_translator_function * +_libelf_get_translator(Elf_Type t, int direction, int elfclass, int elfmachine) { assert(elfclass == ELFCLASS32 || elfclass == ELFCLASS64); + assert(elfmachine >= EM_NONE && elfmachine < EM__LAST__); assert(direction == ELF_TOFILE || direction == ELF_TOMEMORY); if (t >= ELF_T_NUM || @@ -1082,6 +1086,9 @@ int (*_libelf_get_translator(Elf_Type t, int direction, int elfclass)) (direction != ELF_TOFILE && direction != ELF_TOMEMORY)) return (NULL); + /* TODO: Handle MIPS64 REL{,A} sections (ticket #559). */ + (void) elfmachine; + return ((elfclass == ELFCLASS32) ? (direction == ELF_TOFILE ? cvt[t].tof32 : cvt[t].tom32) : (direction == ELF_TOFILE ? cvt[t].tof64 : cvt[t].tom64)); diff --git a/libelf/libelf_ehdr.c b/libelf/libelf_ehdr.c index 6630e6eba73e..38e4e74e14d2 100644 --- a/libelf/libelf_ehdr.c +++ b/libelf/libelf_ehdr.c @@ -31,7 +31,7 @@ #include "_libelf.h" -ELFTC_VCSID("$Id: libelf_ehdr.c 3575 2017-09-14 02:13:36Z emaste $"); +ELFTC_VCSID("$Id: libelf_ehdr.c 3632 2018-10-10 21:12:43Z jkoshy $"); /* * Retrieve counts for sections, phdrs and the section string table index @@ -41,11 +41,10 @@ static int _libelf_load_extended(Elf *e, int ec, uint64_t shoff, uint16_t phnum, uint16_t strndx) { - Elf_Scn *scn; size_t fsz; - int (*xlator)(unsigned char *_d, size_t _dsz, unsigned char *_s, - size_t _c, int _swap); + Elf_Scn *scn; uint32_t shtype; + _libelf_translator_function *xlator; assert(STAILQ_EMPTY(&e->e_u.e_elf.e_scn)); @@ -60,7 +59,8 @@ _libelf_load_extended(Elf *e, int ec, uint64_t shoff, uint16_t phnum, if ((scn = _libelf_allocate_scn(e, (size_t) 0)) == NULL) return (0); - xlator = _libelf_get_translator(ELF_T_SHDR, ELF_TOMEMORY, ec); + xlator = _libelf_get_translator(ELF_T_SHDR, ELF_TOMEMORY, ec, + _libelf_elfmachine(e)); (*xlator)((unsigned char *) &scn->s_shdr, sizeof(scn->s_shdr), (unsigned char *) e->e_rawfile + shoff, (size_t) 1, e->e_byteorder != LIBELF_PRIVATE(byteorder)); @@ -166,7 +166,8 @@ _libelf_ehdr(Elf *e, int ec, int allocate) if (e->e_cmd == ELF_C_WRITE) return (ehdr); - xlator = _libelf_get_translator(ELF_T_EHDR, ELF_TOMEMORY, ec); + xlator = _libelf_get_translator(ELF_T_EHDR, ELF_TOMEMORY, ec, + _libelf_elfmachine(e)); (*xlator)((unsigned char*) ehdr, msz, e->e_rawfile, (size_t) 1, e->e_byteorder != LIBELF_PRIVATE(byteorder)); diff --git a/libelf/libelf_elfmachine.c b/libelf/libelf_elfmachine.c new file mode 100644 index 000000000000..f9c423950886 --- /dev/null +++ b/libelf/libelf_elfmachine.c @@ -0,0 +1,63 @@ +/*- + * Copyright (c) 2018 Joseph Koshy + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND + * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE + * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL + * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS + * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY + * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + */ + +#include <assert.h> +#include <libelf.h> + +#include "_libelf.h" + +ELFTC_VCSID("$Id$"); + +/* + * A convenience helper that returns the ELF machine architecture for + * a ELF descriptor. + */ +int +_libelf_elfmachine(Elf *e) +{ + Elf32_Ehdr *eh32; + Elf64_Ehdr *eh64; + + if (!e) + return EM_NONE; + + assert(e->e_kind == ELF_K_ELF); + assert(e->e_class != ELFCLASSNONE); + + eh32 = NULL; + eh64 = NULL; + + switch (e->e_class) { + case ELFCLASS32: + eh32 = e->e_u.e_elf.e_ehdr.e_ehdr32; + return eh32 ? eh32->e_machine : EM_NONE; + case ELFCLASS64: + eh64 = e->e_u.e_elf.e_ehdr.e_ehdr64; + return eh64 ? eh64->e_machine : EM_NONE; + } + + return (EM_NONE); +} diff --git a/libelf/libelf_phdr.c b/libelf/libelf_phdr.c index ba872bbb9744..336ef3877f6f 100644 --- a/libelf/libelf_phdr.c +++ b/libelf/libelf_phdr.c @@ -31,7 +31,7 @@ #include "_libelf.h" -ELFTC_VCSID("$Id: libelf_phdr.c 3174 2015-03-27 17:13:41Z emaste $"); +ELFTC_VCSID("$Id: libelf_phdr.c 3632 2018-10-10 21:12:43Z jkoshy $"); void * _libelf_getphdr(Elf *e, int ec) @@ -42,8 +42,7 @@ _libelf_getphdr(Elf *e, int ec) Elf32_Ehdr *eh32; Elf64_Ehdr *eh64; void *ehdr, *phdr; - int (*xlator)(unsigned char *_d, size_t _dsz, unsigned char *_s, - size_t _c, int _swap); + _libelf_translator_function *xlator; assert(ec == ELFCLASS32 || ec == ELFCLASS64); @@ -98,7 +97,8 @@ _libelf_getphdr(Elf *e, int ec) e->e_u.e_elf.e_phdr.e_phdr64 = phdr; - xlator = _libelf_get_translator(ELF_T_PHDR, ELF_TOMEMORY, ec); + xlator = _libelf_get_translator(ELF_T_PHDR, ELF_TOMEMORY, ec, + _libelf_elfmachine(e)); (*xlator)(phdr, phnum * msz, e->e_rawfile + phoff, phnum, e->e_byteorder != LIBELF_PRIVATE(byteorder)); diff --git a/libelf/libelf_xlate.c b/libelf/libelf_xlate.c index 6ee76244b83e..cfe6a0bdfdbd 100644 --- a/libelf/libelf_xlate.c +++ b/libelf/libelf_xlate.c @@ -29,7 +29,7 @@ #include "_libelf.h" -ELFTC_VCSID("$Id: libelf_xlate.c 3174 2015-03-27 17:13:41Z emaste $"); +ELFTC_VCSID("$Id: libelf_xlate.c 3632 2018-10-10 21:12:43Z jkoshy $"); /* * Translate to/from the file representation of ELF objects. @@ -45,11 +45,12 @@ ELFTC_VCSID("$Id: libelf_xlate.c 3174 2015-03-27 17:13:41Z emaste $"); Elf_Data * _libelf_xlate(Elf_Data *dst, const Elf_Data *src, unsigned int encoding, - int elfclass, int direction) + int elfclass, int elfmachine, int direction) { int byteswap; size_t cnt, dsz, fsz, msz; uintptr_t sb, se, db, de; + _libelf_translator_function *xlator; if (encoding == ELFDATANONE) encoding = LIBELF_PRIVATE(byteorder); @@ -138,8 +139,9 @@ _libelf_xlate(Elf_Data *dst, const Elf_Data *src, unsigned int encoding, (db == sb && !byteswap && fsz == msz)) return (dst); /* nothing more to do */ - if (!(_libelf_get_translator(src->d_type, direction, elfclass)) - (dst->d_buf, dsz, src->d_buf, cnt, byteswap)) { + xlator = _libelf_get_translator(src->d_type, direction, elfclass, + elfmachine); + if (!xlator(dst->d_buf, dsz, src->d_buf, cnt, byteswap)) { LIBELF_SET_ERROR(DATA, 0); return (NULL); } diff --git a/libelftc/elftc.3 b/libelftc/elftc.3 index bbf51738bb20..08b3f5293dc0 100644 --- a/libelftc/elftc.3 +++ b/libelftc/elftc.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elftc.3 2818 2012-12-24 12:32:48Z jkoshy $ +.\" $Id: elftc.3 3645 2018-10-15 20:17:14Z jkoshy $ .\" .Dd December 24, 2012 -.Os .Dt ELFTC 3 +.Os .Sh NAME .Nm elftc .Nd support routines used in the Elftoolchain project @@ -46,7 +46,7 @@ manual pages for the functions listed below. .Ss Functional Grouping .Bl -tag -width indent .It "Binary Object Handling" -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn elftc_bfd_find_target Locate a binary object descriptor. .It Fn elftc_bfd_target_class @@ -59,20 +59,20 @@ Query the object format for a binary object descriptor. Query the target machine for a binary object descriptor. .El .It "C++ support" -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn elftc_demangle Decodes a symbol name encoded according to the encoding rules for the C++ language. .El .It "Programming conveniences" -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn elftc_copyfile Copies the contents of a file to another. .It Fn elftc_set_timestamp Portably set the time stamps on a file. .El .It "Project Configuration" -.Bl -tag -compact +.Bl -tag -compact -width indent .It Fn elftc_version Returns a project-wide identifier string that encodes the source revision of the source tree. diff --git a/libelftc/elftc_bfd_find_target.3 b/libelftc/elftc_bfd_find_target.3 index 302c319f0b83..39d72b05341f 100644 --- a/libelftc/elftc_bfd_find_target.3 +++ b/libelftc/elftc_bfd_find_target.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elftc_bfd_find_target.3 3516 2017-02-10 02:33:08Z emaste $ +.\" $Id: elftc_bfd_find_target.3 3645 2018-10-15 20:17:14Z jkoshy $ .\" .Dd November 30, 2011 +.Dt ELFTC_BFD_FIND_TARGET 3 .Os -.Dt ELFTC_BFD_FIND_TARGET .Sh NAME .Nm elftc_bfd_find_target , .Nm elftc_bfd_target_byteorder , diff --git a/libelftc/elftc_copyfile.3 b/libelftc/elftc_copyfile.3 index 45204338bac7..2e0a7dd82f69 100644 --- a/libelftc/elftc_copyfile.3 +++ b/libelftc/elftc_copyfile.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elftc_copyfile.3 2315 2011-12-11 09:28:55Z jkoshy $ +.\" $Id: elftc_copyfile.3 3645 2018-10-15 20:17:14Z jkoshy $ .\" .Dd December 11, 2011 -.Os .Dt ELFTC_COPYFILE 3 +.Os .Sh NAME .Nm elftc_copyfile .Nd convenience function to copy data @@ -51,23 +51,23 @@ offset at the beginning of the file. The argument .Ar ofd should contain a file descriptor opened for writing. -.Sh RETURN VALUE +.Sh RETURN VALUES .Rv -std .Sh ERRORS The function .Fn elftc_copyfile may fail with any of the errors returned by .Xr fstat 2 , -.Xr malloc 3 , .Xr mmap 2 , .Xr munmap 2 , -.Xr read 2 +.Xr read 2 , +.Xr write 2 , or -.Xr write 2 . +.Xr malloc 3 . .Sh SEE ALSO .Xr fstat 2 , -.Xr malloc 3 , .Xr mmap 2 , .Xr munmap 2 , .Xr read 2 , -.Xr write 2 +.Xr write 2 , +.Xr malloc 3 diff --git a/libelftc/elftc_demangle.3 b/libelftc/elftc_demangle.3 index 44cf0073ca55..2b222eabbf74 100644 --- a/libelftc/elftc_demangle.3 +++ b/libelftc/elftc_demangle.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elftc_demangle.3 3182 2015-04-10 16:08:10Z emaste $ +.\" $Id: elftc_demangle.3 3645 2018-10-15 20:17:14Z jkoshy $ .\" .Dd August 24, 2011 -.Os .Dt ELFTC_DEMANGLE 3 +.Os .Sh NAME .Nm elftc_demangle .Nd demangle a C++ name @@ -76,7 +76,7 @@ Argument may be zero, in which case the function will attempt to guess the encoding scheme from the contents of .Ar encodedname . -.Sh RETURN VALUE +.Sh RETURN VALUES Function .Fn elftc_demangle returns 0 on success. diff --git a/libelftc/elftc_reloc_type_str.3 b/libelftc/elftc_reloc_type_str.3 index 5cd08a6933bd..2f4644af842b 100644 --- a/libelftc/elftc_reloc_type_str.3 +++ b/libelftc/elftc_reloc_type_str.3 @@ -27,8 +27,8 @@ .\" $Id$ .\" .Dd February 19, 2016 -.Os .Dt ELFTC_RELOC_TYPE_STR 3 +.Os .Sh NAME .Nm elftc_reloc_type_str .Nd return the type name for an ELF relocation @@ -52,7 +52,7 @@ specifies the machine (architecture) type. Argument .Ar type specifies the relocation value. -.Sh RETURN VALUE +.Sh RETURN VALUES Function .Fn elftc_program_version returns a pointer to a string constant, or to an internal character buffer diff --git a/libelftc/elftc_set_timestamps.3 b/libelftc/elftc_set_timestamps.3 index 115fe92707a3..b6d4898c2391 100644 --- a/libelftc/elftc_set_timestamps.3 +++ b/libelftc/elftc_set_timestamps.3 @@ -24,8 +24,8 @@ .\" $Id$ .\" .Dd December 15, 2011 -.Os .Dt ELFTC_SET_TIMESTAMPS 3 +.Os .Sh NAME .Nm elftc_set_timestamps .Nd set file timestamps @@ -81,4 +81,4 @@ if (elftc_set_timestamps(new_filename, &sb) < 0) .Xr fstat 2 , .Xr stat 2 , .Xr utime 2 , -.Xr utimes 2 . +.Xr utimes 2 diff --git a/libelftc/elftc_string_table_create.3 b/libelftc/elftc_string_table_create.3 index e11e73cc4a51..387ad72a3727 100644 --- a/libelftc/elftc_string_table_create.3 +++ b/libelftc/elftc_string_table_create.3 @@ -22,11 +22,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elftc_string_table_create.3 2866 2013-01-06 03:20:14Z jkoshy $ +.\" $Id: elftc_string_table_create.3 3645 2018-10-15 20:17:14Z jkoshy $ .\" .Dd January 5, 2013 -.Os .Dt ELFTC_STRING_TABLE_CREATE 3 +.Os .Sh NAME .Nm elftc_string_table_create , .Nm elftc_string_table_destroy , @@ -177,7 +177,6 @@ The library manages its own memory allocations. The application should not free the pointers returned by the string table functions. -.El .Sh IMPLEMENTATION NOTES The current implementation is optimized for the case where strings are added to a string table, but rarely removed from it. diff --git a/libelftc/elftc_timestamp.3 b/libelftc/elftc_timestamp.3 index 3c56f2fe5b9e..a62570258013 100644 --- a/libelftc/elftc_timestamp.3 +++ b/libelftc/elftc_timestamp.3 @@ -27,8 +27,8 @@ .\" $Id$ .\" .Dd August 24, 2016 -.Os .Dt ELFTC_TIMESTAMP 3 +.Os .Sh NAME .Nm elftc_timestamp .Nd return the current or environment-provided timestamp @@ -53,7 +53,7 @@ The .Ar timestamp argument specifies a pointer to the location where the timestamp will be stored. -.Sh RETURN VALUE +.Sh RETURN VALUES Function .Fn elftc_timestamp returns 0 on success, and -1 in the event of an error. diff --git a/libelftc/elftc_version.3 b/libelftc/elftc_version.3 index f7018a50d087..b61acad515cd 100644 --- a/libelftc/elftc_version.3 +++ b/libelftc/elftc_version.3 @@ -21,11 +21,11 @@ .\" out of the use of this software, even if advised of the possibility of .\" such damage. .\" -.\" $Id: elftc_version.3 2828 2012-12-30 04:41:27Z jkoshy $ +.\" $Id: elftc_version.3 3645 2018-10-15 20:17:14Z jkoshy $ .\" .Dd December 30, 2012 -.Os .Dt ELFTC_VERSION 3 +.Os .Sh NAME .Nm elftc_version .Nd return a project-wide version identifier string @@ -54,7 +54,7 @@ The operating system that the tool chain was compiled for. A tree-wide version number extracted from the version control system in use. .El -.Sh RETURN VALUE +.Sh RETURN VALUES Function .Fn elftc_program_version returns a pointer to an internal character buffer. @@ -68,7 +68,9 @@ To retrieve and print the current toolchain version identifier, use: .Ed .Pp On the HEAD branch of the project's sources, when checked out using -Subversion and compiled on a NetBSD host, this would print: +Subversion and compiled on a +.Nx +host, this would print: .D1 Dq elftoolchain HEAD NetBSD svn: Ns Em REVINFO where .Em REVINFO diff --git a/mk/elftoolchain.lib.mk b/mk/elftoolchain.lib.mk index 59eed7a9c5d3..541a9ac0a14a 100644 --- a/mk/elftoolchain.lib.mk +++ b/mk/elftoolchain.lib.mk @@ -1,5 +1,5 @@ # -# $Id: elftoolchain.lib.mk 3594 2018-04-11 18:26:50Z jkoshy $ +# $Id: elftoolchain.lib.mk 3652 2018-12-23 07:59:42Z jkoshy $ # .if !defined(TOP) @@ -67,5 +67,5 @@ ${DESTDIR}${INCSDIR}/${inc}: ${inc} .endif # OpenBSD -# Bring in rules related to test code. -.include "${TOP}/mk/elftoolchain.test.mk" +# Bring in rules related to running the related test suite. +.include "${TOP}/mk/elftoolchain.test-target.mk" diff --git a/mk/elftoolchain.prog.mk b/mk/elftoolchain.prog.mk index 98585cef2518..3731f5336b12 100644 --- a/mk/elftoolchain.prog.mk +++ b/mk/elftoolchain.prog.mk @@ -1,7 +1,7 @@ # # Rules for building programs. # -# $Id: elftoolchain.prog.mk 3607 2018-04-13 19:41:17Z jkoshy $ +# $Id: elftoolchain.prog.mk 3652 2018-12-23 07:59:42Z jkoshy $ .if !defined(TOP) .error Make variable \"TOP\" has not been defined. @@ -120,5 +120,5 @@ clobber: clean os-specific-clobber .PHONY CFLAGS:= ${CFLAGS:N-O*} -g .endif -# Bring in rules related to test code. -.include "${TOP}/mk/elftoolchain.test.mk" +# Bring in rules related to running the related test suite. +.include "${TOP}/mk/elftoolchain.test-target.mk" diff --git a/mk/elftoolchain.test-target.mk b/mk/elftoolchain.test-target.mk new file mode 100644 index 000000000000..1bd7351d0230 --- /dev/null +++ b/mk/elftoolchain.test-target.mk @@ -0,0 +1,16 @@ +# $Id: elftoolchain.test-target.mk 3652 2018-12-23 07:59:42Z jkoshy $ + +# +# Rules for invoking test suites. +# + +TEST_DIRECTORY= test +TEST_TARGET= test + +.if !target(test) +# The special target 'test' runs the test suite associated with a +# utility or library. +test: all .PHONY + cd ${TOP}/${TEST_DIRECTORY}/${.CURDIR:T} && \ + ${MAKE} all ${TEST_TARGET} +.endif diff --git a/mk/elftoolchain.test.mk b/mk/elftoolchain.test.mk index 2182ff907b8a..8fd933809cbe 100644 --- a/mk/elftoolchain.test.mk +++ b/mk/elftoolchain.test.mk @@ -1,14 +1,50 @@ -# $Id: elftoolchain.test.mk 2068 2011-10-26 15:49:07Z jkoshy $ - +# $Id$ # -# Rules for invoking test suites. +# Rules for handling libtest based test suites. # -TEST_DIRECTORY= test -TEST_TARGET= test +.if !defined(TOP) +.error Make variable \"TOP\" has not been defined. +.endif + +TEST_BASE= $(TOP)/test/libtest +TEST_LIB= $(TEST_BASE)/lib +TEST_DRIVER= ${TEST_BASE}/driver +TEST_DRIVER_MAIN= $(TEST_DRIVER)/test_main.o + +CFLAGS+= -I$(TEST_LIB) -I${TEST_DRIVER} + +MAKE_TEST_SCAFFOLDING?= yes + +.if exists(${.CURDIR}/../Makefile.tset) +.include "${.CURDIR}/../Makefile.tset" +.endif + +.if defined(TEST_SRCS) +PROG= tc_${.CURDIR:T:R} + +_C_SRCS= ${TEST_SRCS:M*.c} +_M4_SRCS= ${TEST_SRCS:M*.m4} + +SRCS= ${_C_SRCS} ${_M4_SRCS} # See <bsd.prog.mk> +CLEANFILES+= ${_M4_SRCS:S/.m4$/.c/g} ${TEST_DATA} + +${PROG}: ${TEST_DATA} ${TEST_LIB} ${TEST_DRIVER_MAIN} + +.if defined(MAKE_TEST_SCAFFOLDING) && ${MAKE_TEST_SCAFFOLDING} == "yes" +_TC_SRC= ${.OBJDIR}/tc.c # Test scaffolding. + +SRCS+= ${_TC_SRC} +CLEANFILES+= ${_TC_SRC} + +# Generate the scaffolding file "tc.c" from the test objects. +_TEST_OBJS= ${_C_SRCS:S/.c$/.o/g} ${_M4_SRCS:S/.m4$/.o/g} +_MAKE_SCAFFOLDING= ${TEST_BASE}/bin/make-test-scaffolding +${_TC_SRC}: ${_TEST_OBJS} + ${_MAKE_SCAFFOLDING} -o ${.TARGET} ${.ALLSRC} +.endif +.endif + +LDADD+= ${TEST_DRIVER_MAIN} -L${TEST_LIB} -ltest -# The special target 'test' runs the test suite associated with a -# utility or library. -test: all .PHONY - cd ${TOP}/${TEST_DIRECTORY}/${.CURDIR:T} && \ - ${MAKE} all ${TEST_TARGET} +.include "${TOP}/mk/elftoolchain.prog.mk" diff --git a/mk/os.FreeBSD.mk b/mk/os.FreeBSD.mk index 2c2d6a241dd1..c37b02e9f81d 100644 --- a/mk/os.FreeBSD.mk +++ b/mk/os.FreeBSD.mk @@ -1,4 +1,4 @@ -# $Id: os.FreeBSD.mk 2569 2012-09-04 16:34:04Z jkoshy $ +# $Id: os.FreeBSD.mk 3651 2018-12-06 21:41:47Z jkoshy $ # # Build definitions for FreeBSD @@ -20,7 +20,7 @@ PDFLATEX?= /usr/local/bin/pdflatex # Translate the spelling of a build knob (see ticket #316). .if defined(NOMAN) -NO_MAN= yes +MK_MAN= no # FreeBSD 7 and later. .endif # Literate programming utility. @@ -22,11 +22,11 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $Id: nm.1 3573 2017-09-14 02:06:31Z emaste $ +.\" $Id: nm.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd September 13, 2017 -.Os .Dt NM 1 +.Os .Sh NAME .Nm nm .Nd display symbolic information in object files diff --git a/readelf/readelf.1 b/readelf/readelf.1 index 0741238c9261..9df20621c278 100644 --- a/readelf/readelf.1 +++ b/readelf/readelf.1 @@ -22,11 +22,11 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $Id: readelf.1 3486 2016-08-22 14:10:05Z emaste $ +.\" $Id: readelf.1 3642 2018-10-14 14:24:28Z jkoshy $ .\" .Dd September 13, 2012 -.Os .Dt READELF 1 +.Os .Sh NAME .Nm readelf .Nd display information about ELF objects diff --git a/readelf/readelf.c b/readelf/readelf.c index dd2854e9bacd..b2534792e2e0 100644 --- a/readelf/readelf.c +++ b/readelf/readelf.c @@ -47,7 +47,7 @@ #include "_elftc.h" -ELFTC_VCSID("$Id: readelf.c 3580 2017-09-15 23:29:59Z emaste $"); +ELFTC_VCSID("$Id: readelf.c 3649 2018-11-24 03:26:23Z emaste $"); /* * readelf(1) options. @@ -1115,6 +1115,7 @@ note_type_freebsd(unsigned int nt) case 1: return "NT_FREEBSD_ABI_TAG"; case 2: return "NT_FREEBSD_NOINIT_TAG"; case 3: return "NT_FREEBSD_ARCH_TAG"; + case 4: return "NT_FREEBSD_FEATURE_CTL"; default: return (note_type_unknown(nt)); } } @@ -2372,11 +2373,22 @@ dump_phdr(struct readelf *re) } printf(" %2.2d ", i); /* skip NULL section. */ - for (j = 1; (size_t)j < re->shnum; j++) - if (re->sl[j].addr >= phdr.p_vaddr && - re->sl[j].addr + re->sl[j].sz <= + for (j = 1; (size_t)j < re->shnum; j++) { + if (re->sl[j].off < phdr.p_offset) + continue; + if (re->sl[j].off + re->sl[j].sz > + phdr.p_offset + phdr.p_filesz && + re->sl[j].type != SHT_NOBITS) + continue; + if (re->sl[j].addr < phdr.p_vaddr || + re->sl[j].addr + re->sl[j].sz > phdr.p_vaddr + phdr.p_memsz) - printf("%s ", re->sl[j].name); + continue; + if (phdr.p_type == PT_TLS && + (re->sl[j].flags & SHF_TLS) == 0) + continue; + printf("%s ", re->sl[j].name); + } printf("\n"); } #undef PH_HDR @@ -4697,7 +4709,7 @@ dump_dwarf_line_decoded(struct readelf *re) DW_DLV_OK) dir = NULL; printf("CU: "); - if (dir && file) + if (dir && file && file[0] != '/') printf("%s/", dir); if (file) printf("%s", file); diff --git a/strings/strings.c b/strings/strings.c index 253b8c5d0074..b78956c0310b 100644 --- a/strings/strings.c +++ b/strings/strings.c @@ -24,8 +24,8 @@ * SUCH DAMAGE. */ -#include <sys/stat.h> #include <sys/types.h> +#include <sys/stat.h> #include <ctype.h> #include <err.h> @@ -46,7 +46,7 @@ #include "_elftc.h" -ELFTC_VCSID("$Id: strings.c 3571 2017-09-14 02:04:50Z emaste $"); +ELFTC_VCSID("$Id: strings.c 3648 2018-11-22 23:26:43Z emaste $"); enum radix_style { RADIX_DECIMAL, @@ -64,7 +64,7 @@ enum encoding_style { }; #define PRINTABLE(c) \ - ((c) >= 0 && (c) <= 255 && \ + ((c) >= 0 && (c) <= 255 && \ ((c) == '\t' || isprint((c)) || \ (encoding == ENCODING_8BIT && (c) > 127))) @@ -109,8 +109,8 @@ main(int argc, char **argv) elf_errmsg(-1)); while ((ch = getopt_long(argc, argv, "1234567890ae:fhn:ot:Vv", - strings_longopts, NULL)) != -1) - switch((char)ch) { + strings_longopts, NULL)) != -1) { + switch ((char)ch) { case 'a': entire_file = 1; break; @@ -183,14 +183,15 @@ main(int argc, char **argv) usage(); /* NOTREACHED */ } + } argc -= optind; argv += optind; - if (!min_len) + if (min_len == 0) min_len = 4; - if (!*argv) + if (*argv == NULL) rc = find_strings("{standard input}", 0, 0); - else while (*argv) { + else while (*argv != NULL) { if (handle_file(*argv) != 0) rc = 1; argv++; @@ -226,10 +227,10 @@ handle_binary(const char *name, int fd) { struct stat buf; - memset(&buf, 0, sizeof(struct stat)); - (void) lseek(fd, (off_t)0, SEEK_SET); + memset(&buf, 0, sizeof(buf)); + (void)lseek(fd, 0, SEEK_SET); if (!fstat(fd, &buf)) - return (find_strings(name, (off_t)0, buf.st_size)); + return (find_strings(name, 0, buf.st_size)); return (1); } @@ -253,21 +254,21 @@ handle_elf(const char *name, int fd) if (entire_file) return (handle_binary(name, fd)); - (void) lseek(fd, (off_t)0, SEEK_SET); + (void)lseek(fd, 0, SEEK_SET); elf = elf_begin(fd, ELF_C_READ, NULL); if (elf_kind(elf) != ELF_K_ELF) { - (void) elf_end(elf); + (void)elf_end(elf); return (handle_binary(name, fd)); } if (gelf_getehdr(elf, &elfhdr) == NULL) { - (void) elf_end(elf); + (void)elf_end(elf); warnx("%s: ELF file could not be processed", name); return (1); } if (elfhdr.e_shnum == 0 && elfhdr.e_type == ET_CORE) { - (void) elf_end(elf); + (void)elf_end(elf); return (handle_binary(name, fd)); } else { scn = NULL; @@ -281,7 +282,7 @@ handle_elf(const char *name, int fd) } } } - (void) elf_end(elf); + (void)elf_end(elf); return (rc); } @@ -304,7 +305,7 @@ getcharacter(void) buf[i] = c; } - switch(encoding) { + switch (encoding) { case ENCODING_7BIT: case ENCODING_8BIT: rt = buf[0]; @@ -317,12 +318,12 @@ getcharacter(void) break; case ENCODING_32BIT_BIG: rt = ((long) buf[0] << 24) | ((long) buf[1] << 16) | - ((long) buf[2] << 8) | buf[3]; - break; + ((long) buf[2] << 8) | buf[3]; + break; case ENCODING_32BIT_LITTLE: rt = buf[0] | ((long) buf[1] << 8) | ((long) buf[2] << 16) | - ((long) buf[3] << 24); - break; + ((long) buf[3] << 24); + break; } return (rt); } @@ -341,63 +342,60 @@ find_strings(const char *name, off_t offset, off_t size) int i; if ((obuf = (char*)calloc(1, min_len + 1)) == NULL) { - (void) fprintf(stderr, "Unable to allocate memory: %s\n", - strerror(errno)); + fprintf(stderr, "Unable to allocate memory: %s\n", + strerror(errno)); return (1); } - (void) fseeko(stdin, offset, SEEK_SET); + (void)fseeko(stdin, offset, SEEK_SET); cur_off = offset; start_off = 0; - while(1) { + for (;;) { if ((offset + size) && (cur_off >= offset + size)) break; start_off = cur_off; - memset(obuf, 0, min_len+1); + memset(obuf, 0, min_len + 1); for(i = 0; i < min_len; i++) { c = getcharacter(); if (c == EOF && feof(stdin)) goto _exit1; - if (PRINTABLE(c)) { - obuf[i] = c; - obuf[i+1] = 0; - cur_off += encoding_size; - } else { + if (PRINTABLE(c)) { + obuf[i] = c; + obuf[i + 1] = 0; + cur_off += encoding_size; + } else { if (encoding == ENCODING_8BIT && (uint8_t)c > 127) { - obuf[i] = c; - obuf[i+1] = 0; - cur_off += encoding_size; - continue; - } - cur_off += encoding_size; - break; - } + obuf[i] = c; + obuf[i + 1] = 0; + cur_off += encoding_size; + continue; + } + cur_off += encoding_size; + break; + } } if (i >= min_len && ((cur_off <= offset + size) || !(offset + size))) { if (show_filename) - printf ("%s: ", name); + printf("%s: ", name); if (show_loc) { - switch(radix) { + switch (radix) { case RADIX_DECIMAL: - (void) printf("%7ju ", - (uintmax_t)start_off); + printf("%7ju ", (uintmax_t)start_off); break; case RADIX_HEX: - (void) printf("%7jx ", - (uintmax_t)start_off); + printf("%7jx ", (uintmax_t)start_off); break; case RADIX_OCTAL: - (void) printf("%7jo ", - (uintmax_t)start_off); + printf("%7jo ", (uintmax_t)start_off); break; } } printf("%s", obuf); - while(1) { + for (;;) { if ((offset + size) && (cur_off >= offset + size)) break; @@ -405,9 +403,9 @@ find_strings(const char *name, off_t offset, off_t size) cur_off += encoding_size; if (encoding == ENCODING_8BIT && (uint8_t)c > 127) { - putchar(c); - continue; - } + putchar(c); + continue; + } if (!PRINTABLE(c) || c == EOF) break; putchar(c); @@ -436,13 +434,15 @@ Usage: %s [options] [file...]\n\ void usage(void) { - (void) fprintf(stderr, USAGE_MESSAGE, ELFTC_GETPROGNAME()); + + fprintf(stderr, USAGE_MESSAGE, ELFTC_GETPROGNAME()); exit(EXIT_FAILURE); } void show_version(void) { - (void) printf("%s (%s)\n", ELFTC_GETPROGNAME(), elftc_version()); + + printf("%s (%s)\n", ELFTC_GETPROGNAME(), elftc_version()); exit(EXIT_SUCCESS); } diff --git a/test/Makefile b/test/Makefile index a9f2480ea15b..1f303bfd8ab8 100644 --- a/test/Makefile +++ b/test/Makefile @@ -1,11 +1,12 @@ -# $Id: Makefile 2827 2012-12-29 16:43:15Z jkoshy $ +# $Id: Makefile 3653 2018-12-25 12:31:28Z jkoshy $ # # TET-based test suites used by the Elftoolchain project. # TOP= .. -# Build TET first. +# Build TET and LIBTEST first. +SUBDIR+= libtest SUBDIR+= tet # Build tests for libraries. diff --git a/test/ar/func.sh b/test/ar/func.sh index 635e799ec690..2c31a76dc12a 100755 --- a/test/ar/func.sh +++ b/test/ar/func.sh @@ -1,4 +1,4 @@ -# $Id: func.sh 2080 2011-10-27 04:23:24Z jkoshy $ +# $Id: func.sh 3626 2018-09-29 19:26:57Z jkoshy $ # `init' initializes test engine global data. # init() { @@ -72,7 +72,7 @@ udecode() { fi cd $1 || exit 1 - find . -type f -execdir uudecode {} \; + find . -type f -a -name '*.uu' -execdir uudecode {} \; find . -type f -name '*.uu' -delete } diff --git a/test/ar/tc/add-nonexistent/add-nonexistent.err b/test/ar/tc/add-nonexistent/add-nonexistent.err new file mode 100644 index 000000000000..852a7613acf1 --- /dev/null +++ b/test/ar/tc/add-nonexistent/add-nonexistent.err @@ -0,0 +1 @@ +ar: warning: can't open file: nonexistent: No such file or directory diff --git a/test/ar/tc/add-nonexistent/add-nonexistent.eval b/test/ar/tc/add-nonexistent/add-nonexistent.eval new file mode 100644 index 000000000000..d00491fd7e5b --- /dev/null +++ b/test/ar/tc/add-nonexistent/add-nonexistent.eval @@ -0,0 +1 @@ +1 diff --git a/test/ar/tc/add-nonexistent/add-nonexistent.out b/test/ar/tc/add-nonexistent/add-nonexistent.out new file mode 100644 index 000000000000..e69de29bb2d1 --- /dev/null +++ b/test/ar/tc/add-nonexistent/add-nonexistent.out diff --git a/test/ar/tc/add-nonexistent/add-nonexistent.sh b/test/ar/tc/add-nonexistent/add-nonexistent.sh new file mode 100755 index 000000000000..7918ee5bef83 --- /dev/null +++ b/test/ar/tc/add-nonexistent/add-nonexistent.sh @@ -0,0 +1,4 @@ +# $Id$ +inittest add-nonexistent tc/add-nonexistent +runcmd "${AR} rc archive.a nonexistent" work true +rundiff true diff --git a/test/ar/tc/addself-liba/addself-liba.eval b/test/ar/tc/addself-liba/addself-liba.eval index 573541ac9702..d00491fd7e5b 100644 --- a/test/ar/tc/addself-liba/addself-liba.eval +++ b/test/ar/tc/addself-liba/addself-liba.eval @@ -1 +1 @@ -0 +1 diff --git a/test/ar/tc/extract-nonexistent/extract-nonexistent.err b/test/ar/tc/extract-nonexistent/extract-nonexistent.err new file mode 100644 index 000000000000..c19434648514 --- /dev/null +++ b/test/ar/tc/extract-nonexistent/extract-nonexistent.err @@ -0,0 +1 @@ +ar: warning: nonexistent: not found in archive diff --git a/test/ar/tc/extract-nonexistent/extract-nonexistent.eval b/test/ar/tc/extract-nonexistent/extract-nonexistent.eval new file mode 100644 index 000000000000..d00491fd7e5b --- /dev/null +++ b/test/ar/tc/extract-nonexistent/extract-nonexistent.eval @@ -0,0 +1 @@ +1 diff --git a/test/ar/tc/extract-nonexistent/extract-nonexistent.out b/test/ar/tc/extract-nonexistent/extract-nonexistent.out new file mode 100644 index 000000000000..e69de29bb2d1 --- /dev/null +++ b/test/ar/tc/extract-nonexistent/extract-nonexistent.out diff --git a/test/ar/tc/extract-nonexistent/extract-nonexistent.sh b/test/ar/tc/extract-nonexistent/extract-nonexistent.sh new file mode 100755 index 000000000000..ff6aa408891e --- /dev/null +++ b/test/ar/tc/extract-nonexistent/extract-nonexistent.sh @@ -0,0 +1,6 @@ +# $Id$ +inittest extract-nonexistent tc/extract-nonexistent +extshar ${TESTDIR} +extshar ${RLTDIR} +runcmd "${AR} xv valid.a nonexistent" work true +rundiff true diff --git a/test/ar/tc/extract-nonexistent/in/valid.shar b/test/ar/tc/extract-nonexistent/in/valid.shar new file mode 100644 index 000000000000..b5a569ea5c5e --- /dev/null +++ b/test/ar/tc/extract-nonexistent/in/valid.shar @@ -0,0 +1,55 @@ +#!/bin/sh +# This is a shell archive (produced by GNU sharutils 4.15.2). +# To extract the files from this archive, save it to some FILE, remove +# everything before the '#!/bin/sh' line above, then type 'sh FILE'. +# +lock_dir=_sh05539 +# Made on 2018-09-30 19:46 BST by <jkoshy@erebor>. +# Source directory was '/home/jkoshy/Work/Elftoolchain/trunk/test/ar/tc/extract-nonexistent/in'. +# +# Existing files will *not* be overwritten, unless '-c' is specified. +# +# This shar contains: +# length mode name +# ------ ---------- ------------------------------------------ +# 80 -rw-rw-r-- valid.a +# +if test "X$1" = "X-c" +then keep_file='' +else keep_file=true +fi +echo=echo +shar_tty= +shar_n= +shar_c='\n' +if test ! -d ${lock_dir} ; then : +else ${echo} "lock directory ${lock_dir} exists" + exit 1 +fi +if mkdir ${lock_dir} ; then : +else ${echo} "failed to create ${lock_dir} lock directory" + exit 1 +fi +# ============= valid.a ============== +if test -n "${keep_file}" && test -f 'valid.a' +then +${echo} "x - SKIPPING valid.a (file already exists)" + +else +${echo} "x - extracting valid.a (text)" + sed 's/^X//' << 'SHAR_EOF' > 'valid.a' && +X!<arch> +Xs1/ 0 0 0 644 12 ` +Xs1-contents +SHAR_EOF +: +if test $? -ne 0 +then ${echo} "restore of valid.a failed" +fi +fi +if rm -fr ${lock_dir} +then ${echo} "x - removed lock directory ${lock_dir}." +else ${echo} "x - failed to remove lock directory ${lock_dir}." + exit 1 +fi +exit 0 diff --git a/test/ar/tc/extract-nonexistent/out/valid.shar b/test/ar/tc/extract-nonexistent/out/valid.shar new file mode 100644 index 000000000000..b5a569ea5c5e --- /dev/null +++ b/test/ar/tc/extract-nonexistent/out/valid.shar @@ -0,0 +1,55 @@ +#!/bin/sh +# This is a shell archive (produced by GNU sharutils 4.15.2). +# To extract the files from this archive, save it to some FILE, remove +# everything before the '#!/bin/sh' line above, then type 'sh FILE'. +# +lock_dir=_sh05539 +# Made on 2018-09-30 19:46 BST by <jkoshy@erebor>. +# Source directory was '/home/jkoshy/Work/Elftoolchain/trunk/test/ar/tc/extract-nonexistent/in'. +# +# Existing files will *not* be overwritten, unless '-c' is specified. +# +# This shar contains: +# length mode name +# ------ ---------- ------------------------------------------ +# 80 -rw-rw-r-- valid.a +# +if test "X$1" = "X-c" +then keep_file='' +else keep_file=true +fi +echo=echo +shar_tty= +shar_n= +shar_c='\n' +if test ! -d ${lock_dir} ; then : +else ${echo} "lock directory ${lock_dir} exists" + exit 1 +fi +if mkdir ${lock_dir} ; then : +else ${echo} "failed to create ${lock_dir} lock directory" + exit 1 +fi +# ============= valid.a ============== +if test -n "${keep_file}" && test -f 'valid.a' +then +${echo} "x - SKIPPING valid.a (file already exists)" + +else +${echo} "x - extracting valid.a (text)" + sed 's/^X//' << 'SHAR_EOF' > 'valid.a' && +X!<arch> +Xs1/ 0 0 0 644 12 ` +Xs1-contents +SHAR_EOF +: +if test $? -ne 0 +then ${echo} "restore of valid.a failed" +fi +fi +if rm -fr ${lock_dir} +then ${echo} "x - removed lock directory ${lock_dir}." +else ${echo} "x - failed to remove lock directory ${lock_dir}." + exit 1 +fi +exit 0 diff --git a/test/ar/tc/extract-nonleaf/extract-nonleaf.err b/test/ar/tc/extract-nonleaf/extract-nonleaf.err new file mode 100644 index 000000000000..4d22e623f489 --- /dev/null +++ b/test/ar/tc/extract-nonleaf/extract-nonleaf.err @@ -0,0 +1 @@ +ar: warning: ignoring entry: a/s1 diff --git a/test/ar/tc/extract-nonleaf/extract-nonleaf.eval b/test/ar/tc/extract-nonleaf/extract-nonleaf.eval new file mode 100644 index 000000000000..573541ac9702 --- /dev/null +++ b/test/ar/tc/extract-nonleaf/extract-nonleaf.eval @@ -0,0 +1 @@ +0 diff --git a/test/ar/tc/extract-nonleaf/extract-nonleaf.out b/test/ar/tc/extract-nonleaf/extract-nonleaf.out new file mode 100644 index 000000000000..d4fb851ef13d --- /dev/null +++ b/test/ar/tc/extract-nonleaf/extract-nonleaf.out @@ -0,0 +1 @@ +x - s1 diff --git a/test/ar/tc/extract-nonleaf/extract-nonleaf.sh b/test/ar/tc/extract-nonleaf/extract-nonleaf.sh new file mode 100755 index 000000000000..671833867f35 --- /dev/null +++ b/test/ar/tc/extract-nonleaf/extract-nonleaf.sh @@ -0,0 +1,6 @@ +# $Id$ +inittest extract-nonleaf tc/extract-nonleaf +extshar ${TESTDIR} +extshar ${RLTDIR} +runcmd "${AR} xv invalid.a" work true +rundiff true diff --git a/test/ar/tc/extract-nonleaf/in/invalid.shar b/test/ar/tc/extract-nonleaf/in/invalid.shar new file mode 100644 index 000000000000..7e718a8192fc --- /dev/null +++ b/test/ar/tc/extract-nonleaf/in/invalid.shar @@ -0,0 +1,54 @@ +#!/bin/sh +# This is invalid, a shell archive (produced by GNU sharutils 4.15.2). +# To extract the files from this archive, save it to some FILE, remove +# everything before the '#!/bin/sh' line above, then type 'sh FILE'. +# +lock_dir=_sh29263 +# Existing files will *not* be overwritten, unless '-c' is specified. +# +# This shar contains: +# length mode name +# ------ ---------- ------------------------------------------ +# 152 -rw-rw-r-- invalid.a +# +if test "X$1" = "X-c" +then keep_file='' +else keep_file=true +fi +echo=echo +shar_tty= +shar_n= +shar_c='\n' +if test ! -d ${lock_dir} ; then : +else ${echo} "lock directory ${lock_dir} exists" + exit 1 +fi +if mkdir ${lock_dir} ; then : +else ${echo} "failed to create ${lock_dir} lock directory" + exit 1 +fi +# ============= invalid.a ============== +if test -n "${keep_file}" && test -f 'invalid.a' +then +${echo} "x - SKIPPING invalid.a (file already exists)" + +else +${echo} "x - extracting invalid.a (text)" + sed 's/^X//' << 'SHAR_EOF' > 'invalid.a' && +X!<arch> +Xa/s1/ 0 0 0 644 12 ` +Xs1-contents +Xs1/ 0 0 0 644 12 ` +Xs1-contents +SHAR_EOF +: +if test $? -ne 0 +then ${echo} "restore of invalid.a failed" +fi +fi +if rm -fr ${lock_dir} +then ${echo} "x - removed lock directory ${lock_dir}." +else ${echo} "x - failed to remove lock directory ${lock_dir}." + exit 1 +fi +exit 0 diff --git a/test/ar/tc/extract-nonleaf/out/invalid.shar b/test/ar/tc/extract-nonleaf/out/invalid.shar new file mode 100644 index 000000000000..7e718a8192fc --- /dev/null +++ b/test/ar/tc/extract-nonleaf/out/invalid.shar @@ -0,0 +1,54 @@ +#!/bin/sh +# This is invalid, a shell archive (produced by GNU sharutils 4.15.2). +# To extract the files from this archive, save it to some FILE, remove +# everything before the '#!/bin/sh' line above, then type 'sh FILE'. +# +lock_dir=_sh29263 +# Existing files will *not* be overwritten, unless '-c' is specified. +# +# This shar contains: +# length mode name +# ------ ---------- ------------------------------------------ +# 152 -rw-rw-r-- invalid.a +# +if test "X$1" = "X-c" +then keep_file='' +else keep_file=true +fi +echo=echo +shar_tty= +shar_n= +shar_c='\n' +if test ! -d ${lock_dir} ; then : +else ${echo} "lock directory ${lock_dir} exists" + exit 1 +fi +if mkdir ${lock_dir} ; then : +else ${echo} "failed to create ${lock_dir} lock directory" + exit 1 +fi +# ============= invalid.a ============== +if test -n "${keep_file}" && test -f 'invalid.a' +then +${echo} "x - SKIPPING invalid.a (file already exists)" + +else +${echo} "x - extracting invalid.a (text)" + sed 's/^X//' << 'SHAR_EOF' > 'invalid.a' && +X!<arch> +Xa/s1/ 0 0 0 644 12 ` +Xs1-contents +Xs1/ 0 0 0 644 12 ` +Xs1-contents +SHAR_EOF +: +if test $? -ne 0 +then ${echo} "restore of invalid.a failed" +fi +fi +if rm -fr ${lock_dir} +then ${echo} "x - removed lock directory ${lock_dir}." +else ${echo} "x - failed to remove lock directory ${lock_dir}." + exit 1 +fi +exit 0 diff --git a/test/ar/tc/extract-nonleaf/out/s1 b/test/ar/tc/extract-nonleaf/out/s1 new file mode 100644 index 000000000000..c77eb94df2df --- /dev/null +++ b/test/ar/tc/extract-nonleaf/out/s1 @@ -0,0 +1 @@ +s1-contents diff --git a/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.err b/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.err new file mode 100644 index 000000000000..7e22663fb0c7 --- /dev/null +++ b/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.err @@ -0,0 +1 @@ +ranlib: warning: nonexistent.a: no such file diff --git a/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.eval b/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.eval new file mode 100644 index 000000000000..d00491fd7e5b --- /dev/null +++ b/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.eval @@ -0,0 +1 @@ +1 diff --git a/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.out b/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.out new file mode 100644 index 000000000000..e69de29bb2d1 --- /dev/null +++ b/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.out diff --git a/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.sh b/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.sh new file mode 100755 index 000000000000..3a35ce3576d6 --- /dev/null +++ b/test/ar/tc/ranlib-missing-archive/ranlib-missing-archive.sh @@ -0,0 +1,7 @@ +# $Id$ +# +# Verify that 'ranlib' exits with an error if asked to operate on a +# non-existent archive. +inittest ranlib-missing-archive tc/ranlib-missing-archive +runcmd "${RANLIB} nonexistent.a" work true +rundiff true diff --git a/test/libelf/tset/elf_getarhdr/Makefile b/test/libelf/tset/elf_getarhdr/Makefile index 9a8245f6f53e..d4bfa2914e27 100644 --- a/test/libelf/tset/elf_getarhdr/Makefile +++ b/test/libelf/tset/elf_getarhdr/Makefile @@ -1,4 +1,4 @@ -# $Id: Makefile 1329 2010-12-26 19:23:13Z jkoshy $ +# $Id: Makefile 3623 2018-09-29 11:19:54Z jkoshy $ TOP= ../../../.. @@ -19,7 +19,7 @@ a.ar: a1.o a2.o .SILENT echo 'This is s1.' > s1 echo 's2.' > ${TS_LONGNAME} echo 's-3.' > "s 3" - ${AR} crv ${.TARGET} s1 a1.o ${TS_LONGNAME} a2.o "s 3" > /dev/null + ${AR} crvU ${.TARGET} s1 a1.o ${TS_LONGNAME} a2.o "s 3" > /dev/null a-bsd.ar: a.ar .SILENT rm -f ${.TARGET} diff --git a/test/libelf/tset/elf_getarhdr/getarhdr.m4 b/test/libelf/tset/elf_getarhdr/getarhdr.m4 index 98325eb212e2..a6af5313a4de 100644 --- a/test/libelf/tset/elf_getarhdr/getarhdr.m4 +++ b/test/libelf/tset/elf_getarhdr/getarhdr.m4 @@ -23,7 +23,7 @@ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * - * $Id: getarhdr.m4 1388 2011-01-26 02:29:24Z jkoshy $ + * $Id: getarhdr.m4 3622 2018-09-29 07:44:28Z jkoshy $ */ #include <sys/types.h> @@ -297,7 +297,7 @@ tcArMember$1(void) } if (arh->ar_mode != sb.st_mode) { - TP_FAIL("\%s\" mode: 0%x != 0%o.", *fn, + TP_FAIL("\"%s\" mode: 0%o != 0%o.", *fn, arh->ar_mode, sb.st_mode); goto done; } diff --git a/test/libtest/Makefile b/test/libtest/Makefile new file mode 100644 index 000000000000..1dc489b9db8a --- /dev/null +++ b/test/libtest/Makefile @@ -0,0 +1,17 @@ +# $Id$ +# +# The test(3) API. + +TOP= ../.. + +SUBDIR+= bin +SUBDIR+= lib +SUBDIR+= driver +SUBDIR+= examples + +.if !make(install) +.include "$(TOP)/mk/elftoolchain.subdir.mk" +.else +install: .SILENT .PHONY + echo Nothing to install. +.endif diff --git a/test/libtest/README.rst b/test/libtest/README.rst new file mode 100644 index 000000000000..3f29c85f8a93 --- /dev/null +++ b/test/libtest/README.rst @@ -0,0 +1,116 @@ +===================================== +test(3) - a library for writing tests +===================================== + +The ``test(3)`` API and its related scaffolding generator +(`make-test-scaffolding(1) <mts_>`_) work together to reduce the +boilerplate needed for tests. + +.. _mts: bin/make-test-scaffolding + +Quick Start +=========== + +The following source code defines a test suite that contains a single +test: + +.. code:: c + + /* File: test.c */ + #include "test.h" + + enum test_result + tf_goodbye_world(testcase_state tcs) + { + return (TEST_PASS); + } + +By convention, test functions are named using a ``tf_`` prefix. + +Given an object file compiled from this source, the +`make-test-scaffolding(1) <mts_>`_ utility would generate scaffolding +describing a single invocable test named "``goodbye_world``". + +Test Cases +---------- + +Test functions that are related to each other can be grouped into test +cases. The following code snippet defines a test suite with two test +functions contained in a test case named "``helloworld``": + +.. code:: c + + /* File: test.c */ + #include "test.h" + + TESTCASE_DESCRIPTION(helloworld) = + "A description of the helloworld test case."; + + enum test_result + tf_helloworld_hello(testcase_state tcs) + { + return (TEST_PASS); + } + + enum test_result + tf_helloworld_goodbye(testcase_state tcs) + { + return (TEST_FAIL); + } + +Test cases can define their own set up and tear down functions: + +.. code:: c + + /* File: test.c continued. */ + struct helloworld_test { .. state used by the helloworld tests .. }; + + enum testcase_status + tc_setup_helloworld(testcase_state *tcs) + { + *tcs = ..allocate a struct helloworld_test.. ; + return (TESTCASE_OK); + } + + enum testcase_status + tc_teardown_helloworld(testcase_state tcs) + { + .. deallocate test case state.. + return (TESTCASE_OK); + } + +The set up function for a test case will be invoked prior to any of +the functions that are part of the test case. The set up function can +allocate test-specific state, which is then passed to each test function +for its use. + +The tear down function for a test case will be invoked after the test +functions in the test case are invoked. This function is responsible for +deallocating the resources allocated by its corresponding set up function. + +Building Tests +-------------- + +Within the `Elftoolchain Project`_'s sources, the ``elftoolchain.test.mk`` +rule set handles the process of invoking the `make-test-scaffolding(1) +<mts_>`_ utility and building an test executable. + +.. code:: make + + # Example Makefile. + + TOP= ..path to the top of the elftoolchain source tree.. + + TEST_SRCS= test.c + + .include "$(TOP)/mk/elftoolchain.test.mk" + + +.. _Elftoolchain Project: http://elftoolchain.sourceforge.net/ + +Further Reading +=============== + +- The `test(3) <lib/test.3>`_ manual page. +- The `make-test-scaffolding(1) <bin/make-test-scaffolding.1>`_ manual page. +- `Example code <examples/>`_. diff --git a/test/libtest/bin/Makefile b/test/libtest/bin/Makefile new file mode 100644 index 000000000000..a6a3b8d6ae43 --- /dev/null +++ b/test/libtest/bin/Makefile @@ -0,0 +1,9 @@ +# $Id$ + +TOP= ../../.. + +SCRIPTS= make-test-scaffolding + +MAN1= make-test-scaffolding.1 + +.include "${TOP}/mk/elftoolchain.prog.mk" diff --git a/test/libtest/bin/make-test-scaffolding b/test/libtest/bin/make-test-scaffolding new file mode 100755 index 000000000000..c0966d34527b --- /dev/null +++ b/test/libtest/bin/make-test-scaffolding @@ -0,0 +1,213 @@ +#!/bin/sh +# +# Copyright (c) 2018, Joseph Koshy. All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions +# are met: +# 1. Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer +# in this position and unchanged. +# 2. Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR +# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +# IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, +# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +# +# $Id$ + +# Given a list of objects that use the test(3) API, this script will +# generate test case and test function descriptors based on the symbols +# contained in those objects. + +usage() +{ + echo Usage: `basename $0`: "[options] objects..." + echo + echo "Generate test(3) scaffolding from objects." + echo "Options include:" + echo + echo "\t-o out\t\tcreate output file \"out\" [default \"tc.c\"]." + echo +} + +output_file="tc.c" +prefix_tc_descr='tc_description_' +prefix_tc_setup='tc_setup_' +prefix_tc_tags='tc_tags_' +prefix_tc_teardown='tc_teardown_' +prefix_tf='tf_' +prefix_tf_descr='tf_description_' +prefix_tf_tags='tf_tags_' + + +args=`getopt o: $*` +if [ ${?} -ne 0 ]; then + usage + exit 2 +fi + +set -- ${args} + +for i +do + case "${i}" in + -o ) + output_file="${2}" + shift; shift;; + -- ) + shift; break;; + esac +done + +if [ ${#} -eq 0 ]; then + usage + exit 2 +fi + +exec > ${output_file} +cat <<EOF +/* GENERATED FROM: ${@} */ +#include <stddef.h> +#include "test.h" +#include "test_runner.h" +EOF + +if ! nm ${*} | sort -k 3 | \ + awk -v prefix_tc_descr=${prefix_tc_descr} \ + -v prefix_tc_setup=${prefix_tc_setup} \ + -v prefix_tc_tags=${prefix_tc_tags} \ + -v prefix_tc_teardown=${prefix_tc_teardown} \ + -v prefix_tf=${prefix_tf} \ + -v prefix_tf_descr=${prefix_tf_descr} \ + -v prefix_tf_tags=${prefix_tf_tags} ' + function suffix(value, prefix) { + return substr(value, length(prefix) + 1); + } + function matched_test_case(tf_name, tc_matched) { + tc_matched = "" + for (tc_name in test_cases) { + if (tf_name ~ tc_name "_" && + length(tc_name) > length(tc_matched)) { + tc_matched = tc_name + } + } + if (tc_matched != "") + return tc_matched + return DEFAULT + } + function print_test_case_record(tc_name) { + printf("\t{\n") + printf("\t\t.tc_name = \"%s\",\n", tc_name) + printf("\t\t.tc_description = %s,\n", test_case_descriptions[tc_name]) + printf("\t\t.tc_tags = %s,\n", test_case_tags[tc_name]) + printf("\t\t.tc_tests = test_functions_%s\n", tc_name) + printf("\t},\n") + } + function delete_test_functions(tc_name) { + for (tf_name in test_functions) { + if (matched_test_case(tf_name) == tc_name) + delete test_functions[tf_name] + } + } + function print_test_functions_record(tc_name) { + printf("struct test_descriptor test_functions_%s[] = {\n", tc_name) + for (tf_name in test_functions) { + if (tc_name != matched_test_case(tf_name)) + continue + printf("\t{\n") + printf("\t\t.t_name = \"%s\",\n", tf_name) + printf("\t\t.t_description = %s,\n", + test_function_descriptions[tf_name]) + printf("\t\t.t_func = %s,\n", prefix_tf tf_name) + printf("\t\t.t_tags = %s\n", test_function_tags[tf_name]) + printf("\t},\n") + } + printf("};\n") + } + function is_non_empty(array, i) { + for (i in array) return 1 + return 0 + } + BEGIN { + DEFAULT = "default" + test_case_descriptions[DEFAULT] = "NULL" + test_case_tags[DEFAULT] = "NULL" + } + ($2 == "R" || $2 == "D") && $3 ~ "^" prefix_tc_descr { + printf("extern testcase_description %s;\n", $3) + tc_name = suffix($3, prefix_tc_descr) + test_cases[tc_name] = 1 + test_case_descriptions[tc_name] = $3 + } + $2 == "T" && $3 ~ "^" prefix_tc_setup { + tc_name = suffix($3, prefix_tc_setup) + test_cases[tc_name] = 1 + test_case_setup[tc_name] = $3 + } + ($2 == "R" || $2 == "D") && $3 ~ "^" prefix_tc_tags { + printf("extern testcase_tags %s;\n", $3) + tc_name = suffix($3, prefix_tc_tags) + test_cases[tc_name] = 1 + test_case_tags[tc_name] = $3 + } + $2 == "T" && $3 ~ "^" prefix_tc_teardown { + tc_name = suffix($3, prefix_tc_teardown) + test_cases[tc_name] = 1 + test_case_teardown[tc_name] = $3 + } + ($2 == "R" || $2 == "D") && $3 ~ "^" prefix_tf_descr { + printf("extern test_description %s;\n", $3) + tf_name = suffix($3, prefix_tf_descr) + test_function_descriptions[tf_name] = $3 + } + ($2 == "R" || $2 == "D") && $3 ~ "^" prefix_tf_tags { + printf("extern test_tags %s;\n", $3) + tf_name = suffix($3, prefix_tf_tags) + test_function_tags[tf_name] = $3 + } + $2 == "T" && $3 ~ "^" prefix_tf { + printf("test_function %s;\n", $3) + tf_name = suffix($3, prefix_tf) + test_functions[tf_name] = 1 + } + END { + for (tf_name in test_functions) { + if (test_function_descriptions[tf_name] == "") + test_function_descriptions[tf_name] = "NULL" + if (test_function_tags[tf_name] == "") + test_function_tags[tf_name] = "NULL" + } + for (tc_name in test_cases) { + if (test_case_descriptions[tc_name] == "") + test_case_descriptions[tc_name] = "NULL" + if (test_case_tags[tc_name] == "") + test_case_tags[tc_name] = "NULL" + } + for (tc_name in test_cases) { + print_test_functions_record(tc_name) + delete_test_functions(tc_name) + } + needs_default = is_non_empty(test_functions) + if (needs_default) + print_test_functions_record(DEFAULT) + printf("struct test_case_descriptor test_cases[] = {\n") + for (tc_name in test_cases) + print_test_case_record(tc_name) + if (needs_default) + print_test_case_record(DEFAULT) + printf("};\n") + }'; then + # Cleanup in case of an error. + rm ${output_file} + exit 1 +fi diff --git a/test/libtest/bin/make-test-scaffolding.1 b/test/libtest/bin/make-test-scaffolding.1 new file mode 100644 index 000000000000..2d120e1bb5b2 --- /dev/null +++ b/test/libtest/bin/make-test-scaffolding.1 @@ -0,0 +1,111 @@ +.\" Copyright (c) 2018, Joseph Koshy. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" $Id$ +.\" +.Dd December 25, 2018 +.Dt TEST 1 +.Os +.Sh NAME +.Nm make-test-scaffolding +.Nd generate scaffolding for tests +.Sh SYNOPSIS +.Nm +.Op Fl o Ar output_file +.Ar test_object ... +.Sh DESCRIPTION +The +.Nm +utility takes as input object files containing symbols following +its naming convention and generates the scaffolding needed to assemble +a test executable. +.Pp +The +.Nm +utility expects symbols to be named using the following conventions: +.Bl -bullet +.It +Test case descriptions are named using the +.Li tc_description_ +prefix, followed by the name of the test case. +For example, the symbol +.Sy tc_description_helloworld +would name the description of a test case named +.Dq helloworld . +.It +Test set up functions are named using a +.Li tc_setup_ +prefix, followed by the name of a test case. +For example, the function +.Fn tc_setup_helloworld +would name the set up function for a test case named +.Dq helloworld . +.It +Test tear down functions are named using a +.Li tc_teardown_ +prefix, followed by the name of a test case. +For example, the function +.Fn tc_teardown_helloworld +would name the tear down function for a test case named +.Dq helloworld . +.It +Tags for test cases are named using symbols with a +.Li tc_tags_ +prefix, followed by the name of their test case. +.It +Test functions are named using a +.Li tf_ +prefix, followed by the name for their containing test case and a +disambiguating suffix. +For example, the two test functions +.Fn tf_helloworld_sayhello +and +.Fn tf_helloworld_saygoodbye +would be associated with the test case named +.Dq helloworld . +.Pp +A test function that is not associated with a test case will be +added to a special test case named +.Dq default . +.It +Tags for test functions are named using symbols with a +.Li tf_tags_ +prefix, followed by the name of their test case. +.El +.Pp +The +.Nm +utility will generate a C source file containing the appropriate +.Vt "struct test_descriptor" +and +.Vt "struct test_case_descriptor" +structures for use by a test driver. +.Sh SEE ALSO +.Xr test 3 , +.Xr test_runner 3 +.Sh AUTHORS +The +.Nm +utility was written by +.An Joseph Koshy Aq Mt jkoshy@users.sourceforge.net . diff --git a/test/libtest/driver/Makefile b/test/libtest/driver/Makefile new file mode 100644 index 000000000000..d149fee159d4 --- /dev/null +++ b/test/libtest/driver/Makefile @@ -0,0 +1,14 @@ +# $Id$ +# +# A command-line driver for libtest based tests. + +TOP= ../../.. + +CFLAGS+= -I${TOP}/test/libtest/lib + +LIB= test_main +SRCS= test_main.c + +WARNS?= 6 + +.include "$(TOP)/mk/elftoolchain.lib.mk" diff --git a/test/libtest/driver/test_main.c b/test/libtest/driver/test_main.c new file mode 100644 index 000000000000..90e46d9a5fe2 --- /dev/null +++ b/test/libtest/driver/test_main.c @@ -0,0 +1,49 @@ +/*- + * Copyright (c) 2018, Joseph Koshy + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer + * in this position and unchanged. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR + * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + * IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +/* + * This file defines a "main" that parses command-line arguments and invokes + * the selected test cases. + */ +#include <sys/param.h> + +#include <assert.h> +#include <stdlib.h> + +#include "_elftc.h" +#include "test.h" +#include "test_runner.h" + +ELFTC_VCSID("$Id$"); + +int +main(int argc, char **argv) +{ + (void) test_cases; + (void) argc; + (void) argv; + exit(0); +} diff --git a/test/libtest/examples/Makefile b/test/libtest/examples/Makefile new file mode 100644 index 000000000000..9cc82d3dd7a4 --- /dev/null +++ b/test/libtest/examples/Makefile @@ -0,0 +1,14 @@ +# $Id$ +# +# Examples of tests built using test(3). + +TOP= ../../.. + +NOMAN= true + +CFLAGS+= -I../lib -Wall -pedantic + +TEST_SRCS= minimal_example.c \ + simple_example.c + +.include "$(TOP)/mk/elftoolchain.test.mk" diff --git a/test/libtest/examples/minimal_example.c b/test/libtest/examples/minimal_example.c new file mode 100644 index 000000000000..4ad08b4bce06 --- /dev/null +++ b/test/libtest/examples/minimal_example.c @@ -0,0 +1,50 @@ +/*- + * Copyright (c) 2018, Joseph Koshy + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer + * in this position and unchanged. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR + * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + * IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +/* $Id$ */ + +/* + * This C source defines a single test function named 'tf_helloworld', + * that is not part of a test case, and lacking a description or tags. + * + * Since no test cases are specified in this file, the test function + * would be assigned to the default test case (named 'default'). + * + * Given the object file created from this source, the + * 'make-test-scaffolding' utility will prepare the scaffolding + * needed to build an executable containing the test function. + */ + +#include "test.h" + +/* + * Function names prefixed with 'tf_' name test functions. + */ +enum test_result +tf_helloworld(testcase_state state) +{ + return (TEST_PASS); +} diff --git a/test/libtest/examples/simple_example.c b/test/libtest/examples/simple_example.c new file mode 100644 index 000000000000..6a4f6697eb51 --- /dev/null +++ b/test/libtest/examples/simple_example.c @@ -0,0 +1,145 @@ +/*- + * Copyright (c) 2018, Joseph Koshy + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer + * in this position and unchanged. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR + * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + * IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +/* $Id$ */ + +#include <stddef.h> + +#include "test.h" + +/* + * This source defines a single test case named 'helloworld' containing a + * single test function named 'sayhello' contained in that test case. At + * test execution time the test case would be selectable using the tags + * "tag1" or "tag2", or by its name 'helloworld'. The test function can + * be selected using tags "tag3" or "tag4", or by its name + * 'helloworld_sayhello'. + * + * Given the object code generated from this file, the + * 'make-test-scaffolding' utility will prepare the scaffolding needed + * to create a executable that can be used to execute these tests. + * + * Specifically the 'make-test-scaffolding' utilit will generate test and + * test case descriptors equivalent to: + * + * struct test_descriptor test_functions_helloworld[] = { + * { + * .t_description = tf_description_helloworld_sayhello, + * .t_tags = tf_tags_helloworld_sayhello, + * .t_func = tf_helloworld_sayhello + * } + * }; + * + * struct test_case_descriptor test_cases[] = { + * { + * .tc_description = tc_description_helloworld, + * .tc_tags = tc_tags_helloworld, + * .tc_tests = test_functions_helloworld + * } + * }; + */ + +/* + * A symbol name prefixed with 'tc_description_' contains a + * test case description. The TESTCASE_DESCRIPTION macro offers + * a convenient way to define such symbols. In the case of the + * symbol below, the test case named is 'helloworld'. + */ +TESTCASE_DESCRIPTION(helloworld) = "A description for a test case."; + +/* + * Function names prefixed with 'tc_setup_' are assumed to be test + * case set up functions. + */ +enum testcase_status +tc_setup_helloworld(testcase_state *state) +{ + return (TESTCASE_OK); +} + +/* + * Function names prefixed with 'tc_teardown_' are assumed to be test + * case tear down functions. + */ +enum testcase_status +tc_teardown_helloworld(testcase_state state) +{ + return (TESTCASE_OK); +} + +/* + * Names prefixed with 'tc_tags_' denote the tags associated with test + * cases. The TESTCASE_TAGS macro offers a convenient way to define such + * symbols. + * + * In the example below, all test functions belonging to the test case + * named 'helloworld' would be associated with tags "tag1" and "tag2". + * + * Tags lists are terminated by a NULL entry. + */ +TESTCASE_TAGS(helloworld) = { + "tag1", + "tag2", + NULL +}; + +/* + * Function names prefixed with 'tf_' name test functions. + */ +enum test_result +tf_helloworld_sayhello(testcase_state state) +{ + return (TEST_PASS); +} + +/* + * Names prefixed by 'tf_description_' contain descriptions of test + * functions (e.g., 'tf_description_helloworld_sayhello' contains the + * description for test function 'tf_helloworld_sayhello'). + * + * The TEST_DESCRIPTION macro offers a convenient way to define such + * symbols. + */ +TEST_DESCRIPTION(helloworld_sayhello) = + "A description for the test function 'tf_helloworld_sayhello'."; + +/* + * Names prefixed by 'tf_tags_' contain the tags associated with + * test functions. + * + * In the example below, the tags 'tag3' and 'tag4' are associated + * with the test function 'tf_helloworld_sayhello'. + * + * Alternately, the TEST_TAGS() macro offers a convenient way to + * define such symbols. + * + * Tags lists are terminated by a NULL entry. + */ +test_tags tf_tags_helloworld_sayhello = { + "tag3", + "tag4", + NULL +}; diff --git a/test/libtest/lib/Makefile b/test/libtest/lib/Makefile new file mode 100644 index 000000000000..7359ddd76a6c --- /dev/null +++ b/test/libtest/lib/Makefile @@ -0,0 +1,16 @@ +# $Id$ + +TOP= ../../.. + +LIB= test + +SRCS= test.c \ + test_runner.c + +INCS= test.h + +WARNS?= 6 + +MAN= test.3 + +.include "${TOP}/mk/elftoolchain.lib.mk" diff --git a/test/libtest/lib/test.3 b/test/libtest/lib/test.3 new file mode 100644 index 000000000000..c7045b4039c4 --- /dev/null +++ b/test/libtest/lib/test.3 @@ -0,0 +1,110 @@ +.\" Copyright (c) 2018, Joseph Koshy. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" This software is provided by Joseph Koshy ``as is'' and +.\" any express or implied warranties, including, but not limited to, the +.\" implied warranties of merchantability and fitness for a particular purpose +.\" are disclaimed. in no event shall Joseph Koshy be liable +.\" for any direct, indirect, incidental, special, exemplary, or consequential +.\" damages (including, but not limited to, procurement of substitute goods +.\" or services; loss of use, data, or profits; or business interruption) +.\" however caused and on any theory of liability, whether in contract, strict +.\" liability, or tort (including negligence or otherwise) arising in any way +.\" out of the use of this software, even if advised of the possibility of +.\" such damage. +.\" +.\" $Id$ +.\" +.Dd December 25, 2018 +.Dt TEST 3 +.Os +.Sh NAME +.Nm test +.Nd API for writing tests +.Sh LIBRARY +.Lb libtest +.Sh SYNOPSIS +.In test.h +.Ft enum testcase_status +.Fn testcase_setup "testcase_state *state" +.Ft enum testcase_status +.Fn testcase_teardown "testcase_state state" +.Ft enum test_result +.Fn test_function "testcase_state state" +.Vt "const char" +.Va test_description [] ; +.Vt "const char *" +.Va test_tags [] ; +.Vt "const char" +.Va testcase_description [] ; +.Vt "const char *" +.Va testcase_tags [] ; +.Sh DESCRIPTION +The +.Lb libtest +implements an API for writing tests. +.Ss Concepts +Tests are implemented using test functions, where each test function +verifies a specific assertion about the system being tested. +Test functions are associated with the following: +.Bl -bullet -compact +.It +An optional human-readable test description. +.It +An optional set of tags. +Tags are used to select or deselect specific tests in a run. +.El +.Pp +Test functions are further grouped into test cases, where a test case +contains a logical group of assertions about the system under test. +Test cases are associated the following: +.Bl -bullet -compact +.It +An optional human-readable test case description. +.It +An optional test case set up function. +If specified, this set up function would be invoked prior to any test +function contained in the test case. +The set up function can allocate and initialize test-specific state, to be +passed to test functions. +If no set up function is specified for the test case, a default no-op +function will be supplied. +.It +An optional test case tear down function. +The tear down function will be invoked after all test functions have been +invoked. +It would be responsible for deallocating any resources that its corresponding +set up function had allocated. +If no tear down function is specified for a test case, a default no-op +function will be supplied. +.It +An optional set of tags for the test case. +These tags are used to select or delect specific test cases in a given test +run. +.El +.Pp +One or more test cases would be linked with a test driver to form a +test executable. +The default test driver supplied allows the test cases and specific tests +within the executable to be specified on the command line. +.Ss Scaffolding Generation +The +.Xr make-test-scaffolding 1 +script will generate the scaffolding needed to produce a test executable +from object files containing symbols following its naming conventions. +.Sh SEE ALSO +.Xr make-test-scaffolding 1 +.Sh AUTHORS +The +.Lb libtest +was written by +.An Joseph Koshy Aq Mt jkoshy@users.sourceforge.net . diff --git a/test/libtest/lib/test.c b/test/libtest/lib/test.c new file mode 100644 index 000000000000..04999c1966ac --- /dev/null +++ b/test/libtest/lib/test.c @@ -0,0 +1,29 @@ +/*- + * Copyright (c) 2018, Joseph Koshy + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer + * in this position and unchanged. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR + * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + * IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#include "test.h" + +/* To be implemented. */ diff --git a/test/libtest/lib/test.h b/test/libtest/lib/test.h new file mode 100644 index 000000000000..86f91463993b --- /dev/null +++ b/test/libtest/lib/test.h @@ -0,0 +1,159 @@ +/*- + * Copyright (c) 2018, Joseph Koshy + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer + * in this position and unchanged. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR + * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + * IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef _LIBTEST_TEST_H_ +#define _LIBTEST_TEST_H_ + +/* + * The return values from test functions. + * + * - TEST_PASS : The assertion(s) in the test function passed. + * - TEST_FAIL : At least one assertion in the test function failed. + * - TEST_UNRESOLVED : The assertions in the test function could not be + * checked for some reason. + */ +enum test_result { + TEST_PASS = 0, + TEST_FAIL = 1, + TEST_UNRESOLVED = 2 +}; + +/* + * The return values from test case set up and tear down functions. + * + * - TESTCASE_OK : The set up or tear down function was successful. + * - TESTCASE_ERROR : Set up or tear down actions could not be completed. + * + * If a test case set up function returns TESTCASE_ERROR then: + * - The test functions in the test case will not be run. + * - The test case's tear down function will not be invoked. + * - The test run as a whole will be treated as being in error. + * + * If a test case tear down function returns a TESTCASE_ERROR, then + * the test run as a whole be treated as being in error. + */ +enum testcase_status { + TESTCASE_OK = 0, + TESTCASE_ERROR = 1 +}; + +/* + * A testcase_state denotes resources that are shared by the test + * functions that are part of a test case. A testcase_state is allocated + * by the set up function for a test case. Conversely the test case's + * tear down function is responsible for deallocating the resources + * allocated by the set up function. + * + * The test(3) framework treats a testcase_state as an opaque value. + */ +typedef void *testcase_state; + +/* + * Test case and test function descriptions, and convenience macros + * to define these. + */ +typedef const char testcase_description[]; + +#if !defined(TEST_DESCRIPTION) +#define TEST_DESCRIPTION(NAME) test_description tf_description_##NAME +#endif + +typedef const char test_description[]; + +#if !defined(TESTCASE_DESCRIPTION) +#define TESTCASE_DESCRIPTION(NAME) testcase_description tc_description_##NAME +#endif + +/* + * Test case and test function tags, and convenience macros to define + * these. + */ +typedef const char *testcase_tags[]; + +#if !defined(TESTCASE_TAGS) +#define TESTCASE_TAGS(NAME) testcase_tags tc_tags_##NAME +#endif + +typedef const char *test_tags[]; +#if !defined(TEST_TAGS) +#define TEST_TAGS(NAME) test_tags tf_tags_##NAME +#endif + +/* + * A test case set up function. + * + * If defined for a test case, this function will be called prior to + * the execution of an of the test functions within the test cae. Test + * case execution will be aborted if the function returns any value other + * than TESTCASE_OK. + * + * The function can set '*state' to a memory area holding test state to be + * passed to test functions. + * + * If the test case does not define a set up function, then a default + * no-op set up function will be used. + */ +typedef enum testcase_status (test_case_setup_function) + (testcase_state *state); + +/* + * A test function. + * + * This function will be invoked with the state that had been set by the + * test case set up function. The function returns TEST_PASS to report that + * its test succeeded or TEST_FAIL otherwise. In the event the test could + * not be executed, it can return TEST_UNRESOLVED. + */ +typedef enum test_result (test_function)(testcase_state state); + +/* + * A test case tear down function. + * + * If defined for a test case, this function will be called after the + * execution of the test functions in the test case. It is passed the + * state that had been allocated by the test case set up function, and is + * responsible for deallocating the resources that the set up function + * had allocated. + */ +typedef enum testcase_status (test_case_teardown_function)(testcase_state state); + +#ifdef __cplusplus +extern "C" { +#endif + +/* + * Write a progress report to the test log. + * + * This function takes a printf(3)-like format string and associated + * arguments. + */ +int test_report_progress(const char *format, ...); + +#ifdef __cplusplus +} +#endif + +#endif /* _LIBTEST_TEST_H_ */ diff --git a/test/libtest/lib/test_runner.c b/test/libtest/lib/test_runner.c new file mode 100644 index 000000000000..1366ff4a538e --- /dev/null +++ b/test/libtest/lib/test_runner.c @@ -0,0 +1,31 @@ +/*- + * Copyright (c) 2018, Joseph Koshy + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer + * in this position and unchanged. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR + * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + * IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +/* + * An implementation of a test driver for test(3) tests. + */ + +/* To be implemented. */ diff --git a/test/libtest/lib/test_runner.h b/test/libtest/lib/test_runner.h new file mode 100644 index 000000000000..cbf00f29b44d --- /dev/null +++ b/test/libtest/lib/test_runner.h @@ -0,0 +1,118 @@ +/*- + * Copyright (c) 2018, Joseph Koshy + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer + * in this position and unchanged. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR + * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. + * IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, + * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT + * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef _LIBTEST_TEST_RUNNER_H_ +#define _LIBTEST_TEST_RUNNER_H_ + +#include "test.h" + +/* + * These data structures and functions are used by test driver that + * execute tests. + */ + +/* + * The completion status for a test run: + * + * - TESTRUN_PASS : All test cases were successfully invoked and all test + * purposes in the test cases passed. + * - TESTRUN_FAIL : All test cases were successfully invoked but at least + * one test purpose reported a test failure. + * - TESTRUN_ERROR : At least one test case reported an error during its + * set up or tear down phase. + */ +enum testrun_status { + TESTRUN_PASS = 0, + TESTRUN_FAIL = 1, + TESTRUN_ERROR = 2 +}; + +/* + * A single test function, with its associated tags and description. + */ +struct test_descriptor { + const char *t_name; /* Test name. */ + const char *t_description; /* Test description. */ + const char **t_tags; /* Tags associated with the test. */ + test_function *t_func; /* The function to invoke. */ +}; + +/* + * A test case. + */ +struct test_case_descriptor { + const char *tc_name; /* Test case name. */ + const char *tc_description; /* Test case description. */ + const char **tc_tags; /* Any associated tags. */ + struct test_descriptor *tc_tests; /* The tests in this test case. */ +}; + +/* + * All test cases. + */ +extern struct test_case_descriptor test_cases[]; + +enum testrun_style { + /* Libtest semantics. */ + TESTRUN_STYLE_LIBTEST, + + /* + * Be compatible with the Test Anything Protocol + * (http://testanything.org/). + */ + TESTRUN_STYLE_TAP, + + /* Be compatible with NetBSD ATF(9). */ + TESTRUN_STYLE_ATF +}; + +/* + * Parameters for the run. + */ +struct test_run { + /* + * An optional name assigned by the user for this test run. + * + * This name is reported in test logs and is not interpreted + * by the test harness. + */ + char *testrun_name; + + /* The source directory for the run. */ + char *testrun_source_directory; + + /* The directory in which the test is executing. */ + char *testrun_test_directory; +}; + +#ifdef __cplusplus +extern "C" { +#endif +#ifdef __cplusplus +} +#endif + +#endif /* _LIBTEST_TEST_RUNNER_H_ */ |