Main Content

loadlibrary

将 C 共享库加载到 MATLAB

全页折叠

语法

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

说明

loadlibrary(libname,hfile) 将头文件 hfile 中定义的 C 共享库 libname 中的函数加载到 MATLAB® 中。loadlibrary 函数仅支持可从 C 语言环境中调用的调用函数，以及可由 C 编译器解析的头文件。采用 C++ 语言编写的函数必须声明为 extern "C"。或者，要调用 C++ 库中的函数，请参阅 从 MATLAB 中调用 C++。

示例

如果头文件的名称与库文件的名称相同，则 loadlibrary(libname) 则会加载库文件。

示例

loadlibrary(libname,hfile,Name,Value) 使用一个或多个 Name,Value 参量加载库。

示例

loadlibrary(libname,@protofile) 使用原型文件 protofile 代替头文件。

[notfound,warnings] = loadlibrary(___) 返回警告信息，且可包含上述语法中的任何输入参量。

示例

全部折叠

打开实时脚本

添加 examples 文件夹的路径。

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

显示库中的函数。

if not(libisloaded('shrlibsample'))
    loadlibrary('shrlibsample')
end
libfunctions('shrlibsample')
Functions in library shrlibsample:

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

清空库。

unloadlibrary shrlibsample

假定您具有库 mylib，其头文件为 mylib.h。该头文件包含语句 #include header2.h。要使用 header2.h 中定义的函数，请使用 addheader 选项调用 loadlibrary。

loadlibrary('mylib','mylib.h','addheader','header2')
打开实时脚本
if libisloaded('shrlibsample')
    unloadlibrary('shrlibsample')
else
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
end

为库 shrlibsample 创建一个别名 lib。

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

使用该别名调用 stringToUpper 函数。

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

清空库。

unloadlibrary lib

向包含 shrlibsample 及其头文件 shrlibsample.h 的文件夹添加路径。

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

shrlibsample.h 头文件包括头文件 shrhelp.h。如果 shrhelp.h 在不同文件夹中（例如 c:\work），则使用 'includepath' 选项告知 MATLAB 在何处查找该文件。

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

清空库。

unloadlibrary shrlibsample

此示例说明如何将 MATLAB shrlibsample 库中的 addMixedTypes 函数名称替换为别名 addTypes。要定义别名，请创建一个原型文件，然后使用该原型文件作为头文件加载该库。

使用您对其有写访问权限的文件夹。

cd('c:\work')

创建一个原型文件 mxproto.m。

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

MATLAB 在当前文件夹中创建原型文件。忽略警告消息。

将别名添加到原型文件中。在 MATLAB 编辑器中打开该文件。

edit mxproto.m

搜索函数 addMixedTypes。

下面的语句指定别名 addTypes。

fcns.alias{fcnNum}='addTypes';

将上面的语句添加到递增 fcnNum 的语句行之前。新函数原型如下所示，其中的新语句以粗体显示：

%  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

使用原型文件重新加载 shrlibsample。

unloadlibrary shrlibsample
loadlibrary('shrlibsample',@mxproto)

按函数别名调用相应函数。

calllib('shrlibsample','addTypes',int16(127),int32(33000),pi)
ans = 3.3130e+04

清空库。

unloadlibrary shrlibsample

输入参数

全部折叠

共享库的名称，指定为字符向量。该名称区分大小写，并且必须与系统上的文件一致。

在 Microsoft® Windows® 系统上，libname 指共享库 (.dll) 文件的名称。在 Linux® 系统上，它指共享对象 (.so) 文件的名称。在 Apple Mac 系统上，它指动态共享库 (.dylib)。如果未在 libname 参量中包括文件扩展名，则 loadlibrary 会尝试查找具有相应平台 MEX 文件扩展名或相应平台库扩展名的库。要获取 MEX 文件扩展名列表，请使用 mexext。

MATLAB 提取 libname 的名称部分以便在其他共享库函数中标识该库。例如，调用 calllib 函数时，不要在库参量名称中包含路径或文件扩展名。

数据类型: char

C 头文件的名称，指定为字符向量。该名称区分大小写，并且必须与系统上的文件一致。如果未在文件名中包括文件扩展名，则 loadlibrary 将使用 .h 作为扩展名。

数据类型: char

原型文件的名称，指定为字符向量。该名称区分大小写，并且必须与系统上的文件一致。@protofile 指定原型文件的函数句柄。使用原型文件时，唯一有效的 Name,Value 对组参量为 alias。

数据类型: char

名称-值参数

将可选的参量对组指定为 Name1=Value1,...,NameN=ValueN，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但参量对组的顺序无关紧要。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: loadlibrary('mylib','mylib.h','addheader','header2')

头文件，指定为以逗号分隔的对组，其中包含“addheader”和字符向量。指定不包括文件扩展名的文件名。

addheader 指定的每个文件必须在基本头文件中具有对应的 #include 语句。使用 addheader 仅加载您要在 MATLAB 中使用的头文件中定义的函数。

MATLAB 不验证头文件是否存在并将忽略任何不需要的头文件。

库的替代名称，指定为以逗号分隔的对组，其中包含“alias”和字符向量。将指定的名称与库关联。所有后续对引用此库的 MATLAB 函数的调用都必须使用此别名，直至卸载该库为止。

附属头文件（头文件中的头文件）的更多搜索路径，指定为以逗号分隔的对组，其中包含“includepath”和字符向量。

原型文件，指定为以逗号分隔的对组，其中包含“mfilename”和字符向量。在当前文件夹中生成原型文件。原型文件名必须与库名称不同。加载库时使用此文件代替头文件。

Thunk 文件，指定为以逗号分隔的对组，其中包含“thunkfilename”和字符向量。覆盖默认 thunk 文件名。

输出参量

全部折叠

在头文件中发现但库中缺少的函数名称，以元胞数组形式返回。

数据类型: cell

处理头文件时生成的警告，以字符数组形式返回。

局限性

  • 您必须具有支持的 C 编译器并且必须可以使用 Perl。

  • 如果库已位于内存中，请不要调用 loadlibrary。要测试此条件，请调用 libisloaded。

  • loadlibrary 不支持 MATLAB Compiler SDK™ 和代码生成产品（如 MATLAB Coder）生成的库。

  • MATLAB 共享库接口不支持具有函数指针输入的库函数。

  • 有关详细信息，请参阅Limitations to Shared Library Support。

详细信息

全部折叠

原型文件

原型文件是可以修改和用于代替头文件的 MATLAB 命令文件。

Thunk 文件

Thunk 文件是 MATLAB 生成的 64 位库的兼容性层。Thunk 文件的名称为 BASENAME_thunk_COMPUTER.c，其中 BASENAME 为共享库名称或 mfilename 原型名称（如果已指定）。COMPUTER 为 computer 函数返回的文本。

MATLAB 编译此文件并创建文件 BASENAME_thunk_COMPUTER.LIBEXT，其中 LIBEXT 是与平台相关的默认共享库扩展名，例如 Windows 上的 dll。

提示

  • 如果有多个同名的库文件，请使用库文件名加载第一个文件。然后，使用 alias 选项加载其他库。

  • 使用 alias 选项作为库的替代名称。要加载替代头文件，请使用 @protofile 参量。

版本历史记录

在 R2006a 之前推出

另请参阅

| | | | | |

主题