C MEX File Applications

Write C programs that work with MATLAB® R2017b or earlier, using mxArray

You can call your own C or 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.

  • MathWorks recommends that you create MEX functions using modern C++ features, as defined in the MATLAB Data API. For more information, see C++ MEX Applications.

  • 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 mxArray data structure. The functions and topics on this page are based on mxArray.

Note

Choose functions from either the C Matrix API or the MATLAB Data API; you cannot mix functions from these APIs.

Build your source file into an executable program using the mex function. You can also 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 MEX File Functions.

If you have a C/C++ program and want to call MATLAB functions from the program, then use one of the engine APIs.

If you want to read and write MATLAB data from C/C++ programs, then use the MATLAB C API to Read MAT-File Data.

Functions

mexBuild MEX function or engine application
dbmexEnable MEX-file debugging on UNIX platforms

C MEX API

mexFunctionEntry point to C/C++ MEX function built with C Matrix API
mexFunctionNameName of current MEX function
mexAtExitRegister function to call when MEX function clears or MATLAB terminates
mexCallMATLABCall MATLAB function, user-defined function, or MEX function
mexCallMATLABWithTrapCall MATLAB function, user-defined function, or MEX file and capture error information
mexEvalStringExecute MATLAB command in caller workspace
mexEvalStringWithTrapExecute MATLAB command in caller workspace and capture error information
mexGetVariableCopy of variable from specified workspace
mexGetVariablePtrRead-only pointer to variable from another workspace
mexPutVariableArray from MEX function into specified workspace
mexGetValue of specified graphics property
mexSetSet value of specified graphics property
mexPrintfANSI C PRINTF-style output routine
mexErrMsgIdAndTxtDisplay error message with identifier and return to MATLAB prompt
mexWarnMsgIdAndTxtWarning message with identifier
mexIsLockedDetermine if MEX file is locked
mexLockPrevent clearing MEX file from memory
mexUnlockAllow clearing MEX file from memory
mexMakeArrayPersistentMake array persist after MEX file completes
mexMakeMemoryPersistentMake memory allocated by MATLAB persist after MEX function completes

Topics

Write C MEX Functions

Create C Source MEX File

This example shows how to create the arrayProduct C 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 mxArray in MEX files.

Memory Management Issues

Rules for managing mxArray memory.

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 the mexErrMsgIdAndTxt function.

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.

C Matrix API Versions

Upgrade MEX Files to Use Interleaved Complex API

MATLAB Version 9.4 (R2018a) supports an interleaved representation of complex numbers.

Upgrade MEX Files to Use 64-Bit API

MATLAB Version 9.2 (R2017a) builds MEX files with the 64-bit API by default.

Upgrade MEX Files to Use Graphics Objects

MATLAB Version 8.4 (R2014b) changes the data type of handles to graphics objects from double to object.

Share MEX Files

Document Build Information in the MEX File

This example shows how to document the xtimesy MEX 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 the mex function 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 a mexFunction.

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 Mac Platforms

This example shows how to debug a MEX file on Mac Platforms.

Debug on Linux Platforms

This example shows how to debug a MEX file on Linux® Platforms.