summaryrefslogtreecommitdiffstats
path: root/man7/rtld-audit.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/rtld-audit.7')
-rw-r--r--man7/rtld-audit.7606
1 files changed, 0 insertions, 606 deletions
diff --git a/man7/rtld-audit.7 b/man7/rtld-audit.7
deleted file mode 100644
index 67678b4..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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)