[thirdparty/glibc.git] / dlfcn / dlfcn.h

/* User functions for run-time dynamic loading.
   Copyright (C) 1995-2024 Free Software Foundation, Inc.
   This file is part of the GNU C Library.

   The GNU C Library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   The GNU C Library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with the GNU C Library; if not, see
   <https://www.gnu.org/licenses/>.  */

#ifndef	_DLFCN_H
#define	_DLFCN_H 1

#include <features.h>
#define __need_size_t
#include <stddef.h>

/* Collect various system dependent definitions and declarations.  */
#include <bits/dlfcn.h>


#ifdef __USE_GNU
#include <bits/dl_find_object.h>

/* Type for namespace indices.  */
typedef long int Lmid_t;

/* Special namespace ID values.  */
# define LM_ID_BASE	0	/* Initial namespace.  */
# define LM_ID_NEWLM	-1	/* For dlmopen: request new namespace.  */
#endif

/* If the first argument of `dlsym' or `dlvsym' is set to RTLD_NEXT
   the run-time address of the symbol called NAME in the next shared
   object is returned.  The "next" relation is defined by the order
   the shared objects were loaded.  */
#define RTLD_NEXT	((void *) -1l)

/* If the first argument to `dlsym' or `dlvsym' is set to RTLD_DEFAULT
   the run-time address of the symbol called NAME in the global scope
   is returned.  */
#define RTLD_DEFAULT	((void *) 0)

__BEGIN_DECLS

/* Open the shared object FILE and map it in; return a handle that can be
   passed to `dlsym' to get symbol values from it.  */
extern void *dlopen (const char *__file, int __mode) __THROWNL;

/* Unmap and close a shared object opened by `dlopen'.
   The handle cannot be used again after calling `dlclose'.  */
extern int dlclose (void *__handle) __THROWNL __nonnull ((1));

/* Find the run-time address in the shared object HANDLE refers to
   of the symbol called NAME.  */
extern void *dlsym (void *__restrict __handle,
		    const char *__restrict __name) __THROW __nonnull ((2));

#ifdef __USE_GNU
/* Like `dlopen', but request object to be allocated in a new namespace.  */
extern void *dlmopen (Lmid_t __nsid, const char *__file, int __mode) __THROWNL;

/* Find the run-time address in the shared object HANDLE refers to
   of the symbol called NAME with VERSION.  */
extern void *dlvsym (void *__restrict __handle,
		     const char *__restrict __name,
		     const char *__restrict __version)
     __THROW __nonnull ((2, 3));
#endif

/* When any of the above functions fails, call this function
   to return a string describing the error.  Each call resets
   the error string so that a following call returns null.  */
extern char *dlerror (void) __THROW;


#ifdef __USE_GNU
/* Structure containing information about object searched using
   `dladdr'.  */
typedef struct
{
  const char *dli_fname;	/* File name of defining object.  */
  void *dli_fbase;		/* Load address of that object.  */
  const char *dli_sname;	/* Name of nearest symbol.  */
  void *dli_saddr;		/* Exact value of nearest symbol.  */
} Dl_info;

/* Fill in *INFO with the following information about ADDRESS.
   Returns 0 iff no shared object's segments contain that address.  */
extern int dladdr (const void *__address, Dl_info *__info)
     __THROW __nonnull ((2));

/* Same as `dladdr', but additionally sets *EXTRA_INFO according to FLAGS.  */
extern int dladdr1 (const void *__address, Dl_info *__info,
		    void **__extra_info, int __flags) __THROW __nonnull ((2));

/* These are the possible values for the FLAGS argument to `dladdr1'.
   This indicates what extra information is stored at *EXTRA_INFO.
   It may also be zero, in which case the EXTRA_INFO argument is not used.  */
enum
  {
    /* Matching symbol table entry (const ElfNN_Sym *).  */
    RTLD_DL_SYMENT = 1,

    /* The object containing the address (struct link_map *).  */
    RTLD_DL_LINKMAP = 2
  };


/* Get information about the shared object HANDLE refers to.
   REQUEST is from among the values below, and determines the use of ARG.

   On success, returns zero.  On failure, returns -1 and records an error
   message to be fetched with `dlerror'.  */
extern int dlinfo (void *__restrict __handle,
		   int __request, void *__restrict __arg)
     __THROW __nonnull ((1, 3));

