'\" te .\" Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved. .TH dlinfo 3C "16 December 2014" "SunOS 5.11" "Standard C Library Functions" .SH NAME dlinfo \- dynamic load information .SH SYNOPSIS .LP .nf #include #include #include #include \fBint\fR \fBdlinfo\fR(\fBvoid *\fR\fIhandle\fR, \fBint\fR \fIrequest\fR, \fBvoid *\fR\fIp\fR); .fi .SH DESCRIPTION .sp .LP The \fBdlinfo()\fR function sets or extracts information from the runtime linker \fBld.so.1\fR(1). This function is loosely modeled after the \fBioctl\fR(2) function. The \fIrequest\fR argument and a third argument of varying type are passed to \fBdlinfo()\fR. The action taken by \fBdlinfo()\fR depends on the value of the \fIrequest\fR that is provided. .sp .LP The \fIhandle\fR argument is either the value that is returned from a \fBdlopen\fR(3C) or \fBdlmopen()\fR call, or the special handle \fBRTLD_SELF\fR. A \fIhandle\fR argument is required for all requests except \fBRTLD_DI_GETSIGNAL\fR, and \fBRTLD_DI_SETSIGNAL\fR. If \fIhandle\fR is the value that is returned from a \fBdlopen()\fR or \fBdlmopen()\fR call, the information returned by the \fBdlinfo()\fR call pertains to the specified object. If \fIhandle\fR is the special handle \fBRTLD_SELF\fR, the information returned by the \fBdlinfo()\fR call pertains to the caller. .sp .LP The \fIrequest\fR argument can take the following values: .sp .ne 2 .mk .na \fB\fBRTLD_DI_ARGSINFO\fR\fR .ad .sp .6 .RS 4n Obtain process argument information. The \fIp\fR argument is a pointer (\fBDl_argsinfo_t *\fR\fIp\fR). The following elements from this structure are initialized: .sp .ne 2 .mk .na \fB\fBdla_argc\fR\fR .ad .RS 12n .rt The number of arguments passed to the process. .RE .sp .ne 2 .mk .na \fB\fBdla_argv\fR\fR .ad .RS 12n .rt The argument array passed to the process. .RE .sp .ne 2 .mk .na \fB\fBdla_envp\fR\fR .ad .RS 12n .rt The active environment variable array that is available to the process. This element initially points to the environment variable array that is made available to \fBexec\fR(2). This element can be updated should an alternative environment be established by the process. See \fBputenv\fR(3C). .RE .sp .ne 2 .mk .na \fB\fBdla_auxv\fR\fR .ad .RS 12n .rt The auxiliary vector array passed to the process. .RE A process can be established from executing the runtime linker directly from the command line. See \fBld.so.1\fR(1). The \fBDl_argsinfo_t\fR information reflects the information that is made available to the application regardless of how the runtime linker has been invoked. .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_LINKMAP\fR\fR .ad .sp .6 .RS 4n Obtain the \fBLink_map\fR for the \fIhandle\fR that is specified. The \fIp\fR argument points to a \fBLink_map\fR pointer (\fBLink_map **\fR\fIp\fR). The actual storage for the \fBLink_map\fR structure is maintained by \fBld.so.1\fR. .sp The \fBLink_map\fR structure includes the following members: .sp .in +2 .nf unsigned long l_addr; /* base address */ char *l_name; /* object name */ Elf32_Dyn *l_ld; /* .dynamic section */ Link_map *l_next; /* next link object */ Link_map *l_prev; /* previous link object */ char *l_refname; /* filter reference name */ .fi .in -2 .sp .ne 2 .mk .na \fB\fBl_addr\fR\fR .ad .RS 13n .rt The base address of the object loaded into memory. .RE .sp .ne 2 .mk .na \fB\fBl_name\fR\fR .ad .RS 13n .rt The full name of the loaded object. This full name is the filename of the object as referenced by \fBld.so.1\fR. .RE .sp .ne 2 .mk .na \fB\fBl_ld\fR\fR .ad .RS 13n .rt Points to the \fBSHT_DYNAMIC\fR structure. .RE .sp .ne 2 .mk .na \fB\fBl_next\fR\fR .ad .RS 13n .rt The next \fBLink_map\fR on the link-map list. Other objects on the same link-map list as the current object can be examined by following the \fBl_next\fR and \fBl_prev\fR members. .RE .sp .ne 2 .mk .na \fB\fBl_prev\fR\fR .ad .RS 13n .rt The previous \fBLink_map\fR on the link-map list. .RE .sp .ne 2 .mk .na \fB\fBl_refname\fR\fR .ad .RS 13n .rt If the object that is referenced is a \fIfilter\fR, this member points to the name of the object being filtered. If the object is not a \fIfilter\fR, this member is \fB0\fR. See \fIShared Objects as Filters\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_LMID\fR\fR .ad .sp .6 .RS 4n Obtain the \fBID\fR for the link-map list upon which the \fIhandle\fR is loaded. The \fIp\fR argument is a \fBLmid_t\fR pointer (\fBLmid_t *\fR\fIp\fR). .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_MMAPCNT\fR\fR .ad .sp .6 .RS 4n Determine the number of segment mappings for the \fIhandle\fR that is specified, for use in a \fBRTLD_DI_MMAPS\fR request. The \fIp\fR argument is a \fBuint_t\fR pointer (\fBuint_t *\fR\fIp\fR). On return from a \fBRTLD_DI_MMAPCNT\fR request, the \fBuint_t\fR value that is pointed to by \fIp\fR contains the number of segment mappings that the associated object uses. .sp To obtain the complete mapping information for an object, a \fBmmapobj_result_t\fR array for \fBRTLD_DI_MMAPCNT\fR entries must be provided. This array is assigned to the \fBdlm_maps\fR member, and the number of entries available in the array are assigned to the \fBdlm_acnt\fR member. This initialized structure is then passed to a \fBRTLD_DI_MMAPS\fR request. See \fBEXAMPLES\fR. .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_MMAPS\fR\fR .ad .sp .6 .RS 4n Obtain segment mapping information for the \fIhandle\fR that is specified. The \fIp\fR argument is a \fBDl_mapinfo_t\fR pointer (\fBDl_mapinfo_t *\fR\fIp\fR). This structure can be initialized from the mapping count obtained from a previous \fBRTLD_DI_MMAPCNT\fR request. .sp Segment mapping information is provided in an array of \fBmmapobj_result_t\fR structures that originate from the \fBmmapobj\fR(2) of the associated object. The \fBdlm_acnt\fR member, typically initialized from a previous \fBRTLD_DI_MMAPCNT\fR request, indicates the number of entries in a \fBmmapobj_result_t\fR array. This array is assigned to the \fBdlm_maps\fR member. This initialized structure is then passed to a \fBRTLD_DI_MMAPS\fR request, where the segment mapping information is copied to the \fBmmapobj_result_t\fR array. The \fBdlm_rcnt\fR member indicates the number of \fBmmapobj_result_t\fR element entries that are returned. See \fBEXAMPLES\fR. .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_SERINFO\fR\fR .ad .sp .6 .RS 4n Obtain the library search paths for the \fIhandle\fR that is specified. The \fIp\fR argument is a \fBDl_serinfo_t\fR pointer (\fBDl_serinfo_t *\fR\fIp\fR). A user must first initialize the \fBDl_serinfo_t\fR structure with a \fBRTLD_DI_SERINFOSIZE\fR request. See \fBEXAMPLES\fR. .sp The returned \fBDl_serinfo_t\fR structure contains \fBdls_cnt\fR \fBDl_serpath_t\fR entries. Each entry's \fBdlp_name\fR member points to the search path. The corresponding \fBdlp_info\fR member contains one of more flags indicating the origin of the path. See the \fBLA_SER_*\fR flags that are defined in <\fBlink.h\fR>. .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_SERINFOSIZE\fR\fR .ad .sp .6 .RS 4n Initialize a \fBDl_serinfo_t\fR structure for the \fIhandle\fR that is specified, for use in a \fBRTLD_DI_SERINFO\fR request. Both the \fBdls_cnt\fR and \fBdls_size\fR members are returned. The \fBdls_cnt\fR member indicates the number of search paths that are applicable to the \fIhandle\fR. The \fBdls_size\fR member indicates the total size of a \fBDl_serinfo_t\fR buffer required to hold \fBdls_cnt\fR \fBDl_serpath_t\fR entries and the associated search path strings. The \fIp\fR argument is a \fBDl_serinfo_t\fR pointer (\fBDl_serinfo_t *\fR\fIp\fR). .sp To obtain the complete path information, a new \fBDl_serinfo_t\fR buffer of size \fBdls_size\fR should be allocated. This new buffer should be initialized with the \fBdls_cnt\fR and \fBdls_size\fR entries. The initialized buffer is then passed to a \fBRTLD_DI_SERINFO\fR request. See \fBEXAMPLES\fR. .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_ORIGIN\fR\fR .ad .sp .6 .RS 4n Obtain the origin of the dynamic object that is associated with the \fIhandle\fR. The \fIp\fR argument is a \fBchar\fR pointer (\fBchar *\fR\fIp\fR). The \fBdirname\fR(3C) of the associated object's \fBrealpath\fR(3C), which can be no larger than {\fBPATH_MAX\fR}, is copied to the pointer \fIp\fR. .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_GETSIGNAL\fR\fR .ad .sp .6 .RS 4n Obtain the numeric signal number used by the runtime linker to kill the process in the event of a fatal runtime error. The \fIp\fR argument is an \fBint\fR pointer (\fBint *\fR\fIp\fR). The signal number is copied to the pointer \fIp\fR. .sp By default, the signal used by the runtime linker to terminate a process is \fBSIGKILL\fR. See \fBthr_kill\fR(3C). This default can be changed by calling \fBdlinfo()\fR with \fBRTLD_DI_SETSIGNAL\fR or by setting the environment variable \fBLD_SIGNAL\fR. See \fBld.so.1\fR(1). .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_SETSIGNAL\fR\fR .ad .sp .6 .RS 4n Provide a numeric signal number used by the runtime linker to kill the process in the event of a fatal runtime error. The \fIp\fR argument is an \fBint\fR pointer (\fBint *\fR\fIp\fR). The value pointed to by \fIp\fR is established as the terminating signal value. .sp The current signal number used by the runtime linker to terminate a process can be obtained from \fBdlinfo()\fR using \fBRTLD_DI_GETSIGNAL\fR. Use of the \fBRTLD_DI_SETSIGNAL\fR option is equivalent to setting the environment variable \fBLD_SIGNAL\fR. See \fBld.so.1\fR(1). .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_DEFERRED\fR\fR .ad .sp .6 .RS 4n Assign a new dependency name to an existing deferred dependency. The \fIp\fR argument is a \fBDl_definfo_t\fR pointer (\fBDl_definfo *\fR\fIp\fR). The \fBdlv_refname\fR field defines an existing dependency name. The \fBdlv_depname\fR field defines the new dependency name. .sp Dependency names are defined by \fBDT_NEEDED\fR dynamic entries, which can be displayed using the \fB-d\fR option of \fBelfdump\fR(1). Individual dependencies can be tagged as deferred. See the \fB-z\fR \fBdeferred\fR option of \fBld\fR(1). Deferred dependencies are only loaded during process execution, when the first binding to a deferred reference is made. Prior to a deferred dependency being loaded, the dependency name can be changed with \fBRTLD_DI_DEFERRED\fR. See also \fBRTLD_DI_DEFERRED_SYM\fR. .sp Once a deferred dependency is loaded, any attempt to change the dependency name with \fBdlinfo()\fR results in an error return of \(mi1. .RE .sp .ne 2 .mk .na \fB\fBRTLD_DI_DEFERRED_SYM\fR\fR .ad .sp .6 .RS 4n Assign a new dependency name to an existing deferred symbol, using a symbol reference that exists to the dependency. The \fIp\fR argument is a \fBDl_definfo_t\fR pointer (\fBDl_definfo *\fR\fIp\fR). The \fBdlv_refname\fR field defines a symbol reference to the deferred dependency. The \fBdlv_depname\fR field defines the new dependency name. .sp \fBRTLD_DI_DEFERRED_SYM\fR provides an alternative means of modifying a deferred dependency to using \fBRTLD_DI_DEFERRED\fR. One, or more symbol references can be associated with a deferred dependency. \fBRTLD_DI_DEFERRED_SYM\fR allows one of these deferred symbol references to be used to select the associated deferred dependency. Prior to a deferred dependency being loaded, the dependency name can be changed with \fBRTLD_DI_DEFERRED_SYM\fR. See \fBEXAMPLES\fR. .sp Once a deferred dependency is loaded, any attempt to change the dependency name with \fBdlinfo()\fR results in an error return of \(mi1. .RE .SH RETURN VALUES .sp .LP The \fBdlinfo()\fR function returns \(mi1 if the \fIrequest\fR is invalid, the parameter \fIp\fR is \fINULL\fR, or the \fBDl_serinfo_t\fR structure is uninitialized for a \fBRTLD_DI_SERINFO\fR request. \fBdlinfo()\fR also returns \(mi1 if the \fIhandle\fR argument does not refer to a valid object opened by \fBdlopen()\fR, or is not the special handle \fBRTLD_SELF\fR. Detailed diagnostic information is available with \fBdlerror\fR(3C). .SH EXAMPLES .LP \fBExample 1 \fRUse \fBdlinfo()\fR to obtain library search paths. .sp .LP The following example demonstrates how a dynamic object can inspect the library search paths that would be used to locate a simple filename with \fBdlopen()\fR. For simplicity, error checking has been omitted. .sp .in +2 .nf Dl_serinfo_t _info, *info = &_info; Dl_serpath_t *path; uint_t cnt; /* determine search path count and required buffer size */ dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, info); /* allocate new buffer and initialize */ info = malloc(_info.dls_size); info->dls_size = _info.dls_size; info->dls_cnt = _info.dls_cnt; /* obtain search path information */ dlinfo(RTLD_SELF, RTLD_DI_SERINFO, info); path = &info->dls_serpath[0]; for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) { (void) printf("%2d: %s\en", cnt, path->dls_name); } .fi .in -2 .LP \fBExample 2 \fRUse \fBdlinfo()\fR to obtain segment information. .sp .LP The following example demonstrates how a dynamic object can inspect its segment mapping information. For simplicity, error checking has been omitted .sp .in +2 .nf Dl_mapinfo_t mi; uint_t cnt; /* determine the number of segment mappings */ dlinfo(RTLD_SELF, RTLD_DI_MMAPCNT, &mi.dlm_acnt); /* allocate the appropriate mapping array */ mi.dlm_maps = malloc(mi.dlm_acnt * sizeof (mmapobj_result_t)); /* obtain the mapping information */ dlinfo(RTLD_SELF, RTLD_DI_MMAPS, &mi); for (cnt = 0; cnt < mi.dlm_rcnt; cnt++) { (void) printf("addr=%x - memory size=%x\en", mi.dlm_maps[cnt].mr_addr, mi.dlm_maps[cnt].mr_msize); } .fi .in -2 .LP \fBExample 3 \fRUse \fBdlinfo()\fR to change a deferred dependency. .sp .LP The following program defines a deferred dependency, \fBfoo.so\fR, and an associated deferred symbol reference, \fBfoo()\fR. .sp .in +2 .nf $ \fBelfdump -d main | egrep "NEEDED|POSFLAG\fR [0] POSFLAG_1 0x5 [ LAZY DEFERRED ] [1] NEEDED 0x17e foo.so $ \fBelfdump -y main | fgrep foo\fR [12] DBLP [1] foo.so foo .fi .in -2 .sp .sp .LP The program probes the existence of the symbol \fBfoo()\fR to verify that an associated deferred dependency exists. If the dependency does not exist, and hence the symbol can not be found, the program exchanges the deferred dependency associated with the symbol for a new dependency named \fBbar.so\fR. Following this exchange, the program once more probes for the existence of the symbol \fBfoo()\fRto verify that the new dependency can be loaded, and the symbol can be found. .sp .in +2 .nf if (dlsym(RTLD_PROBE, "foo") == NULL) { Dl_definfo_t info; info.dld_refname = "foo"; info.dld_depname = "bar.so"; if (dlinfo(RTLD_SELF, RTLD_DI_DEFERRED_SYM, &info) == -1) return (1); if (dlsym(RTLD_PROBE, "foo") == NULL) return (1); } foo(); .fi .in -2 .sp .LP A deferred dependency can only be exchanged before the dependency is loaded. If the dependency exists, then any probe would cause the dependency to be loaded, and any following exchange attempts would fail. To successfully exchange a deferred dependency that is expected to exist, a program must not probe for the symbol before making the exchange. .sp .in +2 .nf Dl_definfo_t info; info.dld_refname = "foo"; info.dld_depname = "bar.so"; if (dlinfo(RTLD_SELF, RTLD_DI_DEFERRED_SYM, &info) == -1) (void) printf("Using original dependency\en"); else (void) printf("Using new dependency: bar.so\en"); .fi .in -2 .SH USAGE .sp .LP The \fBdlinfo()\fR function is one of a family of functions that give the user direct access to the dynamic linking facilities. These facilities are available to dynamically-linked processes only. See the \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelMT-Safe .TE .SH SEE ALSO .sp .LP \fBelfdump\fR(1), \fBld\fR(1), \fBld.so.1\fR(1), \fBexec\fR(2), \fBioctl\fR(2), \fBmmapobj\fR(2), \fBdirname\fR(3C), \fBdlclose\fR(3C), \fBdldump\fR(3C), \fBdlerror\fR(3C), \fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBputenv\fR(3C), \fBrealpath\fR(3C), \fBthr_kill\fR(3C), \fBattributes\fR(5). .sp .LP \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR