Main Content

Call a C Shared Library

To use one or more MATLAB® Compiler SDK™ generated C shared libraries in your C application:

  1. Include the generated header file for each library in your application.

    Each generated shared library has an associated header file named libname.h.

  2. Initialize the MATLAB Runtime proxy layer by calling mclmcrInitialize.

  3. Use mclRunMain to call the C function in your driver code that uses the MATLAB generated shared libraries.

    mclRunMain() provides a convenient cross platform mechanism for wrapping the execution of MATLAB code in the shared library.

    Caution

    Do not use mclRunMain() on Mac if your application brings up its own full graphical environment.

  4. Declare variables and process input arguments.

  5. Initialize the MATLAB Runtime by calling the mclInitializeApplication function. This function sets up the global MATLAB Runtime state and enables the construction of MATLAB Runtime instances.

    Call the mclInitializeApplication() function once per application. It must be called before any other MATLAB API functions. You can pass application-level options to this function. mclInitializeApplication() returns a boolean status code.

    Caution

    Avoid issuing cd commands from the driver application before calling mclInitializeApplication. Failure to do so can cause a failure in MATLAB Runtime initialization.

  6. For each C shared library that you include in your application, call the initialization function for the library.

    The initialization function performs library-local initialization. It unpacks the deployable archive and starts a MATLAB Runtime instance with the necessary information to execute the code in that archive. The library initialization function is named libnameInitialize(). This function returns a Boolean status code.

    Note

    On Windows®, if you want to have your shared library call a MATLAB shared library, the MATLAB library initialization function (e.g., <libname>Initialize, <libname>Terminate, mclInitialize, mclTerminate) cannot be called from your shared library during the DllMain(DLL_ATTACH_PROCESS) call. This applies whether the intermediate shared library is implicitly or explicitly loaded. Place the call after DllMain().

  7. Invoke functions in the library, and process the results. (This is the main body of the program.)

    Note

    If your driver application displays MATLAB figure windows, include a call to mclWaitForFiguresToDie before calling the Terminate functions and mclTerminateApplication in the following two steps.

  8. When your application no longer needs a given library, call the termination function for the library.

    The terminate function frees the resources associated with the library's MATLAB Runtime instance. The library termination function is named libnameTerminate(). Once a library has been terminated, the functions exported by the library cannot be called again in the application.

    Caution

    Issuing a <lib>Initialize call after a <lib>Terminate call (whether or not the library is the same) causes unpredictable results.

  9. When your application no longer needs to call any shared libraries, call the mclTerminateApplication API function.

    This function frees application-level resources used by the MATLAB Runtime. Once you call this function, no further calls can be made to shared libraries in the application.

  10. Clean up variables, close files, and exit.

The following example from matrix.c illustrates all of the above steps.

 Call a C Shared Library from Your C Driver Application

Restrictions When Using MATLAB Function loadlibrary

You cannot use the MATLAB function loadlibrary in MATLAB to load a C shared library built with MATLAB Compiler SDK.

For more information about using loadlibrary, see Calling Shared Libraries in Deployed Applications.

See Also

| | | |

Related Topics