/* These are the possible values for the REQUEST argument to `dlinfo'.  */
enum
  {
    /* Treat ARG as `lmid_t *'; store namespace ID for HANDLE there.  */
    RTLD_DI_LMID = 1,

    /* Treat ARG as `struct link_map **';
       store the `struct link_map *' for HANDLE there.  */
    RTLD_DI_LINKMAP = 2,

    RTLD_DI_CONFIGADDR = 3,	/* Unsupported, defined by Solaris.  */

    /* Treat ARG as `Dl_serinfo *' (see below), and fill in to describe the
       directories that will be searched for dependencies of this object.
       RTLD_DI_SERINFOSIZE fills in just the `dls_cnt' and `dls_size'
       entries to indicate the size of the buffer that must be passed to
       RTLD_DI_SERINFO to fill in the full information.  */
    RTLD_DI_SERINFO = 4,
    RTLD_DI_SERINFOSIZE = 5,

    /* Treat ARG as `char *', and store there the directory name used to
       expand $ORIGIN in this shared object's dependency file names.  */
    RTLD_DI_ORIGIN = 6,

    RTLD_DI_PROFILENAME = 7,	/* Unsupported, defined by Solaris.  */
    RTLD_DI_PROFILEOUT = 8,	/* Unsupported, defined by Solaris.  */

    /* Treat ARG as `size_t *', and store there the TLS module ID
       of this object's PT_TLS segment, as used in TLS relocations;
       store zero if this object does not define a PT_TLS segment.  */
    RTLD_DI_TLS_MODID = 9,

    /* Treat ARG as `void **', and store there a pointer to the calling
       thread's TLS block corresponding to this object's PT_TLS segment.
       Store a null pointer if this object does not define a PT_TLS
       segment, or if the calling thread has not allocated a block for it.  */
    RTLD_DI_TLS_DATA = 10,

    /* Treat ARG as const ElfW(Phdr) **, and store the address of the
       program header array at that location.  The dlinfo call returns
       the number of program headers in the array.  */
    RTLD_DI_PHDR = 11,

    RTLD_DI_MAX = 11
  };


/* This is the type of elements in `Dl_serinfo', below.
   The `dls_name' member points to space in the buffer passed to `dlinfo'.  */
typedef struct
{
  char *dls_name;		/* Name of library search path directory.  */
  unsigned int dls_flags;	/* Indicates where this directory came from. */
} Dl_serpath;

/* This is the structure that must be passed (by reference) to `dlinfo' for
   the RTLD_DI_SERINFO and RTLD_DI_SERINFOSIZE requests.  */
typedef struct
{
  size_t dls_size;		/* Size in bytes of the whole buffer.  */
  unsigned int dls_cnt;		/* Number of elements in `dls_serpath'.  */
# if __GNUC_PREREQ (3, 0)
  /* The zero-length array avoids an unwanted array subscript check by
     the compiler, while the surrounding anonymous union preserves the
     historic size of the type.  At the time of writing, GNU C does
     not support structs with flexible array members in unions.  */
  __extension__ union
  {
    Dl_serpath dls_serpath[0]; /* Actually longer, dls_cnt elements.  */
    Dl_serpath __dls_serpath_pad[1];
  };
# else
  Dl_serpath dls_serpath[1];	/* Actually longer, dls_cnt elements.  */
# endif
} Dl_serinfo;

struct dl_find_object
{
  __extension__ unsigned long long int dlfo_flags;
  void *dlfo_map_start;		/* Beginning of mapping containing address.  */
  void *dlfo_map_end;		/* End of mapping.  */
  struct link_map *dlfo_link_map;
  void *dlfo_eh_frame;		/* Exception handling data of the object.  */
# if DLFO_STRUCT_HAS_EH_DBASE
  void *dlfo_eh_dbase;		/* Base address for DW_EH_PE_datarel.  */
#  if __WORDSIZE == 32
  unsigned int __dlfo_eh_dbase_pad;
#  endif
# endif
# if DLFO_STRUCT_HAS_EH_COUNT
  int dlfo_eh_count;		/* Number of exception handling entries.  */
  unsigned int __dlfo_eh_count_pad;
# endif
  __extension__ unsigned long long int __dflo_reserved[7];
};

/* If ADDRESS is found in an object, fill in *RESULT and return 0.
   Otherwise, return -1.  */
int _dl_find_object (void *__address, struct dl_find_object *__result) __THROW;

#endif /* __USE_GNU */


__END_DECLS

#endif	/* dlfcn.h */
Commit	Line	Data
94e365c6	1	/* User functions for run-time dynamic loading.
dff8da6b	2	Copyright (C) 1995-2024 Free Software Foundation, Inc.
94e365c6 UD	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
41bdb6e2 AJ	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.
94e365c6 UD	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
41bdb6e2	13	Lesser General Public License for more details.
94e365c6	14
41bdb6e2	15	You should have received a copy of the GNU Lesser General Public
59ba27a6	16	License along with the GNU C Library; if not, see
5a82c748	17	<https://www.gnu.org/licenses/>. */
94e365c6 UD	18
	19	#ifndef _DLFCN_H
	20	#define _DLFCN_H 1
	21
	22	#include <features.h>
45e4762c RM	23	#define __need_size_t
45e4762c RM	24	#include <stddef.h>
94e365c6 UD	25
	26	/* Collect various system dependent definitions and declarations. */
	27	#include <bits/dlfcn.h>
	28
