To allow for other Substrate APIs such as MSFindSymbol to specify specific images (such as to limit searching for symbols), there needs to be an API that can return a handle to an image, similar in functionality to dlopen with respect to dlsym.

As Substrate needs intricate knowledge of the storage of this handle, it cannot simply use dlopen, which returns an opaque structure. Further, some platforms (such as Android) fail to implement key functionality, such as RTLD_NOLOAD (used to look up existing libraries, rather than load new ones).

Substrate therefore provides an API which returns its own opaque type, MSImageRef. Care should be taken to not intermix the value returned from this API with other APIs available on Unix for referencing images (such as dlsym), as these APIs are often defined to accept any void *.

Barring these above caveats, the resulting functionality of this API is very similar to using dlopen with the RTLD_NOLOAD flag: existing libraries will be looked up and returned, but if the library is not currently loaded then calling this API will not do so.

MSImageRef MSGetImageByName(const char *file);
Parameter Description
file Absolute canonical path of a shared object or dynamic library to query from loaded images.
return Reference to image that can be used with other APIs or NULL if the image is not currently loaded.
MSImageRef image;
image = MSGetImageByName("/system/lib/");
if (image != NULL)
    /* image is loaded */;