Write C Functions Callable from MATLAB (MEX Files)
mxArray to access MATLAB
variables and create arrays to return to MATLABYou can call your own C programs from the MATLAB command line as if they were built-in functions. These programs are called MEX functions, and the function name is the MEX file name. MEX functions are not appropriate for all applications. MATLAB is a high-productivity environment whose specialty is eliminating time-consuming, low-level programming in compiled languages. In general, do your programming in MATLAB. Do not use MEX functions unless your application requires it.
To create a MEX function, write your programs using MATLAB APIs. The functions in these libraries facilitate the transfer of data between MEX functions and the workspace. To choose a MATLAB API, consider the following:
Create MEX functions using modern C++ features, as defined in the MATLAB Data API for C++. For more information, see Write C++ Functions Callable from MATLAB (MEX Files).
If your MEX functions must run in MATLAB R2017b or earlier, or if you prefer to work in the C language, then use functions in the C Matrix API and the C MEX API. These APIs use the MATLAB
mxArraydata structure. The functions and topics on this page are based onmxArray.
Note
Choose functions from either the C Matrix API or the MATLAB Data Array API; you cannot mix functions from these APIs.
Build your source file into an executable program using the mex function. You also can share
the MEX file with other MATLAB users.
For information about writing S-functions, see your Simulink® documentation.
To call a MEX function that someone else created, see Call MEX Functions.
If you have a C/C++ program and want to call MATLAB functions from the program, then use one of the engine APIs. For more information, see:
If you want to read and write MATLAB data from C programs, see Write C Programs to Read MAT File Data.
Functions
C MEX API
mexFunction | Entry point to C/C++ MEX function built with C Matrix API |
mexFunctionName | Name of current MEX function |
mexAtExit | Register function to call when MEX function clears or MATLAB terminates |
mexCallMATLAB | Call MATLAB function, user-defined function, or MEX function |
mexCallMATLABWithTrap | Call MATLAB function, user-defined function, or MEX file and capture error information |
mexEvalString | Execute MATLAB command in caller workspace |
mexEvalStringWithTrap | Execute MATLAB command in caller workspace and capture error information |
mexGetVariable | Copy of variable from specified workspace |
mexGetVariablePtr | Read-only pointer to variable from another workspace |
mexPutVariable | Array from MEX function into specified workspace |
mexGet | Value of specified graphics property |
mexSet | Set value of specified graphics property |
mexPrintf | ANSI C PRINTF-style output routine |
mexErrMsgIdAndTxt | Display error message with identifier and return to MATLAB prompt |
mexWarnMsgIdAndTxt | Warning message with identifier |
mexIsLocked | Determine if MEX file is locked |
mexLock | Prevent clearing MEX file from memory |
mexUnlock | Allow clearing MEX file from memory |
mexMakeArrayPersistent | Make array persist after MEX file completes |
mexMakeMemoryPersistent | Make memory allocated by MATLAB persist after MEX function completes |
Topics
Write C MEX Functions
- Create C Source MEX File arrayProduct.c
This example shows how to create the
arrayProductC MEX function built with the C Matrix API. - Tables of MEX Function Source Code Examples
Links to source code for MEX function examples.
- MATLAB Data
Using
mxArrayin MEX files. - Memory Management Issues
Rules for managing
mxArraymemory. - Create C++ MEX Functions with C Matrix API
C++ language issues to consider when creating MEX functions built with the C Matrix API. - Error Handling in C MEX Files
Print error information using themexErrMsgIdAndTxtfunction. - Handling Large File I/O in MEX Files
How to use 64-bit file I/O in your MEX file. - Testing for Most-Derived Class
How to exclude subclasses of built-in types from MEX file input arguments.
Test Your Build Environment
- Build C MEX Function
This example shows how to build the example C MEX function
arrayProduct.
C Matrix API Versions
- Upgrade MEX Files to Use Interleaved Complex API
How to use an interleaved representation of complex numbers in MEX files.
- Upgrade MEX Files to Use 64-Bit API
How to build MEX files with the 64-bit API by default.
- Upgrade MEX Files to Use Graphics Objects
How to change the data type of handles to graphics objects fromdoubletoobject.
Share MEX Files
- Document Build Information in the MEX File
This example shows how to document thextimesyMEX file built on a Windows® platform using a Microsoft® Visual C++® compiler.
Troubleshooting
Build Errors
- Getting Help When MEX Fails
To help diagnose compiler set up and build errors, call themexfunction with verbose option -v. - Compiling MEX File Fails
What to do when compiling a MEX file fails. - Troubleshooting MEX API Incompatibilities
More information for warnings and error messages. - Troubleshooting and Limitations Compiling C/C++ MEX Files with MinGW-w64
Troubleshooting MEX files built with the MinGW-w64 compiler. - Symbol mexFunction Unresolved or Not Defined
Every MEX file needs amexFunction.
Runtime Errors
- Invalid MEX File Errors
What to do when you get an invalid MEX file error. - MEX Version Compatibility
For best results, run MEX files built with your MATLAB version. - MEX Platform Compatibility
If you get a binary MEX file from another source, be sure that the file was compiled for the same platform on which you want to run it. - MEX API Is Not Thread Safe
Do not call a single session of MATLAB on separate threads from a MEX file. - MEX File Segmentation Fault
What to do when a MEX file causes a segmentation violation or assertion. - MEX File Generates Incorrect Results
What to do when your MEX generates wrong answers.
Debugging
- Debug on Microsoft Windows Platforms
Suggestions for debugging with Microsoft Visual Studio®. - Debug on macOS Platforms
This example shows how to debug a MEX file on Mac Platforms. - Debug on Linux Platforms
These examples show how to debug a MEX file on Linux® platforms.
