summaryrefslogtreecommitdiffstats
path: root/lib/csu/i386/dlopen.3
diff options
context:
space:
mode:
Diffstat (limited to 'lib/csu/i386/dlopen.3')
-rw-r--r--lib/csu/i386/dlopen.3236
1 files changed, 0 insertions, 236 deletions
diff --git a/lib/csu/i386/dlopen.3 b/lib/csu/i386/dlopen.3
deleted file mode 100644
index b9a987c..0000000
--- a/lib/csu/i386/dlopen.3
+++ /dev/null
@@ -1,236 +0,0 @@
-.\" 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
-.Dd September 24, 1989
-.Os FreeBSD
-.Dt DLOPEN 3
-.Sh NAME
-.Nm dlopen, dlsym, dlerror, dlclose
-.Nd programmatic interface to the dynamic linker
-.Sh SYNOPSIS
-.Fd #include <dlfcn.h>
-.Ft void *
-.Fn dlopen "const char *path" "int mode"
-.Ft void *
-.Fn dlsym "void *handle" "const char *symbol"
-.Ft const char *
-.Fn dlerror "void"
-.Ft int
-.Fn dlclose "void *handle"
-.Sh DESCRIPTION
-These functions provide a simple programmatic interface to the services of the
-dynamic linker.
-Operations are provided to add new shared objects to a
-program's address space, to obtain the address bindings of symbols
-defined by such
-objects, and to remove such objects when their use is no longer required.
-.Pp
-.Fn dlopen
-provides access to the shared object in
-.Fa path ,
-returning a descriptor that can be used for later
-references to the object in calls to
-.Fn dlsym
-and
-.Fn dlclose .
-If
-.Fa path
-was not in the address space prior to the call to
-.Fn dlopen ,
-it is placed in the address space.
-When an object is first loaded into the address space in this way, its
-function
-.Fn _init ,
-if any, is called by the dynamic linker.
-(Note that
-.Ql _init
-is the name as expressed in the C language.
-From assembly language, the name would appear as
-.Ql __init
-instead.)
-If
-.Fa path
-has already been placed in the address space in a previous call to
-.Fn dlopen ,
-it is not added a second time, although a reference count of
-.Fn dlopen
-operations on
-.Fa path
-is maintained.
-A null pointer supplied for
-.Fa path
-is interpreted as a reference to the main
-executable of the process.
-.Fa mode
-controls the way in which external function references from the
-loaded object are bound to their referents.
-It must contains one of the following values:
-.Bl -tag -width RTLD_LAZYX
-.It Dv RTLD_LAZY
-Each external function reference is resolved when the function is first
-called.
-.It Dv RTLD_NOW
-All external function references are bound immediately by
-.Fn dlopen .
-.El
-.Pp
-.Dv RTLD_LAZY
-is normally preferred, for reasons of efficiency.
-However,
-.Dv RTLD_NOW
-is useful to ensure that any undefined symbols are discovered during the
-call to
-.Fn dlopen .
-If
-.Fn dlopen
-fails, it returns a null pointer, and sets an error condition which may
-be interrogated with
-.Fn dlerror .
-.Pp
-.Fn dlsym
-returns the address binding of the symbol described in the null-terminated
-character string
-.Fa symbol ,
-as it occurs in the shared object identified by
-.Fa handle .
-Note that
-.Fa symbol
-is the assembly language representation of the symbol name.
-The assembly language representation of a C language symbol contains an
-extra underscore at the beginning.
-For example, the symbol
-.Ql foo
-in C would appear as
-.Ql _foo
-in assembly language, and in the
-.Fa symbol
-argument to
-.Fn dlsym .
-The symbols exported by objects added to the address space by
-.Fn dlopen
-can be accessed only through calls to
-.Fn 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 normal dynamic linking references.
-A null pointer supplied as the value of
-.Fa handle
-is interpreted as a reference to the executable from which the call to
-.Fn dlsym
-is being made. Thus a shared object can reference its own symbols.
-.Fn dlsym
-returns a null pointer if the symbol cannot be found, and sets an error
-condition which may be queried with
-.Fn dlerror .
-.Pp
-If
-.Fn dlsym
-is called with the special
-.Fa handle
-.Dv RTLD_NEXT ,
-then the search for the symbol is limited to the shared objects
-which were loaded after the one issuing the call to
-.Fn dlsym .
-Thus, if the function is called from the main program, all
-the shared libraries are searched.
-If it is called from a shared library, all subsequent shared
-libraries are searched.
-.Dv RTLD_NEXT
-is useful for implementing wrappers around library functions.
-For example, a wrapper function
-.Fn getpid
-could access the
-.Dq real
-.Fn getpid
-with
-.Li dlsym(RTLD_NEXT, \&"_getpid\&") .
-.Pp
-.Fn dlerror
-returns a null-terminated character string describing the last error that
-occurred during a call to
-.Fn dlopen ,
-.Fn dlsym ,
-or
-.Fn dlclose .
-If no such error has occurred,
-.Fn dlerror
-returns a null pointer.
-At each call to
-.Fn dlerror ,
-the error indication is reset. Thus in the case of two calls
-to
-.Fn dlerror ,
-where the second call follows the first immediately, the second call
-will always return a null pointer.
-.Pp
-.Fn dlclose
-deletes a reference to the shared object referenced by
-.Fa handle .
-If the reference count drops to 0, the object is removed from the
-address space, and
-.Fa handle
-is rendered invalid.
-Just before removing a shared object in this way, the dynamic linker
-calls the object's
-.Fn _fini
-function, if such a function is defined by the object.
-As with
-.Ql _init ,
-.Ql _fini
-is the C language name of the function.
-If
-.Fn dlclose
-is successful, it returns a value of 0.
-Otherwise it returns -1, and sets an error condition that can be
-interrogated with
-.Fn dlerror .
-.Pp
-The object-intrinsic functions
-.Fn _init
-and
-.Fn _fini
-are called with no arguments, and are not expected to return values.
-.Sh ERRORS
-.Fn dlopen
-and
-.Fn dlsym
-return the null pointer in the event of errors.
-.Fn dlclose
-returns 0 on success, or -1 if an error occurred.
-Whenever an error has been detected, a message detailing it can be
-retrieved via a call to
-.Fn dlerror .
-.Sh SEE ALSO
-.Xr ld 1 ,
-.Xr rtld 1 ,
-.Xr link 5
-
OpenPOWER on IntegriCloud