Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 606 insertions, 0 deletions

diff --git a/man7/rtld-audit.7 b/man7/rtld-audit.7
new file mode 100644
index 0000000..df04a8c
--- /dev/null
+++ b/man7/rtld-audit.7
@@ -0,0 +1,606 @@
+.\" 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-05-03 "Linux man-pages 6.05.01"
+.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> .
+.PP
+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.
+.PP
+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
+.PP
+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.
+.PP
+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.
+.PP
+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
+.PP
+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).
+.PP
+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
+.PP
+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
+.PP
+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).
+.PP
+.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.
+.PP
+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.
+.PP
+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
+.PP
+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 ().
+.PP
+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
+.PP
+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
+.PP
+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.
+.PP
+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.
+.PP
+The
+.I ndx
+argument gives the index of the symbol in the symbol table
+of the bound shared object.
+.PP
+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 .
+.PP
+The
+.I symname
+argument points a string containing the name of the symbol.
+.PP
+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.
+.PP
+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.
+.PP
+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:
+.PP
+.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
+.PP
+This function is invoked just before a PLT entry is called,
+between two shared objects that have been marked for binding notification.
+.PP
+The
+.IR sym ,
+.IR ndx ,
+.IR refcook ,
+.IR defcook ,
+and
+.I symname
+are as for
+.BR la_symbind* ().
+.PP
+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.
+.PP
+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* ().
+.PP
+.\" 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.
+.PP
+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:
+.PP
+.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
+.PP
+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.
+.PP
+The
+.IR sym ,
+.IR ndx ,
+.IR refcook ,
+.IR defcook ,
+and
+.I symname
+are as for
+.BR la_symbind* ().
+.PP
+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.
+.PP
+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)