1.\" Copyright (c) 2005 Mark Kettenis 2.\" Copyright (c) 2012 Konstantin Belousov <kib@FreeBSD.org> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.\" $OpenBSD: dl_iterate_phdr.3,v 1.3 2007/05/31 19:19:48 jmc Exp $ 17.Dd April 5, 2021 18.Dt DL_ITERATE_PHDR 3 19.Os 20.Sh NAME 21.Nm dl_iterate_phdr 22.Nd iterate over program headers 23.Sh LIBRARY 24For the dynamically linked binaries, the service is provided by 25.Xr ld-elf.so.1 1 26dynamic linker. 27Statically linked programs use an implementation of 28.Fn dl_iterate_phdr 29from libc. 30.Sh SYNOPSIS 31.In link.h 32.Ft int 33.Fn dl_iterate_phdr "int (*callback)(struct dl_phdr_info *, size_t, void *)" "void *data" 34.Sh DESCRIPTION 35The 36.Fn dl_iterate_phdr 37function iterates over all ELF objects loaded into a process's 38address space, calling 39.Fa callback 40for each object, passing it information about the object's 41program headers and the 42.Fa data 43argument. 44The iteration is aborted when all objects are passed, or when the next 45.Fa callback 46call returns non-zero value. 47The information about the program headers is passed in a structure 48that is defined as: 49.Bd -literal 50struct dl_phdr_info { 51 Elf_Addr dlpi_addr; 52 const char *dlpi_name; 53 const Elf_Phdr *dlpi_phdr; 54 Elf_Half dlpi_phnum; 55 unsigned long long int dlpi_adds; 56 unsigned long long int dlpi_subs; 57 size_t dlpi_tls_modid; 58 void *dlpi_tls_data; 59}; 60.Ed 61.Pp 62The members of 63.Li struct dl_phdr_info 64have the following meaning: 65.Bl -tag -width dlpi_tls_modid 66.It Fa dlpi_addr 67The base address at which the object is mapped into the address 68space of the calling process. 69.It Fa dlpi_name 70The pathname of the ELF object. 71.It Fa dlpi_phdr 72A pointer to the object's program headers. 73.It Fa dlpi_phnum 74The number of program headers in the object. 75.It Fa dlpi_adds 76The counter of the object loads performed by the dynamic linker. 77.It Fa dlpi_subs 78The counter of the object unloads performed by the dynamic linker. 79.It Fa dlpi_tls_modid 80The TLS index of the object. 81.It Fa dlpi_tls_data 82A pointer to the calling thread' TLS data segment for this module, 83if it was allocated, 84.Dv NULL 85otherwise. 86.El 87.Pp 88Future versions of 89.Fx 90might add more members to this structure. 91To make it possible for programs to check whether any new members have 92been added, the size of the structure is passed as an second argument to 93.Fa callback . 94.Pp 95The third argument to callback is the 96.Fa data 97value passed to the call to 98.Fn dl_iterate_phdr , 99allowing the 100.Fa callback 101to have a context. 102.Sh RETURN VALUES 103The 104.Fn dl_iterate_phdr 105returns the value returned by the last 106.Fa callback 107call executed. 108.Sh SEE ALSO 109.Xr ld 1 , 110.Xr ld-elf.so.1 1 , 111.Xr dlopen 3 , 112.Xr elf 5 113.Sh HISTORY 114The 115.Nm 116function first appeared in 117.Fx 7.0 . 118