198 lines
5.8 KiB
Groff
198 lines
5.8 KiB
Groff
.\" This source code is a product of Sun Microsystems, Inc. and is provided
|
|
.\" for unrestricted use provided that this legend is included on all tape
|
|
.\" media and as a part of the software program in whole or part. Users
|
|
.\" may copy or modify this source code without charge, but are not authorized
|
|
.\" to license or distribute it to anyone else except as part of a product or
|
|
.\" program developed by the user.
|
|
.\"
|
|
.\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC.
|
|
.\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY
|
|
.\" OF SUCH SOURCE CODE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT
|
|
.\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND. SUN MICROSYSTEMS, INC. DISCLAIMS
|
|
.\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED
|
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN
|
|
.\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT,
|
|
.\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
|
.\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY.
|
|
.\"
|
|
.\" This source code is provided with no support and without any obligation on
|
|
.\" the part of Sun Microsystems, Inc. to assist in its use, correction,
|
|
.\" modification or enhancement.
|
|
.\"
|
|
.\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
|
|
.\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS
|
|
.\" SOURCE CODE OR ANY PART THEREOF.
|
|
.\"
|
|
.\" Sun Microsystems, Inc.
|
|
.\" 2550 Garcia Avenue
|
|
.\" Mountain View, California 94043
|
|
.\"
|
|
.\" Copyright (c) 1991 Sun Microsystems, Inc.
|
|
.\"
|
|
.\" @(#) dlopen.3 1.6 90/01/31 SMI
|
|
.TH DLOPEN 3 "24 September 1989"
|
|
.SH NAME
|
|
dlopen, dlsym, dlerror, dlclose \- simple programmatic interface to the dynamic linker
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <dlfcn.h>
|
|
.LP
|
|
.ft B
|
|
.nf
|
|
void *dlopen(path, mode)
|
|
const char *path; int mode;
|
|
.fi
|
|
.ft R
|
|
.LP
|
|
.ft B
|
|
.nfvoid *dlopen(path, mode)
|
|
.fi
|
|
.ft R
|
|
.LP
|
|
.ft B
|
|
.nf
|
|
void *dlsym(handle, symbol)
|
|
void *handle; const char *symbol;
|
|
.fi
|
|
.ft R
|
|
.LP
|
|
.ft B
|
|
.nf
|
|
char *dlerror(\|)
|
|
.fi
|
|
.ft R
|
|
.LP
|
|
.ft B
|
|
.nf
|
|
int dlclose(handle);
|
|
void *handle;
|
|
.fi
|
|
.ft R
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.IX "dlopen()" "" "\fLdlopen()\fP \(em dynamically load a shared object"
|
|
.IX "programmatic interface to dynamic linker" dlopen() "" \fLdlopen()\fP
|
|
.IX "dlsym()" "" "\fLdlsym()\fP \(em dynamically lookup a symbol"
|
|
.IX "programmatic interface to dynamic linker" dlsym "" \fLdlsym()\fP
|
|
.IX "dlerror()" "" "\fLdlerror()\fP \(em dynamic linking error string"
|
|
.IX "programmatic interface to dynamic linker" dlerror() "" \fLdlerror()\fP
|
|
.IX "dlclose()" "" "\fLdlclose()\fP \(em unload a shared object"
|
|
.IX "programmatic interface to dynamic linker" dlclose() "" \fLdlclose()\fP
|
|
.LP
|
|
These functions provide a simple programmatic interface to the services of the
|
|
dynamic link-editor.
|
|
Operations are provided to add a new shared object to an
|
|
program's address space, obtain the address bindings of symbols defined by such
|
|
objects, and to remove such objects when their use is no longer required.
|
|
.LP
|
|
.B dlopen(\|)
|
|
provides access to the shared object in
|
|
.IR path ,
|
|
returning a descriptor that can be used for later
|
|
references to the object in calls to
|
|
.B dlsym(\|)
|
|
and
|
|
.BR dlclose(\|) .
|
|
If
|
|
.I path
|
|
was not in the address space prior to the call to
|
|
.BR dlopen(\|) ,
|
|
then it will be placed in the address space, and if it defines a function
|
|
with the name
|
|
.I _init
|
|
that function will be called by
|
|
.BR dlopen(\|) .
|
|
If, however,
|
|
.I path
|
|
has already been placed in the address space in a previous call to
|
|
.BR dlopen(\|) ,
|
|
then it will not be added a
|
|
second time, although a count of
|
|
.B dlopen(\|)
|
|
operations on
|
|
.I path
|
|
will be maintained.
|
|
.I mode
|
|
is an integer containing flags describing options to be applied to the opening
|
|
and loading process \(em it is reserved for future expansion and must always have
|
|
the value 1.
|
|
A null pointer supplied for
|
|
.I path
|
|
is interpreted as a reference to the \*(lqmain\*(rq
|
|
executable of the process.
|
|
If
|
|
.B dlopen(\|)
|
|
fails, it will return a null pointer.
|
|
.LP
|
|
.B dlsym(\|)
|
|
returns the address binding of the symbol described in the null-terminated
|
|
character string
|
|
.I symbol
|
|
as it occurs in the shared object identified by
|
|
.IR handle .
|
|
The symbols exported by objects added to the address space by
|
|
.B dlopen(\|)
|
|
can be accessed
|
|
.I only
|
|
through calls to
|
|
.BR dlsym(\|) ,
|
|
such symbols do not supersede any definition of those symbols already present
|
|
in the address space when the object is loaded, nor are they available to
|
|
satisfy \*(lqnormal\*(rq dynamic linking references.
|
|
.B dlsym(\|)
|
|
returns a null pointer if the symbol can not be found.
|
|
A null pointer supplied as the value of
|
|
.I handle
|
|
is interpreted as a reference to the executable from which the call to
|
|
.B dlsym(\|)
|
|
is being made \(em thus a shared object can reference its own symbols.
|
|
.LP
|
|
.B dlerror
|
|
returns a null-terminated character string describing the last error that
|
|
occurred during a
|
|
.BR dlopen(\|) ,
|
|
.BR dlsym(\|) ,
|
|
or
|
|
.BR dlclose(\|) .
|
|
If no such error has occurred, then
|
|
.B dlerror(\|)
|
|
will return a null pointer.
|
|
At each call to
|
|
.BR dlerror(\|) ,
|
|
the \*(lqlast error\*(rq indication will be reset, thus in the case of two calls
|
|
to
|
|
.BR dlerror(\|) ,
|
|
and where the second call follows the first immediately, the second call
|
|
will always return a null pointer.
|
|
.LP
|
|
.B dlclose(\|)
|
|
deletes a reference to the shared object referenced by
|
|
.IR handle .
|
|
If the reference count drops to 0, then if the object referenced by
|
|
.I handle
|
|
defines a function
|
|
.IR _fini ,
|
|
that function will be called, the object
|
|
removed from the address space, and
|
|
.I handle
|
|
destroyed.
|
|
If
|
|
.B dlclose(\|)
|
|
is successful, it will return a value of 0.
|
|
A failing call to
|
|
.B dlclose(\|)
|
|
will return a non-zero value.
|
|
.LP
|
|
The object-intrinsic functions
|
|
.I _init
|
|
and
|
|
.I _fini
|
|
are called with no arguments and treated as though their types were
|
|
.BR void .
|
|
.SH SEE ALSO
|
|
.BR ld (1),
|
|
.BR link (5)
|
|
.SH NOTES
|