ap/build/uClibc/ldso/man/ld.so.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename ld.so.info
@settitle ld.so : Dynamic-Link Library support
@c %**end of header

@ifinfo
This file documents the dynamic-link support libraries and utilities for the
Linux OS, version 1.8.1.

Copyright 1996 Michael Deutschmann

This document is subject to the GNU General Public License as published by 
the Free Software foundation, version 2 or later (your choice).

Note: The software described in this document is under a different copyright
and license.

@end ifinfo

@titlepage 
@title ld.so
@subtitle Dynamic Link library support for the Linux OS.
@author David Engel
@author Eric Youngdale
@author Peter Macdonald 
@author Hongjiu Lu 
@author Mitch D'Souza
@author Michael Deutschmann (this documentation)

@page
Copyright @copyright{} 1996 Michael Deutschmann

This document is subject to the GNU General Public License as published by 
the Free Software foundation, version 2 or later (your choice).

Note: The software described in this document is under a different copyright
and license.
@end titlepage

@ifinfo
@node Top
@top

The @code{ld.so} module provides dynamic linked library support in Linux.
This file documents @code{ld.so} and its companion software.

@menu
* intro::	Introduction

* ld.so::	The dynamic linker core program
* ldd::		A utility to print out dependencies
* ldconfig::	A utility to maintain the cache and symlinks
* libdl::	Manual dynamic linking library
@end menu

@end ifinfo

@node intro
@unnumbered Introduction

The @code{ld.so} suite contains special files and utilities needed for linux
to handle @dfn{dynamic libraries}.

Ordinary static libraries (@file{lib*.a} files) are included into executables
that use their functions. A file that only uses static libraries needs less
intelligence to load, but takes up more space. If many executables use the
same library, there can be much wastage of storage space, since multiple
copies of the library functions are scattered across the executables.
However, static libraries are easier to make.

Dynamic libraries (@file{lib*.so*} files) are not copied into executables ---
the executable is written in such a way that it will automatically load the
libraries. In linux, the executable will first load the special library 
@code{ld.so} or @code{ld-linux.so}, which contains the intelligence
to load further dynamic libraries. Since multiple files end up getting
executable data from the same file, dynamic libraries are also known as
shared libraries.

Linux executables come in two flavors, @sc{elf} and a.out.

a.out is the original executable format used by Linux. It has somewhat less 
overhead than @sc{elf}. However creating shared libraries for a.out is
@emph{very} involved, and each a.out shared library must be explicitly 
registered.
 
@sc{elf} is a more recent format, which supports a much simpler method of
creating libraries. @sc{elf} libraries may also be linked manually
(@pxref{libdl}).

Since many library authors prefer @sc{elf} and no longer release shared a.out 
libraries, a.out is moribund on Linux. This version of the @code{ld.so} can
be compiled to support only @sc{elf}, or to support both formats. (The last
release of ld.so to support a.out alone was 1.8.0.)

@node ld.so
@chapter @code{ld.so}: Dynamic linker core

@code{ld.so} works behind the scenes to handle dynamic libraries in Linux.
Users will almost never have to deal with it directly, but in special cases
one can send instructions to it through environment variables. Also, if
something is wrong with your libraries (usually an incorrect version) ld.so
will give error messages.

Actually @code{ld.so} is the a.out linker. The new @sc{elf} executables are
handled by a related program @code{ld-linux.so}.

@menu
* files::	Configuration files used by the suite
* environment::	Environment settings that tweak @code{ld.so}
* errors::	Complaints @code{ld.so} might make
@end menu

@node files
@section Configuration Files

@table @file
@item /etc/ld.so.cache
A file created by @code{ldconfig} and used to speed linking. It's structure
is private to the suite.

@item /etc/ld.so.conf
A simple list of directories to scan for libraries, in addition to
@file{/usr/lib} and @file{/lib}, which are hardwired. It may contain
comments started with a @samp{#}.

@item /etc/ld.so.preload
A list of libraries to preload. This allows preloading libraries for
setuid/setgid executables securely. It may contain comments. 
@end table

@node environment
@section Environment Variables

@table @code
@item LD_AOUT_LIBRARY_PATH
@itemx LD_LIBRARY_PATH
These variables supply a library path for finding dynamic libraries, in the
standard colon seperated format. These variables are ignored when executing 
setuid/setgid programs, because otherwise they would be a security hazard. 
@code{ld.so} will use @code{LD_AOUT_LIBRARY_PATH} and @code{ld-linux.so} will 
use @code{LD_LIBRARY_PATH}.

@item LD_AOUT_PRELOAD
@itemx LD_PRELOAD
These variables allow an extra library not specified in the executable to be
loaded. Generally this is only useful if you want to override a function. 
These are also ignored when running setuid/setgid executables. @code{ld.so} 
will use @code{LD_AOUT_PRELOAD} and @code{ld-linux.so} will use 
@code{LD_PRELOAD}.

@item LD_NOWARN
If non-empty, errors about incompatible minor revisions are suppressed.

@item LD_KEEPDIR
If non-empty, allow executables to specify absolute library names. This
option is deprecated.
@c FIXME:
@c The following are things I noticed in the ld-linux.so source.
@c I don't really understand 'em. Could someone help me?
@c
@c @item LD_BIND_NOW
@c This option is used by the @code{ld-linux.so} only. I don't know 
@c what it does. (I suspect, looking at the code, that it specifies
@c "RTLD_NOW" rather than "RTLD_LAZY" mode for the shared libraries.)
@c 
@c @item LD_TRACE_LOADED_OBJECTS
@c @itemx LD_WARN
@c These seem to have something to do with the communication between the
@c @code{ld-linux.so} and @code{ldd}. I don't know more.
@end table

@node errors
@section Errors

@table @samp
@item Can't find library @var{library}
The executable required a dynamically linked library that ld.so cannot find.
Your symbolic links may be not set right, or you may have not installed a 
library needed by the program.

@item Can't load library @var{library}
The library is corrupt. 

@item Incompatible library @var{library}
@itemx   Require major version @var{x} and found @var{y}
Your version of the library is incompatible with the executable. Recompiling
the executable, or upgrading the library will fix the problem.

@item using incompatible library @var{library}
@itemx   Desire minor version >= @var{x} and found @var{y}.
Your version of the library is older than that expected by the executable,
but not so old that the library interface has radically changed, so the
linker will attempt to run anyway. There is a chance that it will work, but 
you should upgrade the library or recompile the software. The environment 
variable @code{LD_NOWARN} can be used to supress this message.

@item too many directories in library path
The linker only supports up to 32 library directories. You have too many.

@item dynamic linker error in @var{blah}
The linker is having trouble handling a binary - it is probably corrupt.

@item can't map cache file @var{cache-file}
@itemx cache file @var{cache-file} @var{blah}
The linker cache file (generally @file{/etc/ld.so.cache}) is corrupt or
non-existent. These errors can be ignored, and can be prevented by 
regenerating the cache file with @code{ldconfig}.
@end table

@node ldd
@chapter @code{ldd}: Dependency scanner

@code{ldd} is a utility that prints out the dynamic libraries that an
executable is linked to. 

Actually @code{ldd} works by signalling ld.so to print the dependencies. 
For a.out executables this is done by starting the executable with 
@code{argc} equal to 0. The linker detects this and prints the dependencies. 
(This can cause problems with @emph{very} old binaries, which would run as 
normal only with an inappropriate @code{argc}.)

For @sc{elf} executables, special environment variables are used to tell the
linker to print the dependencies.

@code{ldd} has a few options:

@table @samp
@item -v
Print the version number of @code{ldd} itself

@item -V
Print the version number of the dynamic linker

@item -d
Report missing functions. This is only supported for @sc{elf} executables.

@item -r
Report missing objects. This is also only available for @sc{elf}
executables.
@end table

@node ldconfig
@chapter @code{ldconfig}: Setup program 

This utility is used by the system administrator to automatically set up
symbolic links needed by the libraries, and also to set up the cache file.

@code{ldconfig} is run after new dynamic libraries are installed, and if the 
cache file or links are damaged. It is also run when upgrading the
@code{ld.so} suite itself.

The @file{/lib} and @file{/usr/lib} directories, and any listed in the file 
@file{/etc/ld.so.conf} are scanned by default unless @samp{-n} is used.
Additional directories may be specified on the command line.

It has the following options:

@table @samp
@item -D
Enter debug mode. Implies @samp{-N} and @samp{-X}.

@item -v
Verbose. Print out links created and directories scanned.

@item -n 
Check directories specified on the commandline @emph{only}.

@item -N
Do not regenerate the cache.

@item -X
Do not rebuild symbolic links.

@item -l
Set up symbolic links for only libraries presented on the command line.

@item -p
Print out the library pathnames in the cache file (@file{/etc/ld.so.cache})
@end table

@node libdl
@chapter User dynamic linking library

The @code{ld.so} package includes a small library of functions
(@code{libdl}) to allow manual dynamic linking. Normally programs are linked 
so that dynamic functions and objects are automagically available. These 
functions allow one to manually load and access a symbol from a library. 
They are only available for @sc{elf} executables.

@menu
* using libdl::	General points
* functions::	How to use the functions
* example::	A sample program
@end menu

@node using libdl
@section Overview

To access this library, add the flag @samp{-ldl} to your compile command when
linking the executable. You also must include the header file
@code{dlfcn.h}. You may also need the flag @samp{-rdynamic}, which enables
resolving references in the loaded libraries against your executable.

Generally, you will first use @code{dlopen} to open a library. Then you use
@code{dlsym} one or more times to access symbols. Finally you use
@code{dlclose} to close the library.

These facilities are most useful for language interpreters that provide
access to external libraries. Without @code{libdl}, it would be neccessary
to link the interpreter executable with any and all external libraries
needed by the programs it runs. With @code{libdl}, the interpreter only 
needs to be linked with the libraries it uses itself, and can dynamically 
load in additional ones if programs need it.

@node functions
@section Functions

@deftypefun void *dlopen ( const char @var{filename}, int @var{flags} )

This function opens the dynamic library specified by @var{filename}
and returns an abstract handle, which can be used in subsequent calls to 
@code{dlsym}. The function will respect the @code{LD_ELF_LIBRARY_PATH} and
@code{LD_LIBRARY_PATH} environment variables.

@end deftypefun

The following flags can be used with @code{dlopen}:

@deftypevr Macro int RTLD_LAZY
Resolve symbols in the library as they are needed.
@end deftypevr

@deftypevr Macro int RTLD_NOW
Resolve all symbols in the library before returning, and fail if not all can
be resolved. This is mutually exclusive with @code{RTLD_LAZY}.
@end deftypevr

@deftypevr Macro int RTLD_GLOBAL
Make symbols in this library available for resolving symbols in other
libraries loaded with @code{dlopen}.
@end deftypevr

@deftypefun int dlclose ( void *@var{handle} )

This function releases a library handle.

Note that if a library opened twice, the handle will be the same. However,
a reference count is used, so you should still close the library as many 
times as you open it.

@end deftypefun

@deftypefun void *dlsym (void *@var{handle},char *@var{symbol-name})

This function looks up the name @var{symbol-name} in the library and returns
it in the void pointer.

If there is an error, a null pointer will be returned. However, it is
possible for a valid name in the library to have a null value, so
@code{dlerror} should be used to check if there was an error.

@end deftypefun

@deftypefun {libdl function} {const char} *dlerror( void )

This function is used to read the error state. It returns a human-readable
string describing the last error, or null, meaning no error.

The function resets the error value each time it is called, so the result
should be copied into a variable. If the function is called more than once
after an error, the second and subsequent calls will return null.

@end deftypefun

@node example
@section Example program

Here is an example program that prints the cosine of two by manually linking
to the math library:
 
@example
@c The following was snarfed verbatim from the dlopen.3 man file.
#include <stdio.h>
#include <dlfcn.h>

int main(int argc, char **argv) @{
    void *handle;
    double (*cosine)(double);
    char *error;

    handle = dlopen ("/lib/libm.so", RTLD_LAZY);
    if (!handle) @{
        fputs (dlerror(), stderr);
        exit(1);
    @}

    cosine = dlsym(handle, "cos");
    if ((error = dlerror()) != NULL)  @{
        fputs(error, stderr);
        exit(1);
    @}

    printf ("%f\\n", (*cosine)(2.0));
    dlclose(handle);
@}
@end example

@contents

@bye