文档

本页对应的英文页面已更新,但尚未翻译。 若要查看最新内容,请点击此处访问英文页面。

loadlibrary

将 C/C++ 共享库加载到 MATLAB

语法

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

说明

loadlibrary(libname,hfile) 将头文件 hfile 中定义的共享库 libname 中的函数加载到 MATLAB® 中。loadlibrary 函数仅支持可从 C 语言环境中调用的调用函数,以及可由 C 编译器解析的头文件。采用 C++ 语言编写的函数必须声明为 extern "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              exportedDoubleValue       printExportedDoubleValue  
addMixedTypes             getListOfStrings          readEnum                  
addStructByRef            multDoubleArray           stringToUpper             
addStructFields           multDoubleRef             
allocateStruct            multiplyShort             
deallocateStruct          print2darray              

清空库。

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

名称-值对组参数

示例: 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 共享库接口不支持具有函数指针输入的库函数。

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

详细信息

全部折叠

原型文件

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

Thunk 文件

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

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

提示

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

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

在 R2006a 之前推出

此主题对您有帮助吗?