This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

coder.ceval

Call external C/C++ function

Syntax

coder.ceval(cfun_name)
coder.ceval(cfun_name,cfun_arguments)
coder.ceval('-global',cfun_name)
coder.ceval('-global',cfun_name,cfun_arguments)
cfun_return = coder.ceval(___)

Description

example

coder.ceval(cfun_name) executes the external C/C++ function specified by cfun_name. Define cfun_name in an external C/C++ source file or library. Provide the external source, library, and header files to the code generator.

example

coder.ceval(cfun_name,cfun_arguments) executes cfun_name with arguments cfun_arguments. cfun_arguments is a comma-separated list of input arguments in the order that cfun_name requires.

By default, coder.ceval passes arguments by value to the C/C++ function whenever C/C++ supports passing arguments by value. To make coder.ceval pass arguments by reference, use the constructs coder.ref, coder.rref, and coder.wref. If C/C++ does not support passing arguments by value, for example, if the argument is an array, coder.ceval passes arguments by reference. If you do not use coder.ref, coder.rref or coder.wref, a copy of the argument can appear in the generated code to enforce MATLAB® semantics for arrays.

example

coder.ceval('-global',cfun_name) executes cfun_name and indicates that cfun_name uses one or more MATLAB global variables. The code generator can then produce code that is consistent with this global variable usage.

coder.ceval('-global',cfun_name,cfun_arguments) executes cfun_name with arguments cfun_arguments and indicates that cfun_name uses one or more MATLAB global variables.

example

cfun_return = coder.ceval(___) executes cfun_name and returns a single scalar value, cfun_return, corresponding to the value that the C/C++ function returns in the return statement. To be consistent with C/C++, coder.ceval can return only a scalar value. It cannot return an array. Use this option with any of the input argument combinations in the previous syntaxes.

Examples

collapse all

Call a C function foo(u) from a MATLAB function from which you intend to generate C code.

Create a C header file foo.h for a function foo that takes two input parameters of type double and returns a value of type double.

double foo(double in1, double in2);

Write the C function foo.c.

#include <stdio.h>
#include <stdlib.h>
#include "foo.h"

double foo(double in1, double in2)
{
  return in1 + in2;
}

Write a function callfoo that calls foo by using coder.ceval. Provide the source and header files to the code generator in the function.

function y = callfoo  %#codegen
y = 0.0;
if coder.target('MATLAB')
    % Executing in MATLAB, call MATLAB equivalent of
    % C function foo
    y = 10 + 20;
else
    % Executing in generated code, call C function foo
    coder.updateBuildInfo('addSourceFiles','foo.c');
    coder.cinclude('foo.h');
    y = coder.ceval('foo', 10, 20);
end
end

Generate C library code for function callfoo. The codegen function generates C code in the \codegen\lib\callfoo subfolder.

codegen -config:lib callfoo -report

Call a C library function from MATLAB code.

Write a MATLAB function myabsval.

function y = myabsval(u)   
%#codegen
y = abs(u);

Generate a C static library for myabsval, using the -args option to specify the size, type, and complexity of the input parameter.

codegen -config:lib myabsval -args {0.0}
The codegen function creates the library file myabsval.lib and header file myabsval.h in the folder \codegen\lib\myabsval. (The library file extension can change depending on your platform.) It generates the functions myabsval_initialize and myabsval_terminate in the same folder.

Write a MATLAB function to call the generated C library function using coder.ceval.

function y = callmyabsval(y)  
%#codegen
% Check the target. Do not use coder.ceval if callmyabsval is
% executing in MATLAB
if coder.target('MATLAB')
  % Executing in MATLAB, call function myabsval
  y = myabsval(y);
else
  % add the required include statements to generated function code
  coder.updateBuildInfo('addIncludePaths','$(START_DIR)\codegen\lib\myabsval');
  coder.cinclude('myabsval_initialize.h');
  coder.cinclude('myabsval.h');
  coder.cinclude('myabsval_terminate.h');

  % Executing in the generated code. 
  % Call the initialize function before calling the 
  % C function for the first time
  coder.ceval('myabsval_initialize');

  % Call the generated C library function myabsval
  y = coder.ceval('myabsval',y);
  
  % Call the terminate function after
  % calling the C function for the last time
  coder.ceval('myabsval_terminate');
