205 lines
11 KiB
HTML
205 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>dlopen</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="dlopen"></a> <a name="tag_03_111"></a><!-- dlopen -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_111_01"></a>NAME</h4>
|
|
|
|
<blockquote>dlopen - gain access to an executable object file</blockquote>
|
|
|
|
<h4><a name="tag_03_111_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> #include <<a href="../basedefs/dlfcn.h.html">dlfcn.h</a>><br>
|
|
<br>
|
|
void *dlopen(const char *</tt><i>file</i><tt>, int</tt> <i>mode</i><tt>); <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></tt></code></div>
|
|
|
|
<tt><br>
|
|
</tt></blockquote>
|
|
|
|
<h4><a name="tag_03_111_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>dlopen</i>() function shall make an executable object file specified by <i>file</i> available to the calling program. The
|
|
class of files eligible for this operation and the manner of their construction are implementation-defined, though typically such
|
|
files are executable objects such as shared libraries, relocatable files, or programs. Note that some implementations permit the
|
|
construction of dependencies between such objects that are embedded within files. In such cases, a <i>dlopen</i>() operation shall
|
|
load such dependencies in addition to the object referenced by <i>file</i>. Implementations may also impose specific constraints on
|
|
the construction of programs that can employ <i>dlopen</i>() and its related services.</p>
|
|
|
|
<p>A successful <i>dlopen</i>() shall return a <i>handle</i> which the caller may use on subsequent calls to <a href=
|
|
"../functions/dlsym.html"><i>dlsym</i>()</a> and <a href="../functions/dlclose.html"><i>dlclose</i>()</a>. The value of this
|
|
<i>handle</i> should not be interpreted in any way by the caller.</p>
|
|
|
|
<p>The <i>file</i> argument is used to construct a pathname to the object file. If <i>file</i> contains a slash character, the
|
|
<i>file</i> argument is used as the pathname for the file. Otherwise, <i>file</i> is used in an implementation-defined manner to
|
|
yield a pathname.</p>
|
|
|
|
<p>If the value of <i>file</i> is 0, <i>dlopen</i>() shall provide a <i>handle</i> on a global symbol object. This object shall
|
|
provide access to the symbols from an ordered set of objects consisting of the original program image file, together with any
|
|
objects loaded at program start-up as specified by that process image file (for example, shared libraries), and the set of objects
|
|
loaded using a <i>dlopen</i>() operation together with the RTLD_GLOBAL flag. As the latter set of objects can change during
|
|
execution, the set identified by <i>handle</i> can also change dynamically.</p>
|
|
|
|
<p>Only a single copy of an object file is brought into the address space, even if <i>dlopen</i>() is invoked multiple times in
|
|
reference to the file, and even if different pathnames are used to reference the file.</p>
|
|
|
|
<p>The <i>mode</i> parameter describes how <i>dlopen</i>() shall operate upon <i>file</i> with respect to the processing of
|
|
relocations and the scope of visibility of the symbols provided within <i>file</i>. When an object is brought into the address
|
|
space of a process, it may contain references to symbols whose addresses are not known until the object is loaded. These references
|
|
shall be relocated before the symbols can be accessed. The <i>mode</i> parameter governs when these relocations take place and may
|
|
have the following values:</p>
|
|
|
|
<dl compact>
|
|
<dt>RTLD_LAZY</dt>
|
|
|
|
<dd>Relocations shall be performed at an implementation-defined time, ranging from the time of the <i>dlopen</i>() call until the
|
|
first reference to a given symbol occurs. Specifying RTLD_LAZY should improve performance on implementations supporting dynamic
|
|
symbol binding as a process may not reference all of the functions in any given object. And, for systems supporting dynamic symbol
|
|
resolution for normal process execution, this behavior mimics the normal handling of process execution.</dd>
|
|
|
|
<dt>RTLD_NOW</dt>
|
|
|
|
<dd>All necessary relocations shall be performed when the object is first loaded. This may waste some processing if relocations are
|
|
performed for functions that are never referenced. This behavior may be useful for applications that need to know as soon as an
|
|
object is loaded that all symbols referenced during execution are available.</dd>
|
|
</dl>
|
|
|
|
<p>Any object loaded by <i>dlopen</i>() that requires relocations against global symbols can reference the symbols in the original
|
|
process image file, any objects loaded at program start-up, from the object itself as well as any other object included in the same
|
|
<i>dlopen</i>() invocation, and any objects that were loaded in any <i>dlopen</i>() invocation and which specified the RTLD_GLOBAL
|
|
flag. To determine the scope of visibility for the symbols loaded with a <i>dlopen</i>() invocation, the <i>mode</i> parameter
|
|
should be a bitwise-inclusive OR with one of the following values:</p>
|
|
|
|
<dl compact>
|
|
<dt>RTLD_GLOBAL</dt>
|
|
|
|
<dd>The object's symbols shall be made available for the relocation processing of any other object. In addition, symbol lookup
|
|
using <i>dlopen</i>(<i>0, mode</i>) and an associated <a href="../functions/dlsym.html"><i>dlsym</i>()</a> allows objects loaded
|
|
with this <i>mode</i> to be searched.</dd>
|
|
|
|
<dt>RTLD_LOCAL</dt>
|
|
|
|
<dd>The object's symbols shall not be made available for the relocation processing of any other object.</dd>
|
|
</dl>
|
|
|
|
<p>If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, then an implementation-defined default behavior shall be applied.</p>
|
|
|
|
<p>If a <i>file</i> is specified in multiple <i>dlopen</i>() invocations, <i>mode</i> is interpreted at each invocation. Note,
|
|
however, that once RTLD_NOW has been specified all relocations shall have been completed rendering further RTLD_NOW operations
|
|
redundant and any further RTLD_LAZY operations irrelevant. Similarly, note that once RTLD_GLOBAL has been specified the object
|
|
shall maintain the RTLD_GLOBAL status regardless of any previous or future specification of RTLD_LOCAL, as long as the object
|
|
remains in the address space (see <a href="dlclose.html"><i>dlclose</i>()</a> ).</p>
|
|
|
|
<p>Symbols introduced into a program through calls to <i>dlopen</i>() may be used in relocation activities. Symbols so introduced
|
|
may duplicate symbols already defined by the program or previous <i>dlopen</i>() operations. To resolve the ambiguities such a
|
|
situation might present, the resolution of a symbol reference to symbol definition is based on a symbol resolution order. Two such
|
|
resolution orders are defined: <i>load</i> or <i>dependency</i> ordering. Load order establishes an ordering among symbol
|
|
definitions, such that the definition first loaded (including definitions from the image file and any dependent objects loaded with
|
|
it) has priority over objects added later (via <i>dlopen</i>()). Load ordering is used in relocation processing. Dependency
|
|
ordering uses a breadth-first order starting with a given object, then all of its dependencies, then any dependents of those,
|
|
iterating until all dependencies are satisfied. With the exception of the global symbol object obtained via a <i>dlopen</i>()
|
|
operation on a <i>file</i> of 0, dependency ordering is used by the <a href="../functions/dlsym.html"><i>dlsym</i>()</a> function.
|
|
Load ordering is used in <a href="../functions/dlsym.html"><i>dlsym</i>()</a> operations upon the global symbol object.</p>
|
|
|
|
<p>When an object is first made accessible via <i>dlopen</i>() it and its dependent objects are added in dependency order. Once all
|
|
the objects are added, relocations are performed using load order. Note that if an object or its dependencies had been previously
|
|
loaded, the load and dependency orders may yield different resolutions.</p>
|
|
|
|
<p>The symbols introduced by <i>dlopen</i>() operations and available through <a href="../functions/dlsym.html"><i>dlsym</i>()</a>
|
|
are at a minimum those which are exported as symbols of global scope by the object. Typically such symbols shall be those that were
|
|
specified in (for example) C source code as having <i>extern</i> linkage. The precise manner in which an implementation constructs
|
|
the set of exported symbols for a <i>dlopen</i>() object is specified by that implementation.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_111_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>If <i>file</i> cannot be found, cannot be opened for reading, is not of an appropriate object format for processing by
|
|
<i>dlopen</i>(), or if an error occurs during the process of loading <i>file</i> or relocating its symbolic references,
|
|
<i>dlopen</i>() shall return NULL. More detailed diagnostic information shall be available through <a href=
|
|
"dlerror.html"><i>dlerror</i>()</a> .</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_111_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>No errors are defined.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_111_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_111_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_111_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_111_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_111_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="dlclose.html"><i>dlclose</i>()</a> , <a href="dlerror.html"><i>dlerror</i>()</a> , <a href=
|
|
"dlsym.html"><i>dlsym</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/dlfcn.h.html"><i><dlfcn.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_111_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 5.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|