* 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

12 files changed, 336 insertions, 26 deletions

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);