'\" te .\" Copyright (c) 2010, 2014, Oracle and/or its affiliates. All Rights Reserved. .\" Portions of this manual page were derived from Linux documentation obtained from http://linux.die.net. .TH dl_iterate_phdr 3C "23 April 2014" "SunOS 5.11" "Standard C Library Functions" .SH NAME dl_iterate_phdr \- walk through a list of objects .SH SYNOPSIS .LP .nf #include \fBint\fR \fBdl_iterate_phdr\fR(\fBint (*\fR\fIcallback\fR)(\fBstruct dl_phdr_info *\fR\fIinfo\fR, \fBsize_t\fR \fIsize\fR, \fBvoid *\fR\fIdata\fR), \fBvoid *\fR\fIdata\fR\fB);\fR .fi .SH DESCRIPTION .sp .LP The \fBdl_iterate_phdr()\fR function returns information regarding each ELF object currently resident in the process address space. .sp .LP The \fBdl_iterate_phdr()\fR function calls the function \fIcallback\fR once for each object, until either all objects have been processed or \fIcallback\fR returns a non-zero value. .sp .LP Each call to \fIcallback\fR receives three arguments: \fIinfo\fR, which is a pointer to a structure containing information about the object; \fIsize\fR, which is the size of the structure pointed to by \fIinfo\fR; and the \fIdata\fR argument passed to \fBdl_iterate_phdr()\fR by the caller. .sp .LP The \fIinfo\fR argument is a pointer to a structure of the following type: .sp .in +2 .nf struct dl_phdr_info { /* Fields present in all implementations */ ElfW(Addr) dlpi_addr; const char *dlpi_name; const ElfW(Phdr) *dlpi_phdr; ElfW(Half) dlpi_phnum; /* Additional fields present in this implementation */ u_longlong_t dlpi_adds; u_longlong_t dlpi_subs; }; .fi .in -2 .sp .LP The \fBElfW()\fR macro definition turns its argument into the name of an ELF data type suitable for the hardware architecture, by adding the \fBElf32_\fR prefix for 32-bit code, or \fBElf64_\fR for 64-bit code. .sp .LP The first four fields (\fBdlpi_addr\fR, \fBdlpi_name\fR, \fBdlpi_phdr\fR, \fBdlpi_phnum\fR) are present in all implementations of \fBdl_iterate_phdr()\fR, and can be accessed on any system that provides this function. The callback function must use the \fIsize\fR argument to determine if the remaining fields (\fBdlpi_adds\fR, \fBdlpi_subs\fR) are present. See EXAMPLES. .sp .LP The \fBdlpi_addr\fR field is 0 for executable objects (\fBET_EXEC\fR), and is the base address at which the object is mapped otherwise. Therefore, the address of any loadable segment in the program header array can be calculated as: .sp .in +2 .nf addr = info->dlpi_addr + info->dlpi_phdr[x].p_vaddr .fi .in -2 .sp .LP \fBdlpi_name\fR gives the pathname of the object. .sp .LP \fBdlpi_phdr\fR provides a pointer to the program header array for the object, and \fBdlpi_phnum\fR specifies the number of program headers found in the array. .sp .LP \fBdlpi_adds\fR provides the number of objects that have been mapped into the current process since it started, and \fBdlpi_subs\fR provides the number of objects that have been unmapped. See NOTES. .sp .LP See the \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR for more information about ELF objects, and the information contained in program headers. .SH EXAMPLES .LP \fBExample 1 \fRDisplay all currently mapped object .sp .LP The following program displays the pathnames of currently mapped objects. For each object, the virtual address of each loadable segment is shown. .sp .in +2 .nf #include #include #include static int callback(struct dl_phdr_info *info, size_t size, void *data) { int j; (void) printf("name=%s (%d program headers)\en", info->dlpi_name, info->dlpi_phnum); for (j = 0; j < info->dlpi_phnum; j++) { if (info->dlpi_phdr[j].p_type == PT_LOAD) { (void) printf("\et[%d] 0x%p\en", j, (void *) (info->dlpi_addr + info->dlpi_phdr[j].p_vaddr)); } } return 0; } int main(int argc, char *argv[]) { dl_iterate_phdr(callback, NULL); return(0); } .fi .in -2 .LP \fBExample 2 \fRTesting for optional \fBdl_phdr_info\fR fields .sp .LP Every implementation of dl_iterate_phdr is required to supply the first four fields in struct dl_phdr_info described above. The callback is allowed to assume that they are present and to access them without first testing for their presence. Additional fields may be present. The callback must use the size argument to test for their presence before accessing them. This example demonstrates how a callback function can detect the presence of the dlpi_adds and dlpi_subs fields described above: .sp .in +2 .nf static int callback(struct dl_phdr_info *info, size_t size, void *data) { /* * This must match the definition of dl_phdr_info, * as defined in . It is used to determine * whether the info structure contains optional * fields. */ struct dl_phdr_info_test { ElfW(Addr) dlpi_addr; const char *dlpi_name; const ElfW(Phdr) *dlpi_phdr; ElfW(Half) dlpi_phnum; u_longlong_t dlpi_adds; u_longlong_t dlpi_subs; }; (void) printf("object: %s\en", info->dlpi_name); (void) printf(" addr: 0x%p\en", (u_longlong_t)info->dlpi_addr); (void) printf(" phdr: 0x%p\en", (u_longlong_t)info->dlpi_phdr); (void) printf(" phnum: %d\en", (int)info->dlpi_phnum); if (size >= sizeof (struct dl_phdr_info_test)) { (void) printf(" adds: %llu\en", info->dlpi_adds); (void) printf(" subs: %llu\en", info->dlpi_subs); } return (0); } .fi .in -2 .SH RETURN VALUES .sp .LP The \fBdl_iterate_phdr()\fR function returns whatever value was returned by the last call to callback. .SH USAGE .sp .LP The \fBdl_iterate_phdr()\fR function is a member of a family of functions that give the user direct access to the dynamic linking facilities. This family of functions is available only to dynamically-linked processes. See the \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelMT-Safe .TE .SH SEE ALSO .sp .LP \fBld\fR(1), \fBld.so.1\fR(1), \fBdladdr\fR(3C), \fBdlclose\fR(3C), \fBdldump\fR(3C), \fBdlerror\fR(3C), \fBdlinfo\fR(3C), \fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5) .sp .LP \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR .SH NOTES .sp .LP \fBdl_iterate_phdr()\fR was originally defined by the Linux operating system, and is contained in the Linux Standard Base (LSB). .sp .LP The behavior of \fBdl_iterate_phdr()\fR when a callback function causes a new object to be loaded, either via lazy loading or a call to \fBdlopen()\fR, is undefined. The call to \fBdl_iterate_phdr()\fR that triggers the load may or may not issue a callback for the new object. This depends on the current position of \fBdl_iterate_phdr()\fR in the list of known objects when the new object is added. The caller must make no assumptions about this case. .sp .LP \fBdl_iterate_phdr()\fR callbacks must not unload objects. If a call to \fBdlclose()\fRis detected from within the callback function, \fBdl_iterate_phdr()\fR immediately terminates the iteration operation and returns a value of -1. .sp .LP If two separate calls to \fBdl_iterate_phdr()\fR provide the same two values for \fBdlpi_adds\fR and \fBdlpi_subs\fR, the caller may safely assume that the process object state has not changed between the two calls. An application can use this information to cache object data, and avoid unnecessary iteration. In such a scenario, the first call to the callback function would check to see if a cache exists, and that \fBdlpi_adds\fR and \fBdlpi_subs\fR have not changed since the last call to \fBdl_iterate_phdr()\fR, and if so, return a non-zero value to terminate the iteration operation immediately.