loadlibrary - Load C shared library into MATLAB - MATLAB (original) (raw)

Load C shared library into MATLAB

Syntax

Description

loadlibrary([libname](#btdfvha-1-libname),[hfile](#btdfvha-1-hfile)) loads functions from C shared library libname defined in header file hfile into MATLAB®. The loadlibrary function only supports calling functions that are callable from C and header files that can be parsed by a C compiler. Functions written in C++ must be declared asextern "C". Alternatively, to call functions in C++ libraries, see Call C++ from MATLAB.

loadlibrary([libname](#btdfvha-1-libname)) loads the library if the name of the header file is the same as the name of the library file.

example

loadlibrary([libname](#btdfvha-1-libname),[hfile](#btdfvha-1-hfile),[Name,Value](#namevaluepairarguments)) loads the library with one or more Name,Value arguments.

example

[[notfound](#btdfvha-1-notfound),[warnings](#btdfvha-1-warnings)] = loadlibrary(___) returns warning information, and can include any of the input arguments in previous syntaxes.

Examples

collapse all

Add path to examples folder.

addpath(fullfile(matlabroot,'extern','examples','shrlib'))

Display functions in library.

if not(libisloaded('shrlibsample')) loadlibrary('shrlibsample') end libfunctions('shrlibsample')

Functions in library shrlibsample:

methods:

addDoubleRef addMixedTypes addStructByRef addStructFields allocateStruct deallocateStruct exportedDoubleValue getListOfStrings multDoubleArray multDoubleRef multiplyShort print2darray printExportedDoubleValue readEnum stringToUpper

Clean up.

unloadlibrary shrlibsample

Suppose that you have a library,mylib, with the header file, mylib.h. The header file contains the statement, #include header2.h. To use functions defined inheader2.h, call loadlibrary with the addheader option.

loadlibrary('mylib','mylib.h','addheader','header2')

if libisloaded('shrlibsample') unloadlibrary('shrlibsample') else addpath(fullfile(matlabroot,'extern','examples','shrlib')) end

Create an alias name lib for library shrlibsample.

loadlibrary('shrlibsample','shrlibsample.h','alias','lib')

Call function stringToUpper using the alias name.

str = 'This was a Mixed Case string'; calllib('lib','stringToUpper',str)

ans = 'THIS WAS A MIXED CASE STRING'

Clean up.

Add path to folder containing shrlibsample and its header file, shrlibsample.h.

addpath(fullfile(matlabroot,'extern','examples','shrlib'))

The shrlibsample.h header file includes the header file, shrhelp.h. If shrhelp.h is in a different folder, for example, c:\work, use the 'includepath' option to tell MATLAB where to find the file.

loadlibrary('shrlibsample','shrlibsample.h','includepath','c:\work')

Cleanup.

unloadlibrary shrlibsample

This example shows how to replace theaddMixedTypes function name in the MATLABshrlibsample library with an alias name,addTypes. To define the alias name, create a prototype file then load the library using the prototype file as the header file.

Use a folder for which you have write-access.

Create a prototype file, mxproto.m.

hfile = fullfile(matlabroot,'extern','examples','shrlib','shrlibsample.h'); [notfound,warnings] = loadlibrary('shrlibsample',hfile,'mfilename','mxproto')

MATLAB creates the prototype file in the current folder. Ignore the warning messages.

Add the alias name to the prototype file. Open the file in MATLAB Editor.

Search for the function addMixedTypes.

The following statement assigns the aliasaddTypes.

fcns.alias{fcnNum}='addTypes';

Add the statement to the line before the statement to incrementfcnNum. The new function prototype, with the new statement shown in bold, looks like the following:

% double addMixedTypes ( short , int , double ); fcns.thunkname{fcnNum}='doubleint16int32doubleThunk'; fcns.name{fcnNum}='addMixedTypes'; fcns.calltype{fcnNum}='Thunk'; fcns.LHS{fcnNum}='double'; fcns.RHS{fcnNum}={'int16', 'int32', 'double'}; fcns.alias{fcnNum}='addTypes'; % Alias defined fcnNum=fcnNum+1; % Increment fcnNum

Reload shrlibsample using the prototype file.

unloadlibrary shrlibsample loadlibrary('shrlibsample',@mxproto)

Call the function by its alias name.

calllib('shrlibsample','addTypes',int16(127),int32(33000),pi)

Cleanup.

unloadlibrary shrlibsample

Input Arguments

collapse all

Name of shared library, specified as a character vector. The name is case-sensitive and must match the file on your system.

On Microsoft® Windows® systems, libname refers to the name of a shared library (.dll) file. On Linux® systems, it refers to the name of a shared object (.so) file. On Apple Mac systems, it refers to a dynamic shared library (.dylib). If you do not include a file extension with the libname argument,loadlibrary attempts to find the library with either the appropriate platform MEX file extension or the appropriate platform library extension. For a list of MEX file extensions, use mexext.

MATLAB extracts the name portion of libname to identify the library in other shared library functions. For example, when you call the calllib function, do not include the path or file extension in the library argument name.

Data Types: char

Name of C header file, specified as a character vector. The name is case-sensitive and must match the file on your system. If you do not include a file extension in the file name,loadlibrary uses .h for the extension.

Data Types: char

Name of prototype file, specified as a character vector. The name is case-sensitive and must match the file on your system. @protofile specifies a function handle to the prototype file. When using a prototype file, the only valid Name,Value pair argument is alias.

Data Types: char

Name-Value Arguments

collapse all

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: loadlibrary('mylib','mylib.h','addheader','header2')

Alternative name for library, specified as the comma-separated pair consisting of 'alias' and a character vector. Associates the specified name with the library. All subsequent calls to MATLAB functions that reference this library must use this alias until the library is unloaded.

More search paths for subordinate header files—header files within header files, specified as the comma-separated pair consisting of 'includepath' and a character vector.

Prototype file, specified as the comma-separated pair consisting of 'mfilename' and a character vector. Generates a prototype file in the current folder. The prototype file name must be different from the library name. Use this file in place of a header file when loading the library.

Thunk file, specified as the comma-separated pair consisting of 'thunkfilename' and a character vector. Overrides the default thunk file name.

Output Arguments

collapse all

Names of functions found in header files but missing from the library, returned as cell array.

Data Types: cell

Warnings produced while processing the header file, returned as character array.

Limitations

More About

collapse all

A prototype file is a file of MATLAB commands which you can modify and use in place of a header file.

A thunk file is a compatibility layer to a 64-bit library generated by MATLAB. The name of the thunk file isBASENAME_thunk_COMPUTER.c where_BASENAME_ is either the name of the shared library or, if specified, the mfilename prototype name.COMPUTER is the text returned by thecomputer function.

MATLAB compiles this file and creates the fileBASENAME_thunk_COMPUTER.LIBEXT, where_LIBEXT_ is the platform-dependent default shared library extension, for example, dll on Windows.

Tips

Version History

Introduced before R2006a