Documentation Center

  • Trial Software
  • Product Updates

loadlibrary

Load shared library into MATLAB

Syntax

  • loadlibrary(libname,hfile) example
  • loadlibrary(libname) example
  • loadlibrary(libname,hfile,Name,Value) example
  • loadlibrary(libname,@protofile)
  • [notfound,warnings] = loadlibrary(___)

Description

example

loadlibrary(libname,hfile) loads functions from shared library, libname, defined in header file, hfile, into MATLAB®.

example

loadlibrary(libname) loads the library if the name of the header file is the same as the name of the library file.

example

loadlibrary(libname,hfile,Name,Value) loads the library with one or more Name,Value arguments.

loadlibrary(libname,@protofile) uses a prototype file, protofile, in place of a header file.

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

Examples

expand all

Load Functions in shrlibsample Library

Add path to examples folder.

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

Load shrlibsample.

loadlibrary('shrlibsample')

Cleanup.

unloadlibrary shrlibsample

Load Library Using Header File

The header file for the libmx library is matrix.h.

hfile = fullfile(matlabroot,'extern','include','matrix.h');
loadlibrary('libmx',hfile)

Cleanup.

unloadlibrary libmx

Load Library Using Multiple Header Files

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 in header2.h, call loadlibrary with the addheader option.

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

Load Library Using an Alias Name

Create an alias, lib, for library, shrlibsample.

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

Use the alias name, lib, to call a function in the library.

str = 'This was a Mixed Case string';
calllib('lib','stringToUpper',str)
ans =
   THIS WAS A MIXED CASE STRING

Cleanup.

unloadlibrary lib

Search Alternative Paths for Header Files

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

Input Arguments

expand all

libname — Name of shared librarystring

Name of shared library, specified as a string. 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 Macintosh 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.

Data Types: char

hfile — Name of C header filestring

Name of C header file, specified as a string. 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

protofile — Name of prototype filestring

Name of prototype file, specified as a string. The name is case-sensitive and must match the file on your system. The string @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 Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example:

'addheader' — Header filestring

Header file, specified as the comma-separated pair consisting of 'addheader' and a string. Specify the file name without a file extension.

Each file specified by addheader must have a corresponding #include statement in the base header file. To load only the functions defined in the header file that you want to use in MATLAB, use addheader.

MATLAB does not verify the existence of header files and ignores any that are not needed.

'alias' — Alternative name for librarystring

Alternative name for library, specified as the comma-separated pair consisting of 'alias' and a string. 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.

'includepath' — More search path for subordinate header filesstring

more search path for subordinate header files—header files within header files, specified as the comma-separated pair consisting of 'includepath' and a string.

'mfilename' — Prototype filestring

Prototype file, specified as the comma-separated pair consisting of 'mfilename' and a string. 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.

'thunkfilename' — Thunk filestring

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

Output Arguments

expand all

notfound — Names of functionscell array

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

Data Types: cell

warnings — Warningscharacter array

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

Limitations

  • You must have a supported C compiler and Perl must be available.

  • Do not call loadlibrary if the library is already in memory. To test this condition, call libisloaded.

  • loadlibrary does not support libraries generated by the MATLAB Compiler™ product.

  • The MATLAB Shared Library interface does not support library functions with function pointer inputs.

More About

expand all

Prototype File

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

Thunk File

A thunk file is a compatibility layer to a 64-bit library generated by MATLAB. The name of the thunk file is BASENAME_thunk_COMPUTER.c where BASENAME is either the name of the shared library or, if specified, the mfilename prototype name. COMPUTER is the string returned by the computer function.

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

Tips

  • If you have more than one library file of the same name, load the first using the library file name. Then load the additional libraries using the alias option.

See Also

| | | | | |

Was this topic helpful?