* elf/tst-tls-dlinfo.c: New file.
[platform/upstream/glibc.git] / dlfcn / dlfcn.h
1 /* User functions for run-time dynamic loading.
2    Copyright (C) 1995-1999,2000,2001,2003,2004,2006
3         Free Software Foundation, Inc.
4    This file is part of the GNU C Library.
5
6    The GNU C Library is free software; you can redistribute it and/or
7    modify it under the terms of the GNU Lesser General Public
8    License as published by the Free Software Foundation; either
9    version 2.1 of the License, or (at your option) any later version.
10
11    The GNU C Library is distributed in the hope that it will be useful,
12    but WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14    Lesser General Public License for more details.
15
16    You should have received a copy of the GNU Lesser General Public
17    License along with the GNU C Library; if not, write to the Free
18    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
19    02111-1307 USA.  */
20
21 #ifndef _DLFCN_H
22 #define _DLFCN_H 1
23
24 #include <features.h>
25 #define __need_size_t
26 #include <stddef.h>
27
28 /* Collect various system dependent definitions and declarations.  */
29 #include <bits/dlfcn.h>
30
31
32 #ifdef __USE_GNU
33 /* If the first argument of `dlsym' or `dlvsym' is set to RTLD_NEXT
34    the run-time address of the symbol called NAME in the next shared
35    object is returned.  The "next" relation is defined by the order
36    the shared objects were loaded.  */
37 # define RTLD_NEXT      ((void *) -1l)
38
39 /* If the first argument to `dlsym' or `dlvsym' is set to RTLD_DEFAULT
40    the run-time address of the symbol called NAME in the global scope
41    is returned.  */
42 # define RTLD_DEFAULT   ((void *) 0)
43
44
45 /* Type for namespace indeces.  */
46 typedef long int Lmid_t;
47
48 /* Special namespace ID values.  */
49 # define LM_ID_BASE     0       /* Initial namespace.  */
50 # define LM_ID_NEWLM    -1      /* For dlmopen: request new namespace.  */
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 #ifdef __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 /* Same as `dladdr', but additionally sets *EXTRA_INFO according to FLAGS.  */
104 extern int dladdr1 (__const void *__address, Dl_info *__info,
105                     void **__extra_info, int __flags) __THROW __nonnull ((2));
106
107 /* These are the possible values for the FLAGS argument to `dladdr1'.
108    This indicates what extra information is stored at *EXTRA_INFO.
109    It may also be zero, in which case the EXTRA_INFO argument is not used.  */
110 enum
111   {
112     /* Matching symbol table entry (const ElfNN_Sym *).  */
113     RTLD_DL_SYMENT = 1,
114
115     /* The object containing the address (struct link_map *).  */
116     RTLD_DL_LINKMAP = 2
117   };
118
119
120 /* Get information about the shared object HANDLE refers to.
121    REQUEST is from among the values below, and determines the use of ARG.
122
123    On success, returns zero.  On failure, returns -1 and records an error
124    message to be fetched with `dlerror'.  */
125 extern int dlinfo (void *__restrict __handle,
126                    int __request, void *__restrict __arg)
127      __THROW __nonnull ((1, 3));
128
129 /* These are the possible values for the REQUEST argument to `dlinfo'.  */
130 enum
131   {
132     /* Treat ARG as `lmid_t *'; store namespace ID for HANDLE there.  */
133     RTLD_DI_LMID = 1,
134
135     /* Treat ARG as `struct link_map **';
136        store the `struct link_map *' for HANDLE there.  */
137     RTLD_DI_LINKMAP = 2,
138
139     RTLD_DI_CONFIGADDR = 3,     /* Unsupported, defined by Solaris.  */
140
141     /* Treat ARG as `Dl_serinfo *' (see below), and fill in to describe the
142        directories that will be searched for dependencies of this object.
143        RTLD_DI_SERINFOSIZE fills in just the `dls_cnt' and `dls_size'
144        entries to indicate the size of the buffer that must be passed to
145        RTLD_DI_SERINFO to fill in the full information.  */
146     RTLD_DI_SERINFO = 4,
147     RTLD_DI_SERINFOSIZE = 5,
148
149     /* Treat ARG as `char *', and store there the directory name used to
150        expand $ORIGIN in this shared object's dependency file names.  */
151     RTLD_DI_ORIGIN = 6,
152
153     RTLD_DI_PROFILENAME = 7,    /* Unsupported, defined by Solaris.  */
154     RTLD_DI_PROFILEOUT = 8,     /* Unsupported, defined by Solaris.  */
155
156     /* Treat ARG as `size_t *', and store there the TLS module ID
157        of this object's PT_TLS segment, as used in TLS relocations;
158        store zero if this object does not define a PT_TLS segment.  */
159     RTLD_DI_TLS_MODID = 9,
160
161     /* Treat ARG as `void **', and store there a pointer to the calling
162        thread's TLS block corresponding to this object's PT_TLS segment.
163        Store a null pointer if this object does not define a PT_TLS
164        segment, or if the calling thread has not allocated a block for it.  */
165     RTLD_DI_TLS_DATA = 10,
166
167     RTLD_DI_MAX = 10,
168   };
169
170
171 /* This is the type of elements in `Dl_serinfo', below.
172    The `dls_name' member points to space in the buffer passed to `dlinfo'.  */
173 typedef struct
174 {
175   char *dls_name;               /* Name of library search path directory.  */
176   unsigned int dls_flags;       /* Indicates where this directory came from. */
177 } Dl_serpath;
178
179 /* This is the structure that must be passed (by reference) to `dlinfo' for
180    the RTLD_DI_SERINFO and RTLD_DI_SERINFOSIZE requests.  */
181 typedef struct
182 {
183   size_t dls_size;              /* Size in bytes of the whole buffer.  */
184   unsigned int dls_cnt;         /* Number of elements in `dls_serpath'.  */
185   Dl_serpath dls_serpath[1];    /* Actually longer, dls_cnt elements.  */
186 } Dl_serinfo;
187 #endif /* __USE_GNU */
188
189
190 __END_DECLS
191
192 #endif  /* dlfcn.h */