end

Generate the MEX function callmyabsval_mex. Provide the generated library file at the command line.

codegen -config:mex callmyabsval codegen\lib\myabsval\myabsval.lib -args {-2.75}

Rather than providing the library at the command line, you can use coder.updateBuildInfo to specify the library within the function. Use this option to preconfigure the build. Add this line to the else block:

coder.updateBuildInfo('addLinkObjects','myabsval.lib','$(START_DIR)\codegen\lib\myabsval',100,true,true);

Run the MEX function callmyabsval_mex which calls the library function myabsval.

callmyabsval_mex(-2.75)
ans =

    2.7500

Call the MATLAB function callmyabsval.

callmyabsval(-2.75)
ans =

    2.7500
The callmyabsval function exhibits the desired behavior for execution in MATLAB and in code generation.

Use the '-global' flag when you call a C function that modifies a global variable.

Write a MATLAB function useGlobal that calls a C function addGlobal. Use the '-global' flag to indicate to the code generator that the C function uses a global variable.

function y = useGlobal()
global g;
t = g;
% compare execution with/without '-global' flag
coder.ceval('-global','addGlobal'); 
y = t;
end

Create a C header file addGlobal.h for the function addGlobal.

void addGlobal(void);

Write the C function addGlobal in the file addGlobal.c. This function includes the header file useGlobal_data.h that the code generator creates when you generate code for the function useGlobal. This header file contains the global variable declaration for g.

#include "addGlobal.h"
#include "useGlobal_data.h"
void addGlobal(void) {
    g++;
}

Generate the MEX function for useGlobal. To define the input to the code generator, declare the global variable in the workspace.

global g;
g = 1;
codegen useGlobal -report addGlobal.h addGlobal.c
y = useGlobal_mex();

With the '-global' flag, the MEX function produces the result y = 1. The '-global' flag indicates to the code generator that the C function possibly modifies the global variable. For useGlobal, the code generator produces this code:

real_T useGlobal(const emlrtStack *sp)
{
  real_T y;
  (void)sp;
  y = g;
  addGlobal();
  return y;
}

Without the '-global' flag, the MEX function produces y = 2. Because there is no indication that the C function modifies g, the code generator assumes that y and g are identical. This C code is generated:

real_T useGlobal(const emlrtStack *sp)
{
  (void)sp;
  addGlobal();
  return g;
}

Input Arguments

collapse all

Name of external C/C++ function to call.

Example: coder.ceval('foo')

Data Types: char | string

Comma-separated list of input arguments in the order that cfun_name requires.

Example: coder.ceval('foo', 10, 20);

Example: coder.ceval('myFunction', coder.ref(x));

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | struct
Complex Number Support: Yes

Limitations

  • You cannot use coder.ceval on functions that you declare extrinsic with coder.extrinsic.

  • When the LCC compiler creates a library, it adds a leading underscore to the library function names. If the compiler for the library was LCC and your code generation compiler is not LCC, you must add the leading underscore to the function name, for example, coder.ceval('_mylibfun'). If the compiler for a library was not LCC, you cannot use LCC to generate code from MATLAB code that calls functions from that library. Those library function names do not have the leading underscore that the LCC compiler requires.

  • If a property has a get method, a set method, or validators, or is a System object™ property with certain attributes, then you cannot pass the property by reference to an external function. See Passing By Reference Not Supported for Some Properties.

Tips

  • For code generation, before calling coder.ceval, you must specify the type, size, and complexity data type of return values and output arguments.

  • To apply coder.ceval to a function that accepts or returns variables that do not exist in MATLAB code, such as pointers, FILE types for file I/O, and C/C++ macros, use the coder.opaque function.

  • Use coder.ceval only in MATLAB for code generation. coder.ceval generates an error in uncompiled MATLAB code. To determine if a MATLAB function is executing in MATLAB, use coder.target. If the function is executing in MATLAB, call the MATLAB version of the C/C++ function.

Introduced in R2011a