Synopsis

int HostLib_Close(
         void * handle,
         char ** error );

Function

Release a host loader reference acquired by HostLib_Open(). The
host loader decides when the shared library can be unloaded and
may execute its termination code during this call.

Inputs

handle - A valid handle returned by a successful HostLib_Open()
         whose corresponding reference has not yet been closed.
error - Optional pointer to a char * for a host diagnostic, or NULL
        if no diagnostic is wanted. Initialize *error to NULL before
        the call.

Result

Zero on success; nonzero if the host loader reports failure.
Do not assume a particular nonzero error value across hosts.

Notes

Finish using the library and its symbols before closing it. A
successful close invalidates this reference; symbol pointers may
also become invalid. Concurrent users must coordinate separately.

A returned diagnostic uses host-specific storage. Use or copy it
before another host loader operation can replace it, and release
a non-NULL string with HostLib_FreeErrorStr(), not FreeVec() or
free(). Failure need not produce a diagnostic. Use the return
value to determine success: the Unix wrapper does not clear an
earlier loader error before calling dlclose().

Windows returns the negation of FreeLibrary()'s success value;
Unix returns dlclose()'s result. Hostlib serializes loader calls.

See also

HostLib_Open() HostLib_GetPointer() HostLib_FreeErrorStr()

Synopsis

void HostLib_DropInterface(
         APTR * interface );

Function

Free an array of symbol values obtained by HostLib_GetInterface()

Inputs

interface - A pointer to values array

Result

None

Notes

This function appeared in v2 of hostlib.resource.

See also

HostLib_GetInterface()

Synopsis

void HostLib_FreeErrorStr(
         char * error );

Function

Release error description string.
In some dynamic library loaders (like in Windows) error strings
are allocated dynamically. They need to be explicitly freed
when not used any more.

Inputs

error  - Pointer to a string ro free.

Result

None.

Notes

For portability sake, it is recommended to call this function on any
error string returned by hostlib.resource. However you can omit this
if you exactly know that your code runs only on UNIX-alike operating
system (it's UNIX-specific library or driver).

Synopsis

APTR * HostLib_GetInterface(
         void * handle,
         const char ** symtable,
         ULONG * unresolved );

Function

Resolve array of symbols in the host operating system library.
The result is a pointer to a dynamically allocated array of
symbol values.

Inputs

handle     - An opaque library handle provided by HostLib_Open()
symbable   - A pointer to a NULL-terminated array of symbol names
unresolved - An optional location where count of unresolved symbols
             will be placed. Can be set to NULL to ignore it.

Result

A pointer to a dynamically allocated array of symbol values or NULL if
empty symbol table was given.

Notes

Note that the resulting array will always have as many entries as there
are in symbol names array. It some symbols (or even all of them) fail
to resolve, corresponding entries will be set to NULL. You may supply
a valid unresolved pointer if you want to get unresolved symbols count.

Even incomplete interface needs to be freed using HostLib_DropInterface().

Resulting values are valid as long as the library is open. For portability
sake it's advised to free interfaces before closing corresponding libraries.

This function appeared in v2 of hostlib.resource.

See also

HostLib_GetPointer()

Synopsis

void * HostLib_GetPointer(
         void * handle,
         const char * symbol,
         char ** error );

Synopsis

void HostLib_Lock();

Function

Acquire global host OS call semaphore.

Inputs

None.

Result

None.

Notes

Host OS calls are typically not reentrant. You have to
call this function before you may use any host OS API.
Use HostLib_Unlock() function when you're done with it.

This function has negative impact on AROS multitasking, so
use it gently.

See also

HostLib_Unlock()

Synopsis

void * HostLib_Open(
         const char * filename,
         char ** error );

Function

Open a shared library through the host operating system's dynamic
loader. This function is provided by hostlib.resource on hosted
AROS systems; it does not open an AROS library.

Inputs

filename - Non-NULL pointer to a NUL-terminated host library name
           or path. Name lookup and supported file formats are
           determined by the host loader.
error - Optional pointer to a char * for a host diagnostic, or NULL
        if no diagnostic is wanted. Initialize *error to NULL before
        the call.

Result

A host library handle on success, or NULL on failure. Balance each
successful open with HostLib_Close() after all uses of the library
and its symbols have ended.

Notes

The filename is borrowed only for this call. A returned diagnostic
uses host-specific storage: use or copy it before another host
loader operation can replace it, and release a non-NULL string
with HostLib_FreeErrorStr(). Do not use FreeVec() or free(). A
failure need not have an available diagnostic. Determine success
from the returned handle, not from the diagnostic pointer.

On Unix hosts this uses dlopen() with RTLD_NOW | RTLD_GLOBAL.
On Windows hosts it uses LoadLibrary(). The Unix wrapper does not
clear an earlier loader error before opening, so a diagnostic can
refer to an earlier operation even when this open succeeds.

Hostlib serializes loader calls. Loading may run host initialization
code. Call host library functions using the host ABI and any
required host-call synchronization.

See also

HostLib_Close() HostLib_GetPointer() HostLib_FreeErrorStr() HostLib_Lock() HostLib_Unlock()

Synopsis

void HostLib_Unlock();

Function

Release global host OS call semaphore.

Inputs

None.

Result

None.

See also

HostLib_Lock()