Understanding MEX-File Problems

Use the following figure to help isolate common problems that occur when creating binary MEX-files.

Troubleshooting MEX-File Creation Problems

Problems 1 through 5 refer to the corresponding numbered sections of the previous flowchart. For additional suggestions on resolving MEX-file build problems, see the MathWorks Technical Support website http://www.mathworks.com/support.

Problem 1 — Compiling a Source MEX-File Fails

Syntax Errors Compiling C/C++ MEX-Files on UNIX

The most common configuration problem in creating C/C++ source MEX-files on UNIX® systems involves using a non-ANSI® C compiler, or failing to pass to the compiler a flag that tells it to compile ANSI C code.

A reliable way of knowing if you have this type of configuration problem is if the header files supplied by MATLAB® generate a string of syntax errors when you try to compile your code. See What You Need to Build MEX-Files or, if necessary, obtain an ANSI C compiler.

File Not Found on Windows

The mex function cannot find files located in folder names that contain non-ASCII characters.

Problem 2 — Compiling Your Own Program Fails

Mixing ANSI and non-ANSI C code can generate a string of syntax errors. MATLAB provides header and source files that are ANSI C compliant. Therefore, your C code must also be ANSI compliant.

Other common problems that can occur in any C/C++ program are neglecting to include all necessary header files, or neglecting to link against all required libraries.

Make sure that you are using a MATLAB-supported compiler. For an up-to-date list of supported compilers, see the Supported and Compatible Compilers website. Additional information can be found in Compiler- and Platform-Specific Issues.

Symbol mexFunction Unresolved or Not Defined

Attempting to compile a MEX-function that does not include a gateway function generates errors about the mexFunction symbol. For example, using a C/C++ compiler, MATLAB displays information like:

LINK : error LNK2001: unresolved external symbol mexFunction

Using a Fortran compiler, MATLAB displays information like:

unresolved external symbol _MEXFUNCTION

If you want to call functions from a C/C++ or Fortran library from MATLAB, you must write a gateway function, as described in Components of MEX-File.

Problem 3 — Binary MEX-File Load Errors

If you receive an error of the form:

Unable to load mex file:
Invalid MEX-file

MATLAB does not recognize your MEX-file.

MATLAB loads MEX-files by looking for the gateway routine, mexFunction. If you misspell the function name, MATLAB cannot load your MEX-file and generates an error message. On Windows® systems, check that you are exporting mexFunction correctly.

On some platforms, if you fail to link against required libraries, you might get an error when MATLAB loads your MEX-file rather than when you compile your MEX-file. In such cases, a system error message referring to unresolved symbols or unresolved references appears. Be sure to link against the library that defines the function in question.

On Windows systems, MATLAB fails to load MEX-files if it cannot find all .dll files referenced by the MEX-file; the .dll files must be on the path or in the same folder as the MEX-file. This is also true for third party .dll files. To diagnose this problem, see Invalid MEX-File Error for information.

Problem 4 — Segmentation Fault

If a binary MEX-file causes a segmentation violation or assertion, it means the MEX-file attempted to access protected, read-only, or unallocated memory.

These types of programming errors are sometimes difficult to track down. Segmentation violations do not always occur at the same point as the logical errors that cause them. If a program writes data to an unintended section of memory, an error might not occur until the program reads and interprets the corrupted data. Consequently, a segmentation violation can occur after the MEX-file finishes executing.

One cause of memory corruption is to pass a null pointer to a function. To check for this condition, add code in your MEX-file to check for invalid arguments to MEX Library and MX Matrix Library API functions.

To troubleshoot problems of this nature, run MATLAB within a debugging environment. For more information, see Debugging on Microsoft Windows Platforms or Debug Fortran Source MEX-Files.

Problem 5 — Program Generates Incorrect Results

If your program generates the wrong answers, there are several causes. First, there could be an error in the computational logic. Second, the program could be reading from an uninitialized section of memory. For example, reading the eleventh element of a 10-element vector yields unpredictable results.

Another cause of generating a wrong answer could be overwriting valid data due to memory mishandling. For example, writing to the fifteenth element of a 10-element vector might overwrite data in the adjacent variable in memory. This case can be handled in a similar manner as segmentation violations, as described in Problem 4.

In all of these cases, you can use mexPrintf to examine data values at intermediate stages or run MATLAB within a debugger to exploit all the tools the debugger provides.

Was this topic helpful?