Provides control over the initialization of a LispWorks dynamic library.
On Windows:
int __stdcall InitLispWorks (int MilliTimeOut, void *BaseAddress, size_t ReserveSize)
On Linux, Macintosh, x86/x64 Solaris and FreeBSD:
int InitLispWorks (int MilliTimeOut, void *BaseAddress, size_t ReserveSize)
The C function InitLispWorks allows you to relocate a LispWorks dynamic library if this is necessary, and offers control of the initialization process.
A LispWorks dynamic library is automatically initialized by any call to its exported symbols, so in most cases there is no need to call InitLispWorks. It is however necessary when you need to relocate LispWorks or when you need finer control over the initialization process.
For more information about relocating a LispWorks dynamic library, see 27.6 Startup relocation.
MilliTimeOut specifies the time in milliseconds to wait for LispWorks to finish initializing before returning. InitLispWorks checks whether the library was initialized and if not initiates initialization. It then waits at most MilliTimeOut milliseconds before returning.
BaseAddress specifies the base address for relocation. Can be 0.
ReserveSize specifies the reserve size for relocation. Can be 0.
BaseAddress and ReserveSize are interpreted as described in 27.6 Startup relocation.
Non-negative return values indicate success:
| 1 |
LispWorks was already initialized or in the process of initializing, and finished initializing by the time InitLispWorks returned. |
| 0 | InitLispWorks initialized LispWorks and the initialization finished successfully. |
Values in the inclusive range [-1, -99] indicate a timeout:
| -1 | InitLispWorks started initialization and timed out before LispWorks finished mapping itself from the file. |
| -2 |
LispWorks already started initialization, and InitLispWorks timed out before LispWorks finished mapping itself from the file. |
| -3 | InitLispWorks started initialization and timed out after LispWorks mapped itself from the file, but before the initialization was complete. |
| -4 |
LispWorks already started initialization, and InitLispWorks timed out before after LispWorks mapped itself from the file, but before the initialization was complete. |
After InitLispWorks times out, the state of LispWorks can be queried by LispWorksState.
Lower values indicate failure, as follows:
| -1000 |
Failure to start a thread to do the initialization. |
| -1401 |
The file seems to be corrupted. |
| -1402 |
Failure to map into memory. |
| -1403 |
Failure to read the LispWorks header from the file. |
| -1406 |
Bad base address. |
| -1408 |
Some failure in Lisp code during initialization. In LispWorks 8.0, this can be reported only on Android. |
| -1409 |
LispWorks failed to open its own executable/dynamic library. This is done using dlopen to allow LispWorks to find foreign symbols. In LispWorks 8.0, this can be reported only on Android. This error means that the library was found and loaded by the runtime system, and it is only the call to dlopen by LispWorks that failed. |
Additionally, a value value in the inclusive range [-1400, -1001] on Linux, Macintosh, FreeBSD and x86/x64 Solaris platforms indicates an error in a system call. Calculate the errno number by -1001 - value.
Note: If LispWorks is already initialized or in the process of being initialized, InitLispWorks does not initiate the process of initialization. Therefore the arguments to InitLispWorks have no effect if LispWorks was already initialized when it is called. On Microsoft Windows, the default behavior is to initialize a LispWorks dynamic library automatically during loading, so this needs to be disabled to use InitLispWorks effectively. Disable automatic initialization of a library as described for deliver and save-image.
Note: Once QuitLispWorks has returned 0, LispWorks can be initialized again. It is possible to quit and restart LispWorks several times, at the same address or at a different address.
Note: On Linux, Macintosh, FreeBSD and x86/x64 Solaris you can create wrappers to the C functions described in this chapter from your application by writing them in C and adding them to the dynamic library using dll-added-files in deliver and save-image. Such wrappers can be used to add calls to InitLispWorks before actually calling into Lisp.
InitLispWorks is defined in each LispWorks dynamic library. For information about creating a LispWorks dynamic library, see deliver and save-image. For an overview of LispWorks as a dynamic library, see 14 LispWorks as a dynamic library.
LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:31:10