ca6c7389	29
70b2845f	30	#ifdef __USE_GNU
5d28a896 FW	31	#include <bits/dl_find_object.h>
5d28a896 FW	32
14ef9c18	33	/* Type for namespace indices. */
c0f62c56 UD	34	typedef 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. */
70b2845f	39	#endif
94e365c6	40
748df812 FS	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)
ca6c7389	51
94e365c6 UD	52	__BEGIN_DECLS
	53
	54	/* Open the shared object FILE and map it in; return a handle that can be
73299943	55	passed to `dlsym' to get symbol values from it. */
3b813b29	56	extern void dlopen (const char __file, int __mode) __THROWNL;
94e365c6 UD	57
	58	/* Unmap and close a shared object opened by `dlopen'.
	59	The handle cannot be used again after calling `dlclose'. */
3b813b29	60	extern int dlclose (void *__handle) __THROWNL __nonnull ((1));
94e365c6 UD	61
	62	/* Find the run-time address in the shared object HANDLE refers to
	63	of the symbol called NAME. */
c1422e5b	64	extern void dlsym (void __restrict __handle,
a784e502	65	const char *__restrict __name) __THROW __nonnull ((2));
94e365c6 UD	66
94e365c6 UD	67	#ifdef __USE_GNU
c0f62c56	68	/* Like `dlopen', but request object to be allocated in a new namespace. */
3b813b29	69	extern void dlmopen (Lmid_t __nsid, const char __file, int __mode) __THROWNL;
c0f62c56	70
94e365c6 UD	71	/* Find the run-time address in the shared object HANDLE refers to
94e365c6 UD	72	of the symbol called NAME with VERSION. */
c1422e5b	73	extern void dlvsym (void __restrict __handle,
a784e502 UD	74	const char *__restrict __name,
a784e502 UD	75	const char *__restrict __version)
b45ff182	76	__THROW __nonnull ((2, 3));
94e365c6 UD	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. */
c1422e5b	82	extern char *dlerror (void) __THROW;
94e365c6	83
ca6c7389	84
94e365c6	85	#ifdef __USE_GNU
dec126b4 UD	86	/* Structure containing information about object searched using
	87	`dladdr'. */
	88	typedef struct
	89	{
a784e502	90	const char dli_fname; / File name of defining object. */
dec126b4	91	void dli_fbase; / Load address of that object. */
a784e502	92	const char dli_sname; / Name of nearest symbol. */
dec126b4 UD	93	void dli_saddr; / Exact value of nearest symbol. */
	94	} Dl_info;
	95
94e365c6 UD	96	/* Fill in *INFO with the following information about ADDRESS.
94e365c6 UD	97	Returns 0 iff no shared object's segments contain that address. */
a784e502	98	extern int dladdr (const void __address, Dl_info __info)
b45ff182	99	__THROW __nonnull ((2));
8dd56993 RM	100
8dd56993 RM	101	/* Same as `dladdr', but additionally sets EXTRA_INFO according to FLAGS. /
a784e502	102	extern int dladdr1 (const void __address, Dl_info __info,
b45ff182	103	void **__extra_info, int __flags) __THROW __nonnull ((2));
8dd56993 RM	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. */
	108	enum
	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
45e4762c RM	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'. */
	123	extern int dlinfo (void *__restrict __handle,
b45ff182 UD	124	int __request, void *__restrict __arg)
b45ff182 UD	125	__THROW __nonnull ((1, 3));
45e4762c RM	126
	127	/* These are the possible values for the REQUEST argument to `dlinfo'. */
	128	enum
	129	{
c0f62c56 UD	130	/* Treat ARG as `lmid_t '; store namespace ID for HANDLE there. /
	131	RTLD_DI_LMID = 1,
	132
45e4762c RM	133	/* Treat ARG as `struct link_map **';
	134	store the `struct link_map ' for HANDLE there. /
	135	RTLD_DI_LINKMAP = 2,
	136
d78efd9f RM	137	RTLD_DI_CONFIGADDR = 3, /* Unsupported, defined by Solaris. */
d78efd9f RM	138
45e4762c RM	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
d78efd9f RM	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
d056c212 FW	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
45e4762c RM	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'. */
	176	typedef 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. */
	184	typedef 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'. */
fabf5e49 FW	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
45e4762c	199	Dl_serpath dls_serpath[1]; /* Actually longer, dls_cnt elements. */
fabf5e49	200	# endif
45e4762c	201	} Dl_serinfo;
5d28a896 FW	202
	203	struct 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	__extension__ unsigned long long int __dflo_reserved[7];
	221	};
	222
	223	/* If ADDRESS is found in an object, fill in *RESULT and return 0.
	224	Otherwise, return -1. */
	225	int _dl_find_object (void __address, struct dl_find_object __result) __THROW;
	226
45e4762c RM	227	#endif /* __USE_GNU */
45e4762c RM	228
94e365c6 UD	229
	230	__END_DECLS
	231
	232	#endif /* dlfcn.h */