generic/utilities/ascDynaLoad.h

/*
 *  -----------------------------------------------------------------
 *    Copyright 1993 D.I.S. - Universita` di Pavia - Italy
 *  -----------------------------------------------------------------
 *
 *  Permission to  use,  copy,   modify,   distribute  this  software
 *  and  its  documentation foar any purpose is hereby granted without
 *  fee, provided that the above copyright  notice   appear   in  all
 *  copies   and  that both that copyright notice and this permission
 *  notice appear in supporting documentation, and that the  name  of
 *  D.I.S.   not  be  used  in advertising or publicity pertaining to
 *  distribution of the software without specific, written prior per-
 *  mission.   D.I.S.  makes no representations about the suitability
 *  of this software for any purpose.  It is provided "as is" without
 *  express or implied warranty.
 *
 *  D.I.S. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, IN-
 *  CLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
 *  NO EVENT SHALL D.I.S.  BE LIABLE FOR  ANY  SPECIAL,  INDIRECT  OR
 *  CONSEQUENTIAL  DAMAGES  OR  ANY DAMAGES WHATSOEVER RESULTING FROM
 *  LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION  OF  CONTRACT,
 *  NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNEC-
 *  TION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

/* ChangeLog
 * Small changes made by Michael Moore (mdm@cis.ohio-state.edu)
 * December 24th, 1993.
 * The tcl sections ripped out by Kirk Abbott (ka0p@edrc.cmu.edu)
 * September 3rd, 1994.
 * To date the architectures supported are:
 * sun
 * osf,
 * solaris,
 * hpux
 * sgi
 * ultrix
 * possibly aix if we plunder it from tcl8
 *
 * Added Asc_DynamicUnLoad. Ben Allan (ballan@cs.cmu.edu) Jan 1998.
 * Your mileage may vary.
 * UnLoad alleged for sun, hp, sgi, and alpha/osf. It probably works
 * only as well as their dlclose and shl_unload do.
 */

/** @file
 *  Dynamic library routines.
 *  <pre>
 *  Reaquires:
 *        #include "utilities/ascConfig.h"
 *  </pre>
 */

#ifndef __ascdynaload_h_seen__
#define __ascdynaload_h_seen__

extern int Asc_DynamicLoad(CONST char *path, CONST char *initFunc);
/**<
 *  Loads a dynamic library and calls its initialization function.
 *  This is our function wrapping dlopen/LoadLibrary.  It makes
 *  provision for dynamic unloading using Asc_DynamicUnLoad().<br><br>
 *
 *  Returns 1 if it fails to load the library named in path and find
 *  the symbol initFunc as an int function.  Otherwise, it returns
 *  the result of the call to (*initFunc).  If initFunc == NULL,
 *  nothing is called and 0 is returned after opening the library.
 *  If path == NULL, 1 is always returned.<br><br>
 *
 *  A consequence of this behavior is that initFunc had better not
 *  return 1, or you won't be able to tell whether the library was
 *  successfully loaded or not.  If it's under your control, have
 *  initFunc only return values other than 1 so you can detect the
 *  proper status.<br><br>
 *
 *  @param path     Path to the dynamic library to load (non-NULL).
 *  @param initFunc The DL initialization function to call.
 *  @return The return value from initFunc is returned if specified.
 *          Otherwise, 0 is returned if the library is successfully
 *          loaded, 1 if it is not.
 */

extern int DynamicLoad(CONST char *path, CONST char *initFunc);
/**<
 *  Loads a dynamic library and calls its initialization function.
 *  This is the standard function wrapping dlopen. It makes no
 *  provision for dynamic unloading, and therefore should not
 *  be used very often.  It is not currently implemented for all
 *  platforms (e.g. Win32).<br><br>
 *
 *  This function returns 1 if it fails to load the file named in
 *  path and find the symbol in initFun as an int function.
 *  Otherwise it returns the result of the call to initFun.  See 
 *  the discussion under Asc_DynamicLoad() for more issues 
 *  arising from this behavior.
 *
 *  @param path     Path to the dynamic library to load (non-NULL).
 *  @param initFunc The DL initialization function to call.
 *  @return The return value from initFunc is returned if specified.
 *          Otherwise, 0 is returned if the library is successfully
 *          loaded, 1 if it is not.
 */
/*
 * note on some systems (ultrix) this header hides a lot of non-static
 * function names which don't appear terribly standard.
 */

extern int Asc_DynamicUnLoad(CONST char *path);
/**<
 *  Attempts to unload a dynamic library.
 *  This function tries to look up the previously-loaded library
 *  in path and unload it.  Only libraries successfully loaded using
 *  Asc_DynamicLoad() may be unloaded using this function.<br><br>
 *
 *  This is our function wrapping dlclose/shl_unload/FreeLibrary
 *  which provides unloading.  Once all references to the
 *  previously-loaded library have been scheduled to be removed
 *  without further ado, it can be unloaded on most architectures.
 *  Once you call this function, you damn well better not reference
 *  functions or data that came from the path given.  Passing a NULL
 *  path will always result in an error condition (-3) being returned.
 *
 *  @param path     Path to the dynamic library to unload.
 *  @return Returns 0 if the library was successfully located and unloaded,
 *          -3 if the library was not located, or the return value of 
 *          dlclose/shl_unload/FreeLibrary otherwise.  Note that the
 *          return value conventions differ between platforms, so if you
 *          get a return value that is not 0 or -3, you are in platform-
 *          specific hell.
 */

extern void *Asc_DynamicSymbol(CONST char *libraryname,
                               CONST char *symbolname);
/**<
 *  Returns a pointer to a symbol exported from a dynamically-linked
 *  library.  It will generally be necessary to cast the returned pointer
 *  to the correct function or data type before use.  If either parameter 
 *  is NULL, or if the library or symbol cannot be located, then NULL will
 *  be returned.
 *  <pre>
 *  Example:
 *    typedef double (*calcfunc)(double *, double *);
 *    calcfunc calc;
 *    calc = (calcfunc))Asc_DynamicSymbol("lib.dll","calc");
 *  </pre>
 *  @param libraryname Name of the dynamic library to query.
 *  @param symbolname  Symbol to look up in the library.
 *  @return A pointer to the symbol in memory, or NULL if not found.
 */

#if (defined(__HPUX__) || defined(__ALPHA_OSF__) || \
     defined(__WIN32__) || defined(__SUN_SOLARIS__) || \
     defined(__SUN_SUNOS__) || defined(__SGI_IRIX__))
#define HAVE_DL_UNLOAD 1
/**<
 *  Set if a platform has a library unload function.
 *  We don't know about ultrix, aix, and others.
 */
#endif

#endif /* __ascdynaload_h_seen__ */

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	* osf,
34	* solaris,
35	* hpux
36	* sgi
37	* ultrix
38	* possibly aix if we plunder it from tcl8
39	*
40	* Added Asc_DynamicUnLoad. Ben Allan (ballan@cs.cmu.edu) Jan 1998.
41	* Your mileage may vary.
42	* UnLoad alleged for sun, hp, sgi, and alpha/osf. It probably works
43	* only as well as their dlclose and shl_unload do.
44	*/
45
46	/** @file
47	* Dynamic library routines.
48	* <pre>
49	* Reaquires:
50	* #include "utilities/ascConfig.h"
51	* </pre>
52	*/
53
54	#ifndef __ascdynaload_h_seen__
55	#define __ascdynaload_h_seen__
56
57	extern int Asc_DynamicLoad(CONST char path, CONST char initFunc);
58	/**<
59	* Loads a dynamic library and calls its initialization function.
60	* This is our function wrapping dlopen/LoadLibrary. It makes
61	* provision for dynamic unloading using Asc_DynamicUnLoad().<br><br>
62	*
63	* Returns 1 if it fails to load the library named in path and find
64	* the symbol initFunc as an int function. Otherwise, it returns
65	* the result of the call to (*initFunc). If initFunc == NULL,
66	* nothing is called and 0 is returned after opening the library.
67	* If path == NULL, 1 is always returned.<br><br>
68	*
69	* A consequence of this behavior is that initFunc had better not
70	* return 1, or you won't be able to tell whether the library was
71	* successfully loaded or not. If it's under your control, have
72	* initFunc only return values other than 1 so you can detect the
73	* proper status.<br><br>
74	*
75	* @param path Path to the dynamic library to load (non-NULL).
76	* @param initFunc The DL initialization function to call.
77	* @return The return value from initFunc is returned if specified.
78	* Otherwise, 0 is returned if the library is successfully
79	* loaded, 1 if it is not.
80	*/
81
82	extern int DynamicLoad(CONST char path, CONST char initFunc);
83	/**<
84	* Loads a dynamic library and calls its initialization function.
85	* This is the standard function wrapping dlopen. It makes no
86	* provision for dynamic unloading, and therefore should not
87	* be used very often. It is not currently implemented for all
88	* platforms (e.g. Win32).<br><br>
89	*
90	* This function returns 1 if it fails to load the file named in
91	* path and find the symbol in initFun as an int function.
92	* Otherwise it returns the result of the call to initFun. See
93	* the discussion under Asc_DynamicLoad() for more issues
94	* arising from this behavior.
95	*
96	* @param path Path to the dynamic library to load (non-NULL).
97	* @param initFunc The DL initialization function to call.
98	* @return The return value from initFunc is returned if specified.
99	* Otherwise, 0 is returned if the library is successfully
100	* loaded, 1 if it is not.
101	*/
102	/*
103	* note on some systems (ultrix) this header hides a lot of non-static
104	* function names which don't appear terribly standard.
105	*/
106
107	extern int Asc_DynamicUnLoad(CONST char *path);
108	/**<
109	* Attempts to unload a dynamic library.
110	* This function tries to look up the previously-loaded library
111	* in path and unload it. Only libraries successfully loaded using
112	* Asc_DynamicLoad() may be unloaded using this function.<br><br>
113	*
114	* This is our function wrapping dlclose/shl_unload/FreeLibrary
115	* which provides unloading. Once all references to the
116	* previously-loaded library have been scheduled to be removed
117	* without further ado, it can be unloaded on most architectures.
118	* Once you call this function, you damn well better not reference
119	* functions or data that came from the path given. Passing a NULL
120	* path will always result in an error condition (-3) being returned.
121	*
122	* @param path Path to the dynamic library to unload.
123	* @return Returns 0 if the library was successfully located and unloaded,
124	* -3 if the library was not located, or the return value of
125	* dlclose/shl_unload/FreeLibrary otherwise. Note that the
126	* return value conventions differ between platforms, so if you
127	* get a return value that is not 0 or -3, you are in platform-
128	* specific hell.
129	*/
130
131	extern void Asc_DynamicSymbol(CONST char libraryname,
132	CONST char *symbolname);
133	/**<
134	* Returns a pointer to a symbol exported from a dynamically-linked
135	* library. It will generally be necessary to cast the returned pointer
136	* to the correct function or data type before use. If either parameter
137	* is NULL, or if the library or symbol cannot be located, then NULL will
138	* be returned.
139	* <pre>
140	* Example:
141	* typedef double (calcfunc)(double , double *);
142	* calcfunc calc;
143	* calc = (calcfunc))Asc_DynamicSymbol("lib.dll","calc");
144	* </pre>
145	* @param libraryname Name of the dynamic library to query.
146	* @param symbolname Symbol to look up in the library.
147	* @return A pointer to the symbol in memory, or NULL if not found.
148	*/
149
150	#if (defined(__HPUX__) \|\| defined(__ALPHA_OSF__) \|\| \
151	defined(__WIN32__) \|\| defined(__SUN_SOLARIS__) \|\| \
152	defined(__SUN_SUNOS__) \|\| defined(__SGI_IRIX__))
153	#define HAVE_DL_UNLOAD 1
154	/**<
155	* Set if a platform has a library unload function.
156	* We don't know about ultrix, aix, and others.
157	*/
158	#endif
159
160	#endif /* __ascdynaload_h_seen__ */
161