123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317 |
- /****************************************************************************
- * include/dlfcn.h
- *
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership. The
- * ASF licenses this file to you under the Apache License, Version 2.0 (the
- * "License"); you may not use this file except in compliance with the
- * License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
- * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
- * License for the specific language governing permissions and limitations
- * under the License.
- *
- ****************************************************************************/
- #ifndef __INCLUDE_DLFCN_H
- #define __INCLUDE_DLFCN_H
- /****************************************************************************
- * Included Files
- ****************************************************************************/
- #include <nuttx/config.h>
- #include <sys/types.h>
- /****************************************************************************
- * Pre-processor Definitions
- ****************************************************************************/
- /* The dlfcn.h header defines at least the following macros for use in the
- * construction of a dlopen() mode argument:
- *
- * RTLD_LAZY - Relocations are performed at an implementation-dependent
- * time, ranging from the time of the dlopen() 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 behaviour mimics the
- * normal handling of process execution.
- * RTLD_NOW - All necessary relocations are performed when the object
- * is first loaded. This may waste some processing if
- * relocations are performed for functions that are never
- * referenced. This behaviour may be useful for
- * applications that need to know as soon as an object is
- * loaded that all symbols referenced during execution will
- * be available.
- *
- * Any object loaded by dlopen() that requires relocations against global
- * symbols can reference the symbols in the original process image file,
- * any objects loaded at program startup, from the object itself as well as
- * any other object included in the same dlopen() invocation, and any
- * objects that were loaded in any dlopen() invocation and which specified
- * the RTLD_GLOBAL flag. To determine the scope of visibility for the
- * symbols loaded with a dlopen() invocation, the mode parameter should be
- * bitwise or'ed with one of the following values:
- *
- * RTLD_GLOBAL - The object's symbols are made available for the
- * relocation processing of any other object. In addition,
- * symbol lookup using dlopen(0, mode) and an associated
- * dlsym() allows objects loaded with this mode to be
- * searched.
- * RTLD_LOCAL - All symbols are not made available for relocation
- * processing by other modules.
- *
- * Reference: OpenGroup.org
- */
- #define RTLD_LAZY (0 << 0)
- #define RTLD_NOW (1 << 0)
- #define RTLD_GLOBAL (1 << 1)
- #define RTLD_LOCAL (1 << 2)
- /****************************************************************************
- * Public Function Prototypes
- ****************************************************************************/
- #ifdef __cplusplus
- #define EXTERN extern "C"
- extern "C"
- {
- #else
- #define EXTERN extern
- #endif
- /****************************************************************************
- * Name: dlsymtab
- *
- * Description:
- * dlsymtab() is a non-standard shared library interface. It selects the
- * symbol table to use when binding a shared library to the base firmware
- * which may be in FLASH memory.
- *
- * Input Parameters:
- * symtab - The new symbol table.
- * nsymbols - The number of symbols in the symbol table.
- *
- * Returned Value:
- * Always returns OK.
- *
- ****************************************************************************/
- struct symtab_s;
- int dlsymtab(FAR const struct symtab_s *symtab, int nsymbols);
- /****************************************************************************
- * Name: dlopen
- *
- * Description:
- * dlopen() makes an executable object file specified by file available to
- * the calling program. The class of files eligible for this operation and
- * the manner of their construction are specified by the implementation,
- * 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 dlopen() operation will load
- * such dependencies in addition to the object referenced by file.
- * Implementations may also impose specific constraints on the construction
- * of programs that can employ dlopen() and its related services.
- *
- * If a file is specified in multiple dlopen() invocations, mode is
- * interpreted at each invocation. Note, however, that once RTLD_NOW has
- * been specified all relocations will 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 will maintain the RTLD_GLOBAL status regardless
- * of any previous or future specification of RTLD_LOCAL, so long as the
- * object remains in the address space (see dlclose()).
- *
- * Symbols introduced into a program through calls to dlopen() may be
- * used in relocation activities. Symbols so introduced may duplicate
- * symbols already defined by the program or previous dlopen()
- * 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: load or dependency 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
- * dlopen()). 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 dlopen() operation on a file of 0,
- * dependency ordering is used by the dlsym() function. Load ordering is
- * used in dlsym() operations upon the global symbol object.
- *
- * When an object is first made accessible via dlopen() 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.
- *
- * The symbols introduced by dlopen() operations, and available through
- * dlsym() are at a minimum those which are exported as symbols of global
- * scope by the object. Typically such symbols will be those that were
- * specified in (for example) C source code as having extern linkage. The
- * precise manner in which an implementation constructs the set of
- * exported symbols for a dlopen() object is specified by that
- * implementation.
- *
- * Input Parameters:
- * file - Used to construct a pathname to the object file. If file
- * contains a slash character, the file argument is used as the
- * pathname for the file. Otherwise, file is used in an
- * implementation-dependent manner to yield a pathname.
- *
- * If the value of file is 0, dlopen() provides a handle on a
- * global symbol object. This object provides access to the symbols
- * from an ordered set of objects consisting of the original
- * program image file, together with any objects loaded at program
- * startup as specified by that process image file (for example,
- * shared libraries), and the set of objects loaded using a
- * dlopen() operation together with the RTLD_GLOBAL flag. As the
- * latter set of objects can change during execution, the set
- * identified by handle can also change dynamically.
- *
- * Only a single copy of an object file is brought into the address
- * space, even if dlopen() is invoked multiple times in reference
- * to the file, and even if different pathnames are used to
- * reference the file.
- * mode - Describes how dlopen() will operate upon file with respect to
- * the processing of relocations and the scope of visibility of the
- * symbols provided within file. 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 must be relocated before the symbols can be accessed.
- * The mode parameter governs when these relocations take place.
- * See definitions above for values of the mode parameter:.
- *
- * Returned Value:
- * A successful dlopen() returns a handle which the caller may use on
- * subsequent calls to dlsym() and dlclose(). The value of this handle
- * should not be interpreted in any way by the caller.
- *
- * If file cannot be found, cannot be opened for reading, is not of an
- * appropriate object format for processing by dlopen(), or if an error
- * occurs during the process of loading file or relocating its symbolic
- * references, dlopen() will return NULL. More detailed diagnostic
- * information will be available through dlerror().
- *
- * Reference: OpenGroup.org
- *
- * **************************************************************************/
- FAR void *dlopen(FAR const char *file, int mode);
- /****************************************************************************
- * Name: dlsym
- *
- * Description:
- * dlsym() allows a process to obtain the address of a symbol defined
- * within an object made accessible through a dlopen() call. handle is the
- * value returned from a call to dlopen() (and which has not since been
- * released via a call to dlclose()), name is the symbol's name as a
- * character string.
- *
- * dlsym() will search for the named symbol in all objects loaded
- * automatically as a result of loading the object referenced by handle
- * (see dlopen()). Load ordering is used in dlsym() operations upon the
- * global symbol object. The symbol resolution algorithm used will be
- * dependency order as described in dlopen().
- *
- * Input Parameters:
- * handle - The opaque, non-NULL value returned by a previous successful
- * call to dlopen().
- * name - A pointer to the symbol name string.
- *
- * Returned Value:
- * If handle does not refer to a valid object opened by dlopen(), or if
- * the named symbol cannot be found within any of the objects associated
- * with handle, dlsym() will return NULL. More detailed diagnostic
- * information will be available through dlerror().
- *
- * Reference: OpenGroup.org
- *
- ****************************************************************************/
- FAR void *dlsym(FAR void *handle, FAR const char *name);
- /****************************************************************************
- * Name: dlclose
- *
- * Description:
- * dlclose() is used to inform the system that the object referenced by a
- * handle returned from a previous dlopen() invocation is no longer needed
- * by the application.
- *
- * The use of dlclose() reflects a statement of intent on the part of the
- * process, but does not create any requirement upon the implementation,
- * such as removal of the code or symbols referenced by handle. Once an
- * object has been closed using dlclose() an application should assume
- * that its symbols are no longer available to dlsym(). All objects loaded
- * automatically as a result of invoking dlopen() on the referenced object
- * are also closed.
- *
- * Although a dlclose() operation is not required to remove structures
- * from an address space, neither is an implementation prohibited from
- * doing so. The only restriction on such a removal is that no object will
- * be removed to which references have been relocated, until or unless all
- * such references are removed. For instance, an object that had been
- * loaded with a dlopen() operation specifying the RTLD_GLOBAL flag might
- * provide a target for dynamic relocations performed in the processing of
- * other objects - in such environments, an application may assume that no
- * relocation, once made, will be undone or remade unless the object
- * requiring the relocation has itself been removed.
- *
- * Input Parameters:
- * handle - The opaque, non-NULL value returned by a previous successful
- * call to dlopen().
- *
- * Returned Value:
- * If the referenced object was successfully closed, dlclose() returns 0.
- * If the object could not be closed, or if handle does not refer to an
- * open object, dlclose() returns a non-zero value. More detailed
- * diagnostic information will be available through dlerror().
- *
- * Reference: OpenGroup.org
- * *************************************************************************/
- int dlclose(FAR void *handle);
- /****************************************************************************
- * Name: dlerror
- *
- * Description:
- * dlerror() returns a null-terminated character string (with no trailing
- * newline) that describes the last error that occurred during dynamic
- * linking processing. If no dynamic linking errors have occurred since
- * the last invocation of dlerror(), dlerror() returns NULL. Thus,
- * invoking dlerror() a second time, immediately following a prior
- * invocation, will result in NULL being returned.
- *
- * Input Parameters:
- * If successful, dlerror() returns a null-terminated character string.
- * Otherwise, NULL is returned.
- *
- * Returned Value:
- *
- * Reference: OpenGroup.org
- *
- ****************************************************************************/
- FAR char *dlerror(void);
- #undef EXTERN
- #ifdef __cplusplus
- }
- #endif
- #endif /* __INCLUDE_DLFCN_H */
|