-.\" Copyright (c) 2003 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Copyright (c) 2003, 2017 by Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
-.TH DL_ITERATE_PHDR 3 2015-07-23 "GNU" "Linux Programmer's Manual"
+.TH DL_ITERATE_PHDR 3 2017-07-13 "GNU" "Linux Programmer's Manual"
.SH NAME
dl_iterate_phdr \- walk through list of shared objects
.SH SYNOPSIS
The
.BR dl_iterate_phdr ()
function allows an application to inquire at run time to find
-out which shared objects it has loaded.
+out which shared objects it has loaded,
+and the order in which they were loaded.
The
.BR dl_iterate_phdr ()
ELF program headers
for this object */
ElfW(Half) dlpi_phnum; /* # of items in \fIdlpi_phdr\fP */
+
+ /* The following fields were added in glibc 2.4, after the first
+ version of this structure was available. Check the \fIsize\fP
+ argument passed to the dl_iterate_phdr callback to determine
+ whether or not each later member is available. */
+
+ unsigned long long int dlpi_adds;
+ /* Incremented when a new object may
+ have been added */
+ unsigned long long int dlpi_subs;
+ /* Incremented when an object may
+ have been removed */
+ size_t dlpi_tls_modid;
+ /* If there is a PT_TLS segment, its module
+ ID as used in TLS relocations, else zero */
+ void *dlpi_tls_data;
+ /* The address of the calling thread's instance
+ of this module's PT_TLS segment, if it has
+ one and it has been allocated in the calling
+ thread, otherwise a null pointer */
};
.fi
.in
macro definition turns its argument into the name of an ELF data
type suitable for the hardware architecture.
For example, on a 32-bit platform,
-ElfW(Addr) yields the data type name Elf32_Addr.
+.I ElfW(Addr)
+yields the data type name
+.IR Elf32_Addr .
Further information on these types can be found in the
.IR <elf.h> " and " <link.h>
header files.)
.nf
addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr;
.fi
+
+Possible values for
+.I p_type
+include the following (see
+.IR <elf.h>
+for further details):
+
+.nf
+.in +4n
+#define PT_LOAD 1 /* Loadable program segment */
+#define PT_DYNAMIC 2 /* Dynamic linking information */
+#define PT_INTERP 3 /* Program interpreter */
+#define PT_NOTE 4 /* Auxiliary information */
+#define PT_SHLIB 5 /* Reserved */
+#define PT_PHDR 6 /* Entry for header table itself */
+#define PT_TLS 7 /* Thread-local storage segment */
+#define PT_GNU_EH_FRAME 0x6474e550 /* GCC .eh_frame_hdr segment */
+#define PT_GNU_STACK 0x6474e551 /* Indicates stack executability */
+.\" For PT_GNU_STACK, see http://www.airs.com/blog/archives/518
+#define PT_GNU_RELRO 0x6474e552 /* Read-only after relocation */
+.in
+.fi
.SH RETURN VALUE
The
.BR dl_iterate_phdr ()
.SH CONFORMING TO
The
.BR dl_iterate_phdr ()
-function is Linux-specific and should be avoided in portable applications.
+function is not specified in any standard.
+Various other systems provide a version of this function,
+although details of the returned
+.I dl_phdr_info
+structure differ.
+On the BSDs and Solaris, the structure includes the fields
+.IR dlpi_addr ,
+.IR dlpi_name ,
+.IR dlpi_phdr ,
+and
+.IR dlpi_phnum
+in addition to other implementation-specific fields.
.SH NOTES
Future versions of the C library may add further fields to the
.IR dl_phdr_info
.I size
argument provides a mechanism for the callback function to discover
whether it is running on a system with added fields.
+
+The first object visited by
+.IR callback
+is the main program.
+For the main program, the
+.I dlpi_name
+field will be an empty string.
.SH EXAMPLE
The following program displays a list of pathnames of the
shared objects it has loaded.
-For each shared object, the program lists the virtual addresses
-at which the object's ELF segments are loaded.
+For each shared object, the program lists some information
+(virtual address, size, flags, and type)
+for each of the objects ELF segments.
+
+The following shell session demonstrates the output
+produced by the program on an x86-64 system.
+The first shared object for which output is displayed
+(where the name is an empty string)
+is the main program.
+.nf
+.in +4n
+$ \fB./a.out\fP
+Name: "" (9 segments)
+ 0: [ 0x400040; memsz: 1f8] flags: 0x5; PT_PHDR
+ 1: [ 0x400238; memsz: 1c] flags: 0x4; PT_INTERP
+ 2: [ 0x400000; memsz: ac4] flags: 0x5; PT_LOAD
+ 3: [ 0x600e10; memsz: 240] flags: 0x6; PT_LOAD
+ 4: [ 0x600e28; memsz: 1d0] flags: 0x6; PT_DYNAMIC
+ 5: [ 0x400254; memsz: 44] flags: 0x4; PT_NOTE
+ 6: [ 0x400970; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME
+ 7: [ (nil); memsz: 0] flags: 0x6; PT_GNU_STACK
+ 8: [ 0x600e10; memsz: 1f0] flags: 0x4; PT_GNU_RELRO
+Name: "linux-vdso.so.1" (4 segments)
+ 0: [0x7ffc6edd1000; memsz: e89] flags: 0x5; PT_LOAD
+ 1: [0x7ffc6edd1360; memsz: 110] flags: 0x4; PT_DYNAMIC
+ 2: [0x7ffc6edd17b0; memsz: 3c] flags: 0x4; PT_NOTE
+ 3: [0x7ffc6edd17ec; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME
+Name: "/lib64/libc.so.6" (10 segments)
+ 0: [0x7f55712ce040; memsz: 230] flags: 0x5; PT_PHDR
+ 1: [0x7f557145b980; memsz: 1c] flags: 0x4; PT_INTERP
+ 2: [0x7f55712ce000; memsz: 1b6a5c] flags: 0x5; PT_LOAD
+ 3: [0x7f55716857a0; memsz: 9240] flags: 0x6; PT_LOAD
+ 4: [0x7f5571688b80; memsz: 1f0] flags: 0x6; PT_DYNAMIC
+ 5: [0x7f55712ce270; memsz: 44] flags: 0x4; PT_NOTE
+ 6: [0x7f55716857a0; memsz: 78] flags: 0x4; PT_TLS
+ 7: [0x7f557145b99c; memsz: 544c] flags: 0x4; PT_GNU_EH_FRAME
+ 8: [0x7f55712ce000; memsz: 0] flags: 0x6; PT_GNU_STACK
+ 9: [0x7f55716857a0; memsz: 3860] flags: 0x4; PT_GNU_RELRO
+Name: "/lib64/ld-linux-x86-64.so.2" (7 segments)
+ 0: [0x7f557168f000; memsz: 20828] flags: 0x5; PT_LOAD
+ 1: [0x7f55718afba0; memsz: 15a8] flags: 0x6; PT_LOAD
+ 2: [0x7f55718afe10; memsz: 190] flags: 0x6; PT_DYNAMIC
+ 3: [0x7f557168f1c8; memsz: 24] flags: 0x4; PT_NOTE
+ 4: [0x7f55716acec4; memsz: 604] flags: 0x4; PT_GNU_EH_FRAME
+ 5: [0x7f557168f000; memsz: 0] flags: 0x6; PT_GNU_STACK
+ 6: [0x7f55718afba0; memsz: 460] flags: 0x4; PT_GNU_RELRO
+.in
+.fi
+.SS Program source
+\&
.nf
#define _GNU_SOURCE
#include <link.h>
static int
callback(struct dl_phdr_info *info, size_t size, void *data)
{
- int j;
+ char *type;
+ int p_type, j;
+
+ printf("Name: \\"%s\\" (%d segments)\\n", info\->dlpi_name,
+ info\->dlpi_phnum);
- printf("name=%s (%d segments)\\n", info\->dlpi_name,
- info\->dlpi_phnum);
+ for (j = 0; j < info\->dlpi_phnum; j++) {
+ p_type = info\->dlpi_phdr[j].p_type;
+ type = (p_type == PT_LOAD) ? "PT_LOAD" :
+ (p_type == PT_DYNAMIC) ? "PT_DYNAMIC" :
+ (p_type == PT_INTERP) ? "PT_INTERP" :
+ (p_type == PT_NOTE) ? "PT_NOTE" :
+ (p_type == PT_INTERP) ? "PT_INTERP" :
+ (p_type == PT_PHDR) ? "PT_PHDR" :
+ (p_type == PT_TLS) ? "PT_TLS" :
+ (p_type == PT_GNU_EH_FRAME) ? "PT_GNU_EH_FRAME" :
+ (p_type == PT_GNU_STACK) ? "PT_GNU_STACK" :
+ (p_type == PT_GNU_RELRO) ? "PT_GNU_RELRO" : NULL;
+
+ printf(" %2d: [%14p; memsz:%7lx] flags: 0x%x; ", j,
+ (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr),
+ info\->dlpi_phdr[j].p_memsz,
+ info\->dlpi_phdr[j].p_flags);
+ if (type != NULL)
+ printf("%s\\n", type);
+ else
+ printf("[other (0x%x)]\\n", p_type);
+ }
- for (j = 0; j < info\->dlpi_phnum; j++)
- printf("\\t\\t header %2d: address=%10p\\n", j,
- (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr));
return 0;
}
.BR ldd (1),
.BR objdump (1),
.BR readelf (1),
+.BR dladdr (3),
.BR dlopen (3),
.BR elf (5),
.BR ld.so (8)