Back to index

glibc  2.9
dlfcn.h
Go to the documentation of this file.
00001 /* User functions for run-time dynamic loading.
00002    Copyright (C) 1995-1999,2000,2001,2003,2004,2006
00003        Free Software Foundation, Inc.
00004    This file is part of the GNU C Library.
00005 
00006    The GNU C Library is free software; you can redistribute it and/or
00007    modify it under the terms of the GNU Lesser General Public
00008    License as published by the Free Software Foundation; either
00009    version 2.1 of the License, or (at your option) any later version.
00010 
00011    The GNU C Library is distributed in the hope that it will be useful,
00012    but WITHOUT ANY WARRANTY; without even the implied warranty of
00013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014    Lesser General Public License for more details.
00015 
00016    You should have received a copy of the GNU Lesser General Public
00017    License along with the GNU C Library; if not, write to the Free
00018    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
00019    02111-1307 USA.  */
00020 
00021 #ifndef       _DLFCN_H
00022 #define       _DLFCN_H 1
00023 
00024 #include <features.h>
00025 #define __need_size_t
00026 #include <stddef.h>
00027 
00028 /* Collect various system dependent definitions and declarations.  */
00029 #include <bits/dlfcn.h>
00030 
00031 
00032 #ifdef __USE_GNU
00033 /* If the first argument of `dlsym' or `dlvsym' is set to RTLD_NEXT
00034    the run-time address of the symbol called NAME in the next shared
00035    object is returned.  The "next" relation is defined by the order
00036    the shared objects were loaded.  */
00037 # define RTLD_NEXT   ((void *) -1l)
00038 
00039 /* If the first argument to `dlsym' or `dlvsym' is set to RTLD_DEFAULT
00040    the run-time address of the symbol called NAME in the global scope
00041    is returned.  */
00042 # define RTLD_DEFAULT       ((void *) 0)
00043 
00044 
00045 /* Type for namespace indeces.  */
00046 typedef long int Lmid_t;
00047 
00048 /* Special namespace ID values.  */
00049 # define LM_ID_BASE  0      /* Initial namespace.  */
00050 # define LM_ID_NEWLM -1     /* For dlmopen: request new namespace.  */
00051 #endif
00052 
00053 
00054 __BEGIN_DECLS
00055 
00056 /* Open the shared object FILE and map it in; return a handle that can be
00057    passed to `dlsym' to get symbol values from it.  */
00058 extern void *dlopen (__const char *__file, int __mode) __THROW;
00059 
00060 /* Unmap and close a shared object opened by `dlopen'.
00061    The handle cannot be used again after calling `dlclose'.  */
00062 extern int dlclose (void *__handle) __THROW __nonnull ((1));
00063 
00064 /* Find the run-time address in the shared object HANDLE refers to
00065    of the symbol called NAME.  */
00066 extern void *dlsym (void *__restrict __handle,
00067                   __const char *__restrict __name) __THROW __nonnull ((2));
00068 
00069 #ifdef __USE_GNU
00070 /* Like `dlopen', but request object to be allocated in a new namespace.  */
00071 extern void *dlmopen (Lmid_t __nsid, __const char *__file, int __mode) __THROW;
00072 
00073 /* Find the run-time address in the shared object HANDLE refers to
00074    of the symbol called NAME with VERSION.  */
00075 extern void *dlvsym (void *__restrict __handle,
00076                    __const char *__restrict __name,
00077                    __const char *__restrict __version)
00078      __THROW __nonnull ((2, 3));
00079 #endif
00080 
00081 /* When any of the above functions fails, call this function
00082    to return a string describing the error.  Each call resets
00083    the error string so that a following call returns null.  */
00084 extern char *dlerror (void) __THROW;
00085 
00086 
00087 #ifdef __USE_GNU
00088 /* Structure containing information about object searched using
00089    `dladdr'.  */
00090 typedef struct
00091 {
00092   __const char *dli_fname;  /* File name of defining object.  */
00093   void *dli_fbase;          /* Load address of that object.  */
00094   __const char *dli_sname;  /* Name of nearest symbol.  */
00095   void *dli_saddr;          /* Exact value of nearest symbol.  */
00096 } Dl_info;
00097 
00098 /* Fill in *INFO with the following information about ADDRESS.
00099    Returns 0 iff no shared object's segments contain that address.  */
00100 extern int dladdr (__const void *__address, Dl_info *__info)
00101      __THROW __nonnull ((2));
00102 
00103 /* Same as `dladdr', but additionally sets *EXTRA_INFO according to FLAGS.  */
00104 extern int dladdr1 (__const void *__address, Dl_info *__info,
00105                   void **__extra_info, int __flags) __THROW __nonnull ((2));
00106 
00107 /* These are the possible values for the FLAGS argument to `dladdr1'.
00108    This indicates what extra information is stored at *EXTRA_INFO.
00109    It may also be zero, in which case the EXTRA_INFO argument is not used.  */
00110 enum
00111   {
00112     /* Matching symbol table entry (const ElfNN_Sym *).  */
00113     RTLD_DL_SYMENT = 1,
00114 
00115     /* The object containing the address (struct link_map *).  */
00116     RTLD_DL_LINKMAP = 2
00117   };
00118 
00119 
00120 /* Get information about the shared object HANDLE refers to.
00121    REQUEST is from among the values below, and determines the use of ARG.
00122 
00123    On success, returns zero.  On failure, returns -1 and records an error
00124    message to be fetched with `dlerror'.  */
00125 extern int dlinfo (void *__restrict __handle,
00126                  int __request, void *__restrict __arg)
00127      __THROW __nonnull ((1, 3));
00128 
00129 /* These are the possible values for the REQUEST argument to `dlinfo'.  */
00130 enum
00131   {
00132     /* Treat ARG as `lmid_t *'; store namespace ID for HANDLE there.  */
00133     RTLD_DI_LMID = 1,
00134 
00135     /* Treat ARG as `struct link_map **';
00136        store the `struct link_map *' for HANDLE there.  */
00137     RTLD_DI_LINKMAP = 2,
00138 
00139     RTLD_DI_CONFIGADDR = 3, /* Unsupported, defined by Solaris.  */
00140 
00141     /* Treat ARG as `Dl_serinfo *' (see below), and fill in to describe the
00142        directories that will be searched for dependencies of this object.
00143        RTLD_DI_SERINFOSIZE fills in just the `dls_cnt' and `dls_size'
00144        entries to indicate the size of the buffer that must be passed to
00145        RTLD_DI_SERINFO to fill in the full information.  */
00146     RTLD_DI_SERINFO = 4,
00147     RTLD_DI_SERINFOSIZE = 5,
00148 
00149     /* Treat ARG as `char *', and store there the directory name used to
00150        expand $ORIGIN in this shared object's dependency file names.  */
00151     RTLD_DI_ORIGIN = 6,
00152 
00153     RTLD_DI_PROFILENAME = 7,       /* Unsupported, defined by Solaris.  */
00154     RTLD_DI_PROFILEOUT = 8, /* Unsupported, defined by Solaris.  */
00155 
00156     /* Treat ARG as `size_t *', and store there the TLS module ID
00157        of this object's PT_TLS segment, as used in TLS relocations;
00158        store zero if this object does not define a PT_TLS segment.  */
00159     RTLD_DI_TLS_MODID = 9,
00160 
00161     /* Treat ARG as `void **', and store there a pointer to the calling
00162        thread's TLS block corresponding to this object's PT_TLS segment.
00163        Store a null pointer if this object does not define a PT_TLS
00164        segment, or if the calling thread has not allocated a block for it.  */
00165     RTLD_DI_TLS_DATA = 10,
00166 
00167     RTLD_DI_MAX = 10,
00168   };
00169 
00170 
00171 /* This is the type of elements in `Dl_serinfo', below.
00172    The `dls_name' member points to space in the buffer passed to `dlinfo'.  */
00173 typedef struct
00174 {
00175   char *dls_name;           /* Name of library search path directory.  */
00176   unsigned int dls_flags;   /* Indicates where this directory came from. */
00177 } Dl_serpath;
00178 
00179 /* This is the structure that must be passed (by reference) to `dlinfo' for
00180    the RTLD_DI_SERINFO and RTLD_DI_SERINFOSIZE requests.  */
00181 typedef struct
00182 {
00183   size_t dls_size;          /* Size in bytes of the whole buffer.  */
00184   unsigned int dls_cnt;            /* Number of elements in `dls_serpath'.  */
00185   Dl_serpath dls_serpath[1];       /* Actually longer, dls_cnt elements.  */
00186 } Dl_serinfo;
00187 #endif /* __USE_GNU */
00188 
00189 
00190 __END_DECLS
00191 
00192 #endif /* dlfcn.h */