diff options
Diffstat (limited to 'trunk/doc/prelink.8')
| -rw-r--r-- | trunk/doc/prelink.8 | 206 |
1 files changed, 110 insertions, 96 deletions
diff --git a/trunk/doc/prelink.8 b/trunk/doc/prelink.8 index c43b08a..f6b9c7c 100644 --- a/trunk/doc/prelink.8 +++ b/trunk/doc/prelink.8 @@ -1,4 +1,4 @@ -.TH prelink 8 "23 November 2004" +.TH prelink 8 "01 March 2007" .SH NAME prelink \- prelink ELF shared libraries and binaries to speed up startup time .SH SYNOPSIS @@ -6,35 +6,38 @@ 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 +is a program that modifies ELF shared libraries and ELF dynamically linked +binaries in such a way that the time needed for the dynamic linker to +perform relocations at startup significantly decreases. +Due to fewer relocations, the +run-time memory consumption decreases as well (especially the +number of unshareable pages). +The prelinking information is only used at startup time if none of the +dependent libraries have changed since prelinking; otherwise programs are relocated normally. .PP .B prelink -first collects ELF binaries which should be prelinked and all the ELF shared +first collects ELF binaries to 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. +slot to 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. +address space slot is already occupied, it maps the library 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 +.BR prelink , +with the help of dynamic linker, resolves all relocations in the binary or +library against its dependent libraries and stores the relocations into the ELF object. -It also stores a list of all dependant libraries together with their +It also stores a list of all dependent 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 +(relocations that resolve differently in the binary's symbol search scope +than in the smaller search scope in which the dependent 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 +At runtime, the dynamic linker first checks whether all dependent 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 @@ -43,92 +46,95 @@ relocations) instead of relocating each library. .TP .B \-v\ \-\-verbose Verbose mode. -Print the virtual address slot assignment to libraries and print what binary +Print the virtual address slots assigned to libraries and 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 +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 +Prelink all binaries and dependent libraries found in directory hierarchies specified in .IR /etc/prelink.conf . -Normally only binaries specified from command line and their dependant +Normally, only binaries specified on the command line and their dependent 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 +binaries or libraries. This results in a smaller virtual address space range +used for libraries. On the other hand, if .B prelink -sees a binary which puts together two libraries which were not present +sees a binary during incremental prelinking +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. +Without this option, +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. +When assigning addresses to libraries, start with a random address within +the architecture-dependent 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 +because libraries are not present on the same addresses across different machines. -Normally, assigning virtual addresses starts at the bottom of architecture -dependant range. +Normally, assigning virtual addresses starts at the bottom of the +architecture-dependent 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 +Don't save the cache file after prelinking. +Normally, the list of libraries (and with .B \-m -binaries also) is stored into +binaries also) is stored into the .I /etc/prelink.cache file together with their given address space slots and dependencies, so -it can be used during incremental prelinking (prelinking without +the cache can be used during incremental prelinking (prelinking without .B \-a option). .TP .B \-c \-\-config\-file=CONFIG -Specify alternate config file instead of default +Specify an alternate config file instead of default .IR /etc/prelink.conf . .TP .B \-C \-\-cache\-file=CACHE -Specify alternate cache file instead of default +Specify an 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 +Force re-prelinking even for already prelinked objects whose +dependencies are unchanged. +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. +whose dependencies have 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. +not change, without parsing or verifying its ELF headers. .TP .B \-p \-\-print\-cache -Print the content of the cache file (normally +Print the contents of the cache file (normally .IR /etc/prelink.cache ) and exit. .TP .B \-\-dynamic\-linker=LDSO -Specify alternate dynamic linker instead of the default. +Specify an alternate dynamic linker instead of the default. .TP .B \-\-ld\-library\-path=PATH -Specify special +Specify a special .IR LD_LIBRARY_PATH to be used when .B prelink -queries dynamic linker about symbol resolution details. +queries the dynamic linker about symbol resolution details. .TP .B \-\-libs\-only Only prelink ELF shared libraries, don't prelink any binaries. @@ -139,20 +145,27 @@ walking directory hierarchies. .TP .B \-l \-\-one\-file\-system When processing command line directory arguments, limit directory tree walk -to a single filesystem. +to a single file system. +.TP +.B \-\-root=PATHNAME +In a cross-compilation environment, this specifies the path to the root of +the target's file system. All other pathnames processed by +.B prelink +are relative to this root, including the name of the configuration file +as well as its contents and pathnames supplied on the command line. .TP .B \-u \-\-undo Revert binaries and libraries to their original content before they were prelinked. -Without +Without the .I \-a -option this causes only the binaries and libraries specified on the command +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 +dependencies). If used together with the .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. +option, all binaries and libraries from command line, all their dependencies, +all binaries found in directories specified on command line and in the config +file, and all their dependencies are undone. .TP .B \-y \-\-verify Verifies a prelinked binary or library. @@ -162,7 +175,7 @@ an 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 +operation on standard output and exits with zero status. Otherwise it exits with error status. Thus if .I \-\-verify @@ -170,37 +183,37 @@ 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 +improbable 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. +option, except instead of outputting 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. +option, except instead of outputting 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 +On IA-32, if the kernel supports Exec-Shield, prelink attempts to lay libraries +out similarly to how the kernel places them (i.e. if possible below the binary, +most widely used into the ASCII armor zone). These switches allow overriding 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. +This option allows blacklisting certain paths, libraries or binaries. Prelink will not touch them during prelinking. .TP .B \-o \-\-undo\-output=FILE -When doing +When performing an .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 @@ -212,91 +225,92 @@ Print version and exit. .B \-? \-\-help Print short help and exit. .SH ARGUMENTS -Command line arguments should be either directory hierarchies (in which case +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. +Specifying a shared library +explicitly on the command line causes it to be prelinked even if no binary +is linked against it. Otherwise, binaries are collected together and only +the libraries they depend on are prelinked with them. .SH EXAMPLES .RS # /usr/sbin/prelink -avmR .RE -will prelink all binaries found in directories specified in +prelinks 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. +and all their dependent libraries, assigning libraries unique virtual +address space slots only if they ever appear together, and starts +assigning libraries at a random address. .RS # /usr/sbin/prelink -vm ~/bin/progx .RE -will prelink ~/bin/progx program and all its dependant libraries (unless +prelinks ~/bin/progx program and all its dependent 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. +reverts 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. +verifies whether /bin/prelinked_prog is unchanged. .SH FILES .PD 0 .TP 20 .B /etc/prelink.cache -Binary file containing list of prelinked libraries and/or binaries together +Binary file containing a 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 +Configuration file containing a list of directory hierarchies that 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 +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 +is given or not, to limit which dependent 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 +finds a dependent library of some binary or other library which is not +present in any of the directories specified either 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 +or on the command line, then it cannot be prelinked. +Each line of the config file should be either a comment starting with .BR # , or a directory name, or a blacklist specification. Directory names can be prefixed -by +by the .B \-l -switch, meaning tree walk of the given directory will be only limited to one -filesystem, or +switch, meaning the tree walk of the given directory is only limited to one +file system; or the .B \-h -switch, meaning tree walk of the given directory will follow symbolic links. -Blacklist specification should be prefixed by +switch, meaning the tree walk of the given directory follows symbolic links. +A 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 +if needed. A blacklist entry can be either an absolute directory name +(in that case all files in that directory hierarchy are ignored by the +prelinker); +an absolute filename +(then that particular library or binary is skipped); +or a glob pattern without a .B / character in it (then all files matching that glob in any directory -will be blacklisted). +are ignored). .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. +Some architectures, including HPPA, are not yet supported. .SH AUTHORS Jakub Jelinek <jakub@redhat.com>. |