From 82c6a0d5cc52ec43523cf92cde5b8f83a24a9dba Mon Sep 17 00:00:00 2001 From: kaiw Date: Wed, 21 Jul 2010 12:14:50 +0000 Subject: * Deprecate `elf_getshnum()`, `elf_getphnum()` and `elf_getshstrndx()` in favour of `elf_getshdrnum()`, `elf_getphdrnum()` and `elf_getshdrstrndx()` respectively. * Add new manual pages for `elf_getshdrstrndx()`, `elf_getphdrnum()` and `elf_getshdrnum()`. * Add a deprecation warning for `elf_getshstrndx()`, `elf_getphnum()` and `elf_getshnum()`. Obtained from: elftoolchain MFC after: 1 month --- lib/libelf/Makefile | 6 ++- lib/libelf/Version.map | 3 ++ lib/libelf/elf_getphdrnum.3 | 86 ++++++++++++++++++++++++++++++++++++++++++ lib/libelf/elf_getphnum.3 | 12 ++++-- lib/libelf/elf_getshdrnum.3 | 78 ++++++++++++++++++++++++++++++++++++++ lib/libelf/elf_getshdrstrndx.3 | 79 ++++++++++++++++++++++++++++++++++++++ lib/libelf/elf_getshnum.3 | 10 ++++- lib/libelf/elf_getshstrndx.3 | 11 +++++- lib/libelf/elf_phnum.c | 23 ++++++++--- lib/libelf/elf_shnum.c | 23 ++++++++--- lib/libelf/elf_shstrndx.c | 22 ++++++++--- lib/libelf/libelf.h | 9 +++-- 12 files changed, 336 insertions(+), 26 deletions(-) create mode 100644 lib/libelf/elf_getphdrnum.3 create mode 100644 lib/libelf/elf_getshdrnum.3 create mode 100644 lib/libelf/elf_getshdrstrndx.3 (limited to 'lib/libelf') diff --git a/lib/libelf/Makefile b/lib/libelf/Makefile index 30e5080..030378f 100644 --- a/lib/libelf/Makefile +++ b/lib/libelf/Makefile @@ -63,7 +63,8 @@ SHLIB_MAJOR= 1 MAN= elf.3 \ elf_begin.3 \ elf_cntl.3 \ - elf_end.3 elf_errmsg.3 \ + elf_end.3 \ + elf_errmsg.3 \ elf_fill.3 \ elf_flagdata.3 \ elf_getarhdr.3 \ @@ -72,8 +73,11 @@ MAN= elf.3 \ elf_getdata.3 \ elf_getident.3 \ elf_getscn.3 \ + elf_getphdrnum.3 \ elf_getphnum.3 \ + elf_getshdrnum.3 \ elf_getshnum.3 \ + elf_getshdrstrndx.3 \ elf_getshstrndx.3 \ elf_hash.3 \ elf_kind.3 \ diff --git a/lib/libelf/Version.map b/lib/libelf/Version.map index 147d6c1..a6a6bd8 100644 --- a/lib/libelf/Version.map +++ b/lib/libelf/Version.map @@ -39,8 +39,11 @@ global: elf_getdata; elf_getident; elf_getscn; + elf_getphdrnum; elf_getphnum; + elf_getshdrnum; elf_getshnum; + elf_getshdrstrndx; elf_getshstrndx; elf_hash; elf_kind; diff --git a/lib/libelf/elf_getphdrnum.3 b/lib/libelf/elf_getphdrnum.3 new file mode 100644 index 0000000..290c69a --- /dev/null +++ b/lib/libelf/elf_getphdrnum.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 2006,2008 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. +.\" +.\" $FreeBSD$ +.\" +.Dd August 5, 2009 +.Os +.Dt ELF_GETPHDRNUM 3 +.Sh NAME +.Nm elf_getphdrnum +.Nd return the number of program headers in an ELF file +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_getphdrnum "Elf *elf" "size_t *phnum" +.Sh DESCRIPTION +Function +.Fn elf_getphdrnum +retrieves the number of ELF program headers associated with descriptor +.Ar elf +and stores it into the location pointed to by argument +.Ar phnum . +.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 +can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +lacks an ELF Executable Header. +.It Bq Er ELF_E_HEADER +The ELF Executable Header associated with argument +.Ar elf +was corrupt. +.It Bq Er ELF_E_SECTION +The section header at index +.Dv SHN_UNDEF +was corrupt. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getident 3 , +.Xr elf_getshdrnum 3 , +.Xr elf_getshdrstrndx 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 diff --git a/lib/libelf/elf_getphnum.3 b/lib/libelf/elf_getphnum.3 index 308f87c..abf4b39 100644 --- a/lib/libelf/elf_getphnum.3 +++ b/lib/libelf/elf_getphnum.3 @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd December 16, 2006 +.Dd August 5, 2009 .Dt ELF_GETPHNUM 3 .Os .Sh NAME @@ -36,6 +36,11 @@ .Ft int .Fn elf_getphnum "Elf *elf" "size_t *phnum" .Sh DESCRIPTION +This function is deprecated. +Please use function +.Xr elf_getphdrnum 3 +instead. +.Pp Function .Fn elf_getphnum retrieves the number of ELF program headers associated with descriptor @@ -81,7 +86,8 @@ was corrupt. .Xr elf32_getehdr 3 , .Xr elf64_getehdr 3 , .Xr elf_getident 3 , -.Xr elf_getshnum 3 , -.Xr elf_getshstrndx 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrnum 3 , +.Xr elf_getshdrstrndx 3 , .Xr gelf 3 , .Xr gelf_getehdr 3 diff --git a/lib/libelf/elf_getshdrnum.3 b/lib/libelf/elf_getshdrnum.3 new file mode 100644 index 0000000..0128e0a --- /dev/null +++ b/lib/libelf/elf_getshdrnum.3 @@ -0,0 +1,78 @@ +.\" Copyright (c) 2006,2008 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. +.\" +.\" $FreeBSD$ +.\" +.Dd August 4, 2009 +.Os +.Dt ELF_GETSHDRNUM 3 +.Sh NAME +.Nm elf_getshdrnum +.Nd return the number of sections in an ELF file +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_getshdrnum "Elf *elf" "size_t *shnum" +.Sh DESCRIPTION +Function +.Fn elf_getshdrnum +retrieves the number of ELF sections associated with descriptor +.Ar elf +and stores it into the location pointed to by argument +.Ar shnum . +.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 +returns zero value if successful, or -1 in case of an error. +.Sh ERRORS +Function +.Fn elf_getshdrnum +can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +lacks an ELF Executable header. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getident 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrstrndx 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 diff --git a/lib/libelf/elf_getshdrstrndx.3 b/lib/libelf/elf_getshdrstrndx.3 new file mode 100644 index 0000000..009662e --- /dev/null +++ b/lib/libelf/elf_getshdrstrndx.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) 2006,2008 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. +.\" +.\" $FreeBSD$ +.\" +.Dd August 5, 2009 +.Os +.Dt ELF_GETSHDRSTRNDX 3 +.Sh NAME +.Nm elf_getshdrstrndx +.Nd retrieve the index of the section name string table +.Sh LIBRARY +.Lb libelf +.Sh SYNOPSIS +.In libelf.h +.Ft int +.Fn elf_getshdrstrndx "Elf *elf" "size_t *ndxptr" +.Sh DESCRIPTION +Function +.Fn elf_getshdrstrndx +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 . +.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 +These functions can fail with the following errors: +.Bl -tag -width "[ELF_E_RESOURCE]" +.It Bq Er ELF_E_ARGUMENT +A NULL value was passed in for argument +.Ar elf . +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +was not for an ELF file. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar elf +lacks an ELF Executable header. +.It Bq Er ELF_E_ARGUMENT +Argument +.Ar ndx +contained a value in the reserved range of section indices. +.El +.Sh SEE ALSO +.Xr elf 3 , +.Xr elf32_getehdr 3 , +.Xr elf64_getehdr 3 , +.Xr elf_getident 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrnum 3 , +.Xr gelf 3 , +.Xr gelf_getehdr 3 diff --git a/lib/libelf/elf_getshnum.3 b/lib/libelf/elf_getshnum.3 index 7c8a04c..41b519e 100644 --- a/lib/libelf/elf_getshnum.3 +++ b/lib/libelf/elf_getshnum.3 @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 31, 2006 +.Dd August 5, 2009 .Dt ELF_GETSHNUM 3 .Os .Sh NAME @@ -36,6 +36,11 @@ .Ft int .Fn elf_getshnum "Elf *elf" "size_t *shnum" .Sh DESCRIPTION +This function is deprecated. +Please use +.Xr elf_getshdrnum 3 +instead. +.Pp Function .Fn elf_getshnum retrieves the number of ELF sections associated with descriptor @@ -73,6 +78,7 @@ lacks an ELF Executable header. .Xr elf32_getehdr 3 , .Xr elf64_getehdr 3 , .Xr elf_getident 3 , -.Xr elf_getshstrndx 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrstrndx 3 , .Xr gelf 3 , .Xr gelf_getehdr 3 diff --git a/lib/libelf/elf_getshstrndx.3 b/lib/libelf/elf_getshstrndx.3 index 71df3ac..f042a6f 100644 --- a/lib/libelf/elf_getshstrndx.3 +++ b/lib/libelf/elf_getshstrndx.3 @@ -23,7 +23,7 @@ .\" .\" $FreeBSD$ .\" -.Dd October 31, 2006 +.Dd August 5, 2009 .Dt ELF_GETSHSTRNDX 3 .Os .Sh NAME @@ -46,6 +46,12 @@ 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 @@ -82,6 +88,7 @@ contained a value in the reserved range of section indices. .Xr elf32_getehdr 3 , .Xr elf64_getehdr 3 , .Xr elf_getident 3 , -.Xr elf_getshnum 3 , +.Xr elf_getphdrnum 3 , +.Xr elf_getshdrnum 3 , .Xr gelf 3 , .Xr gelf_getehdr 3 diff --git a/lib/libelf/elf_phnum.c b/lib/libelf/elf_phnum.c index ff10c7e..4ec108e 100644 --- a/lib/libelf/elf_phnum.c +++ b/lib/libelf/elf_phnum.c @@ -32,8 +32,8 @@ __FBSDID("$FreeBSD$"); #include "_libelf.h" -int -elf_getphnum(Elf *e, size_t *phnum) +static int +_libelf_getphdrnum(Elf *e, size_t *phnum) { void *eh; int ec; @@ -41,13 +41,26 @@ elf_getphnum(Elf *e, size_t *phnum) if (e == NULL || e->e_kind != ELF_K_ELF || ((ec = e->e_class) != ELFCLASS32 && ec != ELFCLASS64)) { LIBELF_SET_ERROR(ARGUMENT, 0); - return (0); + return (-1); } if ((eh = _libelf_ehdr(e, ec, 0)) == NULL) - return (0); + return (-1); *phnum = e->e_u.e_elf.e_nphdr; - return (1); + return (0); +} + +int +elf_getphdrnum(Elf *e, size_t *phnum) +{ + return (_libelf_getphdrnum(e, phnum)); +} + +/* Deprecated API */ +int +elf_getphnum(Elf *e, size_t *phnum) +{ + return (_libelf_getphdrnum(e, phnum) >= 0); } diff --git a/lib/libelf/elf_shnum.c b/lib/libelf/elf_shnum.c index d22a1fc..50cd0f5 100644 --- a/lib/libelf/elf_shnum.c +++ b/lib/libelf/elf_shnum.c @@ -32,8 +32,8 @@ __FBSDID("$FreeBSD$"); #include "_libelf.h" -int -elf_getshnum(Elf *e, size_t *shnum) +static int +_libelf_getshdrnum(Elf *e, size_t *shnum) { void *eh; int ec; @@ -41,13 +41,26 @@ elf_getshnum(Elf *e, size_t *shnum) if (e == NULL || e->e_kind != ELF_K_ELF || ((ec = e->e_class) != ELFCLASS32 && ec != ELFCLASS64)) { LIBELF_SET_ERROR(ARGUMENT, 0); - return (0); + return (-1); } if ((eh = _libelf_ehdr(e, ec, 0)) == NULL) - return (0); + return (-1); *shnum = e->e_u.e_elf.e_nscn; - return (1); + return (0); +} + +int +elf_getshdrnum(Elf *e, size_t *shnum) +{ + return (_libelf_getshdrnum(e, shnum)); +} + +/* Deprecated API. */ +int +elf_getshnum(Elf *e, size_t *shnum) +{ + return (_libelf_getshdrnum(e, shnum) >= 0); } diff --git a/lib/libelf/elf_shstrndx.c b/lib/libelf/elf_shstrndx.c index f4f502d..2c8b1b4 100644 --- a/lib/libelf/elf_shstrndx.c +++ b/lib/libelf/elf_shstrndx.c @@ -32,8 +32,8 @@ __FBSDID("$FreeBSD$"); #include "_libelf.h" -int -elf_getshstrndx(Elf *e, size_t *strndx) +static int +_libelf_getshdrstrndx(Elf *e, size_t *strndx) { void *eh; int ec; @@ -41,15 +41,27 @@ elf_getshstrndx(Elf *e, size_t *strndx) if (e == NULL || e->e_kind != ELF_K_ELF || ((ec = e->e_class) != ELFCLASS32 && ec != ELFCLASS64)) { LIBELF_SET_ERROR(ARGUMENT, 0); - return (0); + return (-1); } if ((eh = _libelf_ehdr(e, ec, 0)) == NULL) - return (0); + return (-1); *strndx = e->e_u.e_elf.e_strndx; - return (1); + return (0); +} + +int +elf_getshdrstrndx(Elf *e, size_t *strndx) +{ + return (_libelf_getshdrstrndx(e, strndx)); +} + +int +elf_getshstrndx(Elf *e, size_t *strndx) /* Deprecated API. */ +{ + return (_libelf_getshdrstrndx(e, strndx) >= 0); } int diff --git a/lib/libelf/libelf.h b/lib/libelf/libelf.h index ac4c04e..2d235b0 100644 --- a/lib/libelf/libelf.h +++ b/lib/libelf/libelf.h @@ -193,10 +193,13 @@ Elf_Arsym *elf_getarsym(Elf *_elf, size_t *_ptr); off_t elf_getbase(Elf *_elf); Elf_Data *elf_getdata(Elf_Scn *, Elf_Data *); char *elf_getident(Elf *_elf, size_t *_ptr); -int elf_getphnum(Elf *_elf, size_t *_dst); +int elf_getphdrnum(Elf *_elf, size_t *_dst); +int elf_getphnum(Elf *_elf, size_t *_dst); /* Deprecated */ Elf_Scn *elf_getscn(Elf *_elf, size_t _index); -int elf_getshnum(Elf *_elf, size_t *_dst); -int elf_getshstrndx(Elf *_elf, size_t *_dst); +int elf_getshdrnum(Elf *_elf, size_t *_dst); +int elf_getshnum(Elf *_elf, size_t *_dst); /* Deprecated */ +int elf_getshdrstrndx(Elf *_elf, size_t *_dst); +int elf_getshstrndx(Elf *_elf, size_t *_dst); /* Deprecated */ unsigned long elf_hash(const char *_name); Elf_Kind elf_kind(Elf *_elf); Elf *elf_memory(char *_image, size_t _size); -- cgit v1.1