diff options
Diffstat (limited to 'man7/rtld-audit.7')
| -rw-r--r-- | man7/rtld-audit.7 | 606 |
1 files changed, 0 insertions, 606 deletions
diff --git a/man7/rtld-audit.7 b/man7/rtld-audit.7 deleted file mode 100644 index 0aab7ca18..000000000 --- a/man7/rtld-audit.7 +++ /dev/null @@ -1,606 +0,0 @@ -.\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk -.\" <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" 2009-01-12, mtk, Created -.\" -.TH RTLD-AUDIT 7 (date) "Linux man-pages (unreleased)" -.SH NAME -rtld\-audit \- auditing API for the dynamic linker -.SH SYNOPSIS -.nf -.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" -.B #include <link.h> -.fi -.SH DESCRIPTION -The GNU dynamic linker (run-time linker) -provides an auditing API that allows an application -to be notified when various dynamic linking events occur. -This API is very similar to the auditing interface provided by the -Solaris run-time linker. -The necessary constants and prototypes are defined by including -.IR <link.h> . -.P -To use this interface, the programmer creates a shared library -that implements a standard set of function names. -Not all of the functions need to be implemented: in most cases, -if the programmer is not interested in a particular class of auditing event, -then no implementation needs to be provided for the corresponding -auditing function. -.P -To employ the auditing interface, the environment variable -.B LD_AUDIT -must be defined to contain a colon-separated list of shared libraries, -each of which can implement (parts of) the auditing API. -When an auditable event occurs, -the corresponding function is invoked in each library, -in the order that the libraries are listed. -.SS la_version() -\& -.nf -.BI "unsigned int la_version(unsigned int " version ); -.fi -.P -This is the only function that -.I must -be defined by an auditing library: -it performs the initial handshake between the dynamic linker and -the auditing library. -When invoking this function, the dynamic linker passes, in -.IR version , -the highest version of the auditing interface that the linker supports. -.P -A typical implementation of this function simply returns the constant -.BR LAV_CURRENT , -which indicates the version of -.I <link.h> -that was used to build the audit module. -If the dynamic linker does -not support this version of the audit interface, it will refuse to -activate this audit module. -If the function returns zero, the dynamic -linker also does not activate this audit module. -.P -In order to enable backwards compatibility with older dynamic linkers, -an audit module can examine the -.I version -argument and return an earlier version than -.BR LAV_CURRENT , -assuming the module can adjust its implementation to match the -requirements of the previous version of the audit interface. -The -.B la_version -function should not return the value of -.I version -without further checks because it could correspond to an interface -that does not match the -.I <link.h> -definitions used to build the audit module. -.SS la_objsearch() -\& -.nf -.BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie , -.BI " unsigned int " flag ); -.fi -.P -The dynamic linker invokes this function to inform the auditing library -that it is about to search for a shared object. -The -.I name -argument is the filename or pathname that is to be searched for. -.I cookie -identifies the shared object that initiated the search. -.I flag -is set to one of the following values: -.TP 17 -.B LA_SER_ORIG -This is the original name that is being searched for. -Typically, this name comes from an ELF -.B DT_NEEDED -entry, or is the -.I filename -argument given to -.BR dlopen (3). -.TP -.B LA_SER_LIBPATH -.I name -was created using a directory specified in -.BR LD_LIBRARY_PATH . -.TP -.B LA_SER_RUNPATH -.I name -was created using a directory specified in an ELF -.B DT_RPATH -or -.B DT_RUNPATH -list. -.TP -.B LA_SER_CONFIG -.I name -was found via the -.BR ldconfig (8) -cache -.RI ( /etc/ld.so.cache ). -.TP -.B LA_SER_DEFAULT -.I name -was found via a search of one of the default directories. -.TP -.B LA_SER_SECURE -.I name -is specific to a secure object (unused on Linux). -.P -As its function result, -.BR la_objsearch () -returns the pathname that the dynamic linker should use -for further processing. -If NULL is returned, then this pathname is ignored for further processing. -If this audit library simply intends to monitor search paths, then -.I name -should be returned. -.SS la_activity() -\& -.nf -.BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag ); -.fi -.P -The dynamic linker calls this function to inform the auditing library -that link-map activity is occurring. -.I cookie -identifies the object at the head of the link map. -When the dynamic linker invokes this function, -.I flag -is set to one of the following values: -.TP 19 -.B LA_ACT_ADD -New objects are being added to the link map. -.TP -.B LA_ACT_DELETE -Objects are being removed from the link map. -.TP -.B LA_ACT_CONSISTENT -Link-map activity has been completed: the map is once again consistent. -.SS la_objopen() -\& -.nf -.BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid , -.BI " uintptr_t *" cookie ); -.fi -.P -The dynamic linker calls this function when a new shared object is loaded. -The -.I map -argument is a pointer to a link-map structure that describes the object. -The -.I lmid -field has one of the following values -.TP 17 -.B LM_ID_BASE -Link map is part of the initial namespace. -.TP -.B LM_ID_NEWLM -Link map is part of a new namespace requested via -.BR dlmopen (3). -.P -.I cookie -is a pointer to an identifier for this object. -The identifier is provided to later calls to functions -in the auditing library in order to identify this object. -This identifier is initialized to point to object's link map, -but the audit library can change the identifier to some other value -that it may prefer to use to identify the object. -.P -As its return value, -.BR la_objopen () -returns a bit mask created by ORing zero or more of the -following constants, -which allow the auditing library to select the objects to be monitored by -.BR la_symbind* (): -.TP 17 -.B LA_FLG_BINDTO -Audit symbol bindings to this object. -.TP -.B LA_FLG_BINDFROM -Audit symbol bindings from this object. -.P -A return value of 0 from -.BR la_objopen () -indicates that no symbol bindings should be audited for this object. -.SS la_objclose() -\& -.nf -.BI "unsigned int la_objclose(uintptr_t *" cookie ); -.fi -.P -The dynamic linker invokes this function after any finalization -code for the object has been executed, -before the object is unloaded. -The -.I cookie -argument is the identifier obtained from a previous invocation of -.BR la_objopen (). -.P -In the current implementation, the value returned by -.BR la_objclose () -is ignored. -.SS la_preinit() -\& -.nf -.BI "void la_preinit(uintptr_t *" cookie ); -.fi -.P -The dynamic linker invokes this function after all shared objects -have been loaded, before control is passed to the application -(i.e., before calling -.IR main ()). -Note that -.IR main () -may still later dynamically load objects using -.BR dlopen (3). -.SS la_symbind*() -\& -.nf -.BI "uintptr_t la_symbind32(Elf32_Sym *" sym ", unsigned int " ndx , -.BI " uintptr_t *" refcook ", uintptr_t *" defcook , -.BI " unsigned int *" flags ", const char *" symname ); -.BI "uintptr_t la_symbind64(Elf64_Sym *" sym ", unsigned int " ndx , -.BI " uintptr_t *" refcook ", uintptr_t *" defcook , -.BI " unsigned int *" flags ", const char *" symname ); -.fi -.P -The dynamic linker invokes one of these functions -when a symbol binding occurs between two shared objects -that have been marked for auditing notification by -.BR la_objopen (). -The -.BR la_symbind32 () -function is employed on 32-bit platforms; -the -.BR la_symbind64 () -function is employed on 64-bit platforms. -.P -The -.I sym -argument is a pointer to a structure -that provides information about the symbol being bound. -The structure definition is shown in -.IR <elf.h> . -Among the fields of this structure, -.I st_value -indicates the address to which the symbol is bound. -.P -The -.I ndx -argument gives the index of the symbol in the symbol table -of the bound shared object. -.P -The -.I refcook -argument identifies the shared object that is making the symbol reference; -this is the same identifier that is provided to the -.BR la_objopen () -function that returned -.BR LA_FLG_BINDFROM . -The -.I defcook -argument identifies the shared object that defines the referenced symbol; -this is the same identifier that is provided to the -.BR la_objopen () -function that returned -.BR LA_FLG_BINDTO . -.P -The -.I symname -argument points a string containing the name of the symbol. -.P -The -.I flags -argument is a bit mask that both provides information about the symbol -and can be used to modify further auditing of this -PLT (Procedure Linkage Table) entry. -The dynamic linker may supply the following bit values in this argument: -.\" LA_SYMB_STRUCTCALL appears to be unused -.TP 22 -.B LA_SYMB_DLSYM -The binding resulted from a call to -.BR dlsym (3). -.TP -.B LA_SYMB_ALTVALUE -A previous -.BR la_symbind* () -call returned an alternate value for this symbol. -.P -By default, if the auditing library implements -.BR la_pltenter () -and -.BR la_pltexit () -functions (see below), then these functions are invoked, after -.BR la_symbind (), -for PLT entries, each time the symbol is referenced. -.\" pltenter/pltexit are called for non-dynamically loaded libraries, -.\" but don't seem to be called for dynamically loaded libs? -.\" Is this the same on Solaris? -The following flags can be ORed into -.I *flags -to change this default behavior: -.TP 22 -.B LA_SYMB_NOPLTENTER -Don't call -.BR la_pltenter () -for this symbol. -.TP 22 -.B LA_SYMB_NOPLTEXIT -Don't call -.BR la_pltexit () -for this symbol. -.P -The return value of -.BR la_symbind32 () -and -.BR la_symbind64 () -is the address to which control should be passed after the function returns. -If the auditing library is simply monitoring symbol bindings, -then it should return -.IR sym\->st_value . -A different value may be returned if the library wishes to direct control -to an alternate location. -.SS la_pltenter() -The precise name and argument types for this function -depend on the hardware platform. -(The appropriate definition is supplied by -.IR <link.h> .) -Here is the definition for x86-32: -.P -.nf -.BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx , -.BI " uintptr_t *" refcook ", uintptr_t *" defcook , -.BI " La_i86_regs *" regs ", unsigned int *" flags , -.BI " const char *" symname ", long *" framesizep ); -.fi -.P -This function is invoked just before a PLT entry is called, -between two shared objects that have been marked for binding notification. -.P -The -.IR sym , -.IR ndx , -.IR refcook , -.IR defcook , -and -.I symname -are as for -.BR la_symbind* (). -.P -The -.I regs -argument points to a structure (defined in -.IR <link.h> ) -containing the values of registers to be used for -the call to this PLT entry. -.P -The -.I flags -argument points to a bit mask that conveys information about, -and can be used to modify subsequent auditing of, this PLT entry, as for -.BR la_symbind* (). -.P -.\" FIXME . Is the following correct? -The -.I framesizep -argument points to a -.I long\~int -buffer that can be used to explicitly set the frame size -used for the call to this PLT entry. -If different -.BR la_pltenter () -invocations for this symbol return different values, -then the maximum returned value is used. -The -.BR la_pltexit () -function is called only if this buffer is -explicitly set to a suitable value. -.P -The return value of -.BR la_pltenter () -is as for -.BR la_symbind* (). -.SS la_pltexit() -The precise name and argument types for this function -depend on the hardware platform. -(The appropriate definition is supplied by -.IR <link.h> .) -Here is the definition for x86-32: -.P -.nf -.BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx , -.BI " uintptr_t *" refcook ", uintptr_t *" defcook , -.BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs , -.BI " const char *" symname ); -.fi -.P -This function is called when a PLT entry, -made between two shared objects that have been marked -for binding notification, returns. -The function is called just before control returns to the caller -of the PLT entry. -.P -The -.IR sym , -.IR ndx , -.IR refcook , -.IR defcook , -and -.I symname -are as for -.BR la_symbind* (). -.P -The -.I inregs -argument points to a structure (defined in -.IR <link.h> ) -containing the values of registers used for the call to this PLT entry. -The -.I outregs -argument points to a structure (defined in -.IR <link.h> ) -containing return values for the call to this PLT entry. -These values can be modified by the caller, -and the changes will be visible to the caller of the PLT entry. -.P -In the current GNU implementation, the return value of -.BR la_pltexit () -is ignored. -.\" This differs from Solaris, where an audit library that monitors -.\" symbol binding should return the value of the 'retval' argument -.\" (not provided by GNU, but equivalent to returning outregs->lrv_eax -.\" on (say) x86-32). -.SH VERSIONS -This API is very similar to the Solaris API -described in the Solaris -.IR "Linker and Libraries Guide" , -in the chapter -.IR "Runtime Linker Auditing Interface" . -.SH STANDARDS -None. -.SH NOTES -Note the following differences from the Solaris dynamic linker -auditing API: -.IP \[bu] 3 -The Solaris -.BR la_objfilter () -interface is not supported by the GNU implementation. -.IP \[bu] -The Solaris -.BR la_symbind32 () -and -.BR la_pltexit () -functions do not provide a -.I symname -argument. -.IP \[bu] -The Solaris -.BR la_pltexit () -function does not provide -.I inregs -and -.I outregs -arguments (but does provide a -.I retval -argument with the function return value). -.SH BUGS -In glibc versions up to and include 2.9, -specifying more than one audit library in -.B LD_AUDIT -results in a run-time crash. -This is reportedly fixed in glibc 2.10. -.\" FIXME . Specifying multiple audit libraries doesn't work on GNU. -.\" My simple tests on Solaris work okay, but not on Linux -- mtk, Jan 2009 -.\" glibc bug filed: http://sourceware.org/bugzilla/show_bug.cgi?id=9733 -.\" Reportedly, this is fixed on 16 Mar 2009 (i.e., for glibc 2.10) -.SH EXAMPLES -.EX -#include <link.h> -#include <stdio.h> -\& -unsigned int -la_version(unsigned int version) -{ - printf("la_version(): version = %u; LAV_CURRENT = %u\en", - version, LAV_CURRENT); -\& - return LAV_CURRENT; -} -\& -char * -la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag) -{ - printf("la_objsearch(): name = %s; cookie = %p", name, cookie); - printf("; flag = %s\en", - (flag == LA_SER_ORIG) ? "LA_SER_ORIG" : - (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" : - (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" : - (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" : - (flag == LA_SER_CONFIG) ? "LA_SER_CONFIG" : - (flag == LA_SER_SECURE) ? "LA_SER_SECURE" : - "???"); -\& - return name; -} -\& -void -la_activity (uintptr_t *cookie, unsigned int flag) -{ - printf("la_activity(): cookie = %p; flag = %s\en", cookie, - (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" : - (flag == LA_ACT_ADD) ? "LA_ACT_ADD" : - (flag == LA_ACT_DELETE) ? "LA_ACT_DELETE" : - "???"); -} -\& -unsigned int -la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie) -{ - printf("la_objopen(): loading \e"%s\e"; lmid = %s; cookie=%p\en", - map\->l_name, - (lmid == LM_ID_BASE) ? "LM_ID_BASE" : - (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" : - "???", - cookie); -\& - return LA_FLG_BINDTO | LA_FLG_BINDFROM; -} -\& -unsigned int -la_objclose (uintptr_t *cookie) -{ - printf("la_objclose(): %p\en", cookie); -\& - return 0; -} -\& -void -la_preinit(uintptr_t *cookie) -{ - printf("la_preinit(): %p\en", cookie); -} -\& -uintptr_t -la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook, - uintptr_t *defcook, unsigned int *flags, const char *symname) -{ - printf("la_symbind32(): symname = %s; sym\->st_value = %p\en", - symname, sym\->st_value); - printf(" ndx = %u; flags = %#x", ndx, *flags); - printf("; refcook = %p; defcook = %p\en", refcook, defcook); -\& - return sym\->st_value; -} -\& -uintptr_t -la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook, - uintptr_t *defcook, unsigned int *flags, const char *symname) -{ - printf("la_symbind64(): symname = %s; sym\->st_value = %p\en", - symname, sym\->st_value); - printf(" ndx = %u; flags = %#x", ndx, *flags); - printf("; refcook = %p; defcook = %p\en", refcook, defcook); -\& - return sym\->st_value; -} -\& -Elf32_Addr -la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx, - uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs, - unsigned int *flags, const char *symname, long *framesizep) -{ - printf("la_i86_gnu_pltenter(): %s (%p)\en", symname, sym\->st_value); -\& - return sym\->st_value; -} -.EE -.SH SEE ALSO -.BR ldd (1), -.BR dlopen (3), -.BR ld.so (8), -.BR ldconfig (8) |