include/dlfcn.h

   1 /* User functions for run-time dynamic loading.
   2    Copyright (C) 1995-2001,2003,2004,2006,2009 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    <http://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 /* If the first argument of `dlsym' or `dlvsym' is set to RTLD_NEXT
  32    the run-time address of the symbol called NAME in the next shared
  33    object is returned.  The "next" relation is defined by the order
  34    the shared objects were loaded.  */
  35 # define RTLD_NEXT      ((void *) -1l)
  36
  37 /* If the first argument to `dlsym' or `dlvsym' is set to RTLD_DEFAULT
  38    the run-time address of the symbol called NAME in the global scope
  39    is returned.  */
  40 # define RTLD_DEFAULT   ((void *) 0)
  41
  42
  43 # if 0 /* uClibc doesnt support this */
  44 /* Type for namespace indeces.  */
  45 typedef long int Lmid_t;
  46
  47 /* Special namespace ID values.  */
  48 # define LM_ID_BASE     0       /* Initial namespace.  */
  49 # define LM_ID_NEWLM    -1      /* For dlmopen: request new namespace.  */
  50 # endif
  51 #endif
  52
  53
  54 __BEGIN_DECLS
  55
  56 /* Open the shared object FILE and map it in; return a handle that can be
  57    passed to `dlsym' to get symbol values from it.  */
  58 extern void *dlopen (const char *__file, int __mode) __THROW;
  59
  60 /* Unmap and close a shared object opened by `dlopen'.
  61    The handle cannot be used again after calling `dlclose'.  */
  62 extern int dlclose (void *__handle) __THROW __nonnull ((1));
  63
  64 /* Find the run-time address in the shared object HANDLE refers to
  65    of the symbol called NAME.  */
  66 extern void *dlsym (void *__restrict __handle,
  67                     const char *__restrict __name) __THROW __nonnull ((2));
  68
  69 #if 0 /*def __USE_GNU*/
  70 /* Like `dlopen', but request object to be allocated in a new namespace.  */
  71 extern void *dlmopen (Lmid_t __nsid, const char *__file, int __mode) __THROW;
  72
  73 /* Find the run-time address in the shared object HANDLE refers to
  74    of the symbol called NAME with VERSION.  */
  75 extern void *dlvsym (void *__restrict __handle,
  76                      const char *__restrict __name,
  77                      const char *__restrict __version)
  78      __THROW __nonnull ((2, 3));
  79 #endif
  80
  81 /* When any of the above functions fails, call this function
  82    to return a string describing the error.  Each call resets
  83    the error string so that a following call returns null.  */
  84 extern char *dlerror (void) __THROW;
  85
  86
  87 #ifdef __USE_GNU
  88 /* Structure containing information about object searched using
  89    `dladdr'.  */
  90 typedef struct
  91 {
  92   const char *dli_fname;        /* File name of defining object.  */
  93   void *dli_fbase;              /* Load address of that object.  */
  94   const char *dli_sname;        /* Name of nearest symbol.  */
  95   void *dli_saddr;              /* Exact value of nearest symbol.  */
  96 } Dl_info;
  97
  98 /* Fill in *INFO with the following information about ADDRESS.
  99    Returns 0 iff no shared object's segments contain that address.  */
 100 extern int dladdr (const void *__address, Dl_info *__info)
 101      __THROW __nonnull ((2));
 102
 103 #if 0 /* not supported by uClibc */
 104 /* Same as `dladdr', but additionally sets *EXTRA_INFO according to FLAGS.  */
 105 extern int dladdr1 (const void *__address, Dl_info *__info,
 106                     void **__extra_info, int __flags) __THROW __nonnull ((2));
 107
 108 /* These are the possible values for the FLAGS argument to `dladdr1'.
 109    This indicates what extra information is stored at *EXTRA_INFO.
 110    It may also be zero, in which case the EXTRA_INFO argument is not used.  */
 111 enum
 112   {
 113     /* Matching symbol table entry (const ElfNN_Sym *).  */
 114     RTLD_DL_SYMENT = 1,
 115
 116     /* The object containing the address (struct link_map *).  */
 117     RTLD_DL_LINKMAP = 2
 118   };
 119
 120
 121 /* Get information about the shared object HANDLE refers to.
 122    REQUEST is from among the values below, and determines the use of ARG.
 123
 124    On success, returns zero.  On failure, returns -1 and records an error
 125    message to be fetched with `dlerror'.  */
 126 extern int dlinfo (void *__restrict __handle,
 127                    int __request, void *__restrict __arg)
 128      __THROW __nonnull ((1, 3));
 129
 130 /* These are the possible values for the REQUEST argument to `dlinfo'.  */
 131 enum
 132   {
 133     /* Treat ARG as `lmid_t *'; store namespace ID for HANDLE there.  */
 134     RTLD_DI_LMID = 1,
 135
 136     /* Treat ARG as `struct link_map **';
 137        store the `struct link_map *' for HANDLE there.  */
 138     RTLD_DI_LINKMAP = 2,
 139
 140     RTLD_DI_CONFIGADDR = 3,     /* Unsupported, defined by Solaris.  */
 141
 142     /* Treat ARG as `Dl_serinfo *' (see below), and fill in to describe the
 143        directories that will be searched for dependencies of this object.
 144        RTLD_DI_SERINFOSIZE fills in just the `dls_cnt' and `dls_size'
 145        entries to indicate the size of the buffer that must be passed to
 146        RTLD_DI_SERINFO to fill in the full information.  */
 147     RTLD_DI_SERINFO = 4,
 148     RTLD_DI_SERINFOSIZE = 5,
 149
 150     /* Treat ARG as `char *', and store there the directory name used to
 151        expand $ORIGIN in this shared object's dependency file names.  */
 152     RTLD_DI_ORIGIN = 6,
 153
 154     RTLD_DI_PROFILENAME = 7,    /* Unsupported, defined by Solaris.  */
 155     RTLD_DI_PROFILEOUT = 8,     /* Unsupported, defined by Solaris.  */
 156
 157     /* Treat ARG as `size_t *', and store there the TLS module ID
 158        of this object's PT_TLS segment, as used in TLS relocations;
 159        store zero if this object does not define a PT_TLS segment.  */
 160     RTLD_DI_TLS_MODID = 9,
 161
 162     /* Treat ARG as `void **', and store there a pointer to the calling
 163        thread's TLS block corresponding to this object's PT_TLS segment.
 164        Store a null pointer if this object does not define a PT_TLS
 165        segment, or if the calling thread has not allocated a block for it.  */
 166     RTLD_DI_TLS_DATA = 10,
 167
 168     RTLD_DI_MAX = 10
 169   };
 170
 171
 172 /* This is the type of elements in `Dl_serinfo', below.
 173    The `dls_name' member points to space in the buffer passed to `dlinfo'.  */
 174 typedef struct
 175 {
 176   char *dls_name;               /* Name of library search path directory.  */
 177   unsigned int dls_flags;       /* Indicates where this directory came from. */
 178 } Dl_serpath;
 179
 180 /* This is the structure that must be passed (by reference) to `dlinfo' for
 181    the RTLD_DI_SERINFO and RTLD_DI_SERINFOSIZE requests.  */
 182 typedef struct
 183 {
 184   size_t dls_size;              /* Size in bytes of the whole buffer.  */
 185   unsigned int dls_cnt;         /* Number of elements in `dls_serpath'.  */
 186   Dl_serpath dls_serpath[1];    /* Actually longer, dls_cnt elements.  */
 187 } Dl_serinfo;
 188 #endif
 189 #endif /* __USE_GNU */
 190
 191
 192 __END_DECLS
 193
 194 #endif  /* dlfcn.h */