1 .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" 2009-01-12, mtk, Created
26 .TH RTLD-AUDIT 7 2010-09-10 "Linux" "Linux Programmer's Manual"
28 rtld-audit \- auditing API for the dynamic linker
30 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
34 The GNU dynamic linker (run-time linker)
35 provides an auditing API that allows an application
36 to be notified when various dynamic linking events occur.
37 This API is very similar to the auditing interface provided by the
38 Solaris run-time linker.
39 The necessary constants and prototypes are defined by including
42 To use this interface, the programmer creates a shared library
43 that implements a standard set of function names.
44 Not all of the functions need to be implemented: in most cases,
45 if the programmer is not interested in a particular class of auditing event,
46 then no implementation needs to be provided for the corresponding
49 To employ the auditing interface, the environment variable
51 must be defined to contain a colon-separated list of shared libraries,
52 each of which can implement (parts of) the auditing API.
53 When an auditable event occurs,
54 the corresponding function is invoked in each library,
55 in the order that the libraries are listed.
59 .BI "unsigned int la_version(unsigned int " version );
62 This is the only function that
64 be defined by an auditing library:
65 it performs the initial handshake between the dynamic linker and
67 When invoking this function, the dynamic linker passes, in
69 the highest version of the auditing interface that the linker supports.
70 If necessary, the auditing library can check that this version
71 is sufficient for its requirements.
73 As its function result,
74 this function should return the version of the auditing interface
75 that this auditing library expects to use (returning
78 If the returned value is 0,
79 or a version that is greater than that supported by the dynamic linker,
80 then the audit library is ignored.
84 .BI "char *la_objsearch(const char *" name ", uintptr_t *" cookie ,
85 .BI " unsigned int " flag );
88 The dynamic linker invokes this function to inform the auditing library
89 that it is about to search for a shared object.
92 argument is the filename or pathname that is to be searched for.
94 identifies the shared object that initiated the search.
96 is set to one of the following values:
99 This is the original name that is being searched for.
100 Typically, this name comes from an ELF
109 was created using a directory specified in
110 .BR LD_LIBRARY_PATH .
114 was created using a directory specified in an ELF
125 .RI ( /etc/ld.so.cache ).
129 was found via a search of one of the default directories.
133 is specific to a secure object (unused on Linux).
135 As its function result,
137 returns the pathname that the dynamic linker should use
138 for further processing.
139 If NULL is returned, then this pathname is ignored for further processing.
140 If this audit library simply intends to monitor search paths, then
146 .BI "void la_activity( uintptr_t *" cookie ", unsigned int "flag );
149 The dynamic linker calls this function to inform the auditing library
150 that link-map activity is occurring.
152 identifies the object at the head of the link map.
153 When the dynamic linker invokes this function,
155 is set to one of the following values:
158 New objects are being added to the link map.
161 Objects are being removed from the link map.
164 Link-map activity has been completed: the map is once again consistent.
168 .BI "unsigned int la_objopen(struct link_map *" map ", Lmid_t " lmid ,
169 .BI " uintptr_t *" cookie );
172 The dynamic linker calls this function when a new shared object is loaded.
175 argument is a pointer to a link-map structure that describes the object.
178 field has one of the following values
181 Link map is part of the initial namespace.
184 Link map is part of a new namespace requested via
188 is a pointer to an identifier for this object.
189 The identifier is provided to later calls to functions
190 in the auditing library in order to identify this object.
191 This identifier is initialized to point to object's link map,
192 but the audit library can change the identifier to some other value
193 that it may prefer to use to identify the object.
197 returns a bit mask created by ORing zero or more of the
199 which allow the auditing library to select the objects to be monitored by
203 Audit symbol bindings to this object.
206 Audit symbol bindings from this object.
208 A return value of 0 from
210 indicates that no symbol bindings should be audited for this object.
214 .BI "unsigned int la_objclose(uintptr_t *" cookie);
217 The dynamic linker invokes this function after any finalization
218 code for the object has been executed,
219 before the object is unloaded.
222 argument is the identifier obtained from a previous invocation of
225 In the current implementation, the value returned by
231 .BI "void la_preinit(uintptr_t *" cookie );
234 The dynamic linker invokes this function after all shared objects
235 have been loaded, before control is passed to the application
236 (i.e., before calling
240 may still later dynamically load objects using
245 .BI "uintptr_t la_symbind32(Elf32_Sym *" sym ", unsigned int " ndx ,
246 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
247 .BI " unsigned int *" flags ", const char *" symname );
248 .BI "uintptr_t la_symbind64(Elf64_Sym *" sym ", unsigned int " ndx ,
249 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
250 .BI " unsigned int *" flags ", const char *" symname );
253 The dynamic linker invokes one of these functions
254 when a symbol binding occurs between two shared objects
255 that have been marked for auditing notification by
259 function is employed on 32-bit platforms;
262 function is employed on 64-bit platforms.
266 argument is a pointer to a structure
267 that provides information about the symbol being bound.
268 The structure definition is shown in
270 Among the fields of this structure,
272 indicates the address to which the symbol is bound.
276 argument gives the index of the symbol in the symbol table
277 of the bound shared object.
281 argument identifies the shared object that is making the symbol reference;
282 this is the same identifier that is provided to the
284 function that returned
285 .BR LA_FLG_BINDFROM .
288 argument identifies the shared object that defines the referenced symbol;
289 this is the same identifier that is provided to the
291 function that returned
296 argument points a string containing the name of the symbol.
300 argument is a bit mask that both provides information about the symbol
301 and can be used to modify further auditing of this
302 PLT (Procedure Linkage Table) entry.
303 The dynamic linker may supply the following bit values in this argument:
304 .\" LA_SYMB_STRUCTCALL appears to be unused
307 The binding resulted from a call to
313 call returned an alternate value for this symbol.
315 By default, if the auditing library implements
319 functions (see below), then these functions are invoked, after
321 for PLT entries, each time the symbol is referenced.
322 .\" pltenter/pltexit are called for non-dynamically loaded libraries,
323 .\" but don't seem to be called for dynamically loaded libs?
324 .\" Is this the same on Solaris?
325 The following flags can be ORed into
327 to change this default behavior:
329 .B LA_SYMB_NOPLTENTER
343 is the address to which control should be passed after the function returns.
344 If the auditing library is simply monitoring symbol bindings,
345 then it should return
347 A different value may be returned if the library wishes to direct control
348 to an alternate location.
350 The precise name and argument types for this function
351 depend on the hardware platform.
352 (The appropriate definition is supplied by
354 Here is the definition for x86-32:
357 .BI "Elf32_Addr la_i86_gnu_pltenter(Elf32_Sym *" sym ", unsigned int " ndx ,
358 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
359 .BI " La_i86_regs *" regs ", unsigned int *" flags ,
360 .BI " const char *" symname ", long int *" framesizep );
363 This function is invoked just before a PLT entry is called,
364 between two shared objects that have been marked for binding notification.
378 argument points to a structure (defined in
380 containing the values of registers to be used for
381 the call to this PLT entry.
385 argument points to a bit mask that conveys information about,
386 and can be used to modify subsequent auditing of, this PLT entry, as for
389 .\" FIXME is the following correct?
394 buffer that can be used to explicitly set the frame size
395 used for the call to this PLT entry.
398 invocations for this symbol return different values,
399 then the maximum returned value is used.
402 function is only called if this buffer is
403 explicitly set to a suitable value.
410 The precise name and argument types for this function
411 depend on the hardware platform.
412 (The appropriate definition is supplied by
414 Here is the definition for x86-32:
417 .BI "unsigned int la_i86_gnu_pltexit(Elf32_Sym *" sym ", unsigned int " ndx ,
418 .BI " uintptr_t *" refcook ", uintptr_t *" defcook ,
419 .BI " const La_i86_regs *" inregs ", La_i86_retval *" outregs ,
420 .BI " const char *" symname );
423 This function is called when a PLT entry,
424 made between two shared objects that have been marked
425 for binding notification, returns.
426 The function is called just before control returns to the caller
441 argument points to a structure (defined in
443 containing the values of registers used for the call to this PLT entry.
446 argument points to a structure (defined in
448 containing return values for the call to this PLT entry.
449 These values can be modified by the caller,
450 and the changes will be visible to the caller of the PLT entry.
452 In the current GNU implementation, the return value of
455 .\" This differs from Solaris, where an audit library that monitors
456 .\" symbol binding should return the value of the 'retval' argument
457 .\" (not provided by GNU, but equivalent to returning outregs->lrv_eax
458 .\" on (say) x86-32).
460 This API is nonstandard, but very similar to the Solaris API,
461 described in the Solaris
462 .IR "Linker and Libraries Guide" ,
464 .IR "Runtime Linker Auditing Interface" .
466 Note the following differences from the Solaris dynamic linker
471 interface is not supported by the GNU implementation.
477 functions do not provide a
483 function does not provide
487 arguments (but does provide a
489 argument with the function return value).
496 la_version(unsigned int version)
498 printf("la_version(): %d\\n", version);
504 la_objsearch(const char *name, uintptr_t *cookie, unsigned int flag)
506 printf("la_objsearch(): name = %s; cookie = %x", name, cookie);
507 printf("; flag = %s\\n",
508 (flag == LA_SER_ORIG) ? "LA_SER_ORIG" :
509 (flag == LA_SER_LIBPATH) ? "LA_SER_LIBPATH" :
510 (flag == LA_SER_RUNPATH) ? "LA_SER_RUNPATH" :
511 (flag == LA_SER_DEFAULT) ? "LA_SER_DEFAULT" :
512 (flag == LA_SER_CONFIG) ? "LA_SER_CONFIG" :
513 (flag == LA_SER_SECURE) ? "LA_SER_SECURE" :
520 la_activity (uintptr_t *cookie, unsigned int flag)
522 printf("la_activity(): cookie = %x; flag = %s\\n", cookie,
523 (flag == LA_ACT_CONSISTENT) ? "LA_ACT_CONSISTENT" :
524 (flag == LA_ACT_ADD) ? "LA_ACT_ADD" :
525 (flag == LA_ACT_DELETE) ? "LA_ACT_DELETE" :
530 la_objopen(struct link_map *map, Lmid_t lmid, uintptr_t *cookie)
532 printf("la_objopen(): loading \\"%s\\"; lmid = %s; cookie=%x\\n",
534 (lmid == LM_ID_BASE) ? "LM_ID_BASE" :
535 (lmid == LM_ID_NEWLM) ? "LM_ID_NEWLM" :
539 return LA_FLG_BINDTO | LA_FLG_BINDFROM;
543 la_objclose (uintptr_t *cookie)
545 printf("la_objclose(): %x\\n", cookie);
551 la_preinit(uintptr_t *cookie)
553 printf("la_preinit(): %x\\n", cookie);
557 la_symbind32(Elf32_Sym *sym, unsigned int ndx, uintptr_t *refcook,
558 uintptr_t *defcook, unsigned int *flags, const char *symname)
560 printf("la_symbind32(): symname = %s; sym\->st_value = %p\\n",
561 symname, sym\->st_value);
562 printf(" ndx = %d; flags = 0x%x", ndx, *flags);
563 printf("; refcook = %x; defcook = %x\\n", refcook, defcook);
565 return sym\->st_value;
569 la_symbind64(Elf64_Sym *sym, unsigned int ndx, uintptr_t *refcook,
570 uintptr_t *defcook, unsigned int *flags, const char *symname)
572 printf("la_symbind64(): symname = %s; sym\->st_value = %p\\n",
573 symname, sym\->st_value);
574 printf(" ndx = %d; flags = 0x%x", ndx, *flags);
575 printf("; refcook = %x; defcook = %x\\n", refcook, defcook);
577 return sym\->st_value;
581 la_i86_gnu_pltenter(Elf32_Sym *sym, unsigned int ndx,
582 uintptr_t *refcook, uintptr_t *defcook, La_i86_regs *regs,
583 unsigned int *flags, const char *symname, long int *framesizep)
585 printf("la_i86_gnu_pltenter(): %s (%p)\\n", symname, sym\->st_value);
587 return sym\->st_value;
591 In glibc versions up to and include 2.9,
592 specifying more than one audit library in
594 results in a run-time crash.
595 This is reportedly fixed in glibc 2.10.
596 .\" FIXME Specifying multiple audit libraries doesn't work on GNU.
597 .\" My simple tests on Solaris work okay, but not on Linux -- mtk, Jan 2009
598 .\" glibc bug filed: http://sourceware.org/bugzilla/show_bug.cgi?id=9733
599 .\" Reportedly, this is fixed on 16 Mar 2009 (i.e., for glibc 2.10)