1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\" 2009-01-12, mtk, Created
8 .TH RTLD-AUDIT 7 (date) "Linux man-pages (unreleased)"
10 rtld\-audit \- auditing API for the dynamic linker
13 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
17 The GNU dynamic linker (run-time linker)
18 provides an auditing API that allows an application
19 to be notified when various dynamic linking events occur.
20 This API is very similar to the auditing interface provided by the
21 Solaris run-time linker.
22 The necessary constants and prototypes are defined by including
25 To use this interface, the programmer creates a shared library
26 that implements a standard set of function names.
27 Not all of the functions need to be implemented: in most cases,
28 if the programmer is not interested in a particular class of auditing event,
29 then no implementation needs to be provided for the corresponding
32 To employ the auditing interface, the environment variable
34 must be defined to contain a colon-separated list of shared libraries,
35 each of which can implement (parts of) the auditing API.
36 When an auditable event occurs,
37 the corresponding function is invoked in each library,
38 in the order that the libraries are listed.
42 .BI "unsigned int la_version(unsigned int " version );
45 This is the only function that
47 be defined by an auditing library:
48 it performs the initial handshake between the dynamic linker and
50 When invoking this function, the dynamic linker passes, in
52 the highest version of the auditing interface that the linker supports.
54 A typical implementation of this function simply returns the constant
56 which indicates the version of
58 that was used to build the audit module.
59 If the dynamic linker does
60 not support this version of the audit interface, it will refuse to
61 activate this audit module.
62 If the function returns zero, the dynamic
63 linker also does not activate this audit module.
65 In order to enable backwards compatibility with older dynamic linkers,
66 an audit module can examine the
68 argument and return an earlier version than
70 assuming the module can adjust its implementation to match the
71 requirements of the previous version of the audit interface.
74 function should not return the value of
76 without further checks because it could correspond to an interface
77 that does not match the
79 definitions used to build the audit module.
83 .BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie ,
84 .BI " unsigned int " flag );
87 The dynamic linker invokes this function to inform the auditing library
88 that it is about to search for a shared object.
91 argument is the filename or pathname that is to be searched for.
93 identifies the shared object that initiated the search.
95 is set to one of the following values:
98 This is the original name that is being searched for.
99 Typically, this name comes from an ELF
108 was created using a directory specified in
109 .BR LD_LIBRARY_PATH .
113 was created using a directory specified in an ELF
124 .RI ( /etc/ld.so.cache ).
128 was found via a search of one of the default directories.
132 is specific to a secure object (unused on Linux).
134 As its function result,
136 returns the pathname that the dynamic linker should use
137 for further processing.
138 If NULL is returned, then this pathname is ignored for further processing.
139 If this audit library simply intends to monitor search paths, then
145 .BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag );
148 The dynamic linker calls this function to inform the auditing library
149 that link-map activity is occurring.
151 identifies the object at the head of the link map.
152 When the dynamic linker invokes this function,
154 is set to one of the following values:
157 New objects are being added to the link map.
160 Objects are being removed from the link map.
163 Link-map activity has been completed: the map is once again consistent.
167 .BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid ,
168 .BI " uintptr_t *" cookie );
171 The dynamic linker calls this function when a new shared object is loaded.
174 argument is a pointer to a link-map structure that describes the object.
177 field has one of the following values
180 Link map is part of the initial namespace.
183 Link map is part of a new namespace requested via
187 is a pointer to an identifier for this object.
188 The identifier is provided to later calls to functions
189 in the auditing library in order to identify this object.
190 This identifier is initialized to point to object's link map,
191 but the audit library can change the identifier to some other value
192 that it may prefer to use to identify the object.
196 returns a bit mask created by ORing zero or more of the
198 which allow the auditing library to select the objects to be monitored by
202 Audit symbol bindings to this object.
205 Audit symbol bindings from this object.
207 A return value of 0 from
209 indicates that no symbol bindings should be audited for this object.
213 .BI "unsigned int la_objclose(uintptr_t *" cookie );
216 The dynamic linker invokes this function after any finalization
217 code for the object has been executed,
218 before the object is unloaded.
221 argument is the identifier obtained from a previous invocation of
224 In the current implementation, the value returned by
230 .BI "void la_preinit(uintptr_t *" cookie );
233 The dynamic linker invokes this function after all shared objects
234 have been loaded, before control is passed to the application
235 (i.e., before calling
239 may still later dynamically load objects using
244 .BI "uintptr_t la_symbind32(Elf32_Sym *" sym ", unsigned int " ndx ,
245 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
246 .BI " unsigned int *" flags ", const char *" symname );
247 .BI "uintptr_t la_symbind64(Elf64_Sym *" sym ", unsigned int " ndx ,
248 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
249 .BI " unsigned int *" flags ", const char *" symname );
252 The dynamic linker invokes one of these functions
253 when a symbol binding occurs between two shared objects
254 that have been marked for auditing notification by
258 function is employed on 32-bit platforms;
261 function is employed on 64-bit platforms.
265 argument is a pointer to a structure
266 that provides information about the symbol being bound.
267 The structure definition is shown in
269 Among the fields of this structure,
271 indicates the address to which the symbol is bound.
275 argument gives the index of the symbol in the symbol table
276 of the bound shared object.
280 argument identifies the shared object that is making the symbol reference;
281 this is the same identifier that is provided to the
283 function that returned
284 .BR LA_FLG_BINDFROM .
287 argument identifies the shared object that defines the referenced symbol;
288 this is the same identifier that is provided to the
290 function that returned
295 argument points a string containing the name of the symbol.
299 argument is a bit mask that both provides information about the symbol
300 and can be used to modify further auditing of this
301 PLT (Procedure Linkage Table) entry.
302 The dynamic linker may supply the following bit values in this argument:
303 .\" LA_SYMB_STRUCTCALL appears to be unused
306 The binding resulted from a call to
312 call returned an alternate value for this symbol.
314 By default, if the auditing library implements
318 functions (see below), then these functions are invoked, after
320 for PLT entries, each time the symbol is referenced.
321 .\" pltenter/pltexit are called for non-dynamically loaded libraries,
322 .\" but don't seem to be called for dynamically loaded libs?
323 .\" Is this the same on Solaris?
324 The following flags can be ORed into
326 to change this default behavior:
328 .B LA_SYMB_NOPLTENTER
342 is the address to which control should be passed after the function returns.
343 If the auditing library is simply monitoring symbol bindings,
344 then it should return
346 A different value may be returned if the library wishes to direct control
347 to an alternate location.
349 The precise name and argument types for this function
350 depend on the hardware platform.
351 (The appropriate definition is supplied by
353 Here is the definition for x86-32:
356 .BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx ,
357 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
358 .BI " La_i86_regs *" regs ", unsigned int *" flags ,
359 .BI " const char *" symname ", long *" framesizep );
362 This function is invoked just before a PLT entry is called,
363 between two shared objects that have been marked for binding notification.
377 argument points to a structure (defined in
379 containing the values of registers to be used for
380 the call to this PLT entry.
384 argument points to a bit mask that conveys information about,
385 and can be used to modify subsequent auditing of, this PLT entry, as for
388 .\" FIXME . Is the following correct?
393 buffer that can be used to explicitly set the frame size
394 used for the call to this PLT entry.
397 invocations for this symbol return different values,
398 then the maximum returned value is used.
401 function is called only if this buffer is
402 explicitly set to a suitable value.
409 The precise name and argument types for this function
410 depend on the hardware platform.
411 (The appropriate definition is supplied by
413 Here is the definition for x86-32:
416 .BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx ,
417 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
418 .BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs ,
419 .BI " const char *" symname );
422 This function is called when a PLT entry,
423 made between two shared objects that have been marked
424 for binding notification, returns.
425 The function is called just before control returns to the caller
440 argument points to a structure (defined in
442 containing the values of registers used for the call to this PLT entry.
445 argument points to a structure (defined in
447 containing return values for the call to this PLT entry.
448 These values can be modified by the caller,
449 and the changes will be visible to the caller of the PLT entry.
451 In the current GNU implementation, the return value of
454 .\" This differs from Solaris, where an audit library that monitors
455 .\" symbol binding should return the value of the 'retval' argument
456 .\" (not provided by GNU, but equivalent to returning outregs->lrv_eax
457 .\" on (say) x86-32).
459 This API is very similar to the Solaris API
460 described in the Solaris
461 .IR "Linker and Libraries Guide" ,
463 .IR "Runtime Linker Auditing Interface" .
467 Note the following differences from the Solaris dynamic linker
472 interface is not supported by the GNU implementation.
478 functions do not provide a
484 function does not provide
488 arguments (but does provide a
490 argument with the function return value).
492 In glibc versions up to and include 2.9,
493 specifying more than one audit library in
495 results in a run-time crash.
496 This is reportedly fixed in glibc 2.10.
497 .\" FIXME . Specifying multiple audit libraries doesn't work on GNU.
498 .\" My simple tests on Solaris work okay, but not on Linux -- mtk, Jan 2009
499 .\" glibc bug filed: http://sourceware.org/bugzilla/show_bug.cgi?id=9733
500 .\" Reportedly, this is fixed on 16 Mar 2009 (i.e., for glibc 2.10)
507 la_version(unsigned int version)
509 printf("la_version(): version = %u; LAV_CURRENT = %u\[rs]n",
510 version, LAV_CURRENT);
516 la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag)
518 printf("la_objsearch(): name = %s; cookie = %p", name, cookie);
519 printf("; flag = %s\[rs]n",
520 (flag == LA_SER_ORIG) ? "LA_SER_ORIG" :
521 (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" :
522 (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" :
523 (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" :
524 (flag == LA_SER_CONFIG) ? "LA_SER_CONFIG" :
525 (flag == LA_SER_SECURE) ? "LA_SER_SECURE" :
532 la_activity (uintptr_t *cookie, unsigned int flag)
534 printf("la_activity(): cookie = %p; flag = %s\[rs]n", cookie,
535 (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" :
536 (flag == LA_ACT_ADD) ? "LA_ACT_ADD" :
537 (flag == LA_ACT_DELETE) ? "LA_ACT_DELETE" :
542 la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie)
544 printf("la_objopen(): loading \[rs]"%s\[rs]"; lmid = %s; cookie=%p\[rs]n",
546 (lmid == LM_ID_BASE) ? "LM_ID_BASE" :
547 (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" :
551 return LA_FLG_BINDTO | LA_FLG_BINDFROM;
555 la_objclose (uintptr_t *cookie)
557 printf("la_objclose(): %p\[rs]n", cookie);
563 la_preinit(uintptr_t *cookie)
565 printf("la_preinit(): %p\[rs]n", cookie);
569 la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook,
570 uintptr_t *defcook, unsigned int *flags, const char *symname)
572 printf("la_symbind32(): symname = %s; sym\->st_value = %p\[rs]n",
573 symname, sym\->st_value);
574 printf(" ndx = %u; flags = %#x", ndx, *flags);
575 printf("; refcook = %p; defcook = %p\[rs]n", refcook, defcook);
577 return sym\->st_value;
581 la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook,
582 uintptr_t *defcook, unsigned int *flags, const char *symname)
584 printf("la_symbind64(): symname = %s; sym\->st_value = %p\[rs]n",
585 symname, sym\->st_value);
586 printf(" ndx = %u; flags = %#x", ndx, *flags);
587 printf("; refcook = %p; defcook = %p\[rs]n", refcook, defcook);
589 return sym\->st_value;
593 la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
594 uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs,
595 unsigned int *flags, const char *symname, long *framesizep)
597 printf("la_i86_gnu_pltenter(): %s (%p)\[rs]n", symname, sym\->st_value);
599 return sym\->st_value;