/*

 * CDDL HEADER START

 *

 * The contents of this file are subject to the terms of the

 * Common Development and Distribution License (the "License").

 * You may not use this file except in compliance with the License.

 *

 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE

 * or http://www.opensolaris.org/os/licensing.

 * See the License for the specific language governing permissions

 * and limitations under the License.

 *

 * When distributing Covered Code, include this CDDL HEADER in each

 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.

 * If applicable, add the following below this CDDL HEADER, with the

 * fields enclosed by brackets "[]" replaced with your own identifying

 * information: Portions Copyright [yyyy] [name of copyright owner]

 *

 * CDDL HEADER END

 */

/*

 */

#ifndef	_RTLD_H

#define	_RTLD_H

/*

 * Global include file for the runtime linker.

 */

#include <sys/mman.h>

#include <time.h>

#include <sgs.h>

#include <thread.h>

#include <synch.h>

#include <link.h>

#include <sys/avl.h>

#include <alist.h>

#include <libc_int.h>

#include <elfcap.h>

#ifdef	_SYSCALL32

#include <inttypes.h>

#endif

#ifdef	__cplusplus

extern "C" {

#endif

/*

 * We use rtld_ino_t instead of ino_t so that we can get

 * access to large inode values from 32-bit code.

 */

#ifdef _LP64

typedef ino_t		rtld_ino_t;

#else

typedef ino64_t		rtld_ino_t;

#endif

typedef struct rt_map	Rt_map;

typedef struct slookup	Slookup;

typedef struct sresult	Sresult;

/*

 * A binding descriptor.  Establishes the binding relationship between two

 * objects, the caller (originator) and the dependency (destination).

 *

 * Every relationship between two objects is tracked by a binding descriptor.

 * This descriptor is referenced from a link-map's DEPENDS and CALLERS lists.

 * Note, Aplist's are diagramed to fully expose the allocations required to

 * establish the data structure relationships.

 *

 *                                  Bnd_desc

 *                                 ----------

 *                    ------------| b_caller |

 *                   |            | b_depend | ----------

 *                   |            |          |           |

 *      Rt_map       |             ----------            |       Rt_map

 *    ----------     |                ^ ^                |     ----------

 *   |          | <--                 | |                 --> |          |

 *   |          |        --------     | |                     |          |

 *   | DEPENDS  | ----> |        |    | |     --------        |          |

 *   |          |       |        |    | |    |        | <---- | CALLERS  |

 *   |          |       |        | ---  |    |        |       |          |

 *   |          |       |        |       --- |        |       |          |

 *   |          |        --------            |        |       |          |

 *    ----------          Aplist              --------         ----------

 *                                             Aplist

 */

typedef struct {

	Rt_map		*b_caller;	/* caller (originator) of a binding */

	Rt_map		*b_depend;	/* dependency (destination) of a */

					/*	binding */

	uint_t		b_flags;	/* relationship of caller to the */

					/*	dependency */

} Bnd_desc;

#define	BND_NEEDED	0x0001		/* caller NEEDED the dependency */

#define	BND_REFER	0x0002		/* caller relocation references the */

					/*	dependency */

#define	BND_FILTER	0x0004		/* binding identifies filter, used */

					/*	for diagnostics only */

/*

 * Private structure for communication between rtld_db and rtld.

 *

 * We must bump the version number when ever an update in one of the

 * structures/fields that rtld_db reads is updated.  This hopefully permits

 * rtld_db implementations of the future to recognize core files produced on

 * older systems and deal with these core files accordingly.

 *

 * As of version 'R_RTLDDB_VERSION <= 2' the following fields were valid for

 * core file examination (basically the public Link_map):

 *

 *		ADDR()

 *		NAME()

 *		DYN()

 *		NEXT()

 *		PREV()

 *

 * Valid fields for R_RTLDDB_VERSION3

 *

 *		PATHNAME()

 *		PADSTART()

 *		PADIMLEN()

 *		MSIZE()

 *		FLAGS()

 *		FLAGS1()

 *

 * Valid fields for R_RTLDDB_VERSION4

 *

 *		TLSMODID()

 *

 * Valid fields for R_RTLDDB_VERSION5

 *

 *		Added rtld_flags & FLG_RT_RELOCED to stable flags range

 *

 * Valid fields for R_RTLDDB_VERSION6

 *

 *		rtd_dynlmlst converted from a List to APlist

 */

#define	R_RTLDDB_VERSION1	1	/* base version level - used for core */

					/*	file examination */

#define	R_RTLDDB_VERSION2	2	/* minor revision - not relevant for */

					/*	core files */

#define	R_RTLDDB_VERSION3	3

#define	R_RTLDDB_VERSION4	4

#define	R_RTLDDB_VERSION5	5

#define	R_RTLDDB_VERSION6	6

#define	R_RTLDDB_VERSION	R_RTLDDB_VERSION6	/* current version */

typedef struct rtld_db_priv {

	struct r_debug	rtd_rdebug;	/* original r_debug structure */

	Word		rtd_version;	/* version no. */

	size_t		rtd_objpad;	/* padding around mmap()ed objects */

	APlist		**rtd_dynlmlst;	/* pointer to dynlm_list pointer */

} Rtld_db_priv;

#ifdef _SYSCALL32

typedef struct rtld_db_priv32 {

	struct r_debug32 rtd_rdebug;	/* original r_debug structure */

	Elf32_Word	rtd_version;	/* version no. */

	Elf32_Word	rtd_objpad;	/* padding around mmap()ed objects */

	Elf32_Addr	rtd_dynlmlst;	/* pointer to dynlm_list */

} Rtld_db_priv32;

#endif	/* _SYSCALL32 */

/*

 * External function definitions.  ld.so.1 must convey information to libc in

 * regards to threading.  libc also provides routines for atexit() and message

 * localization.  libc provides the necessary interfaces via its RTLDINFO

 * structure and/or later _ld_libc() calls.

 *

 * These external functions are maintained for each link-map list, and used

 * where appropriate.  The functions are associated with the object that

 * provided them, so that should the object be deleted (say, from an alternative

 * link-map), the functions can be removed.

 */

typedef struct {

	Rt_map	*lc_lmp;			/* function provider */

	union {

		int		(*lc_func)();	/* external function pointer */

		uintptr_t	lc_val;		/* external value */

		char    	*lc_ptr;	/* external character pointer */

	} lc_un;

} Lc_desc;

/*

 * Link map list definition.  Link-maps are used to describe each loaded object.

 * Lists of these link-maps describe the various namespaces within a process.

 * The process executable and its dependencies are maintained on the lml_main

 * list.  The runtime linker, and its dependencies are maintained on the

 * lml_rtld list.  Additional lists can be created (see dlmopen()) for such

 * things as auditors and their dependencies.

 *

 * Each link-map list maintains an Alist of one, or more, linked lists of

 * link-maps.  For backward compatibility, the lm_head/lm_tail elements are

 * initialized to the first linked-list of link-maps:

 *

 *      Lm_list

 *    ----------

 *   | lm_tail  | ------------------------------------

 *   | lm_head  | --------------------                |

 *   |          |                     |     Rt_map    |     Rt_map

 *   |          |                     |     ------    |     ------

 *   |          |          Alist       --> |      |   |--> |      |

 *   |          |        ---------    |    |      | --     |      |

 *   | lm_lists | ----> |         |   |    |      |    --> |      |

 *   |          |       |---------|   |    |      |   |    |      |

 *   |          |       | lc_head | --      ------    |     ------

 *   |          |       | lc_tail | ------------------

 *   |          |       |---------|

 *    ----------        | lc_head |

 *                      | lc_tail |

 *                      |---------|

 *

 * Multiple link-map lists exist to support the addition of lazy loaded

 * families, filtee families, and dlopen() families.  The intent of these

 * lists is to insure that a family of objects that are to be loaded are

 * fully relocatable, and hence usable, before they become part of the main

 * (al_data[0]) link-map control list.  This main link-map control list is

 * the only list in existence when control is transferred to user code.

 *

 * During process initialization, the dynamic executable and its non-lazy

 * dependencies are maintained on al_data[0].  If a new object is loaded, then

 * this object is added to the next available control list [1], typically

 * al_data[1].  Any dependencies of this object that have not already been

 * loaded are added to the same control list.  Once all of the objects on the

 * new control list have been successfully relocated, the objects are moved from

 * the new control list to the highest control list to which objects of the new

 * control list bound to, typically al_data[1] to al_data[0].

 *

 * Each loading scenario can be broken down as follows:

 *

 *  setup() - only the initial link-map control list is used:

 *   i.	  create al_data[0]

 *   ii.  add new link-map for main on al_data[0]

 *   iii. analyze al_data[0] to add all non-lazy dependencies

 *   iv.  relocate al_data[0] dependencies.

 *

 *  dlopen() - the initiator can only be the initial link-map control list:

 *   i.   create al_data[1] from caller al_data[0]

 *   ii.  add new link-map for the dlopen'ed object on al_data[1]

 *   iii. analyze al_data[1] to add all non-lazy dependencies

 *   iv.  relocate al_data[1] dependencies, and move to al_data[0].

 *

 *  filtee and lazy loading processing - the initiator can be any link-map

 *  control list that is being relocated:

 *   i.   create al_data[y] from caller al_data[x]

 *   ii.  add new link-map for the new object on al_data[y]

 *   iii. analyze al_data[y] to add all non-lazy dependencies

 *   iv.  relocate al_data[y] dependencies, and move to al_data[x].

 *

 * This Alist therefore maintains a stack of link-map control lists.  The newest

 * link-map control list can locate symbols within any of the former lists,

 * however, control is not passed to a former list until the newest lists

 * processing is complete.  Thus, objects can't bind to new objects until they

 * have been fully analyzed and relocated.

 *

 * [1]  Note, additional link-map control list creation occurs after the head

 * link-map object (typically the dynamic executable) has been relocated.  This

 * staging is required to satisfy the binding requirements of copy relocations.

 * Copy relocations, effectively, transfer the bindings of the copied data

 * (say _iob in libc.so.1) to the copy location (_iob in the application).

 * Thus an object that might bind to the original copy data must be redirected

 * to the copy reference.  As the knowledge of a copy relocation having taken

 * place is only known after relocating the application, link-map control list

 * additions are suspended until after this relocation has completed.

 */

typedef struct {

	Rt_map		*lc_head;

	Rt_map		*lc_tail;

	APlist		*lc_now;	/* pending promoted bind-now objects */

	uint_t		lc_flags;

} Lm_cntl;

#define	LMC_FLG_ANALYZING	0x01	/* control list is being analyzed */

#define	LMC_FLG_RELOCATING	0x02	/* control list is being relocated */

#define	LMC_FLG_REANALYZE	0x04	/* repeat analysis (established when */

					/*	interposers are added */

struct lm_list {

	/*

	 * BEGIN: Exposed to rtld_db - don't move, don't delete

	 */

	Rt_map		*lm_head;	/* linked list pointers to active */

	Rt_map		*lm_tail;	/*	link-map list */

	APlist		*lm_handle;	/* not used by rtld_db - but spacing */

					/*	is required for flags */

	Word		lm_flags;

	/*

	 * END: Exposed to rtld_db - don't move, don't delete

	 */

	Alist		*lm_rti;	/* list of RTLDINFO tables */

	Audit_list	*lm_alp;	/* audit list descriptor */

	avl_tree_t	*lm_fpavl;	/* avl tree of objects loaded */

	Alist		*lm_lists;	/* active and pending link-map lists */

	char		***lm_environ;	/* pointer to environment array */

	Word		lm_tflags;	/* transferable flags */

	uint_t		lm_obj;		/* total number of objs on link-map */

	uint_t		lm_init;	/* new obj since last init processing */

	uint_t		lm_lazy;	/* number of objects with pending */

					/*	lazy dependencies */

	uint_t		lm_tls;		/* new obj that require TLS */

	uint_t		lm_lmid;	/* unique link-map list identifier, */

	char		*lm_lmidstr;	/* and associated diagnostic string */

	APlist		*lm_actaudit;	/* list of pending audit activity */

	Lc_desc		lm_lcs[CI_MAX];	/* external libc functions */

};

#ifdef	_SYSCALL32

struct lm_list32 {

	/*

	 * BEGIN: Exposed to rtld_db - don't move, don't delete

	 */

	Elf32_Addr	lm_head;

	Elf32_Addr	lm_tail;

	Elf32_Addr	lm_handle;

	Elf32_Word	lm_flags;

	/*

	 * END: Exposed to rtld_db - don't move, don't delete

	 */

	Elf32_Addr	lm_rti;

	Elf32_Addr	lm_fpavl;

	Elf32_Addr	lm_lists;

	Elf32_Addr	lm_environ;

	Elf32_Word	lm_tflags;

	uint_t		lm_obj;

	uint_t		lm_init;

	uint_t		lm_lazy;

	uint_t		lm_tls;

	uint_t		lm_lmid;

	Elf32_Addr	lm_lmidstr;

	Elf32_Addr	lm_actaudit;

	Elf32_Addr	lm_lcs[CI_MAX];

};

#endif /* _SYSCALL32 */

/*

 * Possible Link_map list flags (Lm_list.lm_flags)

 */

/*

 * BEGIN: Exposed to rtld_db - don't move, don't delete

 */

#define	LML_FLG_BASELM		0x00000001	/* primary link-map */

#define	LML_FLG_RTLDLM		0x00000002	/* rtld link-map */

/*

 * END: Exposed to rtld_db - don't move, don't delete

 */

#define	LML_FLG_NOAUDIT		0x00000004	/* symbol auditing disabled */

#define	LML_FLG_PLTREL		0x00000008	/* deferred plt relocation */

						/* 	initialization */

						/*	(ld.so.1 only) */

#define	LML_FLG_HOLDLOCK	0x00000010	/* hold the rtld mutex lock */

#define	LML_FLG_ENVIRON		0x00000020	/* environ var initialized */

#define	LML_FLG_INTRPOSE	0x00000040	/* interposing objs on list */

#define	LML_FLG_LOCAUDIT	0x00000080	/* local auditors exists for */

						/*	this link-map list */

#define	LML_FLG_LOADAVAIL	0x00000100	/* load anything available */

#define	LML_FLG_IGNRELERR	0x00000200	/* ignore relocation errors - */

						/*	internal for crle(1) */

#define	LML_FLG_DBNOTIF		0x00000400	/* binding activity going on */

#define	LML_FLG_STARTREL	0x00000800	/* relocation started */

#define	LML_FLG_ATEXIT		0x00001000	/* atexit processing */

#define	LML_FLG_OBJADDED	0x00002000	/* object(s) added */

#define	LML_FLG_OBJDELETED	0x00004000	/* object(s) deleted */

#define	LML_FLG_OBJREEVAL	0x00008000	/* existing object(s) needs */

						/*	tsort reevaluation */

#define	LML_FLG_INTRPOSETSORT	0x00020000	/* interpose tsorting done */

#define	LML_FLG_AUDITNOTIFY	0x00040000	/* audit consistent required */

#define	LML_FLG_GROUPSEXIST	0x00080000	/* local groups exist */

#define	LML_FLG_TRC_LDDSTUB	0x00100000	/* identify lddstub */

#define	LML_FLG_TRC_ENABLE	0x00200000	/* tracing enabled (ldd) */

#define	LML_FLG_TRC_WARN	0x00400000	/* print warnings for undefs */

#define	LML_FLG_TRC_VERBOSE	0x00800000	/* verbose (versioning) trace */

#define	LML_FLG_TRC_SEARCH	0x01000000	/* trace search paths */

#define	LML_FLG_TRC_UNREF	0x02000000	/* trace unreferenced */

						/*	dependencies */

#define	LML_FLG_TRC_UNUSED	0x04000000	/* trace unused dependencies */

#define	LML_FLG_TRC_INIT	0x08000000	/* print .init order */

#define	LML_FLG_TRC_NOUNRESWEAK	0x10000000	/* unresolved weak references */

						/*	are not allowed */

#define	LML_FLG_TRC_NOPAREXT	0x20000000	/* unresolved PARENT/EXTERN */

						/*	references are not */

						/*	allowed */

#define	LML_MSK_TRC		0xfff00000	/* tracing mask */

/*

 * Possible Link_map transferable flags (Lm_list.lm_tflags), i.e., link-map

 * list flags that can be propagated to any new link-map list created.

 */

#define	LML_TFLG_NOLAZYLD	0x00000001	/* lazy loading disabled */

#define	LML_TFLG_NODIRECT	0x00000002	/* direct bindings disabled */

#define	LML_TFLG_LOADFLTR	0x00000008	/* trigger filtee loading */

#define	LML_TFLG_AUD_PREINIT	0x00001000	/* preinit (audit) exists */

#define	LML_TFLG_AUD_OBJSEARCH	0x00002000	/* objsearch (audit) exists */

#define	LML_TFLG_AUD_OBJOPEN	0x00004000	/* objopen (audit) exists */

#define	LML_TFLG_AUD_OBJFILTER	0x00008000	/* objfilter (audit) exists */

#define	LML_TFLG_AUD_OBJCLOSE	0x00010000	/* objclose (audit) exists */

#define	LML_TFLG_AUD_SYMBIND	0x00020000	/* symbind (audit) exists */

#define	LML_TFLG_AUD_PLTENTER	0x00040000	/* pltenter (audit) exists */

#define	LML_TFLG_AUD_PLTEXIT	0x00080000	/* pltexit (audit) exists */

#define	LML_TFLG_AUD_ACTIVITY	0x00100000	/* activity (audit) exists */

/*

 * NOTE: Each auditing module establishes a set of audit flags, AFLAGS(), that

 * define the auditing interfaces the module offers.  These auditing flags are

 * the LML_TFLG_AUD_ flags defined above.  Global auditors result in setting

 * the lm_tflags too.  Local auditors only use the AFLAGS().  All tests for

 * auditing inspect the lm_tflags and AFLAGS() for a specific auditing

 * interface, and thus use the same flag to test for both types of auditors.

 */

#define	LML_TFLG_AUD_MASK	0x0ffff000	/* audit interfaces mask */

/*

 * Define a Group Handle.

 *

 * The capability of ld.so.1 to associate a group of objects, look for symbols

 * within that group, ensure that groups are isolated from one another (with

 * regard to relocations), and to unload a group, centers around a handle.

 *

 * Dependencies can be added to an existing handle as the dependencies are

 * lazily loaded.  The core dependencies on the handle are the ldd(1) list of

 * the referenced object.

 *

 * Handles can be created from:

 *

 *  -	a dlopen() request.  This associates a caller to a reference object,

 * 	and the referenced objects dependencies.  This group of objects can

 *	then be inspected for symbols (dlsym()).

 *  -	a filtering request.  This associates a filter (caller) to a referenced

 *	object (filtee).  The redirection of filter symbols to their filtee

 *	counterpart is essentially a dlsym() using the filtee's handle.

 *

 * The handle created for these events is referred to as a public handle.  This

 * handle tracks the referenced object, all of the dependencies of the

 * referenced object, and the caller (parent).

 *

 * Presently, an object may have two handles, one requested with RTLD_FIRST

 * and one without.

 *

 * A handle may be referenced by any number of callers (parents).  A reference

 * count tracks the number.  A dlclose() operation drops the reference count,

 * and when the count is zero, the handle is used to determine the family of

 * objects to unload.  As bindings may occur to objects on the handle from

 * other handles, it may not be possible to remove a complete family of objects

 * or the handle itself.  Handles in this state are moved to an orphan list.

 * A handle on the orphan list is taken off the orphan list if the associated

 * object is reopened.  Otherwise, the handle remains on the orphan list for

 * the duration of the process.  The orphan list is inspected any time objects

 * are unloaded, to determine if the orphaned objects can also be unloaded.

 *

 * Handles can also be created for internal uses:

 *

 *  -	to promote objects to RTLD_NOW.

 *  -	to establish families for symbol binding fallback, required when lazy

 *	loadable objects are still pending.

 *

 * The handle created for these events is referred to as a private handle.  This

 * handle does not need to track the caller (parent), and because of this, does

 * not need to be considered during dlclose() operations, as the handle can not

 * be referenced by callers outside of the referenced objects family.

 *

 * Note, a private handle is essentially a subset of a public handle.  Should

 * an internal operation require a private handle, and a public handle already

 * exist, the public handle can be used.  Should an external operation require

 * a public handle, and a private handle exist, the private handle is promoted

 * to a public handle.  Any handle that gets created will remain in existence

 * for the life time of the referenced object.

 *

 * Objects can be dlopened using RTLD_NOW.  This attribute requires that all

 * relocations of the object, and its dependencies are processed immediately,

 * before return to the caller.  Typically, an object is loaded without

 * RTLD_NOW, and procedure linkage relocations are satisfied when their

 * associated function is first called.  If an object is already loaded, and an

 * RTLD_NOW request is made, then the object, and its dependencies, most undergo

 * additional relocation processing.   This promotion from lazy binding to

 * immediate binding is carried out using handles, as the handle defines the

 * dependencies that must be processed.

 *

 * To ensure that objects within a lazy loadable environment can be relocated,

 * no matter whether the objects have their dependencies described completely,

 * a symbol lookup fallback is employed.  Any pending lazy loadable objects are

 * loaded, and a handle established to search the object and it's dependencies

 * for the required symbol.

 *

 * A group handle (and its associated group descriptors), is referenced from

 * a link-map's HANDLES and GROUPS lists.  Note, Aplist's are diagramed to

 * fully expose the allocations required to establish the data structure

 * relationships.

 *

 *                                  Grp_desc

 *                                   Alist

 *                                 -----------

 *                            --> |           |

 *                           |    |-----------|

 *                           |    | gd_depend | ---------

 *                           |    |           |          |

 *                           |    |-----------|          |

 *                   --------|--- | gd_depend |          |

 *                  |        |    | (parent)  |          |

 *                  |        |    |-----------|          |

 *                  |        |    | gd_depend |          |

 *                  |        |    |           |          |