/[ascend]/trunk/base/generic/utilities/ascDynaLoad.h
ViewVC logotype

Contents of /trunk/base/generic/utilities/ascDynaLoad.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 158 - (show annotations) (download) (as text)
Mon Jan 2 09:02:52 2006 UTC (13 years, 11 months ago) by johnpye
File MIME type: text/x-chdr
File size: 7293 byte(s)
Removed support for Ultrix, OSF, which seem to be dead. This
makes the ascDynaload.c file much smaller. Also removed unused DynamicLoad
function (use Asc_DynamicLoad instead). Please let me know if these changes
break anything for you.
1 /*
2 * -----------------------------------------------------------------
3 * Copyright 1993 D.I.S. - Universita` di Pavia - Italy
4 * -----------------------------------------------------------------
5 *
6 * Permission to use, copy, modify, distribute this software
7 * and its documentation foar any purpose is hereby granted without
8 * fee, provided that the above copyright notice appear in all
9 * copies and that both that copyright notice and this permission
10 * notice appear in supporting documentation, and that the name of
11 * D.I.S. not be used in advertising or publicity pertaining to
12 * distribution of the software without specific, written prior per-
13 * mission. D.I.S. makes no representations about the suitability
14 * of this software for any purpose. It is provided "as is" without
15 * express or implied warranty.
16 *
17 * D.I.S. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, IN-
18 * CLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
19 * NO EVENT SHALL D.I.S. BE LIABLE FOR ANY SPECIAL, INDIRECT OR
20 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
21 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
22 * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNEC-
23 * TION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
24 */
25
26 /* ChangeLog
27 * Small changes made by Michael Moore (mdm@cis.ohio-state.edu)
28 * December 24th, 1993.
29 * The tcl sections ripped out by Kirk Abbott (ka0p@edrc.cmu.edu)
30 * September 3rd, 1994.
31 * To date the architectures supported are:
32 * sun
33 * solaris,
34 * hpux
35 * sgi
36 * Windows
37 * possibly aix if we plunder it from tcl8
38 *
39 * Added Asc_DynamicUnLoad. Ben Allan (ballan@cs.cmu.edu) Jan 1998.
40 * Your mileage may vary.
41 * UnLoad alleged for sun, hp, sgi, and alpha/osf. It probably works
42 * only as well as their dlclose and shl_unload do.
43 *
44 * Split Asc_DynamicSymbol() into Asc_DynamicVariable() and
45 * Asc_DynamicFunction() so callers don't have to cast between
46 * data and function pointers (forbidden by ISO C). JDS Dec 2005
47 */
48
49 /** @file
50 * Dynamic library routines.
51 * <pre>
52 * Reaquires:
53 * #include "utilities/ascConfig.h"
54 * </pre>
55 */
56
57 #ifndef ASC_ASCDYNALOAD_H
58 #define ASC_ASCDYNALOAD_H
59
60 extern int Asc_DynamicLoad(CONST char *path, CONST char *initFunc);
61 /**<
62 * Loads a dynamic library and calls its initialization function.
63 * This is our function wrapping dlopen/LoadLibrary. It makes
64 * provision for dynamic unloading using Asc_DynamicUnLoad().<br><br>
65 *
66 * Returns 1 if it fails to load the library named in path and find
67 * the symbol initFunc as an int function. Otherwise, it returns
68 * the result of the call to (*initFunc). If initFunc == NULL,
69 * nothing is called and 0 is returned after opening the library.
70 * If path == NULL, 1 is always returned.<br><br>
71 *
72 * A consequence of this behavior is that initFunc had better not
73 * return 1, or you won't be able to tell whether the library was
74 * successfully loaded or not. If it's under your control, have
75 * initFunc only return values other than 1 so you can detect the
76 * proper status.<br><br>
77 *
78 * @param path Path to the dynamic library to load (non-NULL).
79 * @param initFunc The DL initialization function to call.
80 * @return The return value from initFunc is returned if specified.
81 * Otherwise, 0 is returned if the library is successfully
82 * loaded, 1 if it is not.
83 */
84
85 extern int Asc_DynamicUnLoad(CONST char *path);
86 /**<
87 * Attempts to unload a dynamic library.
88 * This function tries to look up the previously-loaded library
89 * in path and unload it. Only libraries successfully loaded using
90 * Asc_DynamicLoad() may be unloaded using this function.<br><br>
91 *
92 * This is our function wrapping dlclose/shl_unload/FreeLibrary
93 * which provides unloading. Once all references to the
94 * previously-loaded library have been scheduled to be removed
95 * without further ado, it can be unloaded on most architectures.
96 * Once you call this function, you damn well better not reference
97 * functions or data that came from the path given. Passing a NULL
98 * path will always result in an error condition (-3) being returned.
99 *
100 * @param path Path to the dynamic library to unload.
101 * @return Returns 0 if the library was successfully located and unloaded,
102 * -3 if the library was not located, or the return value of
103 * dlclose/shl_unload/FreeLibrary otherwise. Note that the
104 * return value conventions differ between platforms, so if you
105 * get a return value that is not 0 or -3, you are in platform-
106 * specific hell.
107 */
108
109 #define Asc_DynamicSymbol(a,b) Asc_DynamicVariable((a),(b))
110 /**< For backward compatibility to old name of Asc_DynamicVariable() */
111
112 extern void *Asc_DynamicVariable(CONST char *libraryname,
113 CONST char *varname);
114 /**<
115 * Returns a pointer to a variable exported from a dynamically-linked
116 * library. It will generally be necessary to cast the returned
117 * pointer to the correct data type before use. If either parameter
118 * is NULL, or if the library or symbol cannot be located, then NULL
119 * will be returned.<br><br>
120 *
121 * This function was previously called Asc_DynamicSymbol() and could
122 * be used to retrieve either variables or functions from a library.
123 * This necessitated casting the returned void* to a function pointer
124 * for exported functions, which is forbidden by ISO C. Functions
125 * may now be retrieved using Asc_DynamicFunction(), thus avoiding the
126 * need for the caller to cast between data and function pointers.
127 * Never mind what the implementation does to achieve this.
128 * <pre>
129 * Example:
130 * int *value;
131 * value = (int *)Asc_DynamicVariable("lib.dll", "g_variable");
132 * </pre>
133 * @param libraryname Name of the dynamic library to query.
134 * @param varname Name of variable to look up in the library.
135 * @return A pointer to the variable in memory, or NULL if not found.
136 */
137
138 typedef void (*DynamicF)(void);
139 /**< Function pointer type returned by Asc_DynamicFunction(). */
140
141 extern DynamicF Asc_DynamicFunction(CONST char *libraryname,
142 CONST char *funcname);
143 /**<
144 * Returns a pointer to a function exported from a dynamically-linked
145 * library. It will generally be necessary to cast the returned pointer
146 * to the correct function type before use. If either parameter
147 * is NULL, or if the library or function cannot be located, then NULL
148 * will be returned.
149 * <pre>
150 * Example:
151 * typedef double (*calcfunc)(double *, double *);
152 * calcfunc calc;
153 * calc = (calcfunc))Asc_DynamicFunction("lib.dll","calc");
154 * </pre>
155 * @param libraryname Name of the dynamic library to query.
156 * @param funcname Name of function to look up in the library.
157 * @return A pointer to the function in memory, or NULL if not found.
158 */
159
160 #if (defined(__HPUX__) || defined(__ALPHA_OSF__) || \
161 defined(__WIN32__) || defined(__SUN_SOLARIS__) || \
162 defined(__SUN_SUNOS__) || defined(__SGI_IRIX__))
163 #define HAVE_DL_UNLOAD 1
164 /**<
165 * Set if a platform has a library unload function.
166 * We don't know about aix, and others.
167 */
168 #endif
169
170 #endif /* ASC_ASCDYNALOAD_H */
171

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22