MPI_FILE_CALL_ERRHANDLER(3)

💖 MPI_FILE_CALL_ERRHANDLER(3) 💖

okay bestie, so this one lives in the Open MPI manual, section 3, and it's called MPI_File_call_errhandler. Lowkey the whole vibe here is: you got an error code, you got a file, and you're gonna hand that error code straight to whichever error handler your file is vibing with. Let's get into it. ✨

---

🌸 NAME 🌸

MPI_File_call_errhandler — passes the supplied error code to the error handler assigned to a file 🫶

---

✨ SYNTAX ✨

💅 C Syntax

#include <mpi.h>

int MPI_File_call_errhandler(MPI_File fh, int errorcode)

💅 Fortran Syntax

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_FILE_CALL_ERRHANDLER(FH, ERRORCODE, IERROR)
     INTEGER FH, IERRORCODE, IERROR

💅 Fortran 2008 Syntax

USE mpi_f08
MPI_File_call_errhandler(fh, errorcode, ierror)
     TYPE(MPI_File), INTENT(IN) :: fh
     INTEGER, INTENT(IN) :: errorcode
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

---

🎀 INPUT PARAMETERS 🎀

• fh — the file rockin' this error handler (it's a handle, bestie).
• errorcode — the MPI error code, as an integer. 💀

---

🌈 OUTPUT PARAMETER 🌈

• ierror — Fortran only: the error status (integer).

---

👑 DESCRIPTION 👑

So here's the tea: this function invokes the error handler that's assigned to the file handle fh, and it passes along the error code errorcode you gave it. If everything goes right — meaning the error handler actually got called, the process did NOT get aborted, and the error handler returned — then this function hands you back MPI_SUCCESS. periodt. ✨

Now, unlike errors on communicators and windows, the default error handler for files is MPI_ERRORS_RETURN. Highkey a glow-up for files, ngl. 💅

---

😭 ERRORS 😭

Okay so, literally almost all MPI routines return an error value. In C, that's the return result of the function; in Fortran, it comes bundled in the last argument. iykyk.

But before that error value even gets returned, the current MPI error handler associated with the communication object (think: communicator, window, file) is called. And if there's no communication object associated with the MPI call at all? Then the call is considered attached to MPI_COMM_SELF, and it'll call the associated MPI error handler. And when MPI_COMM_SELF is not initialized — like before MPI_Init/MPI_Init_thread, after MPI_Finalize, or when you're using the Sessions Model exclusively — the error raises the initial error handler. 😭

Good news though, you can change the initial error handler: call MPI_Comm_set_errhandler on MPI_COMM_SELF when you're using the World model, or use the mpi_initial_errhandler CLI argument to mpiexec, or an info key to MPI_Comm_spawn/MPI_Comm_spawn_multiple. And if no other appropriate error handler has been set? Then the MPI_ERRORS_RETURN error handler is called for MPI I/O functions, and the MPI_ERRORS_ABORT error handler is called for all other MPI functions.

Open MPI ships with three predefined error handlers you can use, and they're iconic in their own ways:

• MPI_ERRORS_ARE_FATAL — causes the program to abort all connected MPI processes. yeah. all of them. 💀
• MPI_ERRORS_ABORT — an error handler that can be invoked on a communicator, window, file, or session. When it's called on a communicator, it acts as if MPI_Abort was called on that communicator. If it's called on a window or file, it acts as if MPI_Abort was called on a communicator containing the group of processes in the corresponding window or file. And if it's called on a session, it aborts only the local process.
• MPI_ERRORS_RETURN — returns an error code to the application. cute, polite, we love her. 🫶

MPI applications can also cook up their own error handlers by calling:

• MPI_Comm_create_errhandler then MPI_Comm_set_errhandler
• MPI_File_create_errhandler then MPI_File_set_errhandler
• MPI_Session_create_errhandler then MPI_Session_set_errhandler or at MPI_Session_init
• MPI_Win_create_errhandler then MPI_Win_set_errhandler

⚠️ Not me having to say this, but: note that MPI does not guarantee that an MPI program can continue past an error. fr fr. no cap.

See the MPI man page for a full list of MPI error codes. 👑

See the Error Handling section of the MPI-3.1 standard for more info if you're feeling scholarly. 🧚

See also:

• MPI_File_create_errhandler
• MPI_File_set_errhandler

---

💜 Copyright 💜

2003-2026, The Open MPI Community

---

and that's the whole page, bestie 🦋 the Open MPI girlies dropped this one on Sep 10, 2026, and it's filed under MPI_FILE_CALL_ERRHANDLER(3) — go call your error handler, mwah 💅✨🍓