lib/libc/gen/dl_iterate_phdr.3

   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 .\" $FreeBSD$
  18 .Dd February 15, 2012
  19 .Dt DL_ITERATE_PHDR 3
  20 .Os
  21 .Sh NAME
  22 .Nm dl_iterate_phdr
  23 .Nd iterate over program headers
  24 .Sh LIBRARY
  25 For the dynamically linked binaries, the service is provided by
  26 .Xr ld-elf.so.1 1
  27 dynamic linker.
  28 Statically linked programs use an implementation of
  29 .Fn dl_iterate_phdr
  30 from libc.
  31 .Sh SYNOPSIS
  32 .In link.h
  33 .Ft int
  34 .Fn dl_iterate_phdr "int (*callback)(struct dl_phdr_info *, size_t, void *)" "void *data"
  35 .Sh DESCRIPTION
  36 The
  37 .Fn dl_iterate_phdr
  38 function iterates over all ELF objects loaded into a process's
  39 address space, calling
  40 .Fa callback
  41 for each object, passing it information about the object's
  42 program headers and the
  43 .Fa data
  44 argument.
  45 The iteration is aborted when all objects are passed, or when the next
  46 .Fa callback
  47 call returns non-zero value.
  48 The information about the program headers is passed in a structure
  49 that is defined as:
  50 .Bd -literal
  51 struct dl_phdr_info {
  52         Elf_Addr        dlpi_addr;
  53         const char      *dlpi_name;
  54         const Elf_Phdr  *dlpi_phdr;
  55         Elf_Half        dlpi_phnum;
  56         unsigned long long int dlpi_adds;
  57         unsigned long long int dlpi_subs;
  58         size_t          dlpi_tls_modid;
  59         void            *dlpi_tls_data;
  60 };
  61 .Ed
  62 .Pp
  63 The members of
  64 .Li struct dl_phdr_info
  65 have the following meaning:
  66 .Bl -tag -width dlpi_tls_modid
  67 .It Fa dlpi_addr
  68 The base address at which the object is mapped into the address
  69 space of the calling process.
  70 .It Fa dlpi_name
  71 The name of the ELF object.
  72 .It Fa dlpi_phdr
  73 A pointer to the object's program headers.
  74 .It Fa dlpi_phnum
  75 The number of program headers in the object.
  76 .It Fa dlpi_adds
  77 The counter of the object loads performed by the dynamic linker.
  78 .It Fa dlpi_subs
  79 The counter of the object unloads performed by the dynamic linker.
  80 .It Fa dlpi_tls_modid
  81 The TLS index of the object.
  82 .It Fa dlpi_tls_data
  83 A pointer to the initialization data for the object TLS segment.
  84 .El
  85 .Pp
  86 Future versions of
  87 .Fx
  88 might add more members to this structure.
  89 To make it possible for programs to check whether any new members have
  90 been added, the size of the structure is passed as an second argument to
  91 .Fa callback .
  92 .Pp
  93 The third argument to callback is the
  94 .Fa data
  95 value passed to the call to
  96 .Fn dl_iterate_phdr ,
  97 allowing the
  98 .Fa callback
  99 to have a context.
 100 .Sh RETURN VALUES
 101 The
 102 .Fn dl_iterate_phdr
 103 returns the value returned by the last
 104 .Fa callback
 105 call executed.
 106 .Sh SEE ALSO
 107 .Xr ld 1 ,
 108 .Xr ld-elf.so.1 1 ,
 109 .Xr dlopen 3 ,
 110 .Xr elf 5
 111 .Sh HISTORY
 112 The
 113 .Nm
 114 function first appeared in
 115 .Fx 7.0 .