dlfcn/dlfcn.h

   1 /* User functions for run-time dynamic loading.
   2    Copyright (C) 1995-1999,2000,2001,2003,2004 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, write to the Free
  17    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  18    02111-1307 USA.  */
  19
  20 #ifndef _DLFCN_H
  21 #define _DLFCN_H 1
  22
  23 #include <features.h>
  24 #define __need_size_t
  25 #include <stddef.h>
  26
  27 /* Collect various system dependent definitions and declarations.  */
  28 #include <bits/dlfcn.h>
  29
  30
  31 #ifdef __USE_GNU
  32 /* If the first argument of `dlsym' or `dlvsym' is set to RTLD_NEXT
  33    the run-time address of the symbol called NAME in the next shared
  34    object is returned.  The "next" relation is defined by the order
  35    the shared objects were loaded.  */
  36 # define RTLD_NEXT      ((void *) -1l)
  37
  38 /* If the first argument to `dlsym' or `dlvsym' is set to RTLD_DEFAULT
  39    the run-time address of the symbol called NAME in the global scope
  40    is returned.  */
  41 # define RTLD_DEFAULT   ((void *) 0)
  42
  43
  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
  52
  53 __BEGIN_DECLS
  54
  55 /* Open the shared object FILE and map it in; return a handle that can be
  56    passed to `dlsym' to get symbol values from it.  */
  57 extern void *dlopen (__const char *__file, int __mode) __THROW;
  58
  59 /* Unmap and close a shared object opened by `dlopen'.
  60    The handle cannot be used again after calling `dlclose'.  */
  61 extern int dlclose (void *__handle) __THROW;
  62
  63 /* Find the run-time address in the shared object HANDLE refers to
  64    of the symbol called NAME.  */
  65 extern void *dlsym (void *__restrict __handle,
  66                     __const char *__restrict __name) __THROW;
  67
  68 #ifdef __USE_GNU
  69 /* Like `dlopen', but request object to be allocated in a new namespace.  */
  70 extern void *dlmopen (Lmid_t __nsid, __const char *__file, int __mode) __THROW;
  71
  72 /* Find the run-time address in the shared object HANDLE refers to
  73    of the symbol called NAME with VERSION.  */
  74 extern void *dlvsym (void *__restrict __handle,
  75                      __const char *__restrict __name,
  76                      __const char *__restrict __version) __THROW;
  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) __THROW;
  99
 100 /* Same as `dladdr', but additionally sets *EXTRA_INFO according to FLAGS.  */
 101 extern int dladdr1 (__const void *__address, Dl_info *__info,
 102                     void **__extra_info, int __flags) __THROW;
 103
 104 /* These are the possible values for the FLAGS argument to `dladdr1'.
 105    This indicates what extra information is stored at *EXTRA_INFO.
 106    It may also be zero, in which case the EXTRA_INFO argument is not used.  */
 107 enum
 108   {
 109     /* Matching symbol table entry (const ElfNN_Sym *).  */
 110     RTLD_DL_SYMENT = 1,
 111
 112     /* The object containing the address (struct link_map *).  */
 113     RTLD_DL_LINKMAP = 2
 114   };
 115
 116
 117 /* Get information about the shared object HANDLE refers to.
 118    REQUEST is from among the values below, and determines the use of ARG.
 119
 120    On success, returns zero.  On failure, returns -1 and records an error
 121    message to be fetched with `dlerror'.  */
 122 extern int dlinfo (void *__restrict __handle,
 123                    int __request, void *__restrict __arg);
 124
 125 /* These are the possible values for the REQUEST argument to `dlinfo'.  */
 126 enum
 127   {
 128     /* Treat ARG as `lmid_t *'; store namespace ID for HANDLE there.  */
 129     RTLD_DI_LMID = 1,
 130
 131     /* Treat ARG as `struct link_map **';
 132        store the `struct link_map *' for HANDLE there.  */
 133     RTLD_DI_LINKMAP = 2,
 134
 135     /* Treat ARG as `Dl_serinfo *' (see below), and fill in to describe the
 136        directories that will be searched for dependencies of this object.
 137        RTLD_DI_SERINFOSIZE fills in just the `dls_cnt' and `dls_size'
 138        entries to indicate the size of the buffer that must be passed to
 139        RTLD_DI_SERINFO to fill in the full information.  */
 140     RTLD_DI_SERINFO = 4,
 141     RTLD_DI_SERINFOSIZE = 5,
 142
 143     /* Treat ARG as `char *', and store there the directory name used to
 144        expand $ORIGIN in this shared object's dependency file names.  */
 145     RTLD_DI_ORIGIN = 6,
 146
 147     RTLD_DI_CONFIGADDR = 3      /* Unsupported, defined by Solaris.  */
 148   };
 149
 150
 151 /* This is the type of elements in `Dl_serinfo', below.
 152    The `dls_name' member points to space in the buffer passed to `dlinfo'.  */
 153 typedef struct
 154 {
 155   char *dls_name;               /* Name of library search path directory.  */
 156   unsigned int dls_flags;       /* Indicates where this directory came from. */
 157 } Dl_serpath;
 158
 159 /* This is the structure that must be passed (by reference) to `dlinfo' for
 160    the RTLD_DI_SERINFO and RTLD_DI_SERINFOSIZE requests.  */
 161 typedef struct
 162 {
 163   size_t dls_size;              /* Size in bytes of the whole buffer.  */
 164   unsigned int dls_cnt;         /* Number of elements in `dls_serpath'.  */
 165   Dl_serpath dls_serpath[1];    /* Actually longer, dls_cnt elements.  */
 166 } Dl_serinfo;
 167 #endif /* __USE_GNU */
 168
 169
 170 __END_DECLS
 171
 172 #endif  /* dlfcn.h */