dlfcn/dlfcn.h

   1 /* User functions for run-time dynamic loading.
   2    Copyright (C) 1995-2024 Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4
   5    The GNU C Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the License, or (at your option) any later version.
   9
  10    The GNU C Library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <https://www.gnu.org/licenses/>.  */
  18
  19 #ifndef _DLFCN_H
  20 #define _DLFCN_H 1
  21
  22 #include <features.h>
  23 #define __need_size_t
  24 #include <stddef.h>
  25
  26 /* Collect various system dependent definitions and declarations.  */
  27 #include <bits/dlfcn.h>
  28
  29
  30 #ifdef __USE_GNU
  31 #include <bits/dl_find_object.h>
  32
  33 /* Type for namespace indices.  */
  34 typedef long int Lmid_t;
  35
  36 /* Special namespace ID values.  */
  37 # define LM_ID_BASE     0       /* Initial namespace.  */
  38 # define LM_ID_NEWLM    -1      /* For dlmopen: request new namespace.  */
  39 #endif
  40
  41 /* If the first argument of `dlsym' or `dlvsym' is set to RTLD_NEXT
  42    the run-time address of the symbol called NAME in the next shared
  43    object is returned.  The "next" relation is defined by the order
  44    the shared objects were loaded.  */
  45 #define RTLD_NEXT       ((void *) -1l)
  46
  47 /* If the first argument to `dlsym' or `dlvsym' is set to RTLD_DEFAULT
  48    the run-time address of the symbol called NAME in the global scope
  49    is returned.  */
  50 #define RTLD_DEFAULT    ((void *) 0)
  51
  52 __BEGIN_DECLS
  53
  54 /* Open the shared object FILE and map it in; return a handle that can be
  55    passed to `dlsym' to get symbol values from it.  */
  56 extern void *dlopen (const char *__file, int __mode) __THROWNL;
  57
  58 /* Unmap and close a shared object opened by `dlopen'.
  59    The handle cannot be used again after calling `dlclose'.  */
  60 extern int dlclose (void *__handle) __THROWNL __nonnull ((1));
  61
  62 /* Find the run-time address in the shared object HANDLE refers to
  63    of the symbol called NAME.  */
  64 extern void *dlsym (void *__restrict __handle,
  65                     const char *__restrict __name) __THROW __nonnull ((2));
  66
  67 #ifdef __USE_GNU
  68 /* Like `dlopen', but request object to be allocated in a new namespace.  */
  69 extern void *dlmopen (Lmid_t __nsid, const char *__file, int __mode) __THROWNL;
  70
  71 /* Find the run-time address in the shared object HANDLE refers to
  72    of the symbol called NAME with VERSION.  */
  73 extern void *dlvsym (void *__restrict __handle,
  74                      const char *__restrict __name,
  75                      const char *__restrict __version)
  76      __THROW __nonnull ((2, 3));
  77 #endif
  78
  79 /* When any of the above functions fails, call this function
  80    to return a string describing the error.  Each call resets
  81    the error string so that a following call returns null.  */
  82 extern char *dlerror (void) __THROW;
  83
  84
  85 #ifdef __USE_GNU
  86 /* Structure containing information about object searched using
  87    `dladdr'.  */
  88 typedef struct
  89 {
  90   const char *dli_fname;        /* File name of defining object.  */
  91   void *dli_fbase;              /* Load address of that object.  */
  92   const char *dli_sname;        /* Name of nearest symbol.  */
  93   void *dli_saddr;              /* Exact value of nearest symbol.  */
  94 } Dl_info;
  95
  96 /* Fill in *INFO with the following information about ADDRESS.
  97    Returns 0 iff no shared object's segments contain that address.  */
  98 extern int dladdr (const void *__address, Dl_info *__info)
  99      __THROW __nonnull ((2));
 100
 101 /* Same as `dladdr', but additionally sets *EXTRA_INFO according to FLAGS.  */
 102 extern int dladdr1 (const void *__address, Dl_info *__info,
 103                     void **__extra_info, int __flags) __THROW __nonnull ((2));
 104
 105 /* These are the possible values for the FLAGS argument to `dladdr1'.
 106    This indicates what extra information is stored at *EXTRA_INFO.
 107    It may also be zero, in which case the EXTRA_INFO argument is not used.  */
 108 enum
 109   {
 110     /* Matching symbol table entry (const ElfNN_Sym *).  */
 111     RTLD_DL_SYMENT = 1,
 112
 113     /* The object containing the address (struct link_map *).  */
 114     RTLD_DL_LINKMAP = 2
 115   };
 116
 117
 118 /* Get information about the shared object HANDLE refers to.
 119    REQUEST is from among the values below, and determines the use of ARG.
 120
 121    On success, returns zero.  On failure, returns -1 and records an error
 122    message to be fetched with `dlerror'.  */
 123 extern int dlinfo (void *__restrict __handle,
 124                    int __request, void *__restrict __arg)
 125      __THROW __nonnull ((1, 3));
 126
 127 /* These are the possible values for the REQUEST argument to `dlinfo'.  */
 128 enum
 129   {
 130     /* Treat ARG as `lmid_t *'; store namespace ID for HANDLE there.  */
 131     RTLD_DI_LMID = 1,
 132
 133     /* Treat ARG as `struct link_map **';
 134        store the `struct link_map *' for HANDLE there.  */
 135     RTLD_DI_LINKMAP = 2,
 136
 137     RTLD_DI_CONFIGADDR = 3,     /* Unsupported, defined by Solaris.  */
 138
 139     /* Treat ARG as `Dl_serinfo *' (see below), and fill in to describe the
 140        directories that will be searched for dependencies of this object.
 141        RTLD_DI_SERINFOSIZE fills in just the `dls_cnt' and `dls_size'
 142        entries to indicate the size of the buffer that must be passed to
 143        RTLD_DI_SERINFO to fill in the full information.  */
 144     RTLD_DI_SERINFO = 4,
 145     RTLD_DI_SERINFOSIZE = 5,
 146
 147     /* Treat ARG as `char *', and store there the directory name used to
 148        expand $ORIGIN in this shared object's dependency file names.  */
 149     RTLD_DI_ORIGIN = 6,
 150
 151     RTLD_DI_PROFILENAME = 7,    /* Unsupported, defined by Solaris.  */
 152     RTLD_DI_PROFILEOUT = 8,     /* Unsupported, defined by Solaris.  */
 153
 154     /* Treat ARG as `size_t *', and store there the TLS module ID
 155        of this object's PT_TLS segment, as used in TLS relocations;
 156        store zero if this object does not define a PT_TLS segment.  */
 157     RTLD_DI_TLS_MODID = 9,
 158
 159     /* Treat ARG as `void **', and store there a pointer to the calling
 160        thread's TLS block corresponding to this object's PT_TLS segment.
 161        Store a null pointer if this object does not define a PT_TLS
 162        segment, or if the calling thread has not allocated a block for it.  */
 163     RTLD_DI_TLS_DATA = 10,
 164
 165     /* Treat ARG as const ElfW(Phdr) **, and store the address of the
 166        program header array at that location.  The dlinfo call returns
 167        the number of program headers in the array.  */
 168     RTLD_DI_PHDR = 11,
 169
 170     RTLD_DI_MAX = 11
 171   };
 172
 173
 174 /* This is the type of elements in `Dl_serinfo', below.
 175    The `dls_name' member points to space in the buffer passed to `dlinfo'.  */
 176 typedef struct
 177 {
 178   char *dls_name;               /* Name of library search path directory.  */
 179   unsigned int dls_flags;       /* Indicates where this directory came from. */
 180 } Dl_serpath;
 181
 182 /* This is the structure that must be passed (by reference) to `dlinfo' for
 183    the RTLD_DI_SERINFO and RTLD_DI_SERINFOSIZE requests.  */
 184 typedef struct
 185 {
 186   size_t dls_size;              /* Size in bytes of the whole buffer.  */
 187   unsigned int dls_cnt;         /* Number of elements in `dls_serpath'.  */
 188 # if __GNUC_PREREQ (3, 0)
 189   /* The zero-length array avoids an unwanted array subscript check by
 190      the compiler, while the surrounding anonymous union preserves the
 191      historic size of the type.  At the time of writing, GNU C does
 192      not support structs with flexible array members in unions.  */
 193   __extension__ union
 194   {
 195     Dl_serpath dls_serpath[0]; /* Actually longer, dls_cnt elements.  */
 196     Dl_serpath __dls_serpath_pad[1];
 197   };
 198 # else
 199   Dl_serpath dls_serpath[1];    /* Actually longer, dls_cnt elements.  */
 200 # endif
 201 } Dl_serinfo;
 202
 203 struct dl_find_object
 204 {
 205   __extension__ unsigned long long int dlfo_flags;
 206   void *dlfo_map_start;         /* Beginning of mapping containing address.  */
 207   void *dlfo_map_end;           /* End of mapping.  */
 208   struct link_map *dlfo_link_map;
 209   void *dlfo_eh_frame;          /* Exception handling data of the object.  */
 210 # if DLFO_STRUCT_HAS_EH_DBASE
 211   void *dlfo_eh_dbase;          /* Base address for DW_EH_PE_datarel.  */
 212 #  if __WORDSIZE == 32
 213   unsigned int __dlfo_eh_dbase_pad;
 214 #  endif
 215 # endif
 216 # if DLFO_STRUCT_HAS_EH_COUNT
 217   int dlfo_eh_count;            /* Number of exception handling entries.  */
 218   unsigned int __dlfo_eh_count_pad;
 219 # endif
 220   __extension__ unsigned long long int __dflo_reserved[7];
 221 };
 222
 223 /* If ADDRESS is found in an object, fill in *RESULT and return 0.
 224    Otherwise, return -1.  */
 225 int _dl_find_object (void *__address, struct dl_find_object *__result) __THROW;
 226
 227 #endif /* __USE_GNU */
 228
 229
 230 __END_DECLS
 231
 232 #endif  /* dlfcn.h */