dl_iterate_phdr man

2 files changed, 85 insertions, 3 deletions

diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile
index dc959f06457..4a338ee1ba6 100644
--- a/share/man/man3/Makefile
+++ b/share/man/man3/Makefile
@@ -1,8 +1,8 @@
-#	$OpenBSD: Makefile,v 1.16 2004/08/11 19:14:56 drahn Exp $
+#	$OpenBSD: Makefile,v 1.17 2005/01/30 14:38:17 kettenis Exp $
 #	@(#)Makefile	8.2 (Berkeley) 12/13/93
 
-MAN=	assert.3 bitstring.3 dlfcn.3 end.3 intro.3 queue.3 stdarg.3 \
-	sysexits.3 tree.3
+MAN=	assert.3 bitstring.3 dlfcn.3 dl_iterate_phdr.3 end.3 intro.3 queue.3 \
+	stdarg.3 sysexits.3 tree.3
 MLINKS+=bitstring.3 bit_alloc.3 bitstring.3 bit_clear.3 \
 	bitstring.3 bit_decl.3 bitstring.3 bit_ffc.3 bitstring.3 bit_ffs.3 \
 	bitstring.3 bit_nclear.3 bitstring.3 bit_set.3 \
diff --git a/share/man/man3/dl_iterate_phdr.3 b/share/man/man3/dl_iterate_phdr.3
new file mode 100644
index 00000000000..d86bdbd0dd3
--- /dev/null
+++ b/share/man/man3/dl_iterate_phdr.3
@@ -0,0 +1,82 @@
+.\"   $OpenBSD: dl_iterate_phdr.3,v 1.1 2005/01/30 14:38:17 kettenis Exp $
+.\"
+.\" Copyright (c) 2005 Mark Kettenis
+.\"
+.\" 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.
+.\"
+.Dd January 17, 2005
+.Dt DL_ITERATE_PHDR 3
+.Os
+.Sh NAME
+.Nm dl_iterate_phdr
+.Nd iterate over program headers
+.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 shared objects loaded into a process's
+address space, calling
+.Fa callback
+for each shared object, passing it information about the object's
+program headers and the
+.Fa data
+argument.
+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;
+};
+.Ed
+.Pp
+The members of
+.Li struct dl_phdr_info
+have the following meaning:
+.Bl -tag -width XXXdlpi_phdr
+.It Fa dlpi_addr
+The base address at which the shared object is mapped into the address
+space of the calling process.
+.It Fa dlpi_name
+The name of the shared object.
+.It Fa dlpi_phdr
+A pointer to the shared object's program headers.
+.It Fa dlpi_phnum
+The number of program headers in the shared object.
+.El
+.Pp
+Future versions of
+.Ox
+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 argument to
+.Fa callback .
+.Sh SEE ALSO
+.Xr ld 1 ,
+.Xr ld.so 1 ,
+.Xr dlfcn 3 ,
+.Xr elf 5
+.Sh HISTORY
+The
+.Nm
+function first appeared in
+.Ox 3.7 .
+.Sh BUGS
+The
+.Fa callback
+function is not called for the main executable object.