lib/libc/gen/dl_iterate_phdr.3

   1 .\"   $NetBSD: dl_iterate_phdr.3,v 1.2 2010/10/16 12:05:48 wiz Exp $
   2 .\"   $OpenBSD: dl_iterate_phdr.3,v 1.3 2007/05/31 19:19:48 jmc Exp $
   3 .\"
   4 .\" Copyright (c) 2005 Mark Kettenis
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd April 28, 2011
  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 This function is not in a library.
  26 It is included in every dynamically linked program automatically.
  27 .Sh SYNOPSIS
  28 .In link.h
  29 .Ft int
  30 .Fn dl_iterate_phdr "int (*callback)(struct dl_phdr_info *, size_t, void*)" "void *data"
  31 .Sh DESCRIPTION
  32 The
  33 .Fn dl_iterate_phdr
  34 function iterates over all shared objects loaded into a process's
  35 address space, calling
  36 .Fa callback
  37 for each shared object, passing it information about the object's
  38 program headers and the
  39 .Fa data
  40 argument.
  41 The information about the program headers is passed in a structure
  42 that is defined as:
  43 .Bd -literal
  44 struct dl_phdr_info {
  45         Elf_Addr                dlpi_addr;
  46         const char             *dlpi_name;
  47         const Elf_Phdr         *dlpi_phdr;
  48         Elf_Half                dlpi_phnum;
  49         unsigned long long int  dlpi_adds;
  50         unsigned long long int  dlpi_subs;
  51         size_t                  dlpi_tls_modid;
  52         void                   *dlpi_tls_data;
  53 };
  54 .Ed
  55 .Pp
  56 The members of
  57 .Li struct dl_phdr_info
  58 have the following meaning:
  59 .Bl -tag -width XXXdlpi_phdr
  60 .It Fa dlpi_addr
  61 The base address at which the shared object is mapped into the address
  62 space of the calling process.
  63 .It Fa dlpi_name
  64 The name of the shared object.
  65 .It Fa dlpi_phdr
  66 A pointer to the shared object's program headers.
  67 .It Fa dlpi_phnum
  68 The number of program headers in the shared object.
  69 .It Fa dlpi_adds
  70 The number of objects added into the main program.
  71 .It Fa dlpi_subs
  72 The number of objects removed from the main program.
  73 .El
  74 .Pp
  75 To make it possible for programs to check whether any new members have
  76 been added, the size of the structure is passed as an argument to
  77 .Fa callback .
  78 .Sh EXAMPLE
  79 The following program displays a list of pathnames of the shared objects it has
  80 loaded. For each shared object, the program lists the virtual addresses at
  81 which the object's ELF segments are loaded.
  82 .Bd -literal
  83 #include <link.h>
  84 #include <stdlib.h>
  85 #include <stdio.h>
  86
  87 static int
  88 callback(struct dl_phdr_info *info, size_t size, void *data)
  89 {
  90     int j;
  91     printf("name=%s (%d segments)\en", info->dlpi_name,
  92         info->dlpi_phnum);
  93     for (j = 0; j < info->dlpi_phnum; j++)
  94          printf("\t\t header %2d: address=%10p\en", j,
  95              (void *) (info->dlpi_addr + info->dlpi_phdr[j].p_vaddr));
  96     return 0;
  97 }
  98
  99 int
 100 main(int argc, char *argv[])
 101 {
 102     dl_iterate_phdr(callback, NULL);
 103     exit(EXIT_SUCCESS);
 104 }
 105 .Ed
 106 .Sh RETURN VALUE
 107 The
 108 .Fn dl_iterate_phdr
 109 function returns whatever value was returned by the last call to callback.
 110 .Sh SEE ALSO
 111 .Xr ld 1 ,
 112 .Xr ld-elf.so.2 1 ,
 113 .Xr dlfcn 3 ,
 114 .Xr elf 5
 115 .Sh HISTORY
 116 The
 117 .Nm
 118 function first appeared in
 119 .Dx 2.9 .