Subversion Repositories or1k

\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