CLibraryConfiguration

C++ library interface environment information

Since R2023a

Description

CLibraryConfiguration objects contain information about the settings and status of a MATLAB^® interface to a C++ library. The environment information is persistent across different MATLAB sessions.

Creation

To create a CLibraryConfiguration object or change the settings, call clibConfiguration. The library is loaded when you call a command in the clib namespace. You cannot change the execution mode after MATLAB loads the library. To change how the library is loaded, restart MATLAB, and then call clibConfiguration.

Properties

InterfaceLibraryPath — Path to interface library

Read-only: string scalar

This property is read-only.

Path to the interface library, returned as a string scalar.

Libraries — Libraries used to build interface

Read-only: string scalar | string array

This property is read-only.

Libraries used to build the interface, returned as a string scalar or string array.

Loaded — Process status

Read-only: 0 (default) | 1

This property is read-only.

Process status, returned as 1 if the library is loaded and 0 if the library is not loaded. By default, the library is not loaded. MATLAB loads the library when you call a command in the library namespace.

ExecutionMode — Execution mode

inprocess (default) | outofprocess

Execution mode indicating whether to load the C++ library interface in the same process as MATLAB or in an external process, specified as inprocess or outofprocess. To set the ExecutionMode property, call clibConfiguration with the ExecutionMode name-value argument.

ProcessID — MATLAB process ID

Read-only: uint64 scalar

This property is read-only.

MATLAB process ID, returned as a uint64 scalar. If the library is not loaded, then ProcessID is not displayed.

ProcessName — Process name in registry

Read-only: string scalar

This property is read-only.

Process name in the registry, returned as a string scalar. The default name for an out-of-process host is MATLABCLibHost. If the library is not loaded, then ProcessName is not displayed.

OutOfProcessEnvironmentVariables — System environment variable names and values

dictionary object

Since R2025a

System environment variable names and values for the interface to the C++ library in out-of-process execution mode, specified as a dictionary object, where key-value pairs are defined as follows:

• keys — The environment variable name or names, specified as a string scalar or string array.

  If keys contains an operating system path variable ("PATH", "LD_LIBRARY_PATH", or "DYLD_LIBRARY_PATH"), the function adds the specified path value to the existing path variable.

• values — The environment variable value or values, specified as a string scalar or string array.

You can set or view environment variables in out-of-process mode only. To set the OutOfProcessEnvironmentVariables property, call clibConfiguration with the OutOfProcessEnvironmentVariables name-value argument.

Object Functions

unload

Unload process associated with C++ library

Examples

Display Configuration for Library

Suppose that you built an interface libnameInterface.dll in C:\work on the MATLAB path for a C++ library libname.

Call function myfunc from the library.

clib.libname.myfunc

Display the library interface configuration.

configObj = clibConfiguration("libname")

configObj =

      CLibraryConfiguration for libname with properties:

        InterfaceLibraryPath: "C:\work"
                   Libraries: ""
                      Loaded: 1
               ExecutionMode: inprocess
                   ProcessID: 12345

Version History

Introduced in R2023a

R2025a: Pass environment variables in out-of-process mode

The OutofProcessEnvironmentVariables property contains system environment variable names and values to pass to the process hosting your MATLAB interface to a C++ library. To use this property, the library interface must be configured to use out-of-process execution mode. Use the clibConfiguration function to set both the OutofProcessEnvironmentVariables and ExecutionMode properties.