diff options
Diffstat (limited to 'trunk/doc/prelink.8')
| -rw-r--r-- | trunk/doc/prelink.8 | 302 |
1 files changed, 302 insertions, 0 deletions
diff --git a/trunk/doc/prelink.8 b/trunk/doc/prelink.8 new file mode 100644 index 0000000..c43b08a --- /dev/null +++ b/trunk/doc/prelink.8 @@ -0,0 +1,302 @@ +.TH prelink 8 "23 November 2004" +.SH NAME +prelink \- prelink ELF shared libraries and binaries to speed up startup time +.SH SYNOPSIS +prelink +.RB [OPTION...]\ [FILES] +.SH DESCRIPTION +.B prelink +is a program which modifies ELF shared libraries and ELF dynamically linked +binaries, so that the time which dynamic linker needs for their relocation +at startup significantly decreases and also due to fewer relocations the +run-time memory consumption decreases too (especially number of unshareable +pages). Such prelinking information is only used if all its dependant +libraries have not changed since prelinking, otherwise programs are +relocated normally. +.PP +.B prelink +first collects ELF binaries which should be prelinked and all the ELF shared +libraries they depend on. Then it assigns a unique virtual address space +slot for each library and relinks the shared library to that base address. +When the dynamic linker attempts to load such a library, unless that virtual +address space slot is already occupied, it will map it into the given slot. +After this is done, +.B prelink +with the help of dynamic linker resolves all relocations in the binary or +library against its dependant libraries and stores the relocations into the +ELF object. +It also stores a list of all dependant libraries together with their +checksums into the binary or library. +For binaries, it also computes a list of +.IR conflicts +(relocations which resolve differently in the binary's symbol search scope +than in the smaller search scope in which the dependant library was +resolved) and stores it into a special ELF section. +.PP +At runtime, the dynamic linker first checks whether all dependant libraries +were successfully mapped into their designated address space slots and +whether they have not changed since the prelinking was done. +If all checks are successful, the dynamic linker just replays the list of +conflicts (which is usually significantly shorter than total number of +relocations) instead of relocating each library. +.SH OPTIONS +.TP +.B \-v\ \-\-verbose +Verbose mode. +Print the virtual address slot assignment to libraries and print what binary +or library is currently being prelinked. +.TP +.B \-n\ \-\-dry\-run +Don't actually prelink anything, just collect the binaries/libraries, assign +them addresses and with +.B \-v +print what would be prelinked. +.TP +.B \-a \-\-all +Prelink all binaries and dependant libraries found in directory hierarchies +specified in +.IR /etc/prelink.conf . +Normally only binaries specified from command line and their dependant +libraries are prelinked. +.TP +.B \-m \-\-conserve\-memory +When assigning addresses to libraries, allow overlap of address space slots +provided that the two libraries are not present together in any of the +binaries or libraries. This results in smaller virtual address space range +used for libraries, on the other side if during incremental prelinking +.B prelink +sees a binary which puts together two libraries which were not present +together in any other binary and were given the same virtual address space +slots, then the binary cannot be prelinked. +Normally each library is assigned a unique virtual address space slot. +.TP +.B \-R \-\-random +When assigning addresses to libraries, start with random address within +architecture dependant virtual address space range. +This can make some buffer overflow attacks slightly harder to exploit, +because libraries are not present on the same addresses accross different +machines. +Normally, assigning virtual addresses starts at the bottom of architecture +dependant range. +.TP +.B \-r \-\-reloc\-only=ADDRESS +Instead of prelinking, just relink given shared libraries to the specified +base address. +.TP +.B \-N \-\-no\-update\-cache +Don't save cache file after prelinking. Normally, list of libraries (and +with +.B \-m +binaries also) is stored into +.I /etc/prelink.cache +file together with their given address space slots and dependencies, so +it can be used during incremental prelinking (prelinking without +.B \-a +option). +.TP +.B \-c \-\-config\-file=CONFIG +Specify alternate config file instead of default +.IR /etc/prelink.conf . +.TP +.B \-C \-\-cache\-file=CACHE +Specify alternate cache file instead of default +.IR /etc/prelink.cache . +.TP +.B \-f \-\-force +Force re-prelinking even for already prelinked objects for which no +dependencies changed. This option causes new virtual address space slots to +be assigned to all libraries. +Normally, only binaries or libraries which are either not prelinked yet, or +some of their dependencies changed, are prelinked. +.TP +.B \-q \-\-quick +Run prelink in quick mode. This mode checks just mtime and ctime timestamps +of libraries and binaries stored in the cache file. If they are unchanged +from the last prelink run, it is assumed that the library in question did +not change and no parsing of its ELF headers and verifying it is done. +.TP +.B \-p \-\-print\-cache +Print the content of the cache file (normally +.IR /etc/prelink.cache ) +and exit. +.TP +.B \-\-dynamic\-linker=LDSO +Specify alternate dynamic linker instead of the default. +.TP +.B \-\-ld\-library\-path=PATH +Specify special +.IR LD_LIBRARY_PATH +to be used when +.B prelink +queries dynamic linker about symbol resolution details. +.TP +.B \-\-libs\-only +Only prelink ELF shared libraries, don't prelink any binaries. +.TP +.B \-h \-\-dereference +When processing command line directory arguments, follow symbolic links when +walking directory hierarchies. +.TP +.B \-l \-\-one\-file\-system +When processing command line directory arguments, limit directory tree walk +to a single filesystem. +.TP +.B \-u \-\-undo +Revert binaries and libraries to their original content before they were +prelinked. +Without +.I \-a +option this causes only the binaries and libraries specified on the command +line to be reverted to their original state (and e.g. not their +dependencies). If used together with +.I \-a +option all binaries and libraries from command line, all their dependencies, +all binaries found in directories specified on command line and in config +file and all their dependencies will be undone. +.TP +.B \-y \-\-verify +Verifies a prelinked binary or library. +This option can be used only on a single binary or library. It first applies +an +.I \-\-undo +operation on the file, then prelinks just that file again and compares this +with the original file. If both are identical, it prints the file after +.I \-\-undo +operation on standard output and exit with zero status. Otherwise it exits +with error status. +Thus if +.I \-\-verify +operation returns zero exit status and its standard output is +equal to the content of the binary or library before prelinking, you can be +sure that nobody modified the binaries or libraries after prelinking. +Similarly with message digests and checksums (unless you trigger the +unprobable case of modified file and original file having the same digest +or checksum). +.TP +.B \-\-md5 +This is similar to +.I \-\-verify +option, except instead of outputing the content of the binary or library +before prelinking to standard output MD5 digest is printed. +See +.BR md5sum (1). +.TP +.B \-\-sha +This is similar to +.I \-\-verify +option, except instead of outputing the content of the binary or library +before prelinking to standard output SHA1 digest is printed. +See +.BR sha1sum (1). +.TP +.B \-\-exec\-shield \-\-no\-exec\-shield +On IA-32, if kernel supports Exec-Shield, prelink attempts to lay libraries +out similarly to how kernel places them (i.e. if possible below the binary, +most widely used into the ASCII armor zone). These switches allow to override +prelink detection of whether Exec-Shield is supported or not. +.TP +.B \-b \-\-black\-list=PATH +This option allows to blacklist certain paths, libraries or binaries. +Prelink will not touch them during prelinking. +.TP +.B \-o \-\-undo\-output=FILE +When doing +.B \-\-undo +operation, don't overwrite the prelinked binary or library with its +original content (before it was prelinked), but save that into the specified +file. +.TP +.B \-V \-\-version +Print version and exit. +.TP +.B \-? \-\-help +Print short help and exit. +.SH ARGUMENTS +Command line arguments should be either directory hierarchies (in which case +.I \-l +and +.I \-h +options apply), or particular ELF binaries or shared libraries. +Unlike when walking directory hierarchies, specifying a shared library +explicitely on the command line causes it to be prelinked even if no binary +is linked against it. Normally, only binaries are collected together with +all libraries they depend on. +.SH EXAMPLES +.RS +# /usr/sbin/prelink -avmR +.RE +will prelink all binaries found in directories specified in +.I /etc/prelink.conf +and all their dependant libraries, assigning libraries unique virtual +address space slots only if they ever appear together and will start +assigning at random address. +.RS +# /usr/sbin/prelink -vm ~/bin/progx +.RE +will prelink ~/bin/progx program and all its dependant libraries (unless +they were prelinked already e.g. during +.I prelink \-a +invocation). +.RS +# /usr/sbin/prelink -au +.RE +will revert all binaries and libraries to their original content. +.RS +# /usr/sbin/prelink -y /bin/prelinked_prog > /tmp/original_prog; echo $? +will verify whether /bin/prelinked_prog hasn't been changed. +.SH FILES +.PD 0 +.TP 20 +.B /etc/prelink.cache +Binary file containing list of prelinked libraries and/or binaries together +with their assigned virtual address space slots and dependencies. +You can run +.I /usr/sbin/prelink -p +to see what is stored in there. +.TP 20 +.B /etc/prelink.conf +Configuration file containing a list of directory hierarchies which can +contain ELF shared libraries or binaries which should be prelinked. +This configuration file is used in +.B \-a +mode to find binaries which should be prelinked and also no matter whether +.B \-a +is given or not to limit which dependant shared libraries should be +prelinked. If +.B prelink +finds a dependant library of some binary or other library which is not +present in any of the directories specified in +.B /etc/prelink.conf +and neither in any of the directories specified on the command line, then it +cannot be prelinked. +Each line of the config file should be either comment starting with +.BR # , +or a directory name, or a blacklist specification. Directory names can be prefixed +by +.B \-l +switch, meaning tree walk of the given directory will be only limited to one +filesystem, or +.B \-h +switch, meaning tree walk of the given directory will follow symbolic links. +Blacklist specification should be prefixed by +.B \-b +and optionally also +.B \-l +or +.B \-h +if needed. It should be either absolute directory name (in that case +all files in that directory hierarchy will be blacklisted), absolute filename +(in that case that particular library or binary will not be touched by +prelink) or a glob pattern without +.B / +character in it (then all files matching that glob in any directory +will be blacklisted). +.SH SEE ALSO +.BR ldd (1), +.BR ld.so (8). +.SH BUGS +.LP +.B prelink +Some architectures, including IA-64, HPPA and MIPS, are not yet supported. +.SH AUTHORS +Jakub Jelinek <jakub@redhat.com>. |