Document dl_iterate_phdr(3).

Man page is based on the OpenBSD version, extended and corrected for
the FreeBSD implementation.

MFC after:  2 weeks

1 files changed, 115 insertions, 0 deletions

diff --git a/lib/libc/gen/dl_iterate_phdr.3 b/lib/libc/gen/dl_iterate_phdr.3
new file mode 100644
index 0000000..2d81d68
--- /dev/null
+++ b/lib/libc/gen/dl_iterate_phdr.3
@@ -0,0 +1,115 @@
+.\" Copyright (c) 2005 Mark Kettenis
+.\" Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\"   $OpenBSD: dl_iterate_phdr.3,v 1.3 2007/05/31 19:19:48 jmc Exp $
+.\" $FreeBSD$
+.Dd February 15, 2012
+.Dt DL_ITERATE_PHDR 3
+.Os
+.Sh NAME
+.Nm dl_iterate_phdr
+.Nd iterate over program headers
+.Sh LIBRARY
+For the dynamically linked binaries, the service is provided by
+.Xr ld-elf.so.1 5
+dynamic linker.
+Statically linked programs use an implementation of
+.Fn dl_iterate_phdr
+from libc.
+.Sh SYNOPSIS
+.Fd #include <link.h>
+.Ft int
+.Fn dl_iterate_phdr "int (*callback)(struct dl_phdr_info *, size_t, void *)" "void *data"
+.Sh DESCRIPTION
+The
+.Fn dl_iterate_phdr
+function iterates over all ELF objects loaded into a process's
+address space, calling
+.Fa callback
+for each object, passing it information about the object's
+program headers and the
+.Fa data
+argument.
+The iteration is aborted when all objects are passed, or when the next
+.Fa callback
+call returns non-zero value.
+The information about the program headers is passed in a structure
+that is defined as:
+.Bd -literal
+struct dl_phdr_info {
+	Elf_Addr	dlpi_addr;
+	const char	*dlpi_name;
+	const Elf_Phdr	*dlpi_phdr;
+	Elf_Half	dlpi_phnum;
+	unsigned long long int dlpi_adds;
+	unsigned long long int dlpi_subs;
+	size_t		dlpi_tls_modid;
+	void		*dlpi_tls_data;
+};
+.Ed
+.Pp
+The members of
+.Li struct dl_phdr_info
+have the following meaning:
+.Bl -tag -width dlpi_tls_modid
+.It Fa dlpi_addr
+The base address at which the object is mapped into the address
+space of the calling process.
+.It Fa dlpi_name
+The name of the ELF object.
+.It Fa dlpi_phdr
+A pointer to the object's program headers.
+.It Fa dlpi_phnum
+The number of program headers in the object.
+.It Fa dlpi_adds
+The counter of the object loads performed by the dynamic linker.
+.It Fa dlpi_subs
+The counter of the object unloads performed by the dynamic linker.
+.It Fa dlpi_tls_modid
+The TLS index of the object.
+.It Fa dlpi_tls_data
+A pointer to the initialization data for the object TLS segment.
+.El
+.Pp
+Future versions of
+.Fx
+might add more members to this structure.
+To make it possible for programs to check whether any new members have
+been added, the size of the structure is passed as an second argument to
+.Fa callback .
+.Pp
+The third argument to callback is the
+.Fa data
+value passed to the call to
+.Fn dl_iterate_phdr ,
+allowing the
+.Fa callback
+to have a context.
+.Sh RETURN VALUES
+The
+.Fn dl_iterate_phdr
+returns the value returned by the last
+.Fa callback
+call executed.
+.Sh SEE ALSO
+.Xr ld 1 ,
+.Xr ld-elf.so 1 ,
+.Xr dlopen 3 ,
+.Xr elf 5
+.Sh HISTORY
+The
+.Nm
+function first appeared in
+.Fx 7.0 .