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