1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" 2009-01-12, mtk, Created
28 .TH RTLD-AUDIT 7 2015-12-05 "Linux" "Linux Programmer's Manual"
30 rtld-audit \- auditing API for the dynamic linker
32 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
36 The GNU dynamic linker (run-time linker)
37 provides an auditing API that allows an application
38 to be notified when various dynamic linking events occur.
39 This API is very similar to the auditing interface provided by the
40 Solaris run-time linker.
41 The necessary constants and prototypes are defined by including
44 To use this interface, the programmer creates a shared library
45 that implements a standard set of function names.
46 Not all of the functions need to be implemented: in most cases,
47 if the programmer is not interested in a particular class of auditing event,
48 then no implementation needs to be provided for the corresponding
51 To employ the auditing interface, the environment variable
53 must be defined to contain a colon-separated list of shared libraries,
54 each of which can implement (parts of) the auditing API.
55 When an auditable event occurs,
56 the corresponding function is invoked in each library,
57 in the order that the libraries are listed.
61 .BI "unsigned int la_version(unsigned int " version );
64 This is the only function that
66 be defined by an auditing library:
67 it performs the initial handshake between the dynamic linker and
69 When invoking this function, the dynamic linker passes, in
71 the highest version of the auditing interface that the linker supports.
72 If necessary, the auditing library can check that this version
73 is sufficient for its requirements.
75 As its function result,
76 this function should return the version of the auditing interface
77 that this auditing library expects to use (returning
80 If the returned value is 0,
81 or a version that is greater than that supported by the dynamic linker,
82 then the audit library is ignored.
86 .BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie ,
87 .BI " unsigned int " flag );
90 The dynamic linker invokes this function to inform the auditing library
91 that it is about to search for a shared object.
94 argument is the filename or pathname that is to be searched for.
96 identifies the shared object that initiated the search.
98 is set to one of the following values:
101 This is the original name that is being searched for.
102 Typically, this name comes from an ELF
111 was created using a directory specified in
112 .BR LD_LIBRARY_PATH .
116 was created using a directory specified in an ELF
127 .RI ( /etc/ld.so.cache ).
131 was found via a search of one of the default directories.
135 is specific to a secure object (unused on Linux).
137 As its function result,
139 returns the pathname that the dynamic linker should use
140 for further processing.
141 If NULL is returned, then this pathname is ignored for further processing.
142 If this audit library simply intends to monitor search paths, then
148 .BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag );
151 The dynamic linker calls this function to inform the auditing library
152 that link-map activity is occurring.
154 identifies the object at the head of the link map.
155 When the dynamic linker invokes this function,
157 is set to one of the following values:
160 New objects are being added to the link map.
163 Objects are being removed from the link map.
166 Link-map activity has been completed: the map is once again consistent.
170 .BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid ,
171 .BI " uintptr_t *" cookie );
174 The dynamic linker calls this function when a new shared object is loaded.
177 argument is a pointer to a link-map structure that describes the object.
180 field has one of the following values
183 Link map is part of the initial namespace.
186 Link map is part of a new namespace requested via
190 is a pointer to an identifier for this object.
191 The identifier is provided to later calls to functions
192 in the auditing library in order to identify this object.
193 This identifier is initialized to point to object's link map,
194 but the audit library can change the identifier to some other value
195 that it may prefer to use to identify the object.
199 returns a bit mask created by ORing zero or more of the
201 which allow the auditing library to select the objects to be monitored by
205 Audit symbol bindings to this object.
208 Audit symbol bindings from this object.
210 A return value of 0 from
212 indicates that no symbol bindings should be audited for this object.
216 .BI "unsigned int la_objclose(uintptr_t *" cookie );
219 The dynamic linker invokes this function after any finalization
220 code for the object has been executed,
221 before the object is unloaded.
224 argument is the identifier obtained from a previous invocation of
227 In the current implementation, the value returned by
233 .BI "void la_preinit(uintptr_t *" cookie );
236 The dynamic linker invokes this function after all shared objects
237 have been loaded, before control is passed to the application
238 (i.e., before calling
242 may still later dynamically load objects using
247 .BI "uintptr_t la_symbind32(Elf32_Sym *" sym ", unsigned int " ndx ,
248 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
249 .BI " unsigned int *" flags ", const char *" symname );
250 .BI "uintptr_t la_symbind64(Elf64_Sym *" sym ", unsigned int " ndx ,
251 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
252 .BI " unsigned int *" flags ", const char *" symname );
255 The dynamic linker invokes one of these functions
256 when a symbol binding occurs between two shared objects
257 that have been marked for auditing notification by
261 function is employed on 32-bit platforms;
264 function is employed on 64-bit platforms.
268 argument is a pointer to a structure
269 that provides information about the symbol being bound.
270 The structure definition is shown in
272 Among the fields of this structure,
274 indicates the address to which the symbol is bound.
278 argument gives the index of the symbol in the symbol table
279 of the bound shared object.
283 argument identifies the shared object that is making the symbol reference;
284 this is the same identifier that is provided to the
286 function that returned
287 .BR LA_FLG_BINDFROM .
290 argument identifies the shared object that defines the referenced symbol;
291 this is the same identifier that is provided to the
293 function that returned
298 argument points a string containing the name of the symbol.
302 argument is a bit mask that both provides information about the symbol
303 and can be used to modify further auditing of this
304 PLT (Procedure Linkage Table) entry.
305 The dynamic linker may supply the following bit values in this argument:
306 .\" LA_SYMB_STRUCTCALL appears to be unused
309 The binding resulted from a call to
315 call returned an alternate value for this symbol.
317 By default, if the auditing library implements
321 functions (see below), then these functions are invoked, after
323 for PLT entries, each time the symbol is referenced.
324 .\" pltenter/pltexit are called for non-dynamically loaded libraries,
325 .\" but don't seem to be called for dynamically loaded libs?
326 .\" Is this the same on Solaris?
327 The following flags can be ORed into
329 to change this default behavior:
331 .B LA_SYMB_NOPLTENTER
345 is the address to which control should be passed after the function returns.
346 If the auditing library is simply monitoring symbol bindings,
347 then it should return
349 A different value may be returned if the library wishes to direct control
350 to an alternate location.
352 The precise name and argument types for this function
353 depend on the hardware platform.
354 (The appropriate definition is supplied by
356 Here is the definition for x86-32:
359 .BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx ,
360 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
361 .BI " La_i86_regs *" regs ", unsigned int *" flags ,
362 .BI " const char *" symname ", long int *" framesizep );
365 This function is invoked just before a PLT entry is called,
366 between two shared objects that have been marked for binding notification.
380 argument points to a structure (defined in
382 containing the values of registers to be used for
383 the call to this PLT entry.
387 argument points to a bit mask that conveys information about,
388 and can be used to modify subsequent auditing of, this PLT entry, as for
391 .\" FIXME . Is the following correct?
396 buffer that can be used to explicitly set the frame size
397 used for the call to this PLT entry.
400 invocations for this symbol return different values,
401 then the maximum returned value is used.
404 function is called only if this buffer is
405 explicitly set to a suitable value.
412 The precise name and argument types for this function
413 depend on the hardware platform.
414 (The appropriate definition is supplied by
416 Here is the definition for x86-32:
419 .BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx ,
420 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
421 .BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs ,
422 .BI " const char *" symname );
425 This function is called when a PLT entry,
426 made between two shared objects that have been marked
427 for binding notification, returns.
428 The function is called just before control returns to the caller
443 argument points to a structure (defined in
445 containing the values of registers used for the call to this PLT entry.
448 argument points to a structure (defined in
450 containing return values for the call to this PLT entry.
451 These values can be modified by the caller,
452 and the changes will be visible to the caller of the PLT entry.
454 In the current GNU implementation, the return value of
457 .\" This differs from Solaris, where an audit library that monitors
458 .\" symbol binding should return the value of the 'retval' argument
459 .\" (not provided by GNU, but equivalent to returning outregs->lrv_eax
460 .\" on (say) x86-32).
462 This API is nonstandard, but very similar to the Solaris API,
463 described in the Solaris
464 .IR "Linker and Libraries Guide" ,
466 .IR "Runtime Linker Auditing Interface" .
468 Note the following differences from the Solaris dynamic linker
473 interface is not supported by the GNU implementation.
479 functions do not provide a
485 function does not provide
489 arguments (but does provide a
491 argument with the function return value).
493 In glibc versions up to and include 2.9,
494 specifying more than one audit library in
496 results in a run-time crash.
497 This is reportedly fixed in glibc 2.10.
498 .\" FIXME . Specifying multiple audit libraries doesn't work on GNU.
499 .\" My simple tests on Solaris work okay, but not on Linux -- mtk, Jan 2009
500 .\" glibc bug filed: http://sourceware.org/bugzilla/show_bug.cgi?id=9733
501 .\" Reportedly, this is fixed on 16 Mar 2009 (i.e., for glibc 2.10)
508 la_version(unsigned int version)
510 printf("la_version(): %d\\n", version);
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\\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\\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 \\"%s\\"; lmid = %s; cookie=%p\\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\\n", cookie);
563 la_preinit(uintptr_t *cookie)
565 printf("la_preinit(): %p\\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\\n",
573 symname, sym\->st_value);
574 printf(" ndx = %d; flags = 0x%x", ndx, *flags);
575 printf("; refcook = %p; defcook = %p\\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\\n",
585 symname, sym\->st_value);
586 printf(" ndx = %d; flags = 0x%x", ndx, *flags);
587 printf("; refcook = %p; defcook = %p\\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 int *framesizep)
597 printf("la_i86_gnu_pltenter(): %s (%p)\\n", symname, sym\->st_value);
599 return sym\->st_value;