1/* User functions for run-time dynamic loading.
  2   Copyright (C) 1995-2025 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   <https://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#include <bits/dl_find_object.h>
 32
 33/* Type for namespace indices.  */
 34typedef long int Lmid_t;
 35
 36/* Special namespace ID values.  */
 37# define LM_ID_BASE	0	/* Initial namespace.  */
 38# define LM_ID_NEWLM	-1	/* For dlmopen: request new namespace.  */
 39#endif
 40
 41/* If the first argument of `dlsym' or `dlvsym' is set to RTLD_NEXT
 42   the run-time address of the symbol called NAME in the next shared
 43   object is returned.  The "next" relation is defined by the order
 44   the shared objects were loaded.  */
 45#define RTLD_NEXT	((void *) -1l)
 46
 47/* If the first argument to `dlsym' or `dlvsym' is set to RTLD_DEFAULT
 48   the run-time address of the symbol called NAME in the global scope
 49   is returned.  */
 50#define RTLD_DEFAULT	((void *) 0)
 51
 52__BEGIN_DECLS
 53
 54/* Open the shared object FILE and map it in; return a handle that can be
 55   passed to `dlsym' to get symbol values from it.  */
 56extern void *dlopen (const char *__file, int __mode) __THROWNL;
 57
 58/* Unmap and close a shared object opened by `dlopen'.
 59   The handle cannot be used again after calling `dlclose'.  */
 60extern int dlclose (void *__handle) __THROWNL __nonnull ((1));
 61
 62/* Find the run-time address in the shared object HANDLE refers to
 63   of the symbol called NAME.  */
 64extern void *dlsym (void *__restrict __handle,
 65		    const char *__restrict __name) __THROW __nonnull ((2));
 66
 67#ifdef __USE_GNU
 68/* Like `dlopen', but request object to be allocated in a new namespace.  */
 69extern void *dlmopen (Lmid_t __nsid, const char *__file, int __mode) __THROWNL;
 70
 71/* Find the run-time address in the shared object HANDLE refers to
 72   of the symbol called NAME with VERSION.  */
 73extern void *dlvsym (void *__restrict __handle,
 74		     const char *__restrict __name,
 75		     const char *__restrict __version)
 76     __THROW __nonnull ((2, 3));
 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.  */
 82extern char *dlerror (void) __THROW;
 83
 84
 85#ifdef __USE_GNU
 86/* Structure containing information about object searched using
 87   `dladdr'.  */
 88typedef 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.  */
 98extern int dladdr (const void *__address, Dl_info *__info)
 99     __THROW __nonnull ((2));
100
101/* Same as `dladdr', but additionally sets *EXTRA_INFO according to FLAGS.  */
102extern int dladdr1 (const void *__address, Dl_info *__info,
103		    void **__extra_info, int __flags) __THROW __nonnull ((2));
104
105/* These are the possible values for the FLAGS argument to `dladdr1'.
106   This indicates what extra information is stored at *EXTRA_INFO.
107   It may also be zero, in which case the EXTRA_INFO argument is not used.  */
108enum
109  {
110    /* Matching symbol table entry (const ElfNN_Sym *).  */
111    RTLD_DL_SYMENT = 1,
112
113    /* The object containing the address (struct link_map *).  */
114    RTLD_DL_LINKMAP = 2
115  };
116
117
118/* Get information about the shared object HANDLE refers to.
119   REQUEST is from among the values below, and determines the use of ARG.
120
121   On success, returns zero.  On failure, returns -1 and records an error
122   message to be fetched with `dlerror'.  */
123extern int dlinfo (void *__restrict __handle,
124		   int __request, void *__restrict __arg)
125     __THROW __nonnull ((1, 3));
126
127/* These are the possible values for the REQUEST argument to `dlinfo'.  */
128enum
129  {
130    /* Treat ARG as `lmid_t *'; store namespace ID for HANDLE there.  */
131    RTLD_DI_LMID = 1,
132
133    /* Treat ARG as `struct link_map **';
134       store the `struct link_map *' for HANDLE there.  */
135    RTLD_DI_LINKMAP = 2,
136
137    RTLD_DI_CONFIGADDR = 3,	/* Unsupported, defined by Solaris.  */
138
139    /* Treat ARG as `Dl_serinfo *' (see below), and fill in to describe the
140       directories that will be searched for dependencies of this object.
141       RTLD_DI_SERINFOSIZE fills in just the `dls_cnt' and `dls_size'
142       entries to indicate the size of the buffer that must be passed to
143       RTLD_DI_SERINFO to fill in the full information.  */
144    RTLD_DI_SERINFO = 4,
145    RTLD_DI_SERINFOSIZE = 5,
146
147    /* Treat ARG as `char *', and store there the directory name used to
148       expand $ORIGIN in this shared object's dependency file names.  */
149    RTLD_DI_ORIGIN = 6,
150
151    RTLD_DI_PROFILENAME = 7,	/* Unsupported, defined by Solaris.  */
152    RTLD_DI_PROFILEOUT = 8,	/* Unsupported, defined by Solaris.  */
153
154    /* Treat ARG as `size_t *', and store there the TLS module ID
155       of this object's PT_TLS segment, as used in TLS relocations;
156       store zero if this object does not define a PT_TLS segment.  */
157    RTLD_DI_TLS_MODID = 9,
158
159    /* Treat ARG as `void **', and store there a pointer to the calling
160       thread's TLS block corresponding to this object's PT_TLS segment.
161       Store a null pointer if this object does not define a PT_TLS
162       segment, or if the calling thread has not allocated a block for it.  */
163    RTLD_DI_TLS_DATA = 10,
164
165    /* Treat ARG as const ElfW(Phdr) **, and store the address of the
166       program header array at that location.  The dlinfo call returns
167       the number of program headers in the array.  */
168    RTLD_DI_PHDR = 11,
169
170    RTLD_DI_MAX = 11
171  };
172
173
174/* This is the type of elements in `Dl_serinfo', below.
175   The `dls_name' member points to space in the buffer passed to `dlinfo'.  */
176typedef struct
177{
178  char *dls_name;		/* Name of library search path directory.  */
179  unsigned int dls_flags;	/* Indicates where this directory came from. */
180} Dl_serpath;
181
182/* This is the structure that must be passed (by reference) to `dlinfo' for
183   the RTLD_DI_SERINFO and RTLD_DI_SERINFOSIZE requests.  */
184typedef struct
185{
186  size_t dls_size;		/* Size in bytes of the whole buffer.  */
187  unsigned int dls_cnt;		/* Number of elements in `dls_serpath'.  */
188# if __GNUC_PREREQ (3, 0)
189  /* The zero-length array avoids an unwanted array subscript check by
190     the compiler, while the surrounding anonymous union preserves the
191     historic size of the type.  At the time of writing, GNU C does
192     not support structs with flexible array members in unions.  */
193  __extension__ union
194  {
195    Dl_serpath dls_serpath[0]; /* Actually longer, dls_cnt elements.  */
196    Dl_serpath __dls_serpath_pad[1];
197  };
198# else
199  Dl_serpath dls_serpath[1];	/* Actually longer, dls_cnt elements.  */
200# endif
201} Dl_serinfo;
202
203struct dl_find_object
204{
205  __extension__ unsigned long long int dlfo_flags;
206  void *dlfo_map_start;		/* Beginning of mapping containing address.  */
207  void *dlfo_map_end;		/* End of mapping.  */
208  struct link_map *dlfo_link_map;
209  void *dlfo_eh_frame;		/* Exception handling data of the object.  */
210# if DLFO_STRUCT_HAS_EH_DBASE
211  void *dlfo_eh_dbase;		/* Base address for DW_EH_PE_datarel.  */
212#  if __WORDSIZE == 32
213  unsigned int __dlfo_eh_dbase_pad;
214#  endif
215# endif
216# if DLFO_STRUCT_HAS_EH_COUNT
217  int dlfo_eh_count;		/* Number of exception handling entries.  */
218  unsigned int __dlfo_eh_count_pad;
219# endif
220  void *dlfo_sframe;		/* SFrame stack trace data of the object.  */
221#if __WORDSIZE == 32
222  unsigned int __dlfo_sframe_pad;
223#endif
224  __extension__ unsigned long long int __dlfo_reserved[6];
225};
226
227/* If ADDRESS is found in an object, fill in *RESULT and return 0.
228   Otherwise, return -1.  */
229int _dl_find_object (void *__address, struct dl_find_object *__result) __THROW;
230
231/* SFrame stack trace data is valid.  */
232#define DLFO_FLAG_SFRAME      (1ULL << 0)
233
234#endif /* __USE_GNU */
235
236__END_DECLS
237
238#endif	/* dlfcn